Azure AI Foundry 代理服务文件搜索工具

文件搜索利用其模型外部的知识（如专有产品信息或用户提供的文档）提升代理功能。

文件源

• 上传本地文件
• Azure Blob 存储

使用支持

依赖于代理设置

基本代理设置

文件搜索工具的功能与 Azure OpenAI 助手相同。 会使用 Microsoft 托管搜索和存储资源。

• 上传的文件存储在 Microsoft 托管存储中
• 会使用 Microsoft 托管搜索资源创建矢量存储

标准代理设置

文件搜索工具使用在代理设置过程中连接的 Azure AI 搜索和 Azure Blob 存储资源。

• 上传的文件存储在连接的 Azure Blob 存储帐户中
• 使用连接的 Azure AI 搜索资源创建矢量存储

对于这两个代理设置，该服务将处理整个引入过程，其中包括：

• 自动分析文档并将文档分块
• 生成并存储嵌入
• 利用矢量和关键字搜索来检索用户查询的相关内容。

两种设置之间没有代码方面的区别；唯一的区别在于你的文件和创建的矢量存储的存储位置。

工作原理

文件搜索工具现身实现多个检索最佳做法，以帮助你从文件中提取正确的数据，并增强模型响应。 文件搜索工具：

• 重写用户查询以优化其搜索。
• 将复杂的用户查询分解为可以并行运行的多个搜索。
• 在代理和线程矢量存储上运行关键字和语义搜索。
• 在生成最终响应之前，请重新调整搜索结果以选取最相关的搜索结果。
• 默认情况下，文件搜索工具使用以下设置：
  • 区块大小：800 个令牌
  • 区块重叠：400 个令牌
  • 嵌入模型：text-embedding-3-large，尺寸为 256
  • 添加到上下文的最大区块数：20

矢量存储

矢量存储对象使文件搜索工具能够搜索文件。 将文件添加到矢量存储会自动分析、分块、嵌入文件并将其存储在能够进行关键字和语义搜索的矢量数据库中。 每个矢量存储最多可以容纳 10,000 个文件。 矢量存储可以附加到代理和线程。 目前，最多可以将一个矢量存储附加到一个代理，并且最多可以将一个矢量存储附加到一个线程。

同样，可以通过以下任一方法从矢量存储中删除这些文件：

• 删除矢量存储文件对象或
• 通过删除基础文件对象，可以从组织内所有代理和线程中的所有vector_store和code_interpreter配置中移除该文件。

最大文件大小为 512 MB。 每个文件应包含每个文件的令牌不超过 5,000,000 个（会在附加文件时自动计算）。

在创建运行之前确保矢量存储就绪情况

强烈建议在创建运行之前确保已完全处理 vector_store 中的所有文件。 这可以确保矢量存储中的所有数据都可搜索。 可以使用 SDK 中的轮询帮助程序，或者手动轮询矢量存储对象来确保状态为“已完成”，来检查矢量存储就绪情况。

作为回退，当线程的矢量存储包含仍在处理的文件时，最多在 Run 对象中等待 60 秒。 这是为了确保用户在线程中上传的任何文件在运行继续之前完全可搜索。 此回退等待不适用于代理的矢量存储。

创建矢量存储并添加文件

将文件添加到矢量存储是一项异步操作。 为了确保操作完成，我们建议在官方 SDK 中使用“创建和轮询”帮助程序。 如果不使用 SDK，则可以检索 vector_store 对象并监视其 file_counts 属性以查看文件引入操作的结果。

创建矢量存储文件后，还可以将文件添加到矢量存储中。

# create a vector store with no file and wait for it to be processed
vector_store = project_client.agents.vector_stores.create_and_poll(data_sources=[], name="sample_vector_store")
print(f"Created vector store, vector store ID: {vector_store.id}")

# add the file to the vector store or you can supply file ids in the vector store creation
vector_store_file_batch = project_client.agents.vector_store_file_batches.create_and_poll(
    vector_store_id=vector_store.id, file_ids=[file.id]
)
print(f"Created vector store file batch, vector store file batch ID: {vector_store_file_batch.id}")

或者，可以通过创建最多 500 个文件的批处理，将多个文件添加到矢量存储中。

batch = project_client.agents.vector_store_file_batches.create_and_poll(
  vector_store_id=vector_store.id,
  file_ids=[file_1.id, file_2.id, file_3.id, file_4.id, file_5.id]
)

基本代理设置：从矢量存储中删除文件

可以通过以下任一方法从矢量存储中删除文件：

• 删除矢量存储文件对象或
• 删除基础文件对象，这会从组织中所有代理和线程的所有vector_store和code_interpreter配置中删除该文件

最大文件大小为 512 MB。 每个文件应包含每个文件的令牌不超过 5,000,000 个（会在附加文件时自动计算）。

删除矢量存储

可以从文件搜索工具中删除矢量存储。

file_search_tool.remove_vector_store(vector_store.id)
print(f"Removed vector store from file search, vector store ID: {vector_store.id}")

project_client.agents.update_agent(
    agent_id=agent.id, tools=file_search_tool.definitions, tool_resources=file_search_tool.resources
)
print(f"Updated agent, agent ID: {agent.id}")

删除矢量存储

project_client.agents.vector_stores.delete(vector_store.id)
print("Deleted vector store")

使用过期策略管理成本

对于基本代理设置，file_search 工具使用 vector_stores 对象作为其资源，系统将根据创建的 vector_store 对象的大小计费。 矢量存储对象的大小是文件及其相应嵌入的所有已分析区块的总和。

为了帮助你管理与这些 vector_store 对象相关的成本，我们在 vector_store 对象中添加了对过期策略的支持。 创建或更新 vector_store 对象时，可以设置这些策略。

vector_store = project_client.agents.vector_stores.create_and_poll(
  name="Product Documentation",
  file_ids=[file_1.id],
  expires_after={
      "anchor": "last_active_at",
      "days": 7
  }
)

线程矢量存储具有默认过期策略

使用线程帮助程序（如 tool_resources.file_search.vector_stores 线程或 message.attachments 消息中创建的矢量存储）的默认过期策略在上次处于活动状态后七天（定义为最后一次矢量存储是运行的一部分）。

当矢量存储过期时，该线程上的运行将失败。 若要解决此问题，可以使用相同的文件重新创建一个新的 vector_store，并将其重新附加到线程。

支持的文件类型