Modelli di ragionamento delle query

In questo articolo impari come scrivere query request per modelli di fondazione ottimizzati per compiti di ragionamento e serviti da Unity Gateway.

Tip

Genie Code (modalità agente) può farlo per te. Provare questo prompt di esempio:

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.

L'API modello di Databricks Foundation offre un'API unificata per interagire con tutti i modelli di base, inclusi i modelli di ragionamento. Il ragionamento offre ai modelli di base funzionalità avanzate per affrontare attività complesse. Alcuni modelli forniscono anche trasparenza rivelando il loro processo di pensiero dettagliato prima di fornire una risposta finale.

Tipi di modelli di ragionamento

Esistono due tipi di modelli, solo ragionamento e ibrido. La tabella seguente descrive in che modo i diversi modelli usano approcci diversi per controllare il ragionamento:

Tipo di modello di ragionamento Dettagli Esempi di modelli Parametri
Ragionamento ibrido Questo modello supporta il pensiero adattivo per un ragionamento più profondo, e il pensiero può essere disabilitato per risposte più rapide. databricks-claude-haiku-5-5 Usa i seguenti parametri con l'API Anthropic Messages:
  • thinking: Imposta type su adaptive per usare il ragionamento o disabled per disabilitarlo.
  • output_config.effort: Accetta low, medium, o high. Databricks imposta medium come valore predefinito se si omette questo parametro. Altri valori, tra cui none, xhigh, e max, vengono rifiutati.
Solo ragionamento Questo modello utilizza il pensiero adattivo per ogni richiesta, e il ragionamento non può essere disabilitato. databricks-claude-opus-5-5 Usa i seguenti parametri con l'API Anthropic Messages:
  • thinking: Imposta type su adaptive. I valori di pensiero e manuali budget_tokens disabili vengono rifiutati.
  • output_config.effort: Accetta low, medium, high, xhigh, o max. Databricks imposta medium come valore predefinito se si omette questo parametro. Altri valori, inclusi none e disabled, vengono rifiutati.
Solo ragionamento Questo modello utilizza sempre il pensiero adattivo, e il ragionamento non può essere disabilitato. databricks-claude-fable-5-1 Usa i seguenti parametri con l'API Anthropic Messages:
  • thinking: Imposta type su adaptive.
  • output_config.effort: Accetta low, medium, high, xhigh, o max. Databricks non imposta un parametro predefinito; Anthropic usa high quando ometti questo parametro. Altri valori, incluso none, vengono rifiutati.
Ragionamento ibrido Supporta sia risposte rapide che istantanee e ragionamento più approfondito quando necessario.
  • Modelli Claude come databricks-claude-sonnet-4-6, databricks-claude-sonnet-4-5, databricks-claude-opus-5, databricks-claude-opus-4-8, databricks-claude-opus-4-7, databricks-claude-opus-4-6, databricks-claude-opus-4-5, e databricks-claude-opus-4-1.
  • databricks-deepseek-v4-1-flash
 I parametri variano a seconda del modello:
  • Per i modelli Claude, si usano thinking e budget_tokens. Il parametro budget_tokens controlla quanti token il modello può usare per il pensiero interno. I budget più elevati possono migliorare la qualità per le attività complesse, ma l'utilizzo superiore a 32.000 può variare. budget_tokens deve essere minore di max_tokens.
  • Per DeepSeek V4.1 Flash, reasoning_effort accetta "low", "high", "xhigh", o "max" (predefinito). "minimal" corrisponde a "low", e "medium" corrisponde a "high". "none" o "disabled" disabilita il ragionamento. Altri valori vengono rifiutati.
Solo ragionamento Questi modelli usano sempre il ragionamento interno nelle risposte. Modelli OSS GPT come databricks-gpt-oss-120b e databricks-gpt-oss-20b. Usare il parametro seguente nella richiesta:
  • reasoning_effort: accetta valori di "low", "medium" (impostazione predefinita) o "high". Un maggiore sforzo di ragionamento può comportare risposte più ponderate e accurate, ma può aumentare la latenza e l'utilizzo dei token. Questo parametro viene accettato solo da un set limitato di modelli, inclusi databricks-gpt-oss-120b e databricks-gpt-oss-20b.

Esempi di query

Note

I seguenti esempi si basano su Unity Gateway e servizi modello. Se si usa il modello che gestisce gli endpoint anziché i servizi modello, sostituire il nome del servizio modello con un nome di endpoint. Vedi Elenco dettagliato dei modelli supportati dalle API dei modelli di fondazione Databricks per un elenco dei modelli di fondazione disponibili e i loro nomi di servizio modello e endpoint.

La maggior parte dei modelli di ragionamento utilizza l'endpoint di completamento delle chat . Claude Haiku 5.5, Claude Opus 5.5 e Claude Fable 5.1 utilizzano l'API Anthropic Messages, come mostrato nei loro esempi.

Esempio di modello 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)

Esempio di modello Claude Haiku 5.5

Claude Haiku 5.5 supporta il pensiero adattivo. Imposta output_config.effort su low, medium o high per controllare la profondità del ragionamento. Databricks utilizza medium quando ometti questo parametro. Per disabilitare il ragionamento, imposta thinking.type su disabled e ometti 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?"
      }
    ]
  }'

Esempio di modello Claude Opus 5.5

Claude Opus 5.5 utilizza il pensiero adattivo per ogni richiesta. Impostato output_config.effort su low, medium, high, xhigh, oppure max per controllare la profondità del ragionamento. Databricks utilizza medium quando ometti questo parametro.

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?"
      }
    ]
  }'

Esempio di modello Claude Fable 5.1

Claude Fable 5.1 utilizza sempre il pensiero adattivo. Impostato output_config.effort su low, medium, high, xhigh, oppure max per controllare la profondità del ragionamento.

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

Il reasoning_effort parametro per GPT-5.1 è impostato su none per impostazione predefinita, ma può essere sostituito utilizzando le richieste. Un maggiore sforzo di ragionamento può comportare risposte più ponderate e accurate, ma può aumentare la latenza e l'utilizzo dei 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"
  }'

Esempio di modello OSS GPT

Il reasoning_effort parametro accetta "low", "medium" (impostazione predefinita) o "high" valori. Un maggiore sforzo di ragionamento può comportare risposte più ponderate e accurate, ma può aumentare la latenza e l'utilizzo dei 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"
  }'

Esempio di modello Gemini

Questo esempio usa system.ai.gemini-3-1-pro. Il parametro reasoning_effort è impostato su "low" per impostazione predefinita, ma può essere sovrascritto nelle richieste, come illustrato nell'esempio seguente.

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"
  }'

La risposta dell'API include blocchi di contenuto di riflessione e di testo.

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
)

Gestire il ragionamento attraverso più fasi

Questa sezione è specifica del databricks-claude-sonnet-4-5 modello.

Nelle conversazioni a più turni, solo i blocchi di ragionamento associati all'ultimo turno di assistente o alla sessione di utilizzo degli strumenti sono visibili al modello e conteggiati come token di input.

Se non si vogliono passare di nuovo i token di ragionamento al modello ( ad esempio, non è necessario ragionare sui passaggi precedenti), è possibile omettere completamente il blocco di ragionamento. Per esempio:

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)

Tuttavia, se è necessario che il modello ragioni sul suo processo di ragionamento precedente, ad esempio se si creano esperienze che ne evidenziano il ragionamento intermedio, è necessario includere il messaggio di assistente completo e non modificato, incluso il blocco di ragionamento dal turno precedente. Ecco come continuare un thread con il messaggio dell'assistente completo:

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)

Open Responses API

Quando si usa l'API Open Responses, il ragionamento viene restituito come reasoning elementi nella risposta output. Per consentire al modello di ragionare sul proprio ragionamento precedente in un turno successivo, includi gli elementi reasoning, lasciando invariato il relativo campo encrypted_content, nel campo input della richiesta successiva.

Un reasoning elemento restituito nell'output della risposta ha la forma seguente:

{
  "type": "reasoning",
  "id": "rs_abc123",
  "content": [{ "type": "reasoning_text", "text": "Let me work through the question..." }],
  "encrypted_content": "<opaque-provider-signature>"
}

Per continuare la conversazione, rinvia l'output del turno precedente in input, mantenendo l'elemento reasoning alla lettera:

{
  "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?" }
  ]
}

Il encrypted_content valore contiene uno stato di ragionamento specifico del provider. Se viene eliminato o modificato, il modello non può ragionare sul suo pensiero precedente. Questo vale per i modelli Anthropic Claude e Google Gemini.

Come funziona un modello di ragionamento?

I modelli di ragionamento introducono token di ragionamento speciali oltre ai token di input e output standard. Questi token consentono al modello di "pensare" tramite la richiesta, suddividendolo e considerando diversi modi per rispondere. Dopo questo processo di ragionamento interno, il modello genera la risposta finale come token di output visibili. Alcuni modelli, ad esempio databricks-claude-sonnet-4-5, visualizzano questi token di ragionamento agli utenti, mentre altri, ad esempio la serie OpenAI o, li eliminano e non li espongono nell'output finale.

Risorse aggiuntive

  • Ultimo aggiornamento: