Modelos de raciocínio de consulta

Neste artigo, você aprenderá a escrever solicitações de consulta para modelos de base otimizados para tarefas de raciocínio e servidos pelo Gateway de IA do Unity.

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 de Modelo do Databricks Foundation fornece uma API unificada para interagir com todos os Modelos de Fundação, incluindo modelos de raciocínio. O raciocínio fornece recursos aprimorados para modelos de base 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

Há dois tipos de modelos, somente 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

Todos os modelos de raciocínio são acessados pelo ponto de extremidade das conclusões de chat.

Exemplo de modelo de 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)

GPT-5.1

O reasoning_effort parâmetro para GPT-5.1 é definido por padrão para none, mas pode ser substituído em requisições. Um esforço de raciocínio mais alto pode resultar em respostas mais pensativas e precisas, mas pode aumentar a latência e o uso de token.

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 do GPT OSS

O reasoning_effort parâmetro aceita "low", "medium" (padrão) ou "high" valores. Um esforço de raciocínio mais alto pode resultar em respostas mais pensativas e precisas, mas pode aumentar a latência e o uso de token.

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 de modelo gemini

Este exemplo usa system.ai.gemini-3-1-pro. O reasoning_effort parâmetro é definido "low" como por padrão, mas pode ser substituído em 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 à API inclui blocos de conteúdo de pensamento e de 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
)

Gerenciar o raciocínio em várias voltas

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

Em conversas de vários turnos, somente os blocos de raciocínio associados à última vez do assistente ou à sessão de uso de ferramentas são visíveis para o modelo e contados como tokens de entrada.

Se você não quiser passar tokens de raciocínio de volta para o modelo (por exemplo, não precisa que ele raciocine sobre suas etapas anteriores), pode omitir o bloco de raciocínio por completo. 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 do modelo para raciocinar sobre seu processo de raciocínio anterior - por exemplo, se estiver criando experiências que revelem seu raciocínio intermediário -, deverá incluir a mensagem completa e não modificada do assistente, incluindo o bloco de raciocínio do turno anterior. Veja como continuar um thread com a mensagem de assistente completa:

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)

Abrir API de Respostas

Quando você usa a API de Respostas Abertas, o raciocínio é retornado como reasoning itens na resposta output. Para permitir que o modelo raciocine com base no seu raciocínio anterior em um turno posterior, inclua esses itens reasoning — com o campo encrypted_content inalterado — no input da próxima solicitação.

Um reasoning item retornado na saída de resposta tem a seguinte forma:

{
  "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 da rodada 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 isso for descartado ou modificado, o modelo não conseguirá raciocinar com base em seu raciocínio 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 "pense" no prompt, dividindo-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 usuários, enquanto outros, como a série O OpenAI, os descartam e não os expõem na saída final.

Recursos adicionais

• Consultar um modelo de inserção.
• Consultar um modelo de chat.
• Consultar modelos de visão.