使用开放响应 API 查询模型

本文介绍如何使用 开放响应 API 查询基础模型，并介绍在执行此操作时要考虑的提供程序特定行为。

Open Responses API 是一种开放的、支持多提供方的 Responses 风格请求格式实现。 它使用字段 input 而不是 messages 返回结构化 output 数组。 将请求发送到/serving-endpoints/open-responses路径，并在请求正文的model字段中填写模型服务端点名称。

注意

对于 OpenAI 模型，请直接使用 OpenAI 响应 API 。 该路径是原生透传，并支持 OpenAI Responses 的全部参数和工具。 本文介绍开放响应 API，该 API 适用于跨提供程序，但支持重点功能集。

查询示例

以下示例使用 Open Responses API 查询基础模型终结点。

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "databricks-claude-sonnet-4-5",
    "input": [
      {
        "role": "user",
        "content": "What is a mixture of experts model?"
      }
    ],
    "max_output_tokens": 256
  }' \
  https://<workspace_host>.databricks.com/serving-endpoints/open-responses

响应是一个response对象，其中包含一个output数组。 对于流式处理请求（stream: true），响应是 text/event-stream 每个事件都是一个响应区块。

提供程序特有的行为

Databricks 会将 Open Responses 请求转换为各提供程序的原生格式。 对于大多数请求，其行为是一致的，但以下提供程序特有的差异仍然存在。

所有提供方

  • 对话是无状态的。 previous_response_id 和服务器端对话存储均不受支持。 在每个轮次的 input 字段中发送完整对话。
  • 某些 OpenAI 特有字段会被接受，但对于非 OpenAI 提供商会被忽略 user、safety_identifier、metadata 和 truncation 等字段会在响应中返回，以确保可移植性，但不会改变提供程序的行为。

Databricks 托管的（开源）模型

  • 功能支持情况因型号而异。 每个模型都启用了函数调用、推理、结构化输出和图像输入。 使用模型不支持的功能的请求返回错误。 例如，支持推理的模型可能不支持图像输入。
  • 图像输入必须是 URL 或数据 URI。 通过 image_url 以 https URL 或 data: URI 的形式提供图像。 不支持文件引用（file_id）和文档输入（input_file）。

人类 Claude 模型

  • 温度采用 0–2 刻度。 Claude 使用原生的 0–1 范围，因此 Databricks 会将该值减半进行缩放——temperature: 1.0 的行为类似于 0.5。
  • 推理在多个对话轮次间往返。 为了让模型在多轮对话中基于其先前的思考进行推理，请将返回的 reasoning 项（其 encrypted_content 保持不变）在下一条请求的 input 中发回。 请参阅 查询推理模型。
  • 图像和文档输入必须是 base64 数据 URI。 通过 image_url 以 base64 data: URI 的形式提供图像，并通过 file_data 以 base64 data: URI 的形式提供文档。 https 不支持 URL 和 file_id 引用。
  • 结构化输出具有约束。 text.format 支持 json_schema 类型，但不支持 json_object，并会返回错误。 结构化输出不能与流式处理或推理相结合，在使用时不能固定 tool_choice 到特定工具。 请参阅Azure Databricks 上的结构化输出。
  • 推理令牌 计入 usage.output_tokens，而不是单独列出。

Google Gemini 模型

  • 温度采用 0–2 刻度。 Gemini 使用原生的 0–1 范围，因此 Databricks 会通过将该值减半来重新缩放——temperature: 1.0 的行为类似于 0.5。
  • 推理在多个对话轮次间往返。 为了让模型在多轮对话中基于其先前的思考进行推理，请将返回的 reasoning 项（其 encrypted_content 保持不变）在下一条请求的 input 中发回。 请参阅 查询推理模型。
  • 图像输入接受 https URL 和 base64 数据 URI。
  • 推理标记 显示在 usage.output_tokens_details.reasoning_tokens 中。

Important

使用 Gemini 的多轮次工具调用需要保留 encrypted_content。 对于其生成的每个encrypted_content项，Gemini 都会返回一个function_call值。 将工具结果发送回下一轮时，必须包含原始 function_call 项，其 encrypted_content 字段保持不变。 仅根据 name、arguments 和 call_id 重构工具调用的代理框架会丢弃该字段，从而导致后续请求被拒绝。

以下示例展示了在返回工具结果时如何保留 function_call 项（及其 encrypted_content）：

{
  "model": "databricks-gemini-2-5-pro",
  "input": [
    { "role": "user", "content": "What's the weather in San Francisco?" },
    {
      "type": "function_call",
      "call_id": "call_abc123",
      "name": "get_weather",
      "arguments": "{\"city\": \"San Francisco\"}",
      "encrypted_content": "<opaque-provider-signature>"
    },
    {
      "type": "function_call_output",
      "call_id": "call_abc123",
      "output": "{\"temp_f\": 64}"
    }
  ]
}

Tools

Open Responses API 支持跨提供程序的 function 类型工具。 有关详细信息和支持的模型，请参阅对Azure Databricks调用函数。 有关 Web 搜索内置工具，请参阅 Azure Databricks 上的 Web 搜索。

其他内置和自定义工具类型（例如custom，apply_patchimage_generation和mcp）只能通过 OpenAI 响应 API 使用。

支持的模型

Open Responses API 适用于 Databricks 基础模型，包括 Anthropic Claude、Google Gemini 和 Databricks 托管的开放模型，并支持扩展到未来的新模型。 有关可用模型的当前列表，请参阅 基础模型类型。

功能支持（如函数调用、推理、结构化输出和图像输入）取决于基础模型。 请参阅 提供程序特定的行为。

支持的输入类型

输入支持取决于模型和提供程序。 所有模型都支持文本输入。 有关图像输入，请参阅 特定于提供程序的行为中的各提供程序说明，以及 查询视觉模型中的格式和大小要求。 有关每模型输入类型，请参阅 基础模型 API 中提供的 Databricks 托管的基础模型。

其他资源

  • Last updated on