ナレッジベースを作成する - Azure AI Search

注

現在、この機能はパブリックプレビュー段階にあります。このプレビュー版はサービスレベルアグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

Azure AI Search では、 ナレッジベース はエージェントの取得を調整する最上位レベルのオブジェクトです。クエリを実行するナレッジソースと、取得操作の既定の動作を定義します。クエリ時に、取得メソッドはナレッジベースをターゲットにして、構成された取得パイプラインを実行します。

Foundry IQ ワークロードのナレッジベースは、Microsoft Foundry (新しい) ポータルで作成できます。また、Azure AI Search API を使用して作成するすべてのエージェントソリューションのナレッジベースも必要です。

ナレッジベースでは、次の項目を指定します。

検索可能なコンテンツを指す 1 つ以上のナレッジソース。
クエリの計画と回答の定式化のための推論機能を提供するオプションの LLM。
LLM が呼び出されるかどうかを決定し、コスト、待機時間、品質を管理する検索推論プロセス。
ルーティング、ソースの選択、出力形式、およびオブジェクトの暗号化を制御するカスタムプロパティ。

ナレッジベースを作成した後は、いつでもそのプロパティを更新できます。ナレッジベースが使用中の場合、更新は次の取得に有効になります。

Important

2025-11-01-preview では、2025-08-01-preview の "ナレッジエージェント" の名前が "ナレッジベース" に変更されます。これは重大な変更です。できるだけ早い、新しい API への既存のコードからの移行をおすすめします。

[前提条件]

Azure AI Search はエージェント型情報検索を提供する任意のリージョンで利用可能です。セマンティックランカーを有効にする必要があります。デプロイされたモデルへのロールベースのアクセスにマネージド ID を使用している場合、検索サービスは Basic 価格レベル以上である必要があります。
サポートされている LLM デプロイを備えた Azure OpenAI。
検索サービスに関する 1 つ以上のナレッジソース。
Azure AI Search でオブジェクトを作成して使用するためのアクセス許可。ロールベースのアクセスをお勧めします。 Search Service 共同作成者 は、ナレッジベースを作成および管理できます。 検索インデックスデータ閲覧者 はクエリを実行できます。または、ロールの割り当てが不可能な場合は、API キーを使用することもできます。詳細については、「検索サービスへの接続」を参照してください。
Python 用 azure-search-documents クライアントライブラリの最新のプレビューバージョン。

サポートされているモデル

Azure OpenAI または同等のオープンソースモデルから、次のいずれかの LLM を使用します。デプロイ手順については、「 Microsoft Foundry を使用して Azure OpenAI モデルをデプロイする」を参照してください。

gpt-4o
gpt-4o-mini
gpt-4.1
gpt-4.1-nano
gpt-4.1-mini
gpt-5
gpt-5-nano
gpt-5-mini

アクセスを構成する

Azure AI Search では、Azure OpenAI から LLM にアクセスする必要があります。認証には Microsoft Entra ID の使用を推奨し、認可にはロールベースのアクセス制御を推奨します。ロールを割り当てるには、 所有者またはユーザーアクセス管理者である必要があります。ロールを使用できない場合は、代わりにキーベースの認証を使用してください。

ロールを使用する
キーを使用する

マネージド ID を使用するように Azure AI 検索を構成する.
Foundry Models などのモデルプロバイダーで、検索サービスのマネージド ID に Cognitive Services ユーザー を割り当てます。ローカルでテストする場合は、同じロールをユーザーアカウントに割り当てます。
ローカルテストの場合は、「クイックスタート: キーなしで接続して特定のサブスクリプションとテナントにサインインする」の手順に従います。各要求でDefaultAzureCredentialの代わりにAzureKeyCredentialを使用します。これは次の例のようになります。
```
using Azure.Search.Documents.Indexes;
using Azure.Identity;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
```

Azure portal から Azure AI Search 管理 API キーをコピーします。

AzureKeyCredentialを使用して、各要求で API キーを指定します。コードは次の例のようになります。

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

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

Important

この記事のコードスニペットでは、API キーを使用します。ロールベースの認証を使用する場合は、それに応じて各要求を更新します。両方の方法を指定する要求では、API キーが優先されます。

既存のナレッジベースを確認する

既存のナレッジベースについて知ることは、それらを再利用したり、新しいオブジェクトに名前を付けたりするのに役立ちます。 2025-08-01-preview ナレッジエージェントはすべてナレッジベースコレクションに返されます。

次のコードを実行して、既存のナレッジベースを名前で一覧表示します。

// List knowledge bases by name
  using Azure.Search.Documents.Indexes;
  
  var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
  var knowledgeBases = indexClient.GetKnowledgeBasesAsync();
  
  Console.WriteLine("Knowledge Bases:");
  
  await foreach (var kb in knowledgeBases)
  {
      Console.WriteLine($"  - {kb.Name}");
  }

名前で 1 つのナレッジベースを返して、その JSON 定義を確認することもできます。

using Azure.Search.Documents.Indexes;
using System.Text.Json;

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

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

次の JSON は、ナレッジベースの例です。

{
  "Name": "earth-knowledge-base",
  "KnowledgeSources": [
    {
      "Name": "earth-knowledge-source"
    }
  ],
  "Models": [
    {}
  ],
  "RetrievalReasoningEffort": {},
  "OutputMode": {},
  "ETag": "\u00220x8DE278629D782B3\u0022",
  "EncryptionKey": null,
  "Description": null,
  "RetrievalInstructions": null,
  "AnswerInstructions": null
}

ナレッジベースの作成

ナレッジベースによって、エージェント検索パイプラインが推進されます。アプリケーションコードでは、他のエージェントまたはチャットボットがそれを呼び出します。

ナレッジベースは、ナレッジソース (検索可能なコンテンツ) を Azure OpenAI からの LLM デプロイに接続します。 LLM のプロパティは接続を確立しますが、ナレッジソースのプロパティは、クエリの実行と応答を通知する既定値を確立します。

次のコードを実行してナレッジベースを作成します。

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

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

// Create a knowledge base
var knowledgeBase = new KnowledgeBase(
    name: knowledgeBaseName,
    knowledgeSources: new KnowledgeSourceReference[] { new KnowledgeSourceReference(knowledgeSourceName) }
)
{
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { model }
};
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBaseName}' created or updated successfully.");

# Create a knowledge base
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

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

var aoaiParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var knowledgeBase = new KnowledgeBase(
    name: "my-kb",
    knowledgeSources: new KnowledgeSourceReference[] 
    { 
        new KnowledgeSourceReference("hotels-sample-knowledge-source"),
        new KnowledgeSourceReference("earth-knowledge-source")
    }
)
{
    Description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    RetrievalInstructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    AnswerInstructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: aoaiParams) },
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort()
};

await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBase.Name}' created or updated successfully.");

ナレッジベースのプロパティ

ナレッジベースを作成するには、次のプロパティを渡します。

名前	Description	タイプ	必須
`name`	ナレッジベースの名前。ナレッジベースコレクション内で一意である必要があり、Azure AI Search のオブジェクトの名前付けガイドラインに従う必要があります。	糸	イエス
`knowledgeSources`	サポートされている 1 つ以上のナレッジソース。	Array	イエス
`Description`	ナレッジベースの説明。 LLM では、この記述を使用してクエリ計画を通知します。	糸	いいえ
`RetrievalInstructions`	ナレッジソースがクエリのスコープ内に存在する必要があるかどうかを判断するための LLM のプロンプト。複数のナレッジソースがある場合は、このプロンプトを含めます。このフィールドは、ナレッジソースの選択とクエリの作成の両方に影響します。たとえば、指示によって情報が追加されたり、ナレッジソースに優先順位が付けられたりする場合があります。命令は LLM に直接渡されます。つまり、基本的なナレッジソースをバイパスする命令など、クエリ計画を中断する命令を提供できます。	糸	イエス
`AnswerInstructions`	合成された回答を整形するためのカスタム命令。既定値は null です。詳細については、「引用に基づく応答に回答合成を使用する」を参照してください。	糸	イエス
`OutputMode`	有効な値は、0 が LLM で作成された回答を指し、1 が LLM にダウンストリームステップとして渡すことができる完全な検索結果を指します。	糸	イエス
`Models`	回答の作成やクエリの計画に使用するサポートされているLLMへの接続。このプレビューでは、 `Models` には 1 つのモデルのみを含めることができます。モデルプロバイダーは Azure OpenAI である必要があります。 Foundry ポータルまたはコマンドライン要求からモデル情報を取得します。 KnowledgeBaseAzureOpenAIModel クラスを使用してパラメーターを指定します。モデルへの Azure AI Search 接続には、API キーの代わりにロールベースのアクセス制御を使用できます。詳細については、「 Foundry を使用して Azure OpenAI モデルをデプロイする方法」を参照してください。	Object	いいえ
`RetrievalReasoningEffort`	LLM 関連のクエリ処理のレベルを決定します。有効な値は、 `minimal`、 `low` (既定値)、および `medium`です。詳細については、「取得理由の設定」を参照してください。	Object	いいえ

ナレッジベースにクエリを実行する

LLM に送信する手順とメッセージを設定します。

string instructions = @"
Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.
";

var messages = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "role", "system" },
        { "content", instructions }
    }
};

ナレッジベースで retrieve アクションを呼び出して LLM 接続を確認し、結果を返します。 retrieve要求と応答スキーマの詳細については、「Azure AI Search のナレッジベースを使用してデータを取得する」を参照してください。

"海はどこで緑色に見えますか?" を、ナレッジソースに対して有効なクエリ文字列に置き換えます。

using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

var baseClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    tokenCredential: new DefaultAzureCredential()
);

messages.Add(new Dictionary<string, string>
{
    { "role", "user" },
    { "content", @"Where does the ocean look green?" }
});

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
foreach (Dictionary<string, string> message in messages) {
    if (message["role"] != "system") {
        retrievalRequest.Messages.Add(new KnowledgeBaseMessage(content: new[] { new KnowledgeBaseMessageTextContent(message["content"]) }) { Role = message["role"] });
    }
}
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
var retrievalResult = await baseClient.RetrieveAsync(retrievalRequest);

messages.Add(new Dictionary<string, string>
{
    { "role", "assistant" },
    { "content", (retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text }
});

(retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text 

// Print the response, activity, and references
Console.WriteLine("Response:");
Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text);

重要なポイント:

KnowledgeBaseRetrievalRequest は、取得要求の入力コントラクトです。
RetrievalReasoningEffort が必要です。 minimalに設定すると、クエリパイプラインから LLM が除外され、クエリ入力には意図のみが使用されます。既定値は low であり、LLM ベースのクエリ計画と、メッセージとコンテキストを使用した応答合成をサポートします。
knowledgeSourceParams は、クエリ時に既定のパラメーターを上書きするために使用されます。

サンプルクエリへの応答は、次の例のようになります。

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

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

ナレッジベースが不要になった場合、または検索サービスでナレッジベースを再構築する必要がなくなった場合は、この要求を使用してオブジェクトを削除します。

using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

注

現在、この機能はパブリックプレビュー段階にあります。このプレビュー版はサービスレベルアグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

Azure AI Search では、 ナレッジベース はエージェントの取得を調整する最上位レベルのオブジェクトです。クエリを実行するナレッジソースと、取得操作の既定の動作を定義します。クエリ時に、取得メソッドはナレッジベースをターゲットにして、構成された取得パイプラインを実行します。

Foundry IQ ワークロードのナレッジベースは、Microsoft Foundry (新しい) ポータルで作成できます。また、Azure AI Search API を使用して作成するすべてのエージェントソリューションのナレッジベースも必要です。

ナレッジベースでは、次の項目を指定します。

検索可能なコンテンツを指す 1 つ以上のナレッジソース。
クエリの計画と回答の定式化のための推論機能を提供するオプションの LLM。
LLM が呼び出されるかどうかを決定し、コスト、待機時間、品質を管理する検索推論プロセス。
ルーティング、ソースの選択、出力形式、およびオブジェクトの暗号化を制御するカスタムプロパティ。

ナレッジベースを作成した後は、いつでもそのプロパティを更新できます。ナレッジベースが使用中の場合、更新は次の取得に有効になります。

Important

2025-11-01-preview では、2025-08-01-preview の "ナレッジエージェント" の名前が "ナレッジベース" に変更されます。これは重大な変更です。できるだけ早い、新しい API への既存のコードからの移行をおすすめします。

[前提条件]

Azure AI Search はエージェント型情報検索を提供する任意のリージョンで利用可能です。セマンティックランカーを有効にする必要があります。デプロイされたモデルへのロールベースのアクセスにマネージド ID を使用している場合、検索サービスは Basic 価格レベル以上である必要があります。
サポートされている LLM デプロイを備えた Azure OpenAI。
検索サービスに関する 1 つ以上のナレッジソース。
Azure AI Search でオブジェクトを作成して使用するためのアクセス許可。ロールベースのアクセスをお勧めします。 Search Service 共同作成者 は、ナレッジベースを作成および管理できます。 検索インデックスデータ閲覧者 はクエリを実行できます。または、ロールの割り当てが不可能な場合は、API キーを使用することもできます。詳細については、「検索サービスへの接続」を参照してください。
Python 用 azure-search-documents クライアントライブラリの最新のプレビューバージョン。

サポートされているモデル

Azure OpenAI または同等のオープンソースモデルから、次のいずれかの LLM を使用します。デプロイ手順については、「 Microsoft Foundry を使用して Azure OpenAI モデルをデプロイする」を参照してください。

gpt-4o
gpt-4o-mini
gpt-4.1
gpt-4.1-nano
gpt-4.1-mini
gpt-5
gpt-5-nano
gpt-5-mini

アクセスを構成する

Azure AI Search では、Azure OpenAI から LLM にアクセスする必要があります。認証には Microsoft Entra ID の使用を推奨し、認可にはロールベースのアクセス制御を推奨します。ロールを割り当てるには、 所有者またはユーザーアクセス管理者 である必要があります。ロールが実現できない場合は、代わりにキーベースの認証を使用します。

ロールを使用する
キーを使用する

マネージド ID を使用するように Azure AI 検索を構成する.
Foundry Models などのモデルプロバイダーで、検索サービスのマネージド ID に Cognitive Services ユーザー を割り当てます。ローカルでテストする場合は、同じロールをユーザーアカウントに割り当てます。
ローカルテストの場合は、「クイックスタート: キーなしで接続して特定のサブスクリプションとテナントにサインインする」の手順に従います。各要求でDefaultAzureCredentialの代わりにAzureKeyCredentialを使用します。これは次の例のようになります。
```
# Authenticate using roles
from azure.identity import DefaultAzureCredential
index_client = SearchIndexClient(endpoint = "search_url", credential = DefaultAzureCredential())
```

Azure portal から Azure AI Search 管理 API キーをコピーします。

AzureKeyCredentialを使用して、各要求で API キーを指定します。コードは次の例のようになります。

# Authenticate using keys
from azure.core.credentials import AzureKeyCredential
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

Important

この記事のコードスニペットでは、API キーを使用します。ロールベースの認証を使用する場合は、それに応じて各要求を更新します。両方の方法を指定する要求では、API キーが優先されます。

既存のナレッジベースを確認する

既存のナレッジベースについて知ることは、新しいオブジェクトを再利用または名前付けする場合に役立ちます。 2025-08-01-preview ナレッジエージェントはすべてナレッジベースコレクションに返されます。

次のコードを実行して、既存のナレッジベースを名前で一覧表示します。

# List knowledge bases by name
import requests
import json

endpoint = "{search_url}/knowledgebases"
params = {"api-version": "2025-11-01-preview", "$select": "name"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

名前で 1 つのナレッジベースを返して、その JSON 定義を確認することもできます。

# Get a knowledge base definition
import requests
import json

endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

次の JSON は、ナレッジベースに対する応答の例です。

{
  "name": "my-kb",
  "description": "A sample knowledge base.",
  "retrievalInstructions": null,
  "answerInstructions": null,
  "outputMode": null,
  "knowledgeSources": [
    {
      "name": "my-blob-ks"
    }
  ],
  "models": [],
  "encryptionKey": null,
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

ナレッジベースの作成

ナレッジベースによって、エージェント検索パイプラインが推進されます。アプリケーションコードでは、他のエージェントまたはチャットボットがそれを呼び出します。

ナレッジベースは、ナレッジソース (検索可能なコンテンツ) を Azure OpenAI からの LLM デプロイに接続します。 LLM のプロパティは接続を確立しますが、ナレッジソースのプロパティは、クエリの実行と応答を通知する既定値を確立します。

次のコードを実行してナレッジベースを作成します。

# Create a knowledge base
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeBaseAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeRetrievalOutputMode, KnowledgeRetrievalLowReasoningEffort

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url = "aoai_endpoint",
    api_key="aoai_api_key",
    deployment_name = "aoai_gpt_deployment",
    model_name = "aoai_gpt_model",
)

knowledge_base = KnowledgeBase(
    name = "my-kb",
    description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    answer_instructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    output_mode = KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    knowledge_sources = [
        KnowledgeSourceReference(name = "hotels-ks"),
        KnowledgeSourceReference(name = "earth-at-night-ks"),
    ],
    models = [KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters = aoai_params)],
    encryption_key = None,
    retrieval_reasoning_effort = KnowledgeRetrievalLowReasoningEffort,
)

index_client.create_or_update_knowledge_base(knowledge_base)
print(f"Knowledge base '{knowledge_base.name}' created or updated successfully.")

ナレッジベースのプロパティ

ナレッジベースを作成するには、次のプロパティを渡します。

名前	Description	タイプ	必須
`name`	ナレッジベースの名前。ナレッジベースコレクション内で一意である必要があり、Azure AI Search のオブジェクトの名前付けガイドラインに従う必要があります。	糸	イエス
`description`	ナレッジベースの説明。 LLM では、この記述を使用してクエリ計画を通知します。	糸	いいえ
`retrieval_instructions`	ナレッジソースがクエリのスコープ内に存在する必要があるかどうかを判断するための LLM のプロンプト。複数のナレッジソースがある場合は、このプロンプトを含めます。このフィールドは、ナレッジソースの選択とクエリの作成の両方に影響します。たとえば、指示によって情報が追加されたり、ナレッジソースに優先順位が付けられたりする場合があります。 LLM に命令を直接渡します。重要なナレッジソースをバイパスする命令など、クエリの計画を中断する命令を提供できます。	糸	イエス
`answer_instructions`	合成された回答を整形するためのカスタム命令。既定値は null です。詳細については、「引用に基づく応答に回答合成を使用する」を参照してください。	糸	イエス
`output_mode`	有効な値は、0 が LLM で作成された回答を指し、1 が LLM にダウンストリームステップとして渡すことができる完全な検索結果を指します。	糸	イエス
`knowledge_sources`	サポートされている 1 つ以上のナレッジソース。	Array	イエス
`models`	回答の作成やクエリの計画に使用するサポートされているLLMへの接続。このプレビューでは、 `models` には 1 つのモデルのみを含めることができます。モデルプロバイダーは Azure OpenAI である必要があります。 Foundry ポータルまたはコマンドライン要求からモデル情報を取得します。モデルへの Azure AI Search 接続には、API キーの代わりにロールベースのアクセス制御を使用できます。詳細については、「 Foundry を使用して Azure OpenAI モデルをデプロイする方法」を参照してください。	Object	いいえ
`encryption_key`	ナレッジベースと生成されたオブジェクトの両方の機密情報を暗号化するためのカスタマーマネージドキー。	Object	いいえ
`retrieval_reasoning_effort`	LLM 関連のクエリ処理のレベルを決定します。有効な値は、 `minimal`、 `low` (既定値)、および `medium`です。詳細については、「取得理由の設定」を参照してください。	Object	いいえ

ナレッジベースにクエリを実行する

ナレッジベースで retrieve アクションを呼び出して LLM 接続を確認し、結果を返します。 retrieve要求と応答スキーマの詳細については、「Azure AI Search のナレッジベースを使用してデータを取得する」を参照してください。

"海はどこで緑色に見えますか?" を、ナレッジソースに対して有効なクエリ文字列に置き換えます。

# Send grounding request
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, SearchIndexKnowledgeSourceParams

kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role = "assistant",
            content = [KnowledgeBaseMessageTextContent(text = "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.")]
        ),
        KnowledgeBaseMessage(
            role = "user",
            content = [KnowledgeBaseMessageTextContent(text = "Where does the ocean look green?")]
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name = "earth-at-night-ks",
            include_references = True,
            include_reference_source_data = True,
            always_query_source = False,
        )
    ],
    include_activity = True,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

重要なポイント:

messages は必須ですが、クエリを提供する user ロールのみを使用して、この例を実行できます。
knowledge_source_params は、1 つ以上のクエリターゲットを指定します。ナレッジソースごとに、出力に含める情報の量を指定できます。

サンプルクエリへの応答は、次の例のようになります。

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

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

ナレッジベースが不要になった場合、または検索サービスでナレッジベースを再構築する必要がなくなった場合は、この要求を使用してオブジェクトを削除します。

# Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

注

現在、この機能はパブリックプレビュー段階にあります。このプレビュー版はサービスレベルアグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

Azure AI Search では、 ナレッジベース はエージェントの取得を調整する最上位レベルのオブジェクトです。クエリを実行するナレッジソースと、取得操作の既定の動作を定義します。クエリ時に、取得メソッドはナレッジベースをターゲットにして、構成された取得パイプラインを実行します。

Foundry IQ ワークロードのナレッジベースは、Microsoft Foundry (新しい) ポータルで作成できます。また、Azure AI Search API を使用して作成するすべてのエージェントソリューションのナレッジベースも必要です。

ナレッジベースでは、次の項目を指定します。

検索可能なコンテンツを指す 1 つ以上のナレッジソース。
クエリの計画と回答の定式化のための推論機能を提供するオプションの LLM。
LLM が呼び出されるかどうかを決定し、コスト、待機時間、品質を管理する検索推論プロセス。
ルーティング、ソースの選択、出力形式、およびオブジェクトの暗号化を制御するカスタムプロパティ。

ナレッジベースを作成した後は、いつでもそのプロパティを更新できます。ナレッジベースが使用中の場合、更新は次の取得に有効になります。

Important

2025-11-01-preview では、2025-08-01-preview の "ナレッジエージェント" の名前が "ナレッジベース" に変更されます。これは重大な変更です。できるだけ早い、新しい API への既存のコードからの移行をおすすめします。

[前提条件]

Azure AI Search はエージェント型情報検索を提供する任意のリージョンで利用可能です。セマンティックランカーを有効にする必要があります。デプロイされたモデルへのロールベースのアクセスにマネージド ID を使用している場合、検索サービスは Basic 価格レベル以上である必要があります。
サポートされている LLM デプロイを備えた Azure OpenAI。
検索サービスに関する 1 つ以上のナレッジソース。
Azure AI Search でオブジェクトを作成して使用するためのアクセス許可。ロールベースのアクセスをお勧めします。 Search Service 共同作成者 は、ナレッジベースを作成および管理できます。 検索インデックスデータ閲覧者 はクエリを実行できます。または、ロールの割り当てが不可能な場合は、API キーを使用することもできます。詳細については、「検索サービスへの接続」を参照してください。
.NET SDK 用の Azure.Search.Documents クライアントライブラリの最新のプレビューバージョン。

サポートされているモデル

Azure OpenAI または同等のオープンソースモデルから、次のいずれかの LLM を使用します。デプロイ手順については、「 Microsoft Foundry を使用して Azure OpenAI モデルをデプロイする」を参照してください。

gpt-4o
gpt-4o-mini
gpt-4.1
gpt-4.1-nano
gpt-4.1-mini
gpt-5
gpt-5-nano
gpt-5-mini

アクセスを構成する

Azure AI Search では、Azure OpenAI から LLM にアクセスする必要があります。認証には Microsoft Entra ID の使用を推奨し、認可にはロールベースのアクセス制御を推奨します。ロールを割り当てるには、 所有者またはユーザーアクセス管理者である必要があります。ロールを使用できない場合は、代わりにキーベースの認証を使用してください。

ロールを使用する
キーを使用する

マネージド ID を使用するように Azure AI 検索を構成する.
Foundry Models などのモデルプロバイダーで、検索サービスのマネージド ID に Cognitive Services ユーザー を割り当てます。ローカルでテストする場合は、同じロールをユーザーアカウントに割り当てます。
ローカルテストの場合は、「クイックスタート: キーなしで接続して、特定のサブスクリプションとテナントの個人用アクセストークンを取得する」の手順に従います。各要求でアクセストークンを指定します。これは次の例のようになります。
```
# List indexes using roles
GET https://{{search-url}}/indexes?api-version=2025-11-01-preview
Content-Type: application/json
Authorization: Bearer {{access-token}}
```

Azure portal から Azure AI Search 管理 API キーをコピーします。

各要求で API キーを指定します。キーは次の例のようになります。

# List indexes using keys
GET {{search-url}}/indexes?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

Important

この記事のコードスニペットでは、API キーを使用します。ロールベースの認証を使用する場合は、それに応じて各要求を更新します。両方の方法を指定する要求では、API キーが優先されます。

既存のナレッジベースを確認する

ナレッジベースは、最上位の再利用可能なオブジェクトです。既存のナレッジベースについて知ることは、新しいオブジェクトを再利用または名前付けする場合に役立ちます。 2025-08-01-preview ナレッジエージェントはすべてナレッジベースコレクションに返されます。

ナレッジベース - リスト (REST API) を使用して、名前と種類でナレッジベースを一覧表示します。

# List knowledge bases
GET {{search-url}}/knowledgebases?api-version=2025-11-01-preview&$select=name
Content-Type: application/json
api-key: {{search-api-key}}

名前で 1 つのナレッジベースを返して、その JSON 定義を確認することもできます。

# Get knowledge base
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

次の JSON は、ナレッジベースに対する応答の例です。

{
  "name": "my-kb",
  "description": "A sample knowledge base.",
  "retrievalInstructions": null,
  "answerInstructions": null,
  "outputMode": null,
  "knowledgeSources": [
    {
      "name": "my-blob-ks"
    }
  ],
  "models": [],
  "encryptionKey": null,
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

ナレッジベースの作成

ナレッジベースによって、エージェント検索パイプラインが推進されます。アプリケーションコードでは、他のエージェントまたはチャットボットがそれを呼び出します。

ナレッジベースは、ナレッジソース (検索可能なコンテンツ) を Azure OpenAI からの LLM デプロイに接続します。 LLM のプロパティは接続を確立しますが、ナレッジソースセットのプロパティは既定でクエリの実行と応答をガイドします。

ナレッジベース - 作成または更新 (REST API) を使用して要求を作成します。

# Create a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "name" : "my-kb",
    "description": "This knowledge base handles questions directed at two unrelated sample indexes.",
    "retrievalInstructions": "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    "answerInstructions": null,
    "outputMode": "answerSynthesis",
    "knowledgeSources": [
        {
            "name": "hotels-ks"
        },
        {
            "name": "earth-at-night-ks"
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4.1-mini",
                "modelName": "gpt-4.1-mini"
            }
        }
    ],
    "encryptionKey": null,
    "retrievalReasoningEffort": {
        "kind": "low"
    }
}

ナレッジベースのプロパティ

ナレッジベースを作成するには、次のプロパティを渡します。

名前	Description	タイプ	必須
`name`	ナレッジベースの名前。ナレッジベースコレクション内で一意である必要があり、Azure AI Search のオブジェクトの名前付けガイドラインに従う必要があります。	糸	イエス
`description`	ナレッジベースの説明。 LLM では、この記述を使用してクエリ計画を通知します。	糸	いいえ
`retrievalInstructions`	ナレッジソースがクエリのスコープ内に存在する必要があるかどうかを判断するための LLM のプロンプト。複数のナレッジソースがある場合は、このプロンプトを含めます。このフィールドは、ナレッジソースの選択とクエリの作成の両方に影響します。たとえば、指示によって情報が追加されたり、ナレッジソースに優先順位が付けられたりする場合があります。 LLM に命令を直接渡します。つまり、基本的なナレッジソースをバイパスする命令など、クエリ計画を中断する命令を提供できます。	糸	イエス
`answerInstructions`	合成された回答を整形するためのカスタム命令。既定値は null です。詳細については、「引用に基づく応答に回答合成を使用する」を参照してください。	糸	イエス
`outputMode`	有効な値は、0 が LLM で作成された回答を指し、1 が LLM にダウンストリームステップとして渡すことができる完全な検索結果を指します。	糸	イエス
`knowledgeSources`	サポートされている 1 つ以上のナレッジソース。	Array	イエス
`models`	回答の作成やクエリの計画に使用するサポートされているLLMへの接続。このプレビューでは、 `models` には 1 つのモデルのみを含めることができます。モデルプロバイダーは Azure OpenAI である必要があります。 Foundry ポータルまたはコマンドライン要求からモデル情報を取得します。モデルへの Azure AI Search 接続には、API キーの代わりにロールベースのアクセス制御を使用できます。詳細については、「 Foundry を使用して Azure OpenAI モデルをデプロイする方法」を参照してください。	Object	いいえ
`encryptionKey`	ナレッジベースと生成されたオブジェクトの両方の機密情報を暗号化するためのカスタマーマネージドキー。	Object	いいえ
`retrievalReasoningEffort.kind`	LLM 関連のクエリ処理のレベルを決定します。有効な値は、 `minimal`、 `low` (既定値)、および `medium`です。詳細については、「取得理由の設定」を参照してください。	Object	いいえ

ナレッジベースにクエリを実行する

ナレッジベースで retrieve アクションを呼び出して LLM 接続を確認し、結果を返します。 retrieve要求と応答スキーマの詳細については、「Azure AI Search のナレッジベースを使用してデータを取得する」を参照してください。

ナレッジ取得 - 取得 (REST API) を使用して要求を作成します。 "海はどこで緑色に見えますか?" を、ナレッジソースに対して有効なクエリ文字列に置き換えます。

# Send grounding request
POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "messages" : [
        { "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know." }
                ]
        },
        {
            "role" : "user",
            "content" : [
                {
                    "text" : "Where does the ocean look green?",
                    "type" : "text"
                }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "earth-at-night-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "alwaysQuerySource": false
        }
  ]
}

重要なポイント:

messages は必須ですが、クエリを提供する user ロールのみを使用して、この例を実行できます。
knowledgeSourceParams は、1 つ以上のクエリターゲットを指定します。ナレッジソースごとに、出力に含める情報の量を指定できます。

サンプルクエリへの応答は、次の例のようになります。

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

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

ナレッジベースが不要になった場合、または検索サービスでナレッジベースを再構築する必要がなくなった場合は、この要求を使用してオブジェクトを削除します。

# Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{search-api-key}}

次の方法で共有

Azure AI Search でナレッジ ベースを作成する

[前提条件]

サポートされているモデル

アクセスを構成する

既存のナレッジ ベースを確認する

ナレッジ ベースの作成

ナレッジ ベースのプロパティ

ナレッジ ベースにクエリを実行する

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

[前提条件]

サポートされているモデル

アクセスを構成する

既存のナレッジ ベースを確認する

ナレッジ ベースの作成

ナレッジ ベースのプロパティ

ナレッジ ベースにクエリを実行する

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

[前提条件]

サポートされているモデル

アクセスを構成する

既存のナレッジ ベースを確認する

ナレッジ ベースの作成

ナレッジ ベースのプロパティ

ナレッジ ベースにクエリを実行する

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

関連コンテンツ

フィードバック

その他のリソース

Azure AI Search でナレッジベースを作成する

既存のナレッジベースを確認する

ナレッジベースの作成

ナレッジベースのプロパティ

ナレッジベースにクエリを実行する

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

既存のナレッジベースを確認する

ナレッジベースの作成

ナレッジベースのプロパティ

ナレッジベースにクエリを実行する

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

既存のナレッジベースを確認する

ナレッジベースの作成

ナレッジベースのプロパティ

ナレッジベースにクエリを実行する

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