Modèles pour le raisonnement de requêtes

Dans cet article, vous apprenez à écrire des requêtes pour des modèles de fondation optimisés pour des tâches de raisonnement, et desservis par 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.

L’API Databricks Foundation Model fournit une API unifiée pour interagir avec tous les modèles Foundation, y compris les modèles de raisonnement. Le raisonnement offre aux modèles de base des fonctionnalités améliorées pour traiter des tâches complexes. Certains modèles fournissent également une transparence en révélant leur processus de réflexion pas à pas avant de fournir une réponse finale.

Types de modèles de raisonnement

Il existe deux types de modèles, de raisonnement uniquement et hybrides. Le tableau suivant décrit comment différents modèles utilisent différentes approches pour contrôler le raisonnement :

Exemples de requêtes

La plupart des modèles de raisonnement utilisent le point de terminaison de complétions de chat. Claude Haiku 5.5, Claude Opus 5.5 et Claude Fable 5.1 utilisent l’API Anthropic Messages, comme montré dans leurs exemples.

Flash DeepSeek V4.1 (1017)

Cet exemple utilise un effort de raisonnement "low". Définissez reasoning_effort sur "none" pour désactiver le raisonnement.

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.deepseek-v4-1-flash-1017",
    "messages": [
      {
        "role": "user",
        "content": "Why is the sky blue?"
      }
    ],
    "max_tokens": 4096,
    "reasoning_effort": "low"
  }'

Exemple de modèle 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)

Exemple de modèle Claude Haiku 5.5

Claude Haiku 5.5 prend en charge le raisonnement adaptatif. Réglez output_config.effort à low, medium ou high pour contrôler la profondeur de raisonnement. Databricks utilise medium lorsque vous omettez ce paramètre. Pour désactiver le raisonnement, réglez thinking.type sur disabled et omettez 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?"
      }
    ]
  }'

Exemple de modèle Claude Opus 5.5

Claude Opus 5.5 utilise la pensée adaptative pour chaque requête. Régler output_config.effort sur low, medium, high, xhigh, ou max pour contrôler la profondeur de raisonnement. Databricks utilise medium lorsque vous omettez ce paramètre.

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

Exemple de modèle Claude Fable 5.1

Claude Fable 5.1 utilise toujours la pensée adaptative. Régler output_config.effort sur low, medium, high, xhigh, ou max pour contrôler la profondeur de raisonnement.

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

Le reasoning_effort paramètre pour GPT-5.1 est défini none par défaut, mais peut être remplacé dans les requêtes. Un effort de raisonnement plus élevé peut entraîner des réponses plus réfléchies et précises, mais peut augmenter la latence et l’utilisation des jetons.

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

Exemple de modèle OSS GPT

Le reasoning_effort paramètre accepte "low", "medium" (par défaut) ou "high" les valeurs. Un effort de raisonnement plus élevé peut entraîner des réponses plus réfléchies et précises, mais peut augmenter la latence et l’utilisation des jetons.

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

Exemple de modèle Argon Gemini 4

Cet exemple utilise system.ai.databricks-gemini-4-argon avec reasoning_effort défini sur "high". Si vous omettez le paramètre, le modèle utilise "medium".

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DATABRICKS_TOKEN"],
    base_url=os.environ["DATABRICKS_BASE_URL"],
)

response = client.chat.completions.create(
    model="system.ai.databricks-gemini-4-argon",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    max_tokens=2000,
    reasoning_effort="high",
)

print(response.choices[0].message.content)

Exemple de modèle Gemini

Cet exemple utilise system.ai.gemini-3-1-pro. Le reasoning_effort paramètre est défini "low" par défaut, mais peut être remplacé dans les requêtes, comme indiqué dans l’exemple suivant.

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 réponse de l’API comprend des blocs de contenu de pensée et de texte :

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
)

Gérer le raisonnement sur plusieurs itérations

Cette section est spécifique au databricks-claude-sonnet-4-5 modèle.

Dans les conversations à plusieurs tours, seuls les blocs de raisonnement associés au dernier tour de l'assistant ou à la session d'utilisation d'outils sont visibles pour le modèle et comptés comme jetons d'entrée.

Si vous ne souhaitez pas transmettre de jetons de raisonnement au modèle (par exemple, vous n’en avez pas besoin pour raisonner au cours de ses étapes précédentes), vous pouvez omettre entièrement le bloc de raisonnement. Par exemple:

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)

Toutefois, si vous avez besoin du modèle pour raisonner sur son processus de raisonnement précédent ( par exemple, si vous créez des expériences qui surfacent son raisonnement intermédiaire), vous devez inclure le message d’assistant complet, non modifié, y compris le bloc de raisonnement du tour précédent. Voici comment continuer un thread avec le message d’assistant complet :

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 Open Responses

Lorsque vous utilisez l’API Open Response, le raisonnement est retourné en tant qu’éléments reasoning dans la réponse output. Pour laisser le modèle raisonner par rapport à sa pensée précédente à un tour ultérieur, incluez ces reasoning éléments, avec leur encrypted_content champ inchangé, dans la requête inputsuivante.

Un reasoning élément retourné dans la sortie de la réponse a la forme suivante :

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

Pour poursuivre la conversation, renvoyez la sortie du tour précédent dans input, en conservant l’élément reasoning de manière strictement identique :

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

La valeur encrypted_content contient l’état de raisonnement propre au fournisseur. S’il est supprimé ou modifié, le modèle ne peut pas raisonner à partir de ce qu’il a pensé auparavant. Cela s’applique aux modèles Anthropic Claude et Google Gemini.

Comment fonctionne un modèle de raisonnement ?

Les modèles de raisonnement introduisent des jetons de raisonnement spéciaux en plus des jetons d’entrée et de sortie standard. Ces jetons permettent au modèle de « réfléchir » au prompt, en le décomposant et en envisageant différentes façons d’y répondre. Après ce processus de raisonnement interne, le modèle génère sa réponse finale en tant que jetons de sortie visibles. Certains modèles, tels que databricks-claude-sonnet-4-5, affichent ces jetons de raisonnement aux utilisateurs, tandis que d’autres, tels que la série OpenAI o, les ignorent et ne les exposent pas dans la sortie finale.

Ressources supplémentaires

• Interrogez un modèle d’incorporation.
• Interrogez un modèle de chat.
• Modèles de vision des requêtes.