查询推理模型

在本文中,你将学习如何为针对推理任务优化的基础模型编写查询请求,这些模型由 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 配合使用:
  • thinking:将type设置为adaptive以使用推理,或设为disabled以禁用它。
  • output_config.effort:接受 low, medium或 high。 当你省略此参数时,Databricks 会默认设为 medium。 其他值,包括 none、 xhigh和 max,则被拒绝。
仅推理 该模型对每个请求使用自适应思维,推理无法被禁用。 databricks-claude-opus-5-5 使用以下参数与 Anthropic Messages API 配合使用:
  • thinking:将 type 设置为 adaptive。 禁用思考的设置和手动指定的 budget_tokens 值会被拒绝。
  • output_config.effort:接受 low、 medium、 high、 xhigh或 max。 当你省略此参数时,Databricks 会默认设为 medium。 其他值,包括 none 和 disabled,则被拒绝。
仅推理 该模型始终使用适应性思维,推理能力无法被剥夺。 通过 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 配合使用:
  • thinking:将 type 设置为 adaptive。
  • output_config.effort:接受 low、 medium、 high、 xhigh或 max。 Databricks 不设置默认值;Anthropic 会在你省略该参数时使用high。 其他值,包括 none,则被拒绝。
混合推理 这些模型支持适应性思维以实现更深层次的推理。 databricks-claude-opus-5、 databricks-claude-opus-4-8和 databricks-claude-opus-4-7 使用以下参数与 Anthropic Messages API 配合使用:
  • thinking:将 type 设置为 adaptive。 将 type 设置为 enabled 且使用 budget_tokens 的请求会被 HTTP 400 错误拒绝。
  • output_config.effort:控制推理深度。
混合推理 支持快速、即时答复和更深层次的推理(如果需要)。
  • 克劳德模型,如databricks-claude-sonnet-4-6,databricks-claude-sonnet-4-5,databricks-claude-opus-4-6databricks-claude-opus-4-5和databricks-claude-opus-4-1。
  • databricks-deepseek-v4-1-flash-1017
  • databricks-deepseek-v4-1-flash
参数因型号而异:
  • 对于 Claude 模型,使用 thinking 和 budget_tokens。 该 budget_tokens 参数控制模型可用于内部思考的词元数量。 较高的预算可以提高复杂任务的质量,但超过 32K 的使用量可能会有所不同。 budget_tokens 必须小于 max_tokens。 budget_tokens 已弃用,改用 databricks-claude-sonnet-4-6 和 databricks-claude-opus-4-6。 对于这些模型,Databricks 建议采用自适应思维:将thinking.type设置为adaptive,并使用output_config.effort来控制推理深度。
  • 对于 DeepSeek V4.1 Flash 和 DeepSeek V4.1 Flash(1017),reasoning_effort 接受 "low"、"high"、"xhigh" 或 "max"(默认)。 "minimal" 映射到 "low",映射 "medium" 到 "high"。 "none" 或者 "disabled" 使推理失效。 其他价值观被拒绝。
仅推理 这些模型始终在其响应中使用内部推理。 GPT OSS 模型,如 databricks-gpt-oss-120b 和 databricks-gpt-oss-20b。 在请求中使用以下参数:
  • reasoning_effort:接受值 "low"、 "medium" (默认值)或 "high"。 更高的推理工作量可能会导致更周到和准确的响应,但可能会增加延迟和令牌使用。 此参数仅接受一组有限的模型,包括 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 系列)会丢弃它们,并且不会在最终输出中公开它们。

其他资源