Modelos de raciocínio de consulta
Neste artigo, você aprende como escrever solicitações de query para modelos básicos otimizados para tarefas de raciocínio e disponibilizados pelo Unity Gateway.
Genie Code (modo Agente) pode fazer isso por você. Experimente este prompt de exemplo:
Query the databricks-claude-sonnet-4-5 model using the OpenAI client with extended thinking enabled (budget_tokens set to 10240). Send a reasoning question and print both the thinking summary and the final answer.
A API do Databricks Foundation Model fornece uma API unificada para interagir com todos os modelos do Foundation, incluindo os modelos de raciocínio. O raciocínio confere aos modelos fundamentais capacidades aprimoradas para lidar com tarefas complexas. Alguns modelos também oferecem transparência ao revelar seu processo de raciocínio passo a passo antes de apresentar uma resposta final.
Tipos de modelos de raciocínio
Existem dois tipos de modelos, apenas para raciocínio e híbridos. A tabela a seguir descreve como modelos diferentes usam abordagens diferentes para controlar o raciocínio:
Modelos | Tipo de modelo de raciocínio | Detalhes | Parâmetros |
|---|---|---|---|
| Raciocínio híbrido | Este modelo é compatível com pensamento adaptativo para um raciocínio mais profundo, e o pensamento pode ser desativado para respostas mais rápidas. | Use os seguintes parâmetros com a Anthropic Messages API:
|
| Apenas raciocínio | Este modelo usa adaptive thinking para cada solicitação e o raciocínio não pode ser desativado. | Use os seguintes parâmetros com a Anthropic Messages API:
|
| Apenas raciocínio | Este modelo sempre usa raciocínio adaptativo, e o raciocínio não pode ser desativado. | Use os seguintes parâmetros com a Anthropic Messages API:
|
| Apenas raciocínio | Este modelo usa raciocínio interno em suas respostas por default. | Use o parâmetro |
| Apenas raciocínio | These models use internal reasoning in their responses by default. | Use o parâmetro |
| Apenas raciocínio | Este modelo sempre usa raciocínio interno em suas respostas. | Use o parâmetro |
Modelos GPT-5 como | Apenas raciocínio | Esses modelos sempre usam o raciocínio interno em suas respostas. | Use o seguinte parâmetro em sua solicitação:
|
Modelos Claude como | Raciocínio híbrido | Esses modelos oferecem suporte tanto a respostas rápidas e instantâneas quanto a um raciocínio mais profundo quando necessário. | Inclua os seguintes parâmetros para usar o raciocínio híbrido:
|
| Raciocínio híbrido | Este modelo oferece suporte a respostas rápidas e instantâneas e a um raciocínio mais profundo quando necessário. | Inclua o seguinte parâmetro para usar o raciocínio híbrido:
|
| Raciocínio híbrido | Este modelo oferece suporte a respostas rápidas e instantâneas e a um raciocínio mais profundo quando necessário. | Inclua o seguinte parâmetro para usar o raciocínio híbrido:
|
Modelos Gemini 3 como | Raciocínio híbrido | Esses modelos oferecem suporte tanto a respostas rápidas e instantâneas quanto a um raciocínio mais profundo quando necessário. | Inclua os seguintes parâmetros para usar o raciocínio híbrido:
|
Modelos GPT OSS como | Apenas raciocínio | Esses modelos sempre usam o raciocínio interno em suas respostas. | Use o seguinte parâmetro em sua solicitação:
|
| Apenas raciocínio | Este modelo sempre usa raciocínio interno em suas respostas. | Use o seguinte parâmetro em sua solicitação:
|
| Raciocínio híbrido | Esses modelos raciocinam por default e suportam tanto um raciocínio mais profundo quanto respostas rápidas e instantâneas quando | Use o seguinte parâmetro em sua solicitação:
|
| Apenas raciocínio | Estes modelos sempre usam raciocínio interno em suas respostas, e o raciocínio não pode ser desativado. | Use o seguinte parâmetro em sua solicitação:
|
Exemplos de consultas
Os exemplos a seguir são baseados no Unity Gateway e em serviços de modelo. Se você usar Endpoint de servindo modelo em vez de serviços de modelo, substitua o nome do serviço de modelo por um nome de Endpoint. Consulte a lista detalhada de modelos suportados pelas APIs do Databricks Foundation Model para ver uma lista de modelos de fundação disponíveis e seus nomes de serviço e endpoint de modelo.
A maioria dos modelos de raciocínio usa o endpoint chat completions. Claude Haiku 5.5, Claude Opus 5.5 e Claude Fable 5.1 usam a Anthropic Messages API, conforme mostrado em seus exemplos.
- Claude model example
- Claude Haiku 5.5 model example
- Claude Opus 5.5 model example
- Claude Fable 5.1 model example
- GPT-5.1
- GPT OSS model example
- Grok 4.6 model example
- Gemini model example
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get('YOUR_DATABRICKS_TOKEN'),
base_url=os.environ.get('YOUR_DATABRICKS_BASE_URL')
)
response = client.chat.completions.create(
model="system.ai.claude-sonnet-4-5",
messages=[{"role": "user", "content": "Why is the sky blue?"}],
max_tokens=20480,
extra_body={
"thinking": {
"type": "enabled",
"budget_tokens": 10240
}
}
)
msg = response.choices[0].message
reasoning = msg.content[0]["summary"][0]["text"]
answer = msg.content[1]["text"]
print("Reasoning:", reasoning)
print("Answer:", answer)
O Claude Haiku 5.5 oferece suporte ao pensamento adaptativo. Defina output_config.effort como low, medium ou high para controlar a profundidade do raciocínio. O Databricks usa medium quando você omite esse parâmetro. Para desativar o raciocínio, defina thinking.type como disabled e omita output_config.
curl -X POST "https://<workspace_host>.databricks.com/serving-endpoints/anthropic/v1/messages" \
-u token:$DATABRICKS_TOKEN \
-H "Content-Type: application/json" \
-H "anthropic-beta: effort-2025-11-24" \
-d '{
"model": "databricks-claude-haiku-5-5",
"max_tokens": 4096,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
O Claude Opus 5.5 usa adaptive thinking para cada solicitação. Defina output_config.effort como low, medium, high, xhigh ou max para controlar a profundidade do raciocínio. O Databricks usa medium quando você omite este parâmetro.
curl -X POST "https://<workspace_host>.databricks.com/ai-gateway/anthropic/v1/messages" \
-u token:$DATABRICKS_TOKEN \
-H "Content-Type: application/json" \
-H "anthropic-beta: effort-2025-11-24" \
-d '{
"model": "databricks-claude-opus-5-5",
"max_tokens": 4096,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
O Claude Fable 5.1 sempre usa raciocínio adaptativo. Defina output_config.effort como low, medium, high, xhigh ou max para controlar a profundidade do raciocínio.
curl -X POST "https://<workspace_host>.databricks.com/ai-gateway/anthropic/v1/messages" \
-u token:$DATABRICKS_TOKEN \
-H "Content-Type: application/json" \
-H "anthropic-beta: effort-2025-11-24" \
-d '{
"model": "databricks-claude-fable-5-1",
"max_tokens": 4096,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "high"
},
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
O parâmetro reasoning_effort para GPT-5.1 é definido como none por default, mas pode ser alterado nas solicitações. Um maior esforço de raciocínio pode resultar em respostas mais ponderadas e precisas, mas pode aumentar a latência e o uso de tokens.
curl -X POST "https://<workspace_host>/ai-gateway/mlflow/v1/chat/completions" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "system.ai.gpt-5-1",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
],
"max_tokens": 4096,
"reasoning_effort": "none"
}'
O parâmetro reasoning_effort aceita os valores "low", "medium" (default) ou "high". Um maior esforço de raciocínio pode resultar em respostas mais ponderadas e precisas, mas pode aumentar a latência e o uso de tokens.
curl -X POST "https://<workspace_host>/ai-gateway/mlflow/v1/chat/completions" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "system.ai.gpt-oss-120b",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
],
"max_tokens": 4096,
"reasoning_effort": "high"
}'
O parâmetro reasoning_effort aceita valores "low", "medium", "high" ou "xhigh". Um maior esforço de raciocínio pode resultar em respostas mais ponderadas e precisas, mas pode aumentar a latência e a utilização de tokens.
curl -X POST "https://<workspace_host>/ai-gateway/mlflow/v1/chat/completions" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "system.ai.databricks-grok-4-6",
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
],
"max_tokens": 4096,
"reasoning_effort": "high"
}'
Este exemplo usa system.ai.gemini-3-1-pro. O parâmetro reasoning_effort é definido como "low" por default, mas pode ser substituído nas solicitações, como visto no exemplo a seguir.
curl -X POST "https://<workspace_host>/ai-gateway/mlflow/v1/chat/completions" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "system.ai.gemini-3-1-pro",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Why is the sky blue?"
}
],
"max_tokens": 2000,
"stream": true,
"reasoning_effort": "high"
}'
A resposta da API inclui blocos de conteúdo textual e de reflexão:
ChatCompletionMessage(
role="assistant",
content=[
{
"type": "reasoning",
"summary": [
{
"type": "summary_text",
"text": ("The question is asking about the scientific explanation for why the sky appears blue... "),
"signature": ("EqoBCkgIARABGAIiQAhCWRmlaLuPiHaF357JzGmloqLqkeBm3cHG9NFTxKMyC/9bBdBInUsE3IZk6RxWge...")
}
]
},
{
"type": "text",
"text": (
"# Why the Sky Is Blue\n\n"
"The sky appears blue because of a phenomenon called Rayleigh scattering. Here's how it works..."
)
}
],
refusal=None,
annotations=None,
audio=None,
function_call=None,
tool_calls=None
)
gerenciar o raciocínio em várias etapas
Esta seção é específica para o modelo databricks-claude-sonnet-4-5 .
Em conversas com várias voltas, apenas os blocos de raciocínio associados à última volta do assistente ou sessão de uso da ferramenta são visíveis para o modelo e contados como tokens de entrada.
Se não desejar passar tokens de raciocínio de volta para o modelo (por exemplo, se não precisar dele para raciocinar sobre as etapas anteriores), é possível omitir o bloco de raciocínio completamente. Por exemplo:
response = client.chat.completions.create(
model="system.ai.claude-sonnet-4-5",
messages=[
{"role": "user", "content": "Why is the sky blue?"},
{"role": "assistant", "content": text_content},
{"role": "user", "content": "Can you explain in a way that a 5-year-old child can understand?"}
],
max_tokens=20480,
extra_body={
"thinking": {
"type": "enabled",
"budget_tokens": 10240
}
}
)
answer = response.choices[0].message.content[1]["text"]
print("Answer:", answer)
No entanto, se você precisar que o modelo raciocine sobre seu processo de raciocínio anterior - por exemplo, se estiver criando experiências que revelem seu raciocínio intermediário - você deve incluir a mensagem completa e não modificada do assistente, incluindo o bloco de raciocínio do turno anterior. Veja como continuar um tópico com a mensagem completa do assistente:
assistant_message = response.choices[0].message
response = client.chat.completions.create(
model="system.ai.claude-sonnet-4-5",
messages=[
{"role": "user", "content": "Why is the sky blue?"},
{"role": "assistant", "content": text_content},
{"role": "user", "content": "Can you explain in a way that a 5-year-old child can understand?"},
assistant_message,
{"role": "user", "content": "Can you simplify the previous answer?"}
],
max_tokens=20480,
extra_body={
"thinking": {
"type": "enabled",
"budget_tokens": 10240
}
}
)
answer = response.choices[0].message.content[1]["text"]
print("Answer:", answer)
API de Respostas Abertas
Ao usar a Open Responses API, o raciocínio é retornado como reasoning itens na resposta output. Para permitir que o modelo raciocine sobre seu pensamento anterior em uma volta posterior, inclua esses reasoning itens—com seu campo encrypted_content inalterado—na próxima solicitação input.
Um item reasoning retornado na saída da resposta tem o seguinte formato:
{
"type": "reasoning",
"id": "rs_abc123",
"content": [{ "type": "reasoning_text", "text": "Let me work through the question..." }],
"encrypted_content": "<opaque-provider-signature>"
}
Para continuar a conversa, envie a saída do turno anterior de volta em input, com o item reasoning preservado literalmente:
{
"model": "databricks-claude-sonnet-4-5",
"input": [
{ "role": "user", "content": "Why is the sky blue?" },
{
"type": "reasoning",
"id": "rs_abc123",
"content": [{ "type": "reasoning_text", "text": "Let me work through the question..." }],
"encrypted_content": "<opaque-provider-signature>"
},
{ "role": "assistant", "content": "The sky is blue because of Rayleigh scattering..." },
{ "role": "user", "content": "Can you explain it for a five-year-old?" }
]
}
O valor encrypted_content contém o estado de raciocínio específico do provedor. Se for descartado ou modificado, o modelo não poderá raciocinar sobre seu pensamento anterior. Isso se aplica aos modelos Anthropic Claude e Google Gemini.
Como funciona um modelo de raciocínio?
Os modelos de raciocínio introduzem tokens de raciocínio especiais, além dos tokens de entrada e saída padrão. Esses tokens permitem que o modelo "reflita sobre o prompt", decompondo-o e considerando diferentes maneiras de responder. Após esse processo de raciocínio interno, o modelo gera sua resposta final como tokens de saída visíveis. Alguns modelos, como o databricks-claude-sonnet-4-5, exibem esses tokens de raciocínio aos usuários, enquanto outros, como a série OpenAI o, os descartam e não os expõem na saída final.