基础模型 REST API 参考
本文提供 Databricks Foundation 模型 API 及其支持的模型的常规 API 信息。 基础模型 API 设计为类似于 OpenAI 的 REST API，以便更轻松地迁移现有项目。 按令牌付费和预配置吞吐量终结点都接受相同的 REST API 请求格式。
终结点
基础模型 API 支持按令牌付费终结点和预配的吞吐量终结点。
每个支持按令牌付费的模型都可以在工作区中使用预配置终结点，用户可以使用 HTTP POST 请求与这些终结点进行交互。 请参阅受支持模型的按令牌付费。
可以使用 API 或服务 UI 创建预配吞吐量终结点。 只要两个服务模型都公开相同的 API 格式，这些终结点支持每个终结点的多个模型进行 A/B 测试。 例如，这两个模型都是聊天模型。 有关终结点配置参数，请参阅 POST /api/2.0/serving-endpoints。
请求和响应使用 JSON，确切的 JSON 结构取决于终结点的任务类型。 聊天和补全终结点支持流式处理响应。
用法
响应包括 usage 子消息，用于报告请求和响应中的令牌数。 此子消息的格式在所有任务类型中都是相同的。
| 字段 | 类型 | 描述 |
|---|---|---|
completion_tokens |
整数 | 生成的令牌数。 不包含在嵌入响应中。 |
prompt_tokens |
整数 | 输入提示中的令牌数。 |
total_tokens |
整数 | 令牌总数。 |
对于像 Meta-Llama-3.3-70B-Instruct 这样的模型，用户提示在传递到模型之前会使用提示模板进行转换。 对于按令牌付费的端点，可能会添加系统提示。 prompt_tokens 包含服务器添加的所有文本。
聊天任务
聊天任务针对与模型进行多轮次对话进行了优化。 模型响应在对话中提供下一条 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。 |
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 |
FunctionCallCompletion | 必需。 模型建议的函数调用。 |
FunctionCallCompletion
| 字段 | 类型 | 描述 |
|---|---|---|
name |
字符串 | 必填。 模型建议的函数的名称。 |
arguments |
对象 | 必填。 调用函数时的参数是一个序列化的 JSON 字典。 |
ToolChoiceObject
请参阅 Azure Databricks 上的函数调用。
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 工具的类型。 目前仅支持 "function"。 |
function |
对象 | 必需。 一个对象，用于定义要调用表单 {"type": "function", "function": {"name": "my_function"}} 的工具，其中 "my_function 是 tools 字段中 FunctionObject 的名称。 |
ToolObject
请参阅 Azure Databricks 上的函数调用。
| 字段 | 类型 | 描述 |
|---|---|---|
type |
字符串 | 必需。 工具的类型。 目前仅支持 function。 |
function |
FunctionObject | 必需。 与该工具关联的函数定义。 |
FunctionObject
| 字段 | 类型 | 描述 |
|---|---|---|
name |
字符串 | 必需。 要调用的函数的名称。 |
description |
对象 | 必需。 函数的详细说明。 模型使用此说明来了解函数与提示的相关性，并生成具有更高准确度的工具调用。 |
parameters |
对象 | 函数接受的参数，描述为有效的 JSON 架构 对象。 如果调用该工具，则工具调用适合提供的 JSON 架构。 省略参数定义不带任何参数的函数。 properties 数限制为 15 个密钥。 |
strict |
布尔值 | 生成函数调用时是否启用严格的架构遵循。 如果设置为 true，则模型遵循架构字段中定义的确切架构。 在严格为 true 时，仅支持一部分 JSON 模式 |
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，则模型遵循架构字段中定义的确切架构。 当 strict 为 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 |
字符串 | 模型停止生成令牌的原因。 |
ChatCompletionChunk
| 字段 | 类型 | 描述 |
|---|---|---|
index |
整数 | 生成的选项列表中的所选索引。 |
delta |
ChatMessage | 模型生成的流式处理响应一个的聊天补全消息部分。 只能保证在第一个区块中填充 role。 |
finish_reason |
字符串 | 模型停止生成令牌的原因。 只会在最后一个区块中填充此信息。 |
补全任务
文本完成任务用于生成对单个提示的响应。 与聊天不同，此任务支持批量输入：可以在一个请求中发送多个独立提示。 有关查询终结点参数的信息，请参阅 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 |
[] | 字符串 或 列表[字符串] | 遇到 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 |
字符串 | 模型停止生成令牌的原因。 |
嵌入任务
嵌入任务将输入字符串映射到嵌入向量中。 可以在每个请求中对许多输入进行批处理。 有关查询终结点参数的信息，请参阅 POST /serving-endpoints/{name}/invocations。
嵌入请求
| 字段 | 类型 | 描述 |
|---|---|---|
input |
字符串 或 列表[字符串] | 必需。 要嵌入的输入文本。 可以是字符串或字符串列表。 |
instruction |
字符串 | 传递给嵌入模型的可选指令。 |
说明是可选且高度特定于模型的。 例如，BGE 作者在为区块编制索引时建议没有指令，并建议使用指令 "Represent this sentence for searching relevant passages:" 进行检索查询。 其他模型（如 Instructor-XL）支持各种指令字符串。
嵌入响应
| 字段 | 类型 | 描述 |
|---|---|---|
id |
字符串 | 嵌入的唯一标识符。 |
object |
字符串 | 对象类型。 等于 "list"。 |
model |
字符串 | 用于创建嵌入的嵌入模型的名称。 |
data |
嵌入对象 | 嵌入对象。 |
usage |
使用情况 | 令牌使用情况元数据。 |
EmbeddingObject
| 字段 | 类型 | 描述 |
|---|---|---|
object |
字符串 | 对象类型。 等于 "embedding"。 |
index |
整数 | 模型生成的嵌入列表中的嵌入索引。 |
embedding |
List[Float] | 嵌入矢量。 每个模型将返回固定大小矢量 （1024 for BGE-Large） |