基础模型 REST API 参考

项目
11/02/2024

本文提供有关 Databricks 基础模型 API 及其支持的模型的一般 API 信息。基础模型 API 在设计上类似于 OpenAI 的 REST API，但可以更轻松地迁移现有项目。按标记付费和预配吞吐量终结点都接受相同的 REST API 请求格式。

端点

每个按令牌付费模型都有一个终结点，用户可以使用 HTTP POST 请求与这些终结点交互。可以使用 API 或服务 UI 创建预配吞吐量终结点。只要两个所服务模型都公开相同的 API 格式，那么这些终结点也支持在每个终结点使用多个模型进行 A/B 测试。例如，两个模型都是聊天模型。

请求和响应使用 JSON，确切的 JSON 结构取决于终结点的任务类型。聊天和完成终结点支持流式处理响应。

按令牌付费的工作负载支持某些模型，有关这些模型和接受的 API 格式，请参阅支持的按令牌付费模型。

使用情况

响应包含用于报告请求和响应中令牌数的 usage 子消息。此子消息的格式在所有任务类型中都是相同的。

字段	类型	说明
`completion_tokens`	Integer	生成的标记数。不包含在嵌入响应中。
`prompt_tokens`	Integer	输入提示中的令牌数。
`total_tokens`	Integer	标记总数。

对于 llama-2-70b-chat 之类的模型，在将用户提示传递到模型之前，将使用提示模板将其进行转换。对于按标记付费终结点，系统提示也可能会添加。 prompt_tokens 包含服务器添加的所有文本。

聊天任务

聊天任务已针对与模型进行多回合对话进行优化。每个请求将描述到目前为止的对话，其中 messages 字段必须在 user 和 assistant 角色之间交替，以 user 消息结尾。模型响应在对话中提供下一条 assistant 消息。

聊天请求

字段	默认	类型	描述
`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_schemajson_object` `{ "type": "json_schema", "json_schema": {...} }` 设置为启用结构化输出，确保模型遵循提供的 JSON 架构。 `{ "type": "json_object" }`用于确保模型生成的响应是有效的 JSON 的设置，但不确保响应遵循特定的架构。
`logprobs`	`false`	布尔	此参数指示是否提供某个令牌被抽取采样的对数概率。
`top_logprobs`	`null`	Integer	此参数控制每个采样步骤中最有可能的令牌候选项的数量，以返回对数概率。可能的值为 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`	Object	必需。作为序列化 JSON 字典的函数的参数。

`ToolChoiceObject`

请参阅Azure Databricks 上的函数调用。

字段	类型	说明
`type`	字符串	必需。工具的类型。目前仅支持 `"function"`。
`function`	Object	必需。一个对象，用于定义要调用表单`{"type": "function", "function": {"name": "my_function"}}`的工具，其中`"my_function`是`tools`字段中的FunctionObject名称。

`ToolObject`

请参阅Azure Databricks 上的函数调用。

字段	类型	说明
`type`	字符串	必需。工具的类型。目前仅支持 `function`。
`function`	FunctionObject	必需。与该工具关联的函数定义。

`FunctionObject`

字段	类型	说明
`name`	字符串	必需。要调用的函数的名称。
`description`	Object	必需。函数的详细说明。模型使用此说明来了解函数与提示的相关性，并生成准确度更高的工具调用。
`parameters`	Object	函数接受的参数，描述为有效的 JSON 架构对象。如果调用该工具，则工具调用适合提供的 JSON 架构。省略参数会定义无任何参数的函数。 `properties`数限制为 15 个密钥。
`strict`	布尔	生成函数调用时是否启用严格的架构遵循。如果设置为 `true`，则模型遵循架构字段中定义的确切架构。严格时仅支持 JSON 架构的子集 `true`

`ResponseFormatObject`

请参阅 Azure Databricks 上的结构化输出。

字段	类型	说明
`type`	字符串	必需。要定义的响应格式的类型。 `text`对于非结构化文本、`json_object`非结构化 JSON 对象或`json_schema`符合特定架构的 JSON 对象。
`json_schema`	JsonSchemaObject	必需。要遵循的 JSON 架构（如果 `type` 设置为） `json_schema`

`JsonSchemaObject`

请参阅 Azure Databricks 上的结构化输出。

字段	类型	说明
`name`	字符串	必需。响应格式的名称。
`description`	字符串	对响应格式用途的描述，由模型用于确定如何以该格式进行响应。
`schema`	Object	必需。响应格式的架构，描述为 JSON 架构对象。
`strict`	布尔	生成输出时是否启用严格的架构遵循。如果设置为 `true`，则模型遵循架构字段中定义的确切架构。严格时仅支持 JSON 架构的子集 `true`

聊天响应

对于非流式处理请求，响应是单个聊天完成对象。对于流式处理请求，响应是一个 text/event-stream，其中每个事件是一个完成区块对象。完成和区块对象的顶级结构几乎完全相同：只有 choices 具有不同的类型。

字段	类型	说明
`id`	字符串	聊天完成的唯一标识符。
`choices`	List[ChatCompletionChoice] 或 List[ChatCompletionChunk]（流式处理）	聊天补全文本的列表。如果指定了 `n` 参数，则返回 `n` 个选项。
`object`	字符串	对象类型。等于非流式处理的 `"chat.completions"` 或流式处理的 `"chat.completion.chunk"`。
`created`	Integer	生成聊天完成的时间（以秒为单位）。
`model`	字符串	用于生成响应的模型版本。
`usage`	使用情况	标记使用情况元数据。流式处理响应中可能不存在。

`ChatCompletionChoice`

字段	类型	说明
`index`	Integer	生成的选项列表中的所选索引。
`message`	ChatMessage	模型返回的聊天完成消息。角色为 `assistant`。
`finish_reason`	字符串	模型停止生成标记的原因。

`ChatCompletionChunk`

字段	类型	说明
`index`	Integer	生成的选项列表中的所选索引。
`delta`	ChatMessage	模型生成的流式处理响应的聊天完成消息部分。只能保证在第一个区块中填充 `role`。
`finish_reason`	字符串	模型停止生成标记的原因。只会在最后一个区块中填充此信息。

完成任务

文本完成任务用于生成对单个提示的响应。与聊天不同，此任务支持批量输入：可以在一个请求中发送多个独立提示。

完成请求

字段	默认	类型	描述
`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`	Integer	请求中提示的索引。
`text`	字符串	生成的完成。
`finish_reason`	字符串	模型停止生成标记的原因。

嵌入任务

嵌入任务将输入字符串映射到嵌入矢量。可以在每个请求中对许多输入进行批处理。

嵌入请求

字段	类型	描述
`input`	String 或 List[String]	必需。要嵌入的输入文本。可以是字符串或字符串列表。
`instruction`	字符串	传递给嵌入模型的可选指令。

指令是可选的，在很大程度上特定于模型。例如，BGE 作者在为区块编制索引时不建议使用指令，但建议使用指令 "Represent this sentence for searching relevant passages:" 执行检索查询。其他模型（如 Instructor-XL）支持各种指令字符串。

嵌入响应

字段	类型	说明
`id`	字符串	嵌入的唯一标识符。
`object`	字符串	对象类型。等于 `"list"`。
`model`	字符串	用于创建嵌入的嵌入模型的名称。
`data`	EmbeddingObject	嵌入对象。
`usage`	使用情况	标记使用情况元数据。

`EmbeddingObject`

字段	类型	说明
`object`	字符串	对象类型。等于 `"embedding"`。
`index`	整数	模型生成的嵌入列表中的嵌入索引。
`embedding`	List[Float]	嵌入矢量。每个模型将返回固定大小的矢量（对于 BGE-Large 为 1024）

通过