Foundry Agent Service 檔案搜尋工具（經典版）

註

本文件提及 Microsoft Foundry（經典版）代理程式。

🔍 查看新檔案搜尋文件。 Agents（經典版）現已棄用，將於 2027 年 3 月 31 日退役。 請使用普遍可用的 Microsoft Foundry Agents Service 中的新代理。 請依照 遷移指南 更新你的工作負載。

檔案搜尋能增強代理者來自其模型之外的知識，例如專有產品資訊或使用者提供的文件。

註

透過標準代理設定，改良版的檔案搜尋工具確保您的檔案仍存在於您自己的儲存空間，並利用 Azure AI 搜尋服務 資源來匯入檔案，確保您對資料保持完全掌控。

檔案來源

  • 上傳本地檔案
  • Azure Blob 儲存體

使用支援

註

檔案搜尋工具目前在以下地區無法使用：

  • 義大利北部
  • 巴西南部
  • 西歐
Azure AI Foundry 支援 Python SDK C# SDK JavaScript SDK Java SDK REST API 基本代理設定 標準代理設定
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ 僅上傳檔案 檔案上傳和使用自備 Blob 儲存體

對代理設定的依賴

基本代理設定

檔案搜尋工具的功能與 Azure OpenAI 助理相同。 使用Microsoft管理的搜尋與儲存資源。

  • 上傳的檔案會儲存在 Microsoft 管理的儲存空間中
  • 向量儲存是利用 Microsoft 管理的搜尋資源建立的

標準代理設定

檔案搜尋工具會使用你在代理設定時連接的 Azure AI 搜尋服務 和 Azure Blob 儲存體 資源。

  • 上傳的檔案會儲存在你連接的 Azure Blob 儲存體 帳號中
  • 向量儲存是利用你連接的 Azure AI 搜尋服務 資源建立的

在兩種代理設定中，服務都負責整個擷取流程，包括：

  • 自動解析與分塊文件
  • 產生與儲存嵌入
  • 利用向量與關鍵字搜尋，為使用者查詢擷取相關內容。

兩種設定的程式碼並無差異;唯一的差異在於你的檔案和已建立的向量儲存在哪裡。

運作原理

檔案搜尋工具即刻實作多項檢索最佳實務，幫助您從檔案中擷取正確資料並增強模型的回應。 檔案搜尋工具：

  • 重寫使用者查詢以優化搜尋需求。
  • 它能將複雜的使用者查詢拆解成多個搜尋，並可並行執行。
  • 能在代理與執行緒向量儲存庫中執行關鍵字與語意搜尋。
  • 重新排序搜尋結果，挑選最相關的關鍵字，然後生成最終回應。
  • 預設情況下，檔案搜尋工具會使用以下設定：
    • 區塊大小：800 代幣
    • 分段重疊：400 個 token
    • 嵌入模型：text-embedding-3-large，維度為 256
    • 最大新增上下文區塊數：20

向量儲存系統

向量儲存物件讓檔案搜尋工具能夠搜尋你的檔案。 將檔案加入向量儲存會自動解析、區塊、嵌入，並儲存在一個同時具備關鍵字與語意搜尋功能的向量資料庫中。 每個向量儲存庫最多可容納 10,000 個檔案。 向量儲存可以附加在代理程式和執行緒上。 目前，你最多只能將一個向量存儲連接到一個代理和一個執行緒。

同樣地，這些檔案也可以透過以下方式從向量儲存庫中移除：

  • 刪除向量存放區檔案物件，或
  • 透過刪除底層的檔案物件，這將從組織中所有代理程式和執行緒的 vector_store 和 code_interpreter 設定中移除該檔案。

最大檔案大小為 512 MB。 每個檔案的標記數量不應超過 5,000,000 個（這是在附加檔案時自動計算）。

在建立執行之前確認向量存放庫已準備就緒

我們強烈建議您在建立執行前，確保vector_store中所有檔案都已完全處理完畢。 這確保向量儲存中的所有資料都能被搜尋。 你可以透過 SDK 中的輪詢輔助工具檢查向量儲存的準備狀態，或手動輪詢向量儲存物件以確保狀態已完成。

作為備用方案，當執行緒的向量儲存包含仍在處理中的檔案時，執行物件有最大 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 = 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 Threads 或 message.attachments Messages）預設的過期期限為上次啟用後七天（定義為向量儲存最後一次執行時間）。

當向量儲存到期時，該執行緒的執行就會失敗。 要解決這個問題，你可以用相同的檔案重新建立一個新的vector_store，然後重新附加到執行緒上。

支援的檔案類型

註

對於文字/MIME 類型，編碼必須是 utf-8、utf-16 或 ASCII。

檔案格式 MIME 類型
.c text/x-c
.cs text/x-csharp
.cpp text/x-c++
.doc application/msword
.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
.html text/html
.java text/x-java
.json application/json
.md text/markdown
.pdf application/pdf
.php text/x-php
.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
.py text/x-python
.py text/x-script.python
.rb text/x-ruby
.tex text/x-tex
.txt text/plain
.css text/css
.js text/javascript
.sh application/x-sh
.ts application/typescript

限制

  • 當您的 Azure 搜尋服務資源索引有 Azure 原則不允許加密值有非 CMK 索引時，上傳檔案和建立向量存放區都會失敗。 在這種情況下，你需要先從 Azure AI 搜尋服務 資源中取得索引，然後在代理程式中引用它們。 你無法用 Foundry 建立 Encryption type = 客戶管理金鑰的索引。
  • Last updated on