Modèles de raisonnement de query
Dans cet article, vous apprendrez à rédiger des requêtes de query pour des modèles de fondation optimisés pour les tâches de raisonnement, et servis par Unity AI Gateway.
Genie Code (mode Agent) peut le faire pour vous. Essayez cet exemple de prompt :
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 de modèle de fondation Databricks fournit une API unifiée pour interagir avec tous les modèles de fondation, y compris les modèles de raisonnement. Le raisonnement confère aux modèles de fondation des capacités améliorées pour s'attaquer à des tâches complexes. Certains modèles offrent également une transparence en révélant leur processus de pensée étape par étape avant de fournir une réponse finale.
Types de modèles de raisonnement
Il existe deux types de modèles : basés uniquement sur le raisonnement et hybrides. Le tableau suivant décrit comment différents modèles utilisent différentes approches pour contrôler le raisonnement :
Modèles | Type de modèle de raisonnement | Détails | Paramètres |
|---|---|---|---|
Modèles GPT-5 comme | Raisonnement uniquement | Ces modèles utilisent toujours un raisonnement interne dans leurs réponses. | Utilisez le paramètre suivant dans votre requête :
|
Modèles Claude tels que | Raisonnement hybride | Ces modèles prennent en charge les réponses rapides et instantanées ainsi qu'un raisonnement plus approfondi si nécessaire. | Incluez les paramètres suivants pour utiliser le raisonnement hybride :
|
Modèles Gemini 3 tels que | Raisonnement hybride | Ces modèles prennent en charge les réponses rapides et instantanées ainsi qu'un raisonnement plus approfondi si nécessaire. | Incluez les paramètres suivants pour utiliser le raisonnement hybride :
|
Modèles Gemini 2,5 comme | Raisonnement hybride | Ces modèles prennent en charge les réponses rapides et instantanées ainsi qu'un raisonnement plus approfondi si nécessaire. | Incluez les paramètres suivants pour utiliser le raisonnement hybride :
|
Modèles GPT OSS comme | Raisonnement uniquement | Ces modèles utilisent toujours un raisonnement interne dans leurs réponses. | Utilisez le paramètre suivant dans votre requête :
|
| Raisonnement uniquement | Ces modèles utilisent toujours un raisonnement interne dans leurs réponses. | Utilisez le paramètre suivant dans votre requête :
|
Exemples de query
Les exemples suivants sont basés sur Unity AI Gateway et les services de modèles. Si vous utilisez des Endpoint de diffusion de modèles au lieu de services de modèles, remplacez le nom du service de modèle par un nom d'Endpoint. Voir modèles de fondation hébergés par Databricks disponibles dans les API Foundation Model pour une liste des modèles de fondation disponibles ainsi que leurs noms de service de modèle et d'Endpoint.
Tous les modèles de raisonnement sont accessibles via l'endpoint de complétion de 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)
Le paramètre reasoning_effort pour GPT-5.1 est défini sur none par default, 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 plus 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"
}'
Le paramètre reasoning_effort accepte les valeurs "low", "medium" (default) ou "high". Un effort de raisonnement plus élevé peut entraîner des réponses plus réfléchies et plus 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"
}'
Cet exemple utilise system.ai.gemini-3-1-pro. Le parameter reasoning_effort est défini sur "low" par default, mais peut être ignoré dans les requêtes comme le montre 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 réflexion 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 tours
Cette section est spécifique au modèle databricks-claude-sonnet-4-5.
Dans les conversations multi-tours, seuls les blocs de raisonnement associés au dernier tour de l'assistant ou à la session d'utilisation d'outils sont visibles par le modèle et sont comptabilisés comme des jetons d'entrée.
Si vous ne souhaitez pas transmettre les jetons de raisonnement au modèle (par exemple, vous n'avez pas besoin qu'il raisonne sur 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 que le modèle raisonne sur son processus de raisonnement précédent — par exemple, si vous créez des expériences qui mettent en évidence son raisonnement intermédiaire —, vous devez inclure le message de l'assistant complet et non modifié, y compris le bloc de raisonnement du tour précédent. Voici comment poursuivre un fil de discussion avec le message complet de l'assistant :
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 réponses ouvertes
Lorsque vous utilisez l'API des réponses ouvertes, le raisonnement est renvoyé sous la forme de reasoning éléments dans la réponse output. Pour permettre au modèle de raisonner sur sa réflexion précédente lors d'une étape ultérieure, incluez ces reasoning éléments — avec leur champ encrypted_content inchangé — dans le input de la prochaine requête.
Un élément reasoning 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 continuer la conversation, renvoyez la sortie du tour précédent dans input, avec l'élément reasoning conservé tel quel :
{
"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 comporte un état de la raison spécifique au fournisseur. S'il est supprimé ou modifié, le modèle ne peut pas raisonner sur sa réflexion antérieure. Ceci 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 « penser » via le prompt, en le décomposant et en envisageant différentes manières de répondre. Après ce processus de raisonnement interne, le modèle génère sa réponse finale sous forme de jetons de sortie visibles. Certains modèles, comme 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.