你当前正在访问 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 列表。 |
返回
助手对象。
创建助手请求示例
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 列表。 |