Modelos de raciocínio de consulta

Neste artigo, aprende a escrever pedidos de consulta para modelos de fundação otimizados para tarefas de raciocínio e servidos pelo Unity Gateway.

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 Foundation Models, incluindo modelos de raciocínio. O raciocínio dá aos modelos de fundação capacidades aprimoradas para lidar com tarefas complexas. Alguns modelos também fornecem transparência, revelando seu processo de pensamento passo a passo antes de fornecer uma resposta final.

Tipos de modelos de raciocínio

Existem dois tipos de modelos, apenas de raciocínio e híbridos. A tabela a seguir descreve como diferentes modelos usam diferentes abordagens para controlar o raciocínio:

Exemplos de consulta

A maioria dos modelos de raciocínio utiliza o endpoint chat completions. Claude Haiku 5.5, Claude Opus 5.5 e Claude Fable 5.1 usam a API Anthropic Messages, como mostrado nos seus exemplos.

Exemplo de modelo Claude

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)

Exemplo do modelo Claude Haiku 5.5

Claude Haiku 5.5 é compatível com o pensamento adaptativo. Definir output_config.effort para low, medium, ou high para controlar a profundidade do raciocínio. O Databricks usa medium quando se omite este parâmetro. Para desativar o raciocínio, defina thinking.type para 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?"
      }
    ]
  }'

Exemplo do modelo Claude Opus 5.5

Claude Opus 5.5 utiliza pensamento adaptativo para cada pedido. Definir output_config.effort para low, medium, high, xhigh, , ou max para controlar a profundidade do raciocínio. O Databricks usa medium quando se 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?"
      }
    ]
  }'

Exemplo de modelo Claude Fable 5.1

Claude Fable 5.1 usa sempre pensamento adaptativo. Definir output_config.effort para 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?"
      }
    ]
  }'

GPT-5,1

O parâmetro reasoning_effort para GPT-5.1 está definido por defeito none, mas pode ser substituído nos pedidos. 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"
  }'

Exemplo de modelo GPT OSS

O reasoning_effort parâmetro aceita "low", "medium" (padrão) ou "high" valores. 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"
  }'

Exemplo do modelo Gemini

Este exemplo utiliza system.ai.gemini-3-1-pro. O reasoning_effort parâmetro está definido como "low" por defeito, mas pode ser sobreposto nas solicitações, como mostra o exemplo seguinte.

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 de pensamento e texto:

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
)

Gerencie o raciocínio em vários turnos

Esta secção é específica do databricks-claude-sonnet-4-5 modelo.

Em conversas de vários turnos, apenas os blocos de raciocínio associados à última interação do assistente ou sessão de utilização da ferramenta são visíveis para o modelo e são contados como tokens de entrada.

Se você não quiser passar tokens de raciocínio de volta para o modelo (por exemplo, você não precisa que ele raciocine sobre suas etapas anteriores), você pode 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 você estiver construindo experiências que revelem seu raciocínio intermediário - você deve incluir a mensagem de assistente completa e não modificada, 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

Quando usa a API Open Responses, o raciocínio é devolvido como reasoning itens na resposta output. Para deixar que o modelo raciocine sobre o seu pensamento anterior numa turnada posterior, inclua esses reasoning itens — com o seu encrypted_content campo inalterado — no próximo pedido input.

Um item reasoning retornado no resultado da resposta tem a seguinte estrutura:

{
  "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 novamente em input a saída do turno anterior, mantendo o item reasoning textualmente:

{
  "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 fornecedor. Se for eliminado ou modificado, o modelo não consegue justificar o seu pensamento anterior. Isto aplica-se 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 "pense" através do 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 databricks-claude-sonnet-4-5, exibem esses tokens de raciocínio para os utilizadores, enquanto outros, como a série OpenAI o, não os expõem e os descartam na saída final.

Recursos adicionais

• Consultar um modelo de incorporação.
• Consultar um modelo de chat.
• Modelos de visão de consulta.