在本文中,你将学习如何为针对推理任务优化的基础模型编写查询请求,这些模型由 Unity Gateway 提供。
Tip
Genie Code 可以帮你做到这一点。 请尝试以下示例提示:
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.
Databricks Foundation 模型 API 提供了一个统一的 API 来与所有基础模型进行交互,包括推理模型。 推理为基础模型提供了增强功能来处理复杂任务。 一些模型还通过展示其分步思维过程来提供透明度,然后再提供最终答案。
推理模型的类型
有两种类型的模型,即仅推理模型和混合模型。 下表介绍了不同的模型如何使用不同的方法来控制推理:
| 推理模型类型 | 详细信息 | 模型示例 | 参数 |
|---|---|---|---|
| 仅推理 | 该模型对每个请求进行推理,推理功能无法禁用。 |
system.ai.gemini-4-carbon (ADI服务) |
使用 reasoning_effort 搭配聊天完成 API,或使用 reasoning.effort 搭配 Open Responses API。 可接受的值为 "low"、"medium"(默认值)和 "high"。 使用 Google Gemini API,在 generationConfig.thinkingConfig 中使用 thinkingLevel。 不受支持的努力值会被拒绝,而不是重新映射。
"none" 和 "minimal" 不会禁用推理,并且被拒绝。 |
| 仅推理 | 该模型对每个请求进行推理,推理功能无法禁用。 |
databricks-gemini-4-argon (ADI服务) |
使用 reasoning_effort 搭配聊天完成 API,或使用 reasoning.effort 搭配 Open Responses API。 可接受的值为 "low"、"medium"(默认值)和 "high"。 使用 Google Gemini API,在 generationConfig.thinkingConfig 中使用 thinkingLevel。 不受支持的努力值会被拒绝,而不是重新映射。
"none" 和 "minimal" 不会禁用推理,并且被拒绝。 |
| 混合推理 | 该模型支持适应性思维以实现更深层次的推理,并且可以关闭思考以获得更快的反应。 | databricks-claude-haiku-5-5 |
使用以下参数与 Anthropic Messages API 配合使用:
|
| 仅推理 | 该模型对每个请求使用自适应思维,推理无法被禁用。 | databricks-claude-opus-5-5 |
使用以下参数与 Anthropic Messages API 配合使用:
|
| 仅推理 | 该模型始终使用适应性思维,推理能力无法被剥夺。 通过 Unity Gateway 查询它。 | system.ai.claude-fable-5-2 |
与 Anthropic Messages API 一起使用output_config.effort。 可接受的值为 low、medium、high、xhigh 和 max。 Databricks 不设置默认值;Anthropic 会在你省略该参数时使用high。 参见 Anthropic 的 effort 文档。 |
| 仅推理 | 该模型始终使用适应性思维,推理能力无法被剥夺。 | databricks-claude-fable-5-1 |
使用以下参数与 Anthropic Messages API 配合使用:
|
| 混合推理 | 这些模型支持适应性思维以实现更深层次的推理。 |
databricks-claude-opus-5、 databricks-claude-opus-4-8和 databricks-claude-opus-4-7 |
使用以下参数与 Anthropic Messages API 配合使用:
|
| 混合推理 | 支持快速、即时答复和更深层次的推理(如果需要)。 |
|
参数因型号而异:
|
| 仅推理 | 这些模型始终在其响应中使用内部推理。 | GPT OSS 模型,如 databricks-gpt-oss-120b 和 databricks-gpt-oss-20b。 |
在请求中使用以下参数:
|
查询示例
注释
以下示例基于 Unity Gateway 和模型服务。 如果使用模型服务终结点而不是模型服务,请将模型服务名称替换为终结点名称。 请参阅 Databricks 基础模型 API 支持的模型详细列表 ,了解可用的基础模型及其模型服务和端点名称。
大多数推理模型都使用 chat completions 端点。 Claude Haiku 5.5、Claude Opus 5.5、Claude Fable 5.1 和 Claude Fable 5.2 使用 Anthropic Messages API,如其示例所示。
GPT-6.2 Astra
此示例使用带有 "medium" 推理力度的 Responses API。
from databricks_openai import DatabricksOpenAI
client = DatabricksOpenAI()
response = client.responses.create(
model="system.ai.gpt-6-2-astra",
input="Why is the sky blue?",
reasoning={"effort": "medium"},
max_output_tokens=4096,
)
print(response.output_text)
GPT-6.2 Sol
此示例使用 Responses API,采用 "medium" 推理强度。
from databricks_openai import DatabricksOpenAI
client = DatabricksOpenAI()
response = client.responses.create(
model="system.ai.gpt-6-2-sol",
input="Why is the sky blue?",
reasoning={"effort": "medium"},
max_output_tokens=4096,
)
print(response.output_text)
DeepSeek V4.1 Flash(1017)
此示例使用 "low" 推理力度。 将reasoning_effort设置为"none"以禁用推理。
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"
}'
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)
Claude Haiku 5.5 模型示例
Claude Haiku 5.5 支持适应性思维。 将 output_config.effort 设置为 low、medium 或 high,以控制推理深度。 Databricks 会在你省略这个参数时使用 medium 。 要禁用推理,设 thinking.type 为 disabled 并省略 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?"
}
]
}'
Claude Opus 5.5 型号示例
Claude Opus 5.5 对每个请求都采用自适应思维。 将 output_config.effort 设置为 low、medium、high、xhigh 或 max,以控制推理深度。 Databricks 会在你省略这个参数时使用 medium 。
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?"
}
]
}'
Claude Fable 5.2
Claude Fable 5.2 采用了没有明确参数 thinking 的自适应思维。 此示例省略了output_config.effort,以使用提供程序默认值high。
curl -X POST "https://<workspace_host>/ai-gateway/anthropic/v1/messages" \
-H "Authorization: Bearer $DATABRICKS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "system.ai.claude-fable-5-2",
"max_tokens": 2048,
"messages": [
{
"role": "user",
"content": "Why is the sky blue?"
}
]
}'
Claude Fable 5.1 模型示例
Claude Fable 5.1 始终采用适应性思维。 将 output_config.effort 设置为 low、medium、high、xhigh 或 max,以控制推理深度。
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
reasoning_effort GPT-5.1 的参数默认初始化为none,但在请求中可以覆盖此设置。 更高的推理工作量可能会导致更周到和准确的响应,但可能会增加延迟和令牌使用。
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"
}'
GPT OSS 模型示例
参数 reasoning_effort 接受 "low"、 "medium" (默认值)或 "high" 值。 更高的推理工作量可能会导致更周到和准确的响应,但可能会增加延迟和令牌使用。
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"
}'
Gemini 4 Carbon 模型示例
本例使用 system.ai.gemini-4-carbon ,令 reasoning_effort 为 "high"。 如果省略参数,模型会使用 "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.gemini-4-carbon",
messages=[{"role": "user", "content": "Why is the sky blue?"}],
max_tokens=2000,
reasoning_effort="high",
)
print(response.choices[0].message.content)
Gemini 4 Argon 模型示例
本例使用 system.ai.databricks-gemini-4-argon ,令 reasoning_effort 为 "high"。 如果省略参数,模型会使用 "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)
Gemini 模型示例
此示例使用 system.ai.gemini-3-1-pro。 参数 reasoning_effort 默认设置为 "low",但可以在请求中覆盖,具体可见以下示例。
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"
}'
API 响应包括思维和文本内容块:
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
)
跨多个轮次管理推理
此部分特定于 databricks-claude-sonnet-4-5 模型。
在多回合对话中,模型只能看到与最后一次助手回合或工具使用会话相关的推理块,并将其视作输入词元。
如果不想将推理令牌传递回模型(例如,不需要它来推理其先前的步骤),可以完全省略推理块。 例如:
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)
但是,如果你确实需要模型来推理其以前的推理过程(例如,如果你正在构建显示其中间推理的体验),则必须包含完整、未经修改的助理消息,包括上一轮次的推理块。 以下内容介绍如何使用完整的助手消息继续线程:
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 API时,推理会作为reasoning条目在响应output中返回。 若要让模型在后续轮次中对其先前的思考继续推理,请在下一个请求的 reasoning 中包含这些 encrypted_content 项,并保持其 input 字段不变。
reasoning响应输出中返回的项具有以下形状:
{
"type": "reasoning",
"id": "rs_abc123",
"content": [{ "type": "reasoning_text", "text": "Let me work through the question..." }],
"encrypted_content": "<opaque-provider-signature>"
}
若要继续对话,请将上一轮的输出放回 input 中,并逐字保留 reasoning 项内容:
{
"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?" }
]
}
该值 encrypted_content 承载提供程序特定的推理状态。 如果它被删除或修改,则模型无法推理其早期思维。 这适用于Anthropic Claude和谷歌双子座模型。
推理模型的工作原理是什么?
推理模型除了标准输入和输出令牌外,还引入了特殊的推理令牌。 这些令牌让模型通过提示“思考”,将其分解,并考虑不同的响应方式。 在此内部推理过程之后,模型会生成其最终答案作为可见输出标记。 某些模型(例如 databricks-claude-sonnet-4-5)向用户显示这些推理令牌,而其他模型(如 OpenAI o 系列)会丢弃它们,并且不会在最终输出中公开它们。