Foundry Agent Service ファイル検索ツール (クラシック)

注

このドキュメントでは、Microsoft Foundry (クラシック) エージェントについて説明します。

🔍 新しいファイル検索ドキュメントを表示します。 エージェント (クラシック) は非推奨になり、2027 年 3 月 31 日に廃止されます。 一般公開されている Microsoft Foundry Agents Service の新しいエージェントを使用します。 移行ガイドに従ってワークロードを更新します。

ファイル検索は、財産的価値のある製品情報やユーザーから提供されたドキュメントなど、モデルの外部からの知識でエージェントを強化します。

注

標準エージェントのセットアップを使用すると、改善されたファイル検索ツールによってファイルが独自のストレージに保持され、Azure AI Search リソースを使用してそれらを取り込み、データを完全に制御できます。

ファイル ソース

• ローカル ファイルをアップロードする
• Azure Blob Storage

利用サポート

注

ファイル検索ツールは、現在、次のリージョンでは使用できません。

• イタリア北部
• ブラジル南部
• 西ヨーロッパ

Azure AI Foundry のサポート	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	基本エージェントのセットアップ	標準エージェントのセットアップ
✔️	✔️	✔️	✔️	✔️	✔️	ファイルのアップロードのみ	独自の BLOB ストレージを使用してファイルをアップロードする

エージェントのセットアップに対する依存

基本エージェントのセットアップ

ファイル検索ツールは、Azure OpenAI アシスタントと同じ機能を備えています。 Microsoft マネージドの検索とストレージ リソースが使用されます。

• アップロードされたファイルは、Microsoft マネージドのストレージ内に保存されます
• Microsoft マネージドの検索リソースを使用してベクトル ストアが作成されます

標準エージェントのセットアップ

ファイル検索ツールは、エージェントのセットアップ中に接続したAzure AI SearchとAzure Blob Storageリソースを使用します。

• アップロードされたファイルは、接続されているAzure Blob Storage アカウントに格納されます
• 接続されたAzure AI Search リソースを使用してベクター ストアが作成される

どちらのエージェントセットアップでも、サービスはインジェスト プロセス全体を処理します。これには次のものが含まれます。

• ドキュメントの自動解析とチャンキング
• 埋め込みの生成と保存
• ユーザー クエリに対する関連コンテンツを取得するためのベクトル検索とキーワード検索両方の利用。

2 つのセットアップにおいてコードに違いはありません。唯一の違いは、ファイルと作成されたベクトル ストアが保存される場所です。

動作方法

ファイル検索ツールは、取得に関してすぐに使用できるいくつかのベスト プラクティスを実装しており、これらは、ファイルから適切なデータを抽出し、モデルの応答を強化するのに役立ちます。 ファイル検索ツール:

• ユーザーのクエリを書き換えて、検索用に最適化します。
• 複雑なユーザー クエリを複数の検索に分割し、並列で実行できるようにします。
• エージェントとスレッドの両方のベクトル ストアでキーワード検索とセマンティック検索の両方を実行します。
• 検索結果を再ランク付けして、最も関連性の高い結果を選択してから最終的な応答を生成します。
• ファイル検索ツールには、既定で次の設定が使用されます。
  • チャンク サイズ: 800 トークン
  • チャンク オーバーラップ: 400 トークン
  • 埋め込みモデル: 256 ディメンションの text-embedding-3-large
  • コンテキストに追加される最大チャンク数: 20

ベクトル ストア

ベクトル ストア オブジェクトを使用して、ファイル検索ツールでファイルを検索することができます。 ベクトル ストアにファイルを追加すると、ファイルの解析、チャンク化、埋め込みが自動的に行われ、キーワード検索とセマンティック検索の両方が可能なベクトル データベースにファイルが保存されます。 各ベクトル ストアには、最大 10,000 個のファイルを保持できます。 ベクター ストアは、エージェントとスレッドの両方にアタッチできます。 現時点では、最大 1 つのベクター ストアをエージェントにアタッチし、最大で 1 つのベクター ストアをスレッドにアタッチできます。

同様に、次のいずかの方法で、これらのファイルをベクトル ストアから削除できます。

• ベクトル ストア ファイル オブジェクトを削除する、または
• 基になるファイル オブジェクトを削除すると、組織内のすべてのエージェントとスレッドのすべての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 など) を使用して作成されたベクトル ストアには、既定では最後にアクティブになった後 (ベクトル ストアが実行の一部であった最後の時刻として定義されます) 7 日間という有効期限ポリシーがあります。

ベクター ストアの有効期限が切れると、そのスレッドでの実行は失敗します。 この問題を解決するには、同じファイルを使用して新しい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

制限事項

• Encryption 値に対して非 CMK インデックスを拒否するAzure検索リソース インデックスのAzure Policyがある場合、ファイルのアップロードとベクター ストアの作成は失敗します。 この場合は、Azure AI Search リソースからインデックスを事前に取得し、エージェントで参照する必要があります。 暗号化の種類 = カスタマー マネージド キーを使用して Foundry からインデックスを作成することはできません。