本文提供 Databricks Foundation 模型 API 及其支持的模型的常规 API 信息。 基础模型 API 设计为类似于 OpenAI 的 REST API，以便更轻松地迁移现有项目。 按令牌付费和预配置吞吐量终结点都接受相同的 REST API 请求格式。
终结点
基础模型 API 支持按令牌付费终结点和预配的吞吐量终结点。
每个支持按令牌付费的模型都可以在工作区中使用预配置终结点，用户可以使用 HTTP POST 请求与这些终结点进行交互。 有关支持的基础模型，请参阅马赛克 AI 模型服务的支持的模型。
可以使用 API 或服务 UI 创建预配吞吐量终结点。 只要两个服务模型都公开相同的 API 格式，这些终结点支持每个终结点的多个模型进行 A/B 测试。 例如，这两个模型都是聊天模型。 有关终结点配置参数，请参阅 POST /api/2.0/serving-endpoints。
请求和响应使用 JSON，确切的 JSON 结构取决于终结点的任务类型。 聊天和补全终结点支持流式处理响应。
用法
响应包括 usage 子消息，用于报告请求和响应中的令牌数。 此子消息的格式在所有任务类型中都是相同的。
| 字段 | 类型 | 描述 |
|---|---|---|
completion_tokens |
整数 | 生成的令牌数。 不包含在嵌入响应中。 |
prompt_tokens |
整数 | 输入提示中的令牌数。 |
total_tokens |
整数 | 令牌总数。 |
reasoning_tokens |
整数 | 思考令牌的数量。 它仅适用于推理模型。 |
对于像 databricks-meta-llama-3-3-70b-instruct 这样的模型，用户提示在传递到模型之前会使用提示模板进行转换。 对于按令牌付费的端点，可能会添加系统提示。
prompt_tokens 包含服务器添加的所有文本。
响应 API
重要
响应 API 仅与 OpenAI 模型兼容。
响应 API 支持与模型进行多轮次对话。 与聊天完成不同，响应 API 使用 input 而不是 messages。
响应 API 请求
| 字段 | 违约 | 类型 | 描述 |
|---|---|---|---|
model |
字符串 | 必需。 用于生成响应的模型 ID。 | |
input |
字符串或列表[ResponsesInput] | 必需。 用于生成响应的模型的文本、图像或文件输入。 与messages不同，此字段使用input指定对话内容。 |
|
instructions |
null |
字符串 | 插入到模型上下文中的系统（或开发人员）消息。 |
max_output_tokens |
null |
null，这意味着没有限制或大于零的整数 |
可为响应生成的令牌数上限，包括可见输出令牌和推理令牌。 |
temperature |
1.0 |
[0,2] 范围内的浮点数 | 采样温度。 0 是确定性的，较高的值引入了更多的随机性。 |
top_p |
1.0 |
(0,1] 范围内的浮点数 | 用于核采样的概率阈值。 |
stream |
false |
布尔 | 如果设置为 true，模型响应数据将流式传输到客户端，因为它使用服务器发送的事件生成。 |
stream_options |
null |
StreamOptions | 流式处理响应的选项。 仅在设置 stream: true 时设置此项。 |
text |
null |
TextConfig | 来自模型的文本响应的配置选项。 可以是纯文本或结构化 JSON 数据。 |
reasoning |
null |
ReasoningConfig | gpt-5 和 o 系列模型的推理配置。 |
tool_choice |
"auto" |
字符串或 ToolChoiceObject | 模型在生成响应时应如何选择要使用的工具（或工具）。 请参阅参数 tools ，了解如何指定模型可以调用的工具。 |
tools |
null |
列表[ToolObject] | 生成响应时，模型可能会调用的工具数组。 注意：Databricks 不支持代码解释器和 Web 搜索工具。 |
parallel_tool_calls |
true |
布尔 | 是否允许模型并行运行工具调用。 |
max_tool_calls |
null |
大于零的整数 | 响应中可以处理的内置工具的最大调用次数。 |
metadata |
null |
对象 | 按 16 个成组的可附加到对象的键值对。 |
prompt_cache_key |
null |
字符串 | 用于缓存类似请求的响应，以优化缓存命中率。 替换 user 字段。 |
prompt_cache_retention |
null |
字符串 | 提示缓存的保留策略。 将"24h"设置为启用扩展提示缓存，使缓存前缀保持活动状态更长，最长可达24小时。 |
safety_identifier |
null |
字符串 | 用于帮助检测可能违反使用策略的应用程序的用户的稳定标识符。 |
user |
null |
字符串 |
已弃用。 请改用 safety_identifier 和 prompt_cache_key。 |
truncation |
null |
字符串 | 要用于模型响应的截断策略。 |
top_logprobs |
null |
整数 | 一个介于 0 和 20 之间的整数，指定在每个标记位置最有可能返回的的标记数，每个都有关联的对数概率。 |
include |
null |
列表[字符串] | 指定要包含在模型响应中的其他输出数据。 |
prompt |
null |
对象 | 对提示模板及其变量的引用。 |
不支持的参数：Databricks 不支持以下参数，如果指定，将返回 400 错误：
-
background- 不支持后台处理 -
store- 不支持存储的响应 -
conversation- 不支持对话 API -
service_tier- 服务层选择由 Databricks 管理
ResponsesInput
该 input 字段接受包含角色和内容的输入消息对象的字符串或列表。
| 字段 | 类型 | 描述 |
|---|---|---|
role |
字符串 | 必需。 消息作者的角色。 可以是 "user" 或 "assistant"。 |
content |
字符串或列表[ResponsesContentBlock] | 必需。 消息的内容，可以是字符串或内容块数组。 |
ResponsesContentBlock
内容块定义输入和输出消息中内容类型。 内容类型由 type 字段确定。
InputText
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 必须是 "input_text"。 |
text |
字符串 | 必需。 文本内容。 |
OutputText
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 必须是 "output_text"。 |
text |
字符串 | 必需。 文本内容。 |
annotations |
列表[Object] | 文本内容的可选批注。 |
InputImage
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 必须是 "input_image"。 |
image_url |
字符串 | 必需。 图像的 URL 或 base64 编码的数据 URI。 |
InputFile
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 必须是 "input_file"。 |
file_id |
字符串 | 使用上传文件时的文件标识符。 |
filename |
字符串 | 文件的名称。 |
file_data |
字符串 | 带格式前缀的 Base64 编码数据 URI。 例如，PDF 文件使用格式 data:application/pdf;base64,<base64 data>。 |
FunctionCall
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 必须是 "function_call"。 |
id |
字符串 | 必需。 函数调用的唯一标识符。 |
call_id |
字符串 | 必需。 调用标识符。 |
name |
字符串 | 必需。 要调用的函数的名称。 |
arguments |
对象/字符串 | 必需。 函数参数作为 JSON 对象或字符串。 |
FunctionCallOutput
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 必须是 "function_call_output"。 |
call_id |
字符串 | 必需。 此输出所对应的调用标识符。 |
output |
String/Object | 必需。 函数输出为字符串或 JSON 对象。 |
StreamOptions
流式处理响应的配置。 仅当 stream: true 时使用。
| 字段 | 类型 | 描述 |
|---|---|---|
include_usage |
布尔 | 如果为 true，请在流中包含令牌使用情况信息。 默认值为 false。 |
TextConfig
文本输出的配置，包括结构化输出。
| 字段 | 类型 | 描述 |
|---|---|---|
format |
ResponsesFormatObject | 文本输出的格式规范。 |
ResponsesFormatObject
指定文本响应的输出格式。
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 格式的类型： "text" 纯文本、 "json_object" JSON 或 "json_schema" 结构化 JSON。 |
json_schema |
对象 |
需要 当 type 是 "json_schema" 时。 定义输出结构的 JSON 架构对象。 |
该 json_schema 对象具有与聊天完成 API 中记录的 JsonSchemaObject 相同的结构。
ReasoningConfig
推理模型（o 系列和 gpt-5 模型）中推理行为的配置。
| 字段 | 类型 | 描述 |
|---|---|---|
effort |
字符串 | 推理工作级别： "low"， "medium"或 "high"。 默认值为 "medium"。 |
encrypted_content |
字符串 | 无状态模式的加密推理内容。 由模型在以前的响应中提供。 |
ToolObject
请参阅 Azure Databricks 上的函数调用。
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 工具的类型。 目前仅支持 function。 |
function |
FunctionObject | 必需。 与该工具关联的函数定义。 |
FunctionObject
| 字段 | 类型 | 描述 |
|---|---|---|
name |
字符串 | 必需。 要调用的函数的名称。 |
description |
对象 | 必需。 函数的详细说明。 模型使用此说明来了解函数与提示的相关性，并生成具有更高准确度的工具调用。 |
parameters |
对象 | 函数接受的参数，描述为有效的 JSON 架构 对象。 如果调用该工具，则工具调用适合提供的 JSON 架构。 省略参数定义不带任何参数的函数。
properties 数限制为 15 个密钥。 |
strict |
布尔 | 生成函数调用时是否启用严格的架构遵循。 如果设置为 true，则模型遵循架构字段中定义的确切架构。 在严格为 true 时，仅支持一部分 JSON 模式 |
ToolChoiceObject
请参阅 Azure Databricks 上的函数调用。
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 工具的类型。 目前仅支持 "function"。 |
function |
对象 | 必需。 一个对象，用于定义要调用表单 {"type": "function", "function": {"name": "my_function"}} 的工具，其中 "my_function 是 字段中 tools 的名称。 |
API 的响应
对于非流式处理请求，响应是单个响应对象。 对于流式处理请求，响应是 text/event-stream 每个事件都是响应区块。
| 字段 | 类型 | 描述 |
|---|---|---|
id |
字符串 | 响应的唯一标识符。 注意：Databricks 将此 ID 加密为安全性。 |
object |
字符串 | 对象类型。 等于 "response"。 |
created_at |
整数 | 创建响应时，Unix 时间戳（以秒为单位）。 |
status |
字符串 | 响应的状态。 之一：completed、、failed、in_progresscancelled、、queued或incomplete。 |
model |
字符串 | 用于生成响应的模型版本。 |
output |
列表[ResponsesMessage] | 模型生成的输出，通常包含消息对象。 |
usage |
使用情况 | 令牌使用情况元数据。 |
error |
Error | 响应失败时的错误信息。 |
incomplete_details |
详细信息不完整 | 有关响应为何不完整（如果适用）的详细信息。 |
instructions |
字符串 | 请求中提供的说明。 |
max_output_tokens |
整数 | 请求中指定的最大输出令牌。 |
temperature |
漂浮 | 用于生成的温度。 |
top_p |
漂浮 | 用于生成的 top_p 参数值。 |
tools |
列表[ToolObject] | 请求中指定的工具。 |
tool_choice |
字符串或 ToolChoiceObject | 请求中的tool_choice设置。 |
parallel_tool_calls |
布尔 | 是否启用了并行工具调用。 |
store |
布尔 | 响应是否已存储。 |
metadata |
对象 | 附加到响应的元数据。 |
ResponsesMessage
在output字段中包含模型响应内容的消息对象。
| 字段 | 类型 | 描述 |
|---|---|---|
id |
字符串 | 必需。 邮件的唯一标识符。 |
role |
字符串 | 必需。 消息的角色。
"user" 或 "assistant"。 |
content |
列表[ResponsesContentBlock] | 必需。 消息中的内容块。 |
status |
字符串 | 消息处理的状态。 |
type |
字符串 | 必需。 对象类型。 等于 "message"。 |
Error
响应失败时的错误信息。
| 字段 | 类型 | 描述 |
|---|---|---|
code |
字符串 | 必需。 错误代码。 |
message |
字符串 | 必需。 用户可读的错误消息。 |
param |
字符串 | 导致错误的参数（如果适用）。 |
type |
字符串 | 必需。 错误类型。 |
IncompleteDetails
有关响应不完整的原因的详细信息。
| 字段 | 类型 | 描述 |
|---|---|---|
reason |
字符串 | 必需。 响应不完整的原因。 |
聊天完成 API
聊天完成 API 支持使用模型进行多轮次对话。 模型响应在对话中提供下一条 assistant 消息。 有关查询终结点参数的信息，请参阅 POST /serving-endpoints/{name}/invocations。
聊天请求
| 字段 | 违约 | 类型 | 描述 |
|---|---|---|---|
messages |
ChatMessage 列表 | 必需。 表示当前对话的消息列表。 | |
max_tokens |
null |
null，这意味着没有限制或大于零的整数 |
要生成的令牌的最大数目。 |
stream |
true |
布尔 | 将响应流式传回客户端，以允许请求的部分结果。 如果请求中包含此参数，则使用 服务器发送的事件 标准发送响应。 |
temperature |
1.0 |
[0,2] 范围内的浮点数 | 采样温度。 0 是确定性的，较高的值引入了更多的随机性。 |
top_p |
1.0 |
(0,1] 范围内的浮点数 | 用于核采样的概率阈值。 |
top_k |
null |
null，这意味着没有限制或大于零的整数 |
定义用于 top-k 筛选的 k 个最可能标记的数目。 将此值设置为 1 以使输出确定性。 |
stop |
[] | String 或 List[String] | 遇到 stop 中的任何一个序列时，模型将停止生成进一步的标记。 |
n |
1 | 大于零的整数 | 指定了 n 时，API 将返回 n 个独立的聊天补全。 建议用于在同一输入上生成多个输出的工作负载，以提高推理效率并降低成本。 仅适用于预配的吞吐量终结点。 |
tool_choice |
none |
字符串或 ToolChoiceObject | 只能与 tools 一起使用。
tool_choice 支持各种关键字字符串，例如 auto、required和 none。
auto 意味着你正在让模型决定哪个（如果有）工具与使用相关。 如果 auto 模型不相信其中的任何工具 tools 都相关，模型将生成标准助理消息，而不是工具调用。
required 意味着模型选取 tools 中最相关的工具，并且必须生成工具调用。
none 意味着模型不会生成任何工具调用，而必须生成标准助理消息。 若要对 tools 中定义的特定工具强制执行工具调用，请使用 ToolChoiceObject。 默认情况下，如果 tools 字段填充 tool_choice = "auto"。 否则，tools 字段默认为 tool_choice = "none" |
tools |
null |
ToolObject | 模型可以调用的 tools 列表。 目前，function 是唯一受支持的 tool 类型，最多支持 32 个函数。 |
response_format |
null |
ResponseFormatObject | 一个对象，指定模型必须输出的格式。 接受的类型为 text、json_schema 或 json_object设置为 { "type": "json_schema", "json_schema": {...} } 启用结构化输出，确保模型遵循提供的 JSON 架构。设置为 { "type": "json_object" } 可确保模型生成的响应是有效的 JSON，但不确保响应遵循特定的架构。 |
logprobs |
false |
布尔 | 此参数指示是否提供正在采样的令牌的对数概率。 |
top_logprobs |
null |
整数 | 此参数用于控制最有可能的令牌候选项的数目，以在每个抽样步骤返回日志概率。 可以是 0-20。 如果使用此字段，logprobs 必须是 true。 |
reasoning_effort |
"medium" |
字符串 | 控制生成响应时模型应应用的推理工作量级别。 接受的值是 "low"， "medium"或 "high"。 更高的推理工作量可能会导致更周到和准确的响应，但可能会增加延迟和令牌使用。 此参数仅接受一组有限的模型，包括 databricks-gpt-oss-120b 和 databricks-gpt-oss-20b。 |
ChatMessage
| 字段 | 类型 | 描述 |
|---|---|---|
role |
字符串 | 必需。 消息作者的角色。 可以是 "system"、"user"、"assistant" 或 "tool"。 |
content |
字符串 | 消息的内容。 对于不涉及工具调用的聊天任务是必需项。 |
tool_calls |
ToolCall 列表 | 模型生成的 tool_calls 列表。 必须将 role 作为 "assistant"，并且对 content 字段没有规范。 |
tool_call_id |
字符串 | 当 role 为 "tool" 时，与消息正在响应的 ToolCall 关联的 ID。 对于其他 role 选项，必须为空。 |
system 角色只能用作对话中的第一条消息一次。 它会替代默认的模型系统提示符。
ToolCall
模型提供的工具调用操作建议。 请参阅 Azure Databricks 上的函数调用。
| 字段 | 类型 | 描述 |
|---|---|---|
id |
字符串 | 必需。 此工具调用建议的唯一标识符。 |
type |
字符串 | 必需。 仅支持 "function"。 |
function |
函数调用完成 | 必需。 模型建议的函数调用。 |
cache_control |
字符串 | 启用请求的缓存功能。 此参数仅由 Databricks 托管的 Claude 模型接受。 有关示例，请参阅 提示缓存 。 |
FunctionCallCompletion
| 字段 | 类型 | 描述 |
|---|---|---|
name |
字符串 | 必填。 模型建议的函数的名称。 |
arguments |
对象 | 必填。 调用函数时的参数是一个序列化的 JSON 字典。 |
注意：ToolChoiceObject，ToolObject并在FunctionObject“响应 API”部分中定义，并在两个 API 之间共享。
ResponseFormatObject
请参阅 Azure Databricks 上的结构化输出。
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 要定义的响应格式的类型。 非结构化文本 text、非结构化 JSON 对象 json_object，或遵循特定架构的 JSON 对象 json_schema。 |
json_schema |
JsonSchemaObject | 必需。
type 设置为 json_schema 时要遵循的 JSON 模式 |
JsonSchemaObject
请参阅 Azure Databricks 上的结构化输出。
| 字段 | 类型 | 描述 |
|---|---|---|
name |
字符串 | 必需。 响应格式的名称。 |
description |
字符串 | 对响应格式用途的描述，由模型用于确定如何以该格式进行响应。 |
schema |
对象 | 必需。 响应格式的架构，描述为 JSON 架构对象。 |
strict |
布尔 | 是否在生成输出时启用严格的架构遵循。 如果设置为 true，则模型遵循架构字段中定义的确切架构。 在严格为 true 时，仅支持一部分 JSON 模式 |
聊天响应
对于非流式处理请求，响应是单个聊天补全对象。 对于流式处理请求，响应是一个 text/event-stream，其中每个事件是一个完成区块对象。 补全和区块对象的顶级结构几乎完全相同：只有 choices 具有不同的类型。
| 字段 | 类型 | 描述 |
|---|---|---|
id |
字符串 | 聊天补全的唯一标识符。 |
choices |
List[ChatCompletionChoice] 或 List[ChatCompletionChunk]（流式处理） | 聊天补全文本的列表。 如果指定了 n 参数，则返回 n 选项。 |
object |
字符串 | 对象类型。 等于 "chat.completions"（对于非流式处理）或 "chat.completion.chunk"（对于流式处理）。 |
created |
整数 | 生成聊天补全的时间（以秒为单位）。 |
model |
字符串 | 用于生成响应的模型版本。 |
usage |
使用情况 | 令牌使用情况元数据。 流式处理响应中可能不存在。 |
ChatCompletionChoice
| 字段 | 类型 | 描述 |
|---|---|---|
index |
整数 | 生成的选项列表中的所选索引。 |
message |
ChatMessage | 模型返回的聊天完成消息。 角色将为 assistant。 |
finish_reason |
字符串 | 模型停止生成令牌的原因。 |
extra_fields |
字符串 | 从外部模型提供程序使用专有模型时，提供程序的 API 可能包括响应中的其他元数据。 Databricks 会筛选这些响应，并仅返回提供程序原始字段的子集。
safetyRating这是目前唯一支持的额外字段，请参阅 Gemini 文档了解更多详细信息。 |
ChatCompletionChunk
| 字段 | 类型 | 描述 |
|---|---|---|
index |
整数 | 生成的选项列表中的所选索引。 |
delta |
ChatMessage | 模型生成的流式处理响应一个的聊天补全消息部分。 只能保证在第一个区块中填充 role。 |
finish_reason |
字符串 | 模型停止生成令牌的原因。 只会在最后一个区块中填充此信息。 |
嵌入式 API
嵌入任务将输入字符串映射到嵌入向量中。 可以在每个请求中对许多输入进行批处理。 有关查询终结点参数的信息，请参阅 POST /serving-endpoints/{name}/invocations。
嵌入请求
| 字段 | 类型 | 描述 |
|---|---|---|
input |
String 或 List[String] | 必需。 要嵌入的输入文本。 可以是字符串或字符串列表。 |
instruction |
字符串 | 传递给嵌入模型的可选指令。 |
说明是可选且高度特定于模型的。 例如，BGE 作者在为区块编制索引时建议不要使用指令，并建议在检索查询中使用指令 "Represent this sentence for searching relevant passages:"。 其他模型（如 Instructor-XL）支持各种指令字符串。
嵌入响应
| 字段 | 类型 | 描述 |
|---|---|---|
id |
字符串 | 嵌入的唯一标识符。 |
object |
字符串 | 对象类型。 等于 "list"。 |
model |
字符串 | 用于创建嵌入的嵌入模型的名称。 |
data |
嵌入对象 | 嵌入对象。 |
usage |
使用情况 | 令牌使用情况元数据。 |
EmbeddingObject
| 字段 | 类型 | 描述 |
|---|---|---|
object |
字符串 | 对象类型。 等于 "embedding"。 |
index |
整数 | 模型生成的嵌入列表中的嵌入索引。 |
embedding |
列表[浮点数] | 嵌入矢量。 每个模型将返回固定大小矢量 （1024 for BGE-Large） |
补全 API
文本完成任务用于生成对单个提示的响应。 与聊天不同，此任务支持批量输入：可以在一个请求中发送多个独立提示。 有关查询终结点参数的信息，请参阅 POST /serving-endpoints/{name}/invocations。
补全请求
| 字段 | 违约 | 类型 | 描述 |
|---|---|---|---|
prompt |
String 或 List[String] | 必需。 提供给模型的提示。 | |
max_tokens |
null |
null，这意味着没有限制或大于零的整数 |
要生成的令牌的最大数目。 |
stream |
true |
布尔 | 将响应流式传回客户端，以允许请求的部分结果。 如果请求中包含此参数，则使用 服务器发送的事件 标准发送响应。 |
temperature |
1.0 |
[0,2] 范围内的浮点数 | 采样温度。 0 是确定性的，较高的值引入了更多的随机性。 |
top_p |
1.0 |
(0,1] 范围内的浮点数 | 用于核采样的概率阈值。 |
top_k |
null |
null，这意味着没有限制或大于零的整数 |
定义用于 top-k 筛选的 k 个最可能标记的数目。 将此值设置为 1 以使输出确定性。 |
error_behavior |
"error" |
"truncate" 或 "error" |
对于超时和超出上下文长度错误。 其中一个："truncate"（返回尽可能多的令牌）和 "error"（返回错误）。 此参数仅适用于按令牌付费的端点。 |
n |
1 | 大于零的整数 | 指定了 n 时，API 将返回 n 个独立的聊天补全。 建议用于在同一输入上生成多个输出的工作负载，以提高推理效率并降低成本。 仅适用于预配的吞吐量终结点。 |
stop |
[] | String 或 List[String] | 遇到 stop 中的任何一个序列时，模型将停止生成进一步的标记。 |
suffix |
"" |
字符串 | 追加到每个补全末尾的字符串。 |
echo |
false |
布尔 | 返回提示以及补全。 |
use_raw_prompt |
false |
布尔 | 如果 true，则直接将 prompt 传递到模型中，而无需进行任何转换。 |
补全响应
| 字段 | 类型 | 描述 |
|---|---|---|
id |
字符串 | 文本补全的唯一标识符。 |
choices |
CompletionChoice | 文本补全列表。 对于传入的每个提示，如果指定了 n，则会生成 n 个选项。 默认 n 为 1。 |
object |
字符串 | 对象类型。 等于 "text_completion" |
created |
整数 | 生成补全的时间（以秒为单位）。 |
usage |
使用情况 | 令牌使用情况元数据。 |
CompletionChoice
| 字段 | 类型 | 描述 |
|---|---|---|
index |
整数 | 请求中提示的索引。 |
text |
字符串 | 生成的补全。 |
finish_reason |
字符串 | 模型停止生成令牌的原因。 |