通过

你当前正在访问 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/threads/{thread_id}/messages?api-version=2024-08-01-preview

创建邮件。

路径参数

参数 类型​​ 必需 说明
thread_id 字符串 必须 要为其创建消息的线程的 ID。

请求正文

名称 类型​​ 必需 说明
role 字符串 必须 正在创建消息的实体的角色。 可以是 user 或 assistant。 user 指示消息是由实际用户发送的，应在大多数情况下用于表示用户生成的消息。 assistant 指示消息由助手生成。 使用此值将来自助手的消息插入对话。
content string 必须 消息的内容。
attachments array 可选 附加到消息的文件列表及其应添加到的工具。
metadata map 可选 按 16 个成组的可附加到对象的键值对。 这对以结构化格式存储对象相关的附加信息很有用。 键的最大长度为 64 个字符，值的最大长度为 512 个字符。

返回

一个消息对象。

创建消息请求示例

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")
    )

thread_message = client.beta.threads.messages.create(
  "thread_abc123",
  role="user",
  content="How does AI work? Explain it in simple terms.",
)
print(thread_message)

列出消息

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages?api-version=2024-08-01-preview

返回给定线程的消息列表。

路径参数

参数 类型​​ 必需 说明
thread_id 字符串 必须 消息所属的线程的 ID。

查询参数

名称 类型​​ 必需 说明
limit integer 可选 - 默认为 20 要返回的对象数的限制。 限制可以介于 1 和 100 之间，默认值为 20。
order string 可选 - 默认为 desc 按对象的 created_at 时间戳顺序。 asc 表示升序，desc 表示降序。
after string 可选 用于分页的游标。 之后是一个对象 ID，用于定义你在列表中的位置。 例如，如果你发出一个列表请求并收到 100 个对象，以 obj_foo 结尾，那么你的后续调用可以包含 after=obj_foo，以提取列表的下一页。
run_id string 可选 按生成消息的运行 ID 筛选消息。
before string 可选 用于分页的游标。 之前是一个对象 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")
    )

thread_messages = client.beta.threads.messages.list("thread_abc123")
print(thread_messages.data)

检索消息

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview

检索消息文件。

路径参数

参数 类型​​ 必需 说明
thread_id 字符串 必须 消息所属的线程的 ID。
message_id string 必须 要检索的消息的 ID。

返回

与指定 ID 匹配的消息对象。

检索消息请求示例

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")
    )

message = client.beta.threads.messages.retrieve(
  message_id="msg_abc123",
  thread_id="thread_abc123",
)
print(message)

修改消息

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview

修改消息。

路径参数

参数 类型​​ 必需 说明
thread_id 字符串 必须 消息所属的线程的 ID。
message_id string 必须 要修改的消息的 ID。

请求正文

参数 类型​​ 必需 说明
metadata map 可选 按 16 个成组的可附加到对象的键值对。 这对以结构化格式存储对象相关的附加信息很有用。 键的最大长度为 64 个字符，值的最大长度为 512 个字符。

返回

已修改的消息对象。

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")
    )

message = client.beta.threads.messages.update(
  message_id="msg_abc12",
  thread_id="thread_abc123",
  metadata={
    "modified": "true",
    "user": "abc123",
  },
)
print(message)

删除消息

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/messages/{message_id}?api-version=2024-08-01-preview

删除消息。

路径参数

参数 类型​​ 必需 说明
thread_id 字符串 必须 消息所属的线程的 ID。
message_id string 必须 要修改的消息的 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")
    )

deleted_message = client.beta.threads.messages.delete(
  message_id="msg_abc12",
  thread_id="thread_abc123",
)
print(deleted_message)

消息对象

表示线程中的消息。

名称 Type 说明
id string 可以在 API 终结点中引用的标识符。
object string 对象类型，始终为 thread.message。
created_at integer 创建消息时的 Unix 时间戳（以秒为单位）。
thread_id string 此消息所属的线程 ID。
role string 生成消息的实体。 user 或 assistant 中的一项。
content array 文本和/或图像数组中消息的内容。
assistant_id string 或 null 如果适用，则为创作此消息的助手的 ID。
run_id string 或 null 如果适用，则为与此消息的创作关联的运行的 ID。
file_ids array 助手应使用的文件 ID 列表。 适用于可以访问文件的工具，例如检索和 code_interpreter。 一条消息最多可以附加 10 个文件。
metadata map 按 16 个成组的可附加到对象的键值对。 这对以结构化格式存储对象相关的附加信息很有用。 键的最大长度为 64 个字符，值的最大长度为 512 个字符。