Modelos de raciocínio de consulta
Experimente o novo Beta do Gateway de AI do Unity
Uma nova experiência do Unity AI Gateway está disponível em Beta. O novo Unity AI Gateway é o plano de controle corporativo para governar o endpoint LLM e os agentes de codificação com recurso aprimorado. Consulte Unity AI Gateway.
Neste artigo, você aprenderá a escrever solicitações de consulta para modelos básicos otimizados para tarefas de raciocínio e disponibilizados por Unity AI 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 |
|---|---|---|---|
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:
|
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 Gemini 2.5 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:
|
Exemplos de consultas
Os exemplos a seguir são baseados em Unity AI Gateway e serviços de modelo. Se você usa endpoints de servindo modelo em vez de serviços de modelo, substitua o nome do serviço de modelo pelo nome de um endpoint. Consulte modelos de base hospedados pelo Databricks disponíveis nas APIs do Foundation Model para obter uma lista de modelos de base disponíveis e seus nomes de serviço de modelo e endpoint.
Todos os modelos de raciocínio são acessados por meio do endpoint de conclusões do chat.
- Claude model example
- GPT-5.1
- GPT OSS 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 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"
}'
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.