【Azure AI Search】ファイル ナレッジ ソースでファイルを直接アップロードしてインデックスを作成する

ファイル ナレッジ ソースとは

ファイル ナレッジ ソース（プレビュー）は、小規模〜中規模のファイル集合を、エージェント検索のために Azure AI Search へ直接アップロードできる機能です。

ナレッジ ソースは単体で作成され、ナレッジ ベースから参照されて、実行時にナレッジ ベースへクエリが実行される際のグラウンドデータとして使われます。ファイル ナレッジ ソースは、この「ナレッジ ソース」の一種で、Azure Storageのプロビジョニング・アクセス構成・外部コンテナー経由のインデクサー パイプライン構築の代わりに、マネージドなアップロード体験を提供します。アップロードされたファイルからのコンテンツ抽出・チャンク化・（必要に応じた）埋め込み生成は、すべてAzure AI Search側が担当します。

すでにコンテンツがAzure Blob StorageやADLS Gen2にある場合や、大規模な取り込み・ストレージアカウントの機能が必要な場合は、代わりにBlobナレッジ ソースを使う方が適しています。

前提条件と気をつけたいポイント

• 専用モデルの検索サービスが必要：エージェント型取得を提供するリージョンにある、任意の専用モデルの検索サービスが必要です。ファイル ナレッジ ソースはサーバーレスモデルではサポートされていません。
• 認証はキーレスを推奨：ナレッジ ソースを作成する権限として、ユーザーアカウントに割り当てた「Search Service 共同作成者」ロールによるキーレス認証（推奨）か、APIキーのいずれかが必要です。
• 埋め込みモデル用の Azure OpenAIリソースが必要：埋め込みモデルをデプロイしたAzure OpenAIリソースが必要です。アクセスはAPIキーまたはマネージドID(要Cognitive Services User権限)のいずれかで行います。

対応形式と上限

ファイル ナレッジ ソースがサポートするファイル形式は次のとおりです。

また、次の上限も適用されます。

アップロードされたコンテンツは生成された検索インデックスに格納されるため、価格レベルごとのストレージ上限にも影響します。ナレッジソース単位でファイル数の上限があるため、大量のファイルを扱う用途には向きません。

実践：C#でナレッジ ソースを作成し、ファイルをアップロードする

1. 既存のナレッジ ソースを確認する

ナレッジ ソースは最上位の再利用可能なオブジェクトです。新しく作る前に、既存のものを一覧確認しておくと名前の重複や再利用の判断がしやすくなります。

using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// 検索サービス内のナレッジソースを名前・種類つきで列挙する
await foreach (var source in indexClient.GetKnowledgeSourcesAsync())
{
    Console.WriteLine($"{source.Name} / {source.GetType().Name}");
}

2. ナレッジ ソースを作成する

アップロードしたコンテンツをベクター化するための埋め込みモデルを指定して、ファイル ナレッジ ソースを作成します。

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// 埋め込みに使うAzure OpenAIデプロイの情報
var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    ContentExtractionMode = "minimal",
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var fileKnowledgeSource = new FileKnowledgeSource(
    name: "<ナレッジソース名>",
    fileParameters: new FileKnowledgeSourceParameters { IngestionParameters = ingestionParams })
{
    Description = "<ナレッジソースの説明>"
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(fileKnowledgeSource);
Console.WriteLine($"ナレッジソース '{fileKnowledgeSource.Name}' を作成しました。");

3. ファイルをアップロードする

ナレッジ ソースができたら、ファイルを直接アップロードします。アップロードは同期呼び出しで、抽出・チャンク化・埋め込み生成まで完了してから応答が返るため、別途インジェストパイプラインを組む必要はありません。

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

string fileName = "<ファイル名>";
byte[] fileBytes = await File.ReadAllBytesAsync(fileName);
string contentDisposition = $"attachment; filename=\"{fileName}\"";

var uploaded = (await indexClient.UploadKnowledgeSourceFileAsync(
    "<ナレッジソース名>",
    contentDisposition,
    BinaryData.FromBytes(fileBytes))).Value;

Console.WriteLine($"アップロード完了。File ID: {uploaded.FileId}");

4. アップロード済みファイルを一覧・削除する

ナレッジ ソース上のファイル一覧を確認し、不要になったファイルは個別に削除できます。

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// アップロード済みファイルの一覧を確認
await foreach (var file in indexClient.GetKnowledgeSourceFilesAsync("<ナレッジソース名>"))
{
    Console.WriteLine($"{file.FileName} ({file.FileSizeBytes} bytes) error={file.ErrorMessage}");
}

// 不要になったファイルを削除
await indexClient.DeleteKnowledgeSourceFileAsync("<ナレッジソース名>", "<ファイルID>");

errorMessage が null であれば処理は成功しています。サポート対象外の形式や抽出エラー、モデルへのアクセス不可、クォータ超過などがあると、ここにエラー内容が入ります。

生成されたインデックスの中身を覗いてみる

ファイル ナレッジ ソースは、アップロードしたファイルのコンテンツ抽出・チャンク化・埋め込み生成の結果を、内部的に生成される検索インデックスに格納します。この生成されたインデックス自体は、ナレッジ ソース専用の管理画面はなくても、Azure Portalの通常の「インデックス」画面や検索エクスプローラーから中身を確認できます。

1. 生成されたインデックスのJSON定義をコピーする
2. そのインデックスを一度削除する
3. コピーしたJSONの analyzer 部分だけを日本語アナライザー（ja.lucene や ja.microsoft など）に書き換える
4. 同じ名前で、書き換えたJSON定義をもとにインデックスを再作成する

実際にアップロードしたファイルがどう取り込まれているかを見てみると、おおむね次のような構成のドキュメントが生成されていることが確認できます。

• チャンク単位のドキュメント：1ファイルがまるごと1件になるのではなく、内容がいくつかのチャンクに分割され、チャンクごとに1検索ドキュメントとして格納されます。
• チャンクを一意に識別するキー [uid]：チャンクIDにあたるフィールドが主キーとして割り当てられます。
• 元ファイルを指す参照 [snippet_parent_id または、metadata_storage_path(以下の画面キャプチャでは表示を省略)]：どのアップロード元ファイルから生成されたチャンクかを示す、親ドキュメント側の参照が保持されます。
• 本文テキスト [snippet]と 埋め込みベクター[snippet_vector]：抽出された本文（可読なテキスト）と、埋め込みモデルを指定していた場合はそのベクター表現の両方が格納されます。

検索エクスプローラーで実際にクエリを投げてみると、アップロードした資料の該当する部分だけが返ってくることを確認できます。「ファイルをアップロードしたら、裏側ではこの粒度まで分解されて検索対象になっている」ことが視覚的にわかると、ナレッジ ベース側の RetrievalInstructions や maxOutputDocuments のチューニングもイメージしやすくなります。

ナレッジ ソースを削除する

検証が終わったナレッジ ソースは、次のコードで削除できます。

using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeSourceAsync("<ナレッジソース名>");
Console.WriteLine("ナレッジソースを削除しました。");

なお、前のセクションで日本語アナライザーに変更するために手動で作り直したインデックスについてもナレッジソースの削除と連動して削除されることを確認しました。

Foundry ポータルからの操作

ここまでは、APIでナレッジソースの作成、ファイル登録を行ってきました。Azure ポータルは未対応ですが、Foundry ポータルからの操作は可能です。
Foundry ポータルからは、ナレッジソースのみの作成はできず、ナレッジベースの作成が必要になります。

1. ナレッジベースの作成

(1) Foundry ポータルから作成する場合は、「ビルド」（作成）メニューを選択し、「ナレッジ」を選択する。


(2) ナレッジベースタブを選択し、使用するAI Search リソースに接続する。


(3) ナレッジベースの作成をクリックする。


(4) 基本構成で必要な項目を入力し、ナレッジソース欄の「ファイルのアップロード」をクリックする。


(5) ナレッジソースの各項目を入力し、ナレッジとなるファイルをアップロードして、「作成」をクリックする。


(6) 「ナレッジベースの保存」をクリックし、作成を完了させる。

2. ナレッジベースの動作確認

ナレッジベースは、Azure ポータルで動作確認できます。
アップロードしたファイルは、ナレッジソース（ファイル）に登録されています。


ナレッジベースも登録されていることを確認できます。


ナレッジベースをクリックすると、ナレッジ検索のテストができます。 ナレッジベース作成時に出力モードを「抽出データ」とすると、検索したデータ（生データ）が得られます。プログラムからデータを取得して、後続処理につなげる場合に使用できます。


出力モードを「応答の合成」とすると、応答を組み合わせた自然言語での回答が得られます。簡易的なQAボットであれば、このナレッジ検索だけで完結させることができます。

3. 作成されたインデックスの確認

Foundry ポータルから作成したナレッジソースも APIで作成したものと同様の形で作成されています。

よくある質問（FAQ）

まとめ

今回は、Azure AI Search の「ファイル ナレッジ ソース」について、概要と前提条件の整理から、C#での作成・アップロード・一覧・削除までの一連の流れを紹介しました。

• ストレージ構築の手間を省ける：PDFやWordなどのファイルを直接アップロードするだけで、抽出からチャンク化・埋め込み生成までを検索サービスが完結させます。
• サーバーレスとは組み合わせられない：専用モデルの検索サービスが前提のため、サーバーレスで検証を進めている場合は環境を分けて考える必要があります。
• 小〜中規模のファイル集合に向く機能：最大100ファイル・1ファイル50MBという上限があるため、大規模な取り込みにはBlobナレッジ ソースを検討します。

社内マニュアルやFAQ集など、まとまった数のファイルをまずはさくっとエージェント検索に載せてみたい、というシーンでは有力な選択肢になりそうです。プレビュー機能のため、今後のAPIや制限事項の変更にも注目していきたいと思います。