你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

助手 API（预览版）参考

项目
05/24/2024

注意

文件搜索可为每个助手最多引入 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`。
file_ids	array	可选	默认值为 []。已附加到此助手的文件 ID 的列表。助手最多可以附加 20 个文件。文件按其创建日期升序排列。
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`，或者对话超过了最大上下文长度。

助手对象。

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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"}]
)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-1106-preview"
  }'

创建助手文件

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview

通过将 File 附加到 assistant 来创建助手文件。

路径参数

参数	类型	必需	说明
`assistant_id`	字符串	必须	文件应附加到的助手的 ID。

请求正文

名称	类型	必需	说明
file_id	string	必须	助手应使用的文件 ID（用途=“助手”）。适用于可以访问文件的 code_interpreter 等工具。

一个助手文件对象。

创建助手文件请求示例

Python 1.x
REST

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant_file = client.beta.assistants.files.create(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
       "file_id": "assistant-abc123"
     }'

助手列表

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，以提取列表的上一页。

助手对象的列表

列表助手示例

Python 1.x
REST

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

助手文件列表

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview

返回助手文件的列表。

路径参数

参数	类型	必需	说明
assistant_id	string	必须	文件所属助手的 ID。

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，以提取列表的上一页。

助手文件对象的列表

助手文件列表示例

Python 1.x
REST

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant_files = client.beta.assistants.files.list(
  assistant_id="asst_abc123"
)
print(assistant_files)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

检索助手

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview

检索助手。

路径参数

参数	类型	必需	说明
`assistant_id`	字符串	必须	要检索的助手的 ID。

与指定 ID 匹配的助手对象。

检索助手示例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

检索助手文件

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview

检索助手文件。

路径参数

参数	类型	必需	说明
assistant_id	string	必须	文件所属助手的 ID。
file_id	string	必须	要获取的文件的 ID

与指定 ID 匹配的助手文件对象

检索助手文件示例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant_file = client.beta.assistants.files.retrieve(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files/{file-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

修改助手

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview

修改助手。

路径参数

参数	类型	必需	说明
assistant_id	string	必须	文件所属助手的 ID。

请求正文

参数	类型	必需	说明
`model`		可选	要使用的模型的模型部署名称。
`name`	string 或 null	可选	助手的名称。最大长度为 256 个字符。
`description`	string 或 null	可选	助手的说明。最大长度为 512 个字符。
`instructions`	string 或 null	可选	助手使用的系统说明。最大长度为 32768 个字符。
`tools`	array	可选	默认值为 []。在助手上启用的工具列表。每个助手最多可以有 128 个工具。工具类型可以是 code_interpreter 或函数。
`file_ids`	array	可选	默认值为 []。已附加到此助手的文件 ID 的列表。助手最多可以附加 20 个文件。文件按其创建日期升序排列。如果文件之前已附加到列表但未显示在列表中，则会从助手中删除该文件。
`metadata`	map	可选	按 16 个成组的可附加到对象的键值对。这对以结构化格式存储对象相关的附加信息很有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

修改后的助手对象。

修改助手示例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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
  file_ids=["assistant-abc123", "assistant-abc456"],
)

print(my_updated_assistant)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "code-interpreter"}],
      "model": "gpt-4",
      "file_ids": ["assistant-abc123", "assistant-abc456"]
    }'

删除助手

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview

删除助手。

路径参数

参数	类型	必需	说明
`assistant_id`	字符串	必须	文件所属助手的 ID。

删除状态。

删除助手示例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

删除助手文件

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview

删除助手文件。

路径参数

参数	类型	必需	说明
`assistant_id`	字符串	必须	文件所属助手的 ID。
`file_id`	string	必须	要删除的文件的 ID

文件删除状态

删除助手文件示例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

deleted_assistant_file = client.beta.assistants.files.delete(
    assistant_id="asst_abc123",
    file_id="assistant-abc123"
)
print(deleted_assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
```  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

文件上传 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 或函数。
`file_ids`	array	已附加到此助手的文件 ID 的列表。助手最多可以附加 20 个文件。文件按其创建日期升序排列。
`metadata`	map	按 16 个成组的可附加到对象的键值对。这对以结构化格式存储对象相关的附加信息很有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。

助手文件对象

字段	类型	说明
`id`	string	可以在 API 终结点中引用的标识符。
`object`	string	对象类型，始终为 `assistant.file`
`created_at`	integer	创建助手文件时的 Unix 时间戳（以秒为单位）。
`assistant_id`	string	文件附加到的助手 ID。

通过

助手 API（预览版）参考

创建助手

请求正文

返回

创建助手请求示例

创建助手文件

返回

创建助手文件请求示例

助手列表

返回

列表助手示例

助手文件列表

返回

助手文件列表示例

检索助手

检索助手示例

检索助手文件

返回

检索助手文件示例

修改助手

修改助手示例

删除助手

删除助手示例

删除助手文件

删除助手文件示例

文件上传 API 参考

助手对象

助手文件对象

其他资源