你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
助手 API（预览版）参考
注意
-
文件搜索可为每个助手最多引入 10,000 个文件 - 比之前多 500 倍。 它速度快，支持通过多线程搜索进行并行查询，并具有增强的重新排序和查询重写功能。
- 矢量存储是 API 中的新对象。 文件一旦添加到矢量存储中，就会自动进行分析、分块和嵌入，以便随时搜索。 矢量存储可跨助手和线程使用，简化了文件管理和计费。
- 我们添加了对
tool_choice参数的支持，该参数可用于在特定运行中强制使用特定工具（如文件搜索、代码解释器或函数）。
本文提供了新助手 API（预览版）的 Python 和 REST 参考文档。 入门指南中提供了更深入的分步指导。
创建助手
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview
使用模型和说明创建助手。
请求正文
| 名称 | 类型 | 必需 | 说明 |
|---|---|---|---|
| model | string | 必须 | 要使用的模型的模型部署名称。 |
| name | string 或 null | 可选 | 助手的名称。 最大长度为 256 个字符。 |
| description | string 或 null | 可选 | 助手的说明。 最大长度为 512 个字符。 |
| instructions | string 或 null | 可选 | 助手使用的系统说明。 最大长度为 256,000 个字符。 |
| 工具 | array | 可选 | 默认值为 []。 在助手上启用的工具列表。 每个助手最多可以有 128 个工具。 工具类型目前可以是 code_interpreter 或 function。
function 说明最多可包含 1,024 个字符。 |
| metadata | map | 可选 | 按 16 个成组的可附加到对象的键值对。 这对以结构化格式存储对象相关的附加信息很有用。 键的最大长度为 64 个字符，值的最大长度为 512 个字符。 |
| 温度 | 数字或 null | 可选 | 默认值为 1。 确定要使用的采样温度，介于 0 和 2 之间。 较高的值（如 0.8）将使输出更随机，而较小的值（如 0.2）将使输出更集中且更具确定性 |
| top_p | 数字或 null | 可选 | 默认值为 1。 温度采样的替代方法，称为核采样，其中模型考虑具有 top_p 概率质量的令牌的结果。 所以 0.1 意味着只考虑包含前 10% 概率质量的令牌。 我们通常建议更改此设置或温度，但不要同时更改这两者。 |
| response_format | 字符串或对象 | 可选 | 指定模型必须输出的格式。 与 GPT-4 Turbo 和自 gpt-3.5-turbo-1106 起的所有 GPT-3.5 Turbo 型号兼容。 将此参数设置为 { "type": "json_object" } 以启用 JSON 模式，这可以保证模型生成的消息是有效的 JSON。 重要的是，使用 JSON 模式时，还必须使用系统或用户消息指示模型自己生成 JSON。 如果没有此指令，模型可能会生成一个无限的空白流，直到生成达到令牌限制，从而导致请求长时间运行，看似“卡滞”。 此外，如果使用 finish_reason="length"，则消息内容可能会部分截断，这表示生成超过了 max_tokens，或者对话超过了最大上下文长度。 |
| tool_resources | 对象 (object) | 可选 | 助手工具使用的一组资源。 资源特定于工具类型。 例如，code_interpreter 工具需要文件 ID 列表，而 file_search 工具需要矢量存储 ID 列表。 |
response_format types
string
默认值为 auto。
object
可能的 type 值：text、json_object、json_schema。
json_schema
| 名称 | Type | 描述 | Default | 必需/可选 |
|---|---|---|---|---|
description |
string | 对响应格式用途的描述，由模型用于确定如何以该格式进行响应。 | 可选 | |
name |
string | 响应格式的名称。 必须是 a-z、A-z、0-9，或包含下划线和短划线，最大长度为 64。 | 必须 | |
schema |
object | 响应格式的架构，描述为 JSON 架构对象。 | 可选 | |
strict |
布尔或 null | 生成输出时是否启用严格的架构遵循。 如果设置为 true，则模型将始终遵循 schema 字段中定义的确切架构。 当 strict 为 true 时仅支持 JSON 架构的子集。 |
false | 可选 |
tool_resources 属性
code_interpreter
| 名称 | Type | 描述 | 默认 |
|---|---|---|---|
file_ids |
array | 可供 code_interpreter 工具使用的文件 ID 列表。 最多可以有 20 个与该工具关联的文件。 | [] |
file_search
| 名称 | Type | 说明 | 必需/可选 |
|---|---|---|---|
vector_store_ids |
array | 附加到此线程的矢量存储。 线程最多可以附加 1 个矢量存储。 | 可选 |
vector_stores |
array | 一个帮助程序，用于创建具有 file_ids 的矢量存储，并将其附加到此线程。 线程最多可以附加 1 个矢量存储。 | 可选 |
vector_stores
| 名称 | Type | 说明 | 必需/可选 |
|---|---|---|---|
file_ids |
array | 要添加到矢量存储的文件 ID 的列表。 一个矢量存储中最多可以有 10000 个文件。 | 可选 |
chunking_strategy |
object | 用于对文件进行分块的分块策略。 如果未设置，则将使用自动策略。 | 可选 |
metadata |
map | 按 16 个成组的可附加到矢量存储的键值对。 这对以结构化格式存储有关矢量存储的附加信息很有用。 键的最大长度为 64 个字符，值的最大长度为 512 个字符。 | 可选 |
chunking_strategy
| 名称 | Type | 说明 | 必需/可选 |
|---|---|---|---|
Auto Chunking Strategy |
object | 默认策略。 此策略目前使用 800 的 max_chunk_size_tokens 和 400 的 chunk_overlap_tokens。
type 始终是 auto |
必须 |
Static Chunking Strategy |
object |
type 始终为 static |
必须 |
静态分块策略
| 名称 | Type | 说明 | 必需/可选 |
|---|---|---|---|
max_chunk_size_tokens |
integer | 每个区块中的最大标记数。 默认值为 800。 最小值为 100，最大值为 4096。 |
必须 |
chunk_overlap_tokens |
integer | 区块之间重叠的标记数。 默认值为 400。 请注意，重叠不得超过 max_chunk_size_tokens 的一半。 |
必须 |
返回
助手对象。
创建助手请求示例
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant = client.beta.assistants.create(
instructions="You are an AI assistant that can write code to help answer math questions",
model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name.
tools=[{"type": "code_interpreter"}]
)
助手列表
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview
返回所有助手的列表。
Query parameters
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
limit |
integer | 可选 | 要返回的对象数的限制。 限制可以介于 1 和 100 之间，默认值为 20。 |
order |
string | 可选 - 默认为 desc | 按对象的 created_at 时间戳顺序。 asc 表示升序，desc 表示降序。 |
after |
string | 可选 | 用于分页的游标。
after 是一个对象 ID，用于定义你在列表中的位置。 例如，如果你发出一个列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo，以提取列表的下一页。 |
before |
string | 可选 | 用于分页的游标。
before 是一个对象 ID，用于定义你在列表中的位置。 例如，如果你发出一个列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 before=obj_foo，以提取列表的上一页。 |
返回
助手对象的列表
列表助手示例
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistants = client.beta.assistants.list(
order="desc",
limit="20",
)
print(my_assistants.data)
检索助手
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview
检索助手。
路径参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
assistant_id |
字符串 | 必须 | 要检索的助手的 ID。 |
返回
与指定 ID 匹配的助手对象。
检索助手示例
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)
修改助手
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview
修改助手。
路径参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
| assistant_id | string | 必须 | 文件所属助手的 ID。 |
请求正文
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
model |
可选 | 要使用的模型的模型部署名称。 | |
name |
string 或 null | 可选 | 助手的名称。 最大长度为 256 个字符。 |
description |
string 或 null | 可选 | 助手的说明。 最大长度为 512 个字符。 |
instructions |
string 或 null | 可选 | 助手使用的系统说明。 最大长度为 32768 个字符。 |
tools |
array | 可选 | 默认值为 []。 在助手上启用的工具列表。 每个助手最多可以有 128 个工具。 工具类型可以是 code_interpreter 或函数。
function 说明最多可包含 1,024 个字符。 |
metadata |
map | 可选 | 按 16 个成组的可附加到对象的键值对。 这对以结构化格式存储对象相关的附加信息很有用。 键的最大长度为 64 个字符，值的最大长度为 512 个字符。 |
temperature |
数字或 null | 可选 | 默认值为 1。 确定要使用的采样温度，介于 0 和 2 之间。 较高的值（如 0.8）将使输出更随机，而较小的值（如 0.2）将使输出更集中且更具确定性 |
top_p |
数字或 null | 可选 | 默认值为 1。 温度采样的替代方法，称为核采样，其中模型考虑具有 top_p 概率质量的令牌的结果。 所以 0.1 意味着只考虑包含前 10% 概率质量的令牌。 我们通常建议更改此设置或温度，但不要同时更改这两者。 |
response_format |
字符串或对象 | 可选 | 指定模型必须输出的格式。 与 GPT-4 Turbo 和自 gpt-3.5-turbo-1106 起的所有 GPT-3.5 Turbo 型号兼容。 将此参数设置为 { "type": "json_object" } 以启用 JSON 模式，这可以保证模型生成的消息是有效的 JSON。 重要的是，使用 JSON 模式时，还必须使用系统或用户消息指示模型自己生成 JSON。 如果没有此指令，模型可能会生成一个无限的空白流，直到生成达到令牌限制，从而导致请求长时间运行，看似“卡滞”。 此外，如果使用 finish_reason="length"，则消息内容可能会部分截断，这表示生成超过了 max_tokens，或者对话超过了最大上下文长度。 |
tool_resources |
对象 (object) | 可选 | 助手工具使用的一组资源。 资源特定于工具类型。 例如，code_interpreter 工具需要文件 ID 列表，而 file_search 工具需要矢量存储 ID 列表。 |
返回
修改后的助手对象。
修改助手示例
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_updated_assistant = client.beta.assistants.update(
"asst_abc123",
instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
name="HR Helper",
tools=[{"type": "code-interpreter"}],
model="gpt-4", #model = model deployment name
)
print(my_updated_assistant)
删除助手
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview
删除助手。
路径参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
assistant_id |
字符串 | 必须 | 文件所属助手的 ID。 |
返回
删除状态。
删除助手示例
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
response = client.beta.assistants.delete("asst_abc123")
print(response)
文件上传 API 参考
助手使用与微调相同的 API 进行文件上传。 上传文件时，必须为 purpose 参数指定适当的值。
助手对象
| 字段 | 类型 | 说明 |
|---|---|---|
id |
string | 可以在 API 终结点中引用的标识符。 |
object |
string | 对象类型，始终为助手。 |
created_at |
integer | 创建助手时的 Unix 时间戳（以秒为单位）。 |
name |
string 或 null | 助手的名称。 最大长度为 256 个字符。 |
description |
string 或 null | 助手的说明。 最大长度为 512 个字符。 |
model |
string | 要使用的模型部署名称的名称。 |
instructions |
string 或 null | 助手使用的系统说明。 最大长度为 32768 个字符。 |
tools |
array | 在助手上启用的工具列表。 每个助手最多可以有 128 个工具。 工具类型可以是 code_interpreter 或函数。
function 说明最多可包含 1,024 个字符。 |
metadata |
map | 按 16 个成组的可附加到对象的键值对。 这对以结构化格式存储对象相关的附加信息很有用。 键的最大长度为 64 个字符，值的最大长度为 512 个字符。 |
temperature |
数字或 null | 默认值为 1。 确定要使用的采样温度，介于 0 和 2 之间。 较高的值（如 0.8）将使输出更随机，而较小的值（如 0.2）将使输出更集中且更具确定性 |
top_p |
数字或 null | 默认值为 1。 温度采样的替代方法，称为核采样，其中模型考虑具有 top_p 概率质量的令牌的结果。 所以 0.1 意味着只考虑包含前 10% 概率质量的令牌。 我们通常建议更改此设置或温度，但不要同时更改这两者。 |
response_format |
字符串或对象 | 指定模型必须输出的格式。 与 GPT-4 Turbo 和自 gpt-3.5-turbo-1106 起的所有 GPT-3.5 Turbo 型号兼容。 将此参数设置为 { "type": "json_object" } 以启用 JSON 模式，这可以保证模型生成的消息是有效的 JSON。 重要的是，使用 JSON 模式时，还必须使用系统或用户消息指示模型自己生成 JSON。 如果没有此指令，模型可能会生成一个无限的空白流，直到生成达到令牌限制，从而导致请求长时间运行，看似“卡滞”。 此外，如果使用 finish_reason="length"，则消息内容可能会部分截断，这表示生成超过了 max_tokens，或者对话超过了最大上下文长度。 |
tool_resources |
object | 助手工具使用的一组资源。 资源特定于工具类型。 例如，code_interpreter 工具需要文件 ID 列表，而 file_search 工具需要矢量存储 ID 列表。 |