註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
Important
本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。
有關 Foundry IQ(Azure AI 搜尋服務)的特定預覽條款,請參閱 預覽功能。
搜尋索引知識來源將現有的 Foundry IQ(Azure AI 搜尋服務)索引(包括其已建立索引的文字和向量)連接到代理式擷取管線。 知識來源 會獨立建立,並在 知識庫中被引用,並在 執行時查詢知識庫時作為基礎資料。
使用支援
| Azure portal | Microsoft Foundry 入口網站 | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
先決條件
任何 提供代理檢索的區域內的 Foundry IQ 服務。
包含純文字或向量內容且具有語意配置的搜尋索引。 檢視代理式擷取的索引準則。 索引必須與知識庫位於相同的 Foundry IQ 服務中。
允許建立知識來源。 設定無金鑰驗證,並將搜尋服務參與者角色指派給您的使用者帳戶(建議),或使用管理員 API 金鑰。
必備的
Azure.Search.Documents套件:關於
2026-08-01-preview功能,最新預覽包:dotnet add package Azure.Search.Documents --prerelease若為
2026-10-01,最新的穩定套件:dotnet add package Azure.Search.Documents
對於無鑰匙認證,套件如下
Azure.Identity:dotnet add package Azure.Identity
必備的
azure-search-documents套件:關於
2026-08-01-preview功能,最新預覽包:pip install --pre azure-search-documents對於
2026-10-01,最新的穩定套件:pip install azure-search-documents
對於無鑰匙認證,套件如下
azure-identity:pip install azure-identity
必要的搜尋服務 REST API 版本:
預覽功能:2026-11-01-preview
一般可用功能: 2026-10-01
對於無金鑰認證,請在
Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。
Limitations
基礎索引的 defaultScoringProfile 會影響第一階段候選項選取,但它並不直接控制最終知識庫的語意排名。 擷取回應不會顯示 @search.rerankerBoostedScore。
REST 範例使用最新的預覽 API,2026-11-01-preview。 預覽版 SDK 範例會維持文件中記載的 2026-08-01-preview 合約。 在鎖定較新的 API 版本之前,請先檢查套件變更日誌。
檢查現有的知識來源
知識來源是一個頂層且可重複使用的物件。 了解現有的知識來源對於重用或命名新物件都很有幫助。
執行以下程式碼,依名稱和類型列出知識來源。
// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();
Console.WriteLine("Knowledge Sources:");
await foreach (var ks in knowledgeSources)
{
Console.WriteLine($" Name: {ks.Name}, Type: {ks.GetType().Name}");
}
# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
for ks in index_client.list_knowledge_sources():
print(f" - {ks.name} ({ks.kind})")
### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}
參考資料:知識來源 - 列表
你也可以以名稱回傳單一知識來源,以檢視其 JSON 定義。
using Azure.Search.Documents.Indexes;
using System.Text.Json;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";
// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;
// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions
{
WriteIndented = true,
DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));
# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))
### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}
參考資料:知識來源 - 取得
以下 JSON 是一個搜尋索引知識來源的範例回應。 注意知識來源指定了一個索引名稱,以及查詢中要包含哪些欄位。
{
"name": "my-search-index-ks",
"kind": "searchIndex",
"description": "A sample search index knowledge source.",
"encryptionKey": null,
"searchIndexParameters": {
"searchIndexName": "my-search-index",
"semanticConfigurationName": null,
"sourceDataFields": [],
"searchFields": []
}
}
建立知識來源
執行以下程式碼來建立搜尋索引的知識來源。
註
從 2026-05-01-preview API 版本開始,搜尋索引知識來源上的 semanticConfigurationName 為選用。 早期的 API 版本仍需 semanticConfigurationName。 如果你的知識來源需要同時支援舊版和新版 API,請持續指定 semanticConfigurationName。
// Create a search index knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Identity;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var indexKnowledgeSource = new SearchIndexKnowledgeSource(
name: knowledgeSourceName,
searchIndexParameters: new SearchIndexKnowledgeSourceParameters(searchIndexName: indexName)
{
SearchFields = { new SearchIndexFieldReference(name: "page_chunk") },
SourceDataFields = { new SearchIndexFieldReference(name: "id"), new SearchIndexFieldReference(name: "page_chunk"), new SearchIndexFieldReference(name: "page_number") }
}
);
await indexClient.CreateOrUpdateKnowledgeSourceAsync(indexKnowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSourceName}' created or updated successfully.");
# Create a search index knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters, SearchIndexFieldReference
index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())
knowledge_source = SearchIndexKnowledgeSource(
name = "my-search-index-ks",
description= "This knowledge source pulls from an existing index designed for agentic retrieval.",
encryption_key = None,
search_index_parameters = SearchIndexKnowledgeSourceParameters(
search_index_name = "search_index_name",
source_data_fields = [
SearchIndexFieldReference(name="description"),
SearchIndexFieldReference(name="category"),
],
search_fields = [
SearchIndexFieldReference(name="id")
],
)
)
index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
### Create a search index knowledge source
PUT {{search-endpoint}}/knowledgesources/my-search-index-ks?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
{
"name": "my-search-index-ks",
"kind": "searchIndex",
"description": "This knowledge source pulls from an existing index designed for agentic retrieval.",
"encryptionKey": null,
"searchIndexParameters": {
"searchIndexName": "<index-name>",
"sourceDataFields": [
{ "name": "description" },
{ "name": "category" }
]
}
}
參考:知識來源 - 建立或更新
對知識來源保留基本篩選條件(預覽)
從 API 版本開始 2026-05-01-preview ,搜尋索引知識來源可以透過屬性 baseFilter 持久化預設篩選器。 當相同的過濾表達式應套用於每個使用該知識來源的擷取要求時,請使用 baseFilter,這樣呼叫端就不必在每次呼叫時重複指定過濾條件。
以下範例會在搜尋索引知識來源上儲存基本篩選條件。
var knowledgeSource = new SearchIndexKnowledgeSource(
name: "public-docs-ks",
searchIndexParameters: new SearchIndexKnowledgeSourceParameters(searchIndexName: "public-docs-index")
{
BaseFilter = "isPublished eq true and accessScope eq 'public'"
}
);
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
knowledge_source = SearchIndexKnowledgeSource(
name="public-docs-ks",
search_index_parameters=SearchIndexKnowledgeSourceParameters(
search_index_name="public-docs-index",
base_filter="isPublished eq true and accessScope eq 'public'",
),
)
index_client.create_or_update_knowledge_source(knowledge_source)
PUT {{search-endpoint}}/knowledgesources/public-docs-ks?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
{
"name": "public-docs-ks",
"kind": "searchIndex",
"searchIndexParameters": {
"searchIndexName": "public-docs-index",
"baseFilter": "isPublished eq true and accessScope eq 'public'"
}
}
參考:知識來源 - 建立或更新
在擷取時, knowledgeSourceParams.filterAddOn 會在儲存的基底過濾器中加入請求專屬的限制:
var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.KnowledgeSourceParams.Add(
new SearchIndexKnowledgeSourceParams("public-docs-ks")
{
FilterAddOn = "category eq 'Benefits'"
}
);
request = KnowledgeBaseRetrievalRequest(
knowledge_source_params=[
SearchIndexKnowledgeSourceParams(
knowledge_source_name="public-docs-ks",
filter_add_on="category eq 'Benefits'",
),
],
)
{
"knowledgeSourceParams": [
{
"knowledgeSourceName": "public-docs-ks",
"kind": "searchIndex",
"filterAddOn": "category eq 'Benefits'"
}
]
}
有效濾鏡組成如下:
baseFilter AND filterAddOn
由於濾波器與 AND結合, filterAddOn 只能縮小持久基底濾波器範圍。 它無法取代或擴大它。
配置查詢提示(預覽)
從 2026-08-01-preview API 版本開始,查詢提示引導查詢規劃模型從使用者請求中產生篩選條件與排名提升。 將預設提示儲存在 searchIndexParameters.queryHints 中,其中可同時包含篩選條件和權重提升。
以下範例會在適用於 product-docs-index 的知識來源中儲存一個篩選提示和一個 fieldValue 提升;該知識來源具有可篩選的 productFamily 欄位以及可搜尋的 language 欄位。
using System;
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
var endpoint = new Uri("<search-endpoint>");
var indexClient = new SearchIndexClient(
endpoint,
new DefaultAzureCredential());
var queryHints = new SearchIndexKnowledgeSourceQueryHints();
queryHints.Filters.Add(
new SearchIndexKnowledgeSourceFilterHint(
"productFamily",
["Model-X100", "Model-X200"])
{
FilterInstructions =
"Filter only when the user names a model."
});
var languageBoost =
new SearchIndexKnowledgeSourceFieldValueBoost(
"language",
2.0);
languageBoost.FieldValues.Add("en-US");
languageBoost.FieldValues.Add("ja-JP");
languageBoost.BoostInstructions =
"Prefer the language requested by the user.";
queryHints.Boosts.Add(languageBoost);
var knowledgeSource = new SearchIndexKnowledgeSource(
"product-docs-ks",
new SearchIndexKnowledgeSourceParameters(
"product-docs-index")
{
QueryHints = queryHints
});
await indexClient.CreateOrUpdateKnowledgeSourceAsync(
knowledgeSource);
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
SearchIndexKnowledgeSource,
SearchIndexKnowledgeSourceFieldValueBoost,
SearchIndexKnowledgeSourceFilterHint,
SearchIndexKnowledgeSourceParameters,
SearchIndexKnowledgeSourceQueryHints,
)
endpoint = "<search-endpoint>"
index_client = SearchIndexClient(
endpoint=endpoint,
credential=DefaultAzureCredential(),
)
query_hints = SearchIndexKnowledgeSourceQueryHints(
filters=[
SearchIndexKnowledgeSourceFilterHint(
field="productFamily",
field_values=["Model-X100", "Model-X200"],
filter_instructions=(
"Filter only when the user names a model."
),
)
],
boosts=[
SearchIndexKnowledgeSourceFieldValueBoost(
field="language",
field_values=["en-US", "ja-JP"],
boost=2.0,
boost_instructions=(
"Prefer the language requested by the user."
),
)
],
)
knowledge_source = SearchIndexKnowledgeSource(
name="product-docs-ks",
search_index_parameters=SearchIndexKnowledgeSourceParameters(
search_index_name="product-docs-index",
query_hints=query_hints,
),
)
index_client.create_or_update_knowledge_source(knowledge_source)
PUT {{search-endpoint}}/knowledgesources('product-docs-ks')?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
{
"name": "product-docs-ks",
"kind": "searchIndex",
"searchIndexParameters": {
"searchIndexName": "product-docs-index",
"queryHints": {
"filters": [{
"field": "productFamily",
"fieldValues": ["Model-X100", "Model-X200"],
"filterInstructions": "Filter only when the user names a model."
}],
"boosts": [{
"kind": "fieldValue",
"field": "language",
"fieldValues": ["en-US", "ja-JP"],
"boost": 2.0,
"boostInstructions": "Prefer the language requested by the user."
}]
}
}
}
參考:知識來源 - 建立或更新
依據以下需求設定手動有依據的提示:
| Hint | 現場需求 |
fieldValues 行為 |
資料收集限制 |
|---|---|---|---|
| Filter |
field 必須指定一個可篩選的索引欄位。 |
手動接地提示需要此項。 列出所有允許的值集合。 如果請求沒有對應到某個列出的值,規劃師會被指示不要在該欄位進行篩選。 | 最多可有五個提示,且有獨特欄位。 每個值最多可包含 128 個字元,且一個提示中的所有值合計可包含最多 2,048 個字元。 |
fieldValue boost |
field 必須指定使用語言、標準或預設分析器的可搜尋欄位。 |
可選範例。 如果省略它們,請使用 boostInstructions 說明應從請求中選取哪個值。 |
最多可有五個提示,且有獨特欄位。 每個提示最多可包含 20 個值,每個值 128 個字元,總值可達 1,024 個字元。 |
multiWordExpression 加速 |
省略 field。 索引必須包含至少一個可搜尋的欄位,且該欄位使用語言、標準或預設分析器。 |
領域專屬短語的可選範例。 | 一個提示。 它最多可包含 20 個值,每個值 128 個字元,總值則為 1,024 個字元。 |
在 2026-11-01-preview 中,儲存在 searchIndexParameters.queryHints.filters 中的濾波器提示也支援 autoConfiguration。 此選項可從索引面解析基礎值,而非手動提供的 fieldValues 清單。 不要在同一個提示上同時指定兩個屬性。
對於 autoConfiguration,該欄位必須同時可篩選且可分面。 目標索引不能啟用文件層級權限或 Purview 敏感度標籤。 此選項僅支援儲存 queryHints時,不支援請求時 queryHintOverrides。
對於任一種提升類型,boost 都是必要條件,且其值必須為大於 1.0 的有限數值。 較高的分數能讓匹配文件在排名中更具影響力,但不排除其他文件。 將每個選填的 filterInstructions 或 boostInstructions 值限制為 1,024 個字元。
對於其含義無法從個別單字看出的特定領域詞組,請使用 multiWordExpression 加強。 在 fieldValues 中提供範例片語,或省略範例片語,讓 boostInstructions 和使用者的請求引導片語選擇:
{
"boosts": [{
"kind": "multiWordExpression",
"fieldValues": ["deferred tax", "wash sale"],
"boost": 3.0,
"boostInstructions": "Boost domain terms used as complete phrases."
}]
}
設計查詢提示時,請考慮以下行為:
提示會盡力套用,因此模型不一定會為每個要求產生篩選條件或提升權重。 對於必要的限制,例如授權邊界,則可改用 文件層級的存取控制 或確定 性過濾器 。
提示需要模型驅動的查詢規劃,因此當檢索推理工作量為
minimal時,提示不會被應用。 在其他努力層級,當儲存queryHints的物件包含過濾器時,GPT-4o 或 GPT-4.1 家族模型會回傳 HTTP 400。 服務會在套用queryHintOverrides之前先檢查已儲存的過濾器,因此空白覆寫或僅包含 boosts 的覆寫都不會繞過此驗證。 單靠已儲存的fieldValue和multiWordExpression加成,並不會觸發驗證。產生的篩選器會使用
AND與baseFilter和filterAddOn結合。 產生的 boost 會以完整的 Lucene 語法重寫查詢,同時保留原始詞彙。查詢提示使用索引值作為基礎。 他們不會設定分析器或啟用語言偵測。
language這些範例中的值為一般索引元資料。
若要替換單一檢索請求的儲存提示,並驗證產生的過濾器或提升,請參見查詢時覆寫儲存查詢提示(預覽)。
指派至知識庫
如果你對知識來源感到滿意,就 把它加入知識庫。
查詢知識庫
知識庫設定完成後, 呼叫擷取動作或 MCP 端點 查詢知識來源。
刪除知識來源
在刪除知識來源之前,必須刪除所有引用該來源的知識庫,或更新知識庫定義以移除該參考。 對於產生索引與索引管線的知識來源,所有 產生的物件 也會被刪除。 不過,如果你用現有的索引建立知識來源,你的索引不會被刪除。
如果你嘗試刪除正在使用的知識來源,該動作會失敗,並回傳一份受影響的知識庫清單。
刪除知識來源:
取得您 Foundry IQ 服務中所有知識庫的清單。
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}"); }一個範例回應可能如下:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }取得一個獨立的知識庫定義,以檢查是否有知識來源的參考。
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);一個範例回應可能如下:
{ "Name": "earth-knowledge-base", "KnowledgeSources": [ { "Name": "earth-knowledge-source" } ], "Models": [ {} ], "RetrievalReasoningEffort": {}, "OutputMode": {}, "ETag": "\u00220x8DE278629D782B3\u0022", "EncryptionKey": null, "Description": null, "RetrievalInstructions": null, "AnswerInstructions": null }要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。
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.");刪除知識來源。
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
取得您 Foundry IQ 服務中所有知識庫的清單。
# Get knowledge bases from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) print("Knowledge Bases:") for kb in index_client.list_knowledge_bases(): print(f" - {kb.name}")一個範例回應可能如下:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }取得一個獨立的知識庫定義,以檢查是否有知識來源的參考。
# Get a knowledge base definition from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) kb = index_client.get_knowledge_base("knowledge_base_name") print(kb)一個範例回應可能如下:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。
# 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.")刪除知識來源。
# Delete a knowledge source 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_source("knowledge_source_name") print(f"Knowledge source deleted successfully.")
取得您 Foundry IQ 服務中所有知識庫的清單。
### Get knowledge bases GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name Authorization: Bearer {{token}}參考資料:知識庫 - 列出
一個範例回應可能如下:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }取得一個獨立的知識庫定義,以檢查是否有知識來源的參考。
### Get a knowledge base definition GET {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}參考:知識庫 - 取得
一個範例回應可能如下:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }要麼刪除知識庫,要麼如果你有多個知識來源,就更新知識庫來移除該來源。 這個例子顯示刪除。
### Delete a knowledge base DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}參考資料:知識庫 - 刪除
刪除知識來源。
### Delete a knowledge source DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}參考資料:知識來源 - 刪除