Important
知識庫工具的功能目前處於公開預覽階段,並受 Microsoft Azure 預覽版補充使用條款 規範。
如需了解適用於此功能的預覽條款,請參閱 「預覽功能」。
知識庫工具可讓單一知識庫支援多個供應用程式與代理程式使用的特定任務擷取工作流程。 每個工具會選擇知識來源並設定可重複使用的檢索行為,例如推理努力與輸出限制。 用戶端可以透過 REST 呼叫工具,或透過 MCP 端點發現並呼叫它。
當客戶需要一致的擷取進入點,而不必為每個要求重新建置相同的知識來源和預設設定時,請使用知識庫工具。 在本文中,您將建立一個工具,測試其儲存設定如何與請求時間控制項互動,透過 MCP 呼叫它,然後更新或移除它。
使用支援
| Azure portal | Microsoft Foundry 入口網站 | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ❌ | ❌ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Prerequisites
- 建立並查詢範例資源的權限。 使用指派給您的使用者帳戶的搜尋服務貢獻者、搜尋索引資料貢獻者及搜尋索引資料讀取器角色,設定無金鑰驗證。
- 最新版本的預覽版本
azure-search-documents,以及該套件。azure-identity請參閱 Python 用戶端函式庫。
- 一個 .NET 8 或更新版本的主控台專案,且使用最新預覽版本的
Azure.Search.Documents。 請參閱 .NET 用戶端函式庫。
建立範例知識庫
建立索引、知識來源與知識庫。
依照「連接至 Foundry IQ(Azure AI 搜尋服務)」中的說明登入。 依序執行 SDK 片段。
from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient
from azure.search.documents.indexes import SearchIndexClient
search_endpoint = "<search-endpoint>"
index_name = "kb-tools-policy-index"
knowledge_source_name = "kb-tools-policy-source"
knowledge_base_name = "kb-tools-policy-kb"
credential = DefaultAzureCredential()
index_client = SearchIndexClient(search_endpoint, credential)
search_client = SearchClient(search_endpoint, index_name, credential)
參考:DefaultAzureCredential、 SearchClient、 SearchIndexClient。
建立索引並上傳三個合成政策。
from azure.search.documents.indexes.models import (
SearchFieldDataType,
SearchIndex,
SearchableField,
SimpleField,
)
index = index_client.create_index(SearchIndex(
name=index_name,
fields=[
SimpleField(
name="id", type=SearchFieldDataType.STRING, key=True,
),
SearchableField(name="title"),
SearchableField(name="content"),
SimpleField(
name="jurisdiction",
type=SearchFieldDataType.STRING,
filterable=True,
),
],
))
documents = [
{
"id": "ca-leave",
"title": "Canadian parental leave",
"jurisdiction": "CA",
"content": (
"Canadian employees receive four weeks of paid parental leave."
),
},
{
"id": "ca-request",
"title": "Canadian leave requests",
"jurisdiction": "CA",
"content": (
"Canadian employees submit parental leave requests through "
"the HR portal at least 30 days before leave."
),
},
{
"id": "us-leave",
"title": "US parental leave",
"jurisdiction": "US",
"content": "US employees receive six weeks of paid parental leave.",
},
]
search_client.upload_documents(documents=documents)
參考資料:SearchIndexClient、 SearchIndex、 SearchClient.upload_documents。
依照 「Connect to Foundry IQ」中的說明登入。 依序執行 SDK 片段。
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
string searchEndpoint = "<search-endpoint>";
string indexName = "kb-tools-policy-index";
string knowledgeSourceName = "kb-tools-policy-source";
string knowledgeBaseName = "kb-tools-policy-kb";
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var searchClient = new SearchClient(
new Uri(searchEndpoint), indexName, credential);
參考:DefaultAzureCredential、 SearchClient、 SearchIndexClient。
建立索引並上傳三個合成政策。
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
var index = (await indexClient.CreateIndexAsync(
new SearchIndex(indexName,
[
new SimpleField("id", SearchFieldDataType.String)
{
IsKey = true,
},
new SearchableField("title"),
new SearchableField("content"),
new SimpleField("jurisdiction", SearchFieldDataType.String)
{
IsFilterable = true,
},
])).Value;
var documents = new SearchDocument[]
{
new()
{
["id"] = "ca-leave",
["title"] = "Canadian parental leave",
["jurisdiction"] = "CA",
["content"] =
"Canadian employees receive four weeks of paid parental leave.",
},
new()
{
["id"] = "ca-request",
["title"] = "Canadian leave requests",
["jurisdiction"] = "CA",
["content"] =
"Canadian employees submit parental leave requests through " +
"the HR portal at least 30 days before leave.",
},
new()
{
["id"] = "us-leave",
["title"] = "US parental leave",
["jurisdiction"] = "US",
["content"] =
"US employees receive six weeks of paid parental leave.",
},
};
await searchClient.UploadDocumentsAsync(documents);
參考:SearchIndexClient、 SearchIndex、 SearchClient.UploadDocumentsAsync。
建立知識來源。
from azure.search.documents.indexes.models import ( SearchIndexFieldReference, SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters, ) source = index_client.create_knowledge_source( SearchIndexKnowledgeSource( name=knowledge_source_name, search_index_parameters=SearchIndexKnowledgeSourceParameters( search_index_name=index_name, source_data_fields=[ SearchIndexFieldReference(name="id"), SearchIndexFieldReference(name="title"), SearchIndexFieldReference(name="content"), SearchIndexFieldReference(name="jurisdiction"), ], ), ), )參考編號:SearchIndexClient。
建立一個無需模型的知識庫,採用最少的推理與萃取式輸出。
from azure.search.documents.indexes.models import ( KnowledgeBase, KnowledgeSourceReference, ) from azure.search.documents.knowledgebases.models import ( KnowledgeRetrievalMinimalReasoningEffort, KnowledgeRetrievalOutputMode, ) knowledge_base = index_client.create_knowledge_base(KnowledgeBase( name=knowledge_base_name, knowledge_sources=[KnowledgeSourceReference(name=source.name)], retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(), output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA, ))
建立知識來源。
using Azure.Search.Documents.Indexes.Models; var source = (await indexClient.CreateKnowledgeSourceAsync( new SearchIndexKnowledgeSource(knowledgeSourceName, new SearchIndexKnowledgeSourceParameters(indexName) { SourceDataFields = { new SearchIndexFieldReference("id"), new SearchIndexFieldReference("title"), new SearchIndexFieldReference("content"), new SearchIndexFieldReference("jurisdiction"), }, }))).Value;建立一個無需模型的知識庫,採用最少的推理與萃取式輸出。
using Azure.Search.Documents.Indexes.Models; using Azure.Search.Documents.KnowledgeBases.Models; var knowledgeBase = (await indexClient.CreateKnowledgeBaseAsync( new KnowledgeBase(knowledgeBaseName, [new KnowledgeSourceReference(source.Name)]) { RetrievalReasoningEffort = new KnowledgeRetrievalMinimalReasoningEffort(), OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData, })).Value;
設定 Foundry IQ 服務端點及存取權杖。 若要取得存取權杖,請參閱 「連接至 Foundry IQ」。
@searchEndpoint = <search-endpoint> @searchAccessToken = <search-access-token> @indexName = kb-tools-policy-index @knowledgeSourceName = kb-tools-policy-source @knowledgeBaseName = kb-tools-policy-kb建立包含可搜尋政策文字及可篩選管轄區欄位的索引。
PUT {{searchEndpoint}}/indexes/{{indexName}}?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "name": "{{indexName}}", "fields": [ { "name": "id", "type": "Edm.String", "key": true }, { "name": "title", "type": "Edm.String", "searchable": true }, { "name": "content", "type": "Edm.String", "searchable": true }, { "name": "jurisdiction", "type": "Edm.String", "filterable": true } ] }參考:索引 - 建立或更新。
上傳三份模擬保單。
POST {{searchEndpoint}}/indexes/{{indexName}}/docs/index?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "value": [ { "@search.action": "upload", "id": "ca-leave", "title": "Canadian parental leave", "jurisdiction": "CA", "content": "Canadian employees receive four weeks of paid parental leave." }, { "@search.action": "upload", "id": "ca-request", "title": "Canadian leave requests", "jurisdiction": "CA", "content": "Canadian employees submit parental leave requests through the HR portal at least 30 days before leave." }, { "@search.action": "upload", "id": "us-leave", "title": "US parental leave", "jurisdiction": "US", "content": "US employees receive six weeks of paid parental leave." } ] }參考資料:文件 - 索引。
建立知識來源。
PUT {{searchEndpoint}}/knowledgesources/{{knowledgeSourceName}}?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "name": "{{knowledgeSourceName}}", "kind": "searchIndex", "searchIndexParameters": { "searchIndexName": "{{indexName}}", "sourceDataFields": [ { "name": "id" }, { "name": "title" }, { "name": "content" }, { "name": "jurisdiction" } ] } }參考:知識來源 - 建立或更新。
建立具備最低推理與擷取輸出的知識庫。
PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "name": "{{knowledgeBaseName}}", "knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }], "retrievalReasoningEffort": { "kind": "minimal" }, "outputMode": "extractiveData" }參考:知識庫 - 建立或更新。
將自訂工具新增至知識庫
工具引用已定義於知識庫中的知識來源。 知識庫儲存工具名稱、描述及預設值。
設定加拿大知識來源參照。
from azure.search.documents.indexes.models import ( KnowledgeBaseToolKnowledgeSourceReference, ) tool_source = KnowledgeBaseToolKnowledgeSourceReference( name=source.name, filter_add_on="jurisdiction eq 'CA'", reranker_threshold=0, max_output_documents=50, fail_on_error=True, )參考:索引模型。
將此工具加入知識庫。
from azure.search.documents.indexes.models import ( KnowledgeBaseRetrieveDefaults, KnowledgeBaseTool, ) from azure.search.documents.knowledgebases.models import ( KnowledgeRetrievalMinimalReasoningEffort, ) tool = KnowledgeBaseTool( name="canada-hr-search", description="Find Canadian employee leave and benefits policies.", knowledge_sources=[tool_source], retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(), retrieve_defaults=KnowledgeBaseRetrieveDefaults( max_runtime_in_seconds=30, max_output_size_in_tokens=5000, max_output_documents=12, ), ) knowledge_base.tools = [tool] knowledge_base = index_client.create_or_update_knowledge_base( knowledge_base, )
設定加拿大知識來源的參考資料。
using Azure.Search.Documents.Indexes.Models; var toolSource = new KnowledgeBaseToolKnowledgeSourceReference(source.Name) { FilterAddOn = "jurisdiction eq 'CA'", RerankerThreshold = 0, MaxOutputDocuments = 50, FailOnError = true, };參考:索引模型。
將該工具新增至知識庫。
using Azure.Search.Documents.Indexes.Models; using Azure.Search.Documents.KnowledgeBases.Models; var tool = new KnowledgeBaseTool( "canada-hr-search", "Find Canadian employee leave and benefits policies.", [toolSource]) { RetrievalReasoningEffort = new KnowledgeRetrievalMinimalReasoningEffort(), RetrieveDefaults = new KnowledgeBaseRetrieveDefaults { MaxRuntimeInSeconds = 30, MaxOutputSizeInTokens = 5000, MaxOutputDocuments = 12, }, }; knowledgeBase.Tools.Add(tool); knowledgeBase = (await indexClient.CreateOrUpdateKnowledgeBaseAsync( knowledgeBase)).Value;
使用單一工具傳送完整的知識庫定義。
PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}
{
"name": "{{knowledgeBaseName}}",
"knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }],
"retrievalReasoningEffort": { "kind": "minimal" },
"outputMode": "extractiveData",
"tools": [{
"name": "canada-hr-search",
"description": "Find Canadian employee leave and benefits policies.",
"knowledgeSources": [{
"name": "{{knowledgeSourceName}}",
"filterAddOn": "jurisdiction eq 'CA'",
"rerankerThreshold": 0,
"maxOutputDocuments": 50,
"failOnError": true
}],
"retrievalReasoningEffort": { "kind": "minimal" },
"retrieveDefaults": {
"maxRuntimeInSeconds": 30,
"maxOutputSizeInTokens": 5000,
"maxOutputDocuments": 12
}
}]
}
參考:知識庫 - 建立或更新。
CA 篩選器應設於工具的知識來源參照,而非知識來源定義。 選取該工具後,在開始檢索之前,系統會先將檢索限制在其已設定的知識來源內。 在這個單一來源範例中,過濾器將檢索限制為加拿大文件。
叫用工具
在現有的擷取作業中選取該工具。 使用包含完整問題的語意意圖。
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
KnowledgeBaseRetrievalRequest,
KnowledgeRetrievalMinimalReasoningEffort,
KnowledgeRetrievalOutputMode,
KnowledgeRetrievalSemanticIntent,
)
question = "What parental leave do Canadian employees receive and how do they request it?"
retrieval_client = KnowledgeBaseRetrievalClient(
search_endpoint, credential, knowledge_base_name=knowledge_base.name,
)
request = KnowledgeBaseRetrievalRequest(
tool_name="canada-hr-search",
intents=[KnowledgeRetrievalSemanticIntent(search=question)],
retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(),
output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA,
include_activity=True,
)
response = retrieval_client.retrieve(request)
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;
string question = "What parental leave do Canadian employees receive and how do they request it?";
var retrievalClient = new KnowledgeBaseRetrievalClient(
new Uri(searchEndpoint), knowledgeBase.Name, credential);
var request = new KnowledgeBaseRetrievalRequest
{
ToolName = "canada-hr-search",
Intents = { new KnowledgeRetrievalSemanticIntent(question) },
RetrievalReasoningEffort =
new KnowledgeRetrievalMinimalReasoningEffort(),
OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData,
IncludeActivity = true,
};
var response = await retrievalClient.RetrieveAsync(request);
傳送一個包含完整問題的語意意圖。
POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}
{
"toolName": "canada-hr-search",
"intents": [{
"type": "semantic",
"search": "What parental leave do Canadian employees receive and how do they request it?"
}],
"retrievalReasoningEffort": { "kind": "minimal" },
"outputMode": "extractiveData",
"includeActivity": true
}
參考資料:知識檢索 - 檢索。
確認回應包含加拿大政策並排除 us-leave。 若要檢視回傳的證據與來源執行情況,請參閱 「擷取的回應」、「參考資料」陣列及 「活動」陣列。
省略工具名稱,以使用一般的知識庫檢索方式。 若工具名稱為空白或未知,則會失敗,而非回退到全知識庫檢索。
套用預設值與交集篩選器
工具預設會覆蓋知識庫預設值。 明確的請求值會覆蓋一般工具預設值,但請求篩選器不會取代工具篩選器:它們會與 AND 結合。
在加拿大基準之後使用這些控制項。 請求無法將知識來源新增到工具中,也無法取代其篩選條件。 請求的來源排除設定優先於工具的 alwaysQuerySource 設定。
無需選擇工具即可請求美國政策。
from azure.search.documents.knowledgebases.models import ( KnowledgeBaseRetrievalRequest, KnowledgeRetrievalMinimalReasoningEffort, KnowledgeRetrievalOutputMode, KnowledgeRetrievalSemanticIntent, SearchIndexKnowledgeSourceParams, ) us_request = KnowledgeBaseRetrievalRequest( intents=[KnowledgeRetrievalSemanticIntent( search="What parental leave do US employees receive?", )], knowledge_source_params=[SearchIndexKnowledgeSourceParams( knowledge_source_name=source.name, filter_add_on="jurisdiction eq 'US'", )], retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort(), output_mode=KnowledgeRetrievalOutputMode.EXTRACTIVE_DATA, include_activity=True, ) us_response = retrieval_client.retrieve(us_request)在同一個美國請求中選擇加拿大工具。
us_request.tool_name = "canada-hr-search" intersection_response = retrieval_client.retrieve(us_request)參考資料:KnowledgeBaseRetrievalClient。
有效篩選器為 CA 與 US,因此不會回傳任何結果。
在原始加拿大請求上設定一份文件的限制。
request.max_output_documents = 1 limited_response = retrieval_client.retrieve(request)
無需選擇工具即可請求美國政策。
using Azure.Search.Documents.KnowledgeBases.Models; var usRequest = new KnowledgeBaseRetrievalRequest { Intents = { new KnowledgeRetrievalSemanticIntent( "What parental leave do US employees receive?"), }, KnowledgeSourceParams = { new SearchIndexKnowledgeSourceParams(source.Name) { FilterAddOn = "jurisdiction eq 'US'", }, }, RetrievalReasoningEffort = new KnowledgeRetrievalMinimalReasoningEffort(), OutputMode = KnowledgeRetrievalOutputMode.ExtractiveData, IncludeActivity = true, }; var usResponse = await retrievalClient.RetrieveAsync(usRequest);在同一美國請求時選擇加拿大工具。
usRequest.ToolName = "canada-hr-search"; var intersectionResponse = await retrievalClient.RetrieveAsync(usRequest);參考資料:KnowledgeBaseRetrievalClient。
有效篩選器為 CA 與 US,因此不會回傳任何結果。
在原始加拿大請求上將文件預算設為 1。
request.MaxOutputDocuments = 1; var limitedResponse = await retrievalClient.RetrieveAsync(request);
使用明確的美國來源篩選器,請求不含
toolName的美國原則。POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "intents": [{ "type": "semantic", "search": "What parental leave do US employees receive?" }], "knowledgeSourceParams": [{ "knowledgeSourceName": "{{knowledgeSourceName}}", "kind": "searchIndex", "filterAddOn": "jurisdiction eq 'US'" }], "retrievalReasoningEffort": { "kind": "minimal" }, "outputMode": "extractiveData", "includeActivity": true }參考資料:知識檢索 - 檢索。
重複相同的美國問題,並在選取加拿大工具的情況下要求篩選。
POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "toolName": "canada-hr-search", "intents": [{ "type": "semantic", "search": "What parental leave do US employees receive?" }], "knowledgeSourceParams": [{ "knowledgeSourceName": "{{knowledgeSourceName}}", "kind": "searchIndex", "filterAddOn": "jurisdiction eq 'US'" }], "retrievalReasoningEffort": { "kind": "minimal" }, "outputMode": "extractiveData", "includeActivity": true }參考資料:知識檢索 - 檢索。
有效篩選器為 CA 與 US,因此不會回傳任何結果。
以單文件請求配額覆蓋工具的一般輸出文件預設值。
POST {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}/retrieve?api-version=2026-11-01-preview Content-Type: application/json Authorization: Bearer {{searchAccessToken}} { "toolName": "canada-hr-search", "intents": [{ "type": "semantic", "search": "What parental leave do Canadian employees receive and how do they request it?" }], "retrievalReasoningEffort": { "kind": "minimal" }, "outputMode": "extractiveData", "includeActivity": true, "maxOutputDocuments": 1 }參考資料:知識檢索 - 檢索。
相容的搜尋索引來源支援來源層級 filterAddOn;不相容的來源類型在儲存時會驗證失敗。 請參閱查詢時篩選以了解要求格式,並參考代理式擷取限制以了解共用限制。
透過 MCP 發現並呼叫此工具
若要探索並呼叫 canada-hr-search,請依照 呼叫 MCP 端點中的步驟操作,但針對自訂知識庫擷取工具,需做兩項調整。 請使用 2026-11-01-preview MCP 端點,因為較早的 API 版本不支援自訂工具。 當您允許或呼叫工具時,請使用已設定的名稱 canada-hr-search,而非 knowledge_base_retrieve;探索會傳回相同的名稱。
移除工具
清除工具並更新知識庫。
knowledge_base.tools = []
knowledge_base = index_client.create_or_update_knowledge_base(
knowledge_base,
)
清除工具並更新知識庫。
knowledgeBase.Tools.Clear();
knowledgeBase = (await indexClient.CreateOrUpdateKnowledgeBaseAsync(
knowledgeBase)).Value;
請連同空白的 tools 陣列一併傳送完整的知識庫定義。
PUT {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{searchAccessToken}}
{
"name": "{{knowledgeBaseName}}",
"knowledgeSources": [{ "name": "{{knowledgeSourceName}}" }],
"retrievalReasoningEffort": { "kind": "minimal" },
"outputMode": "extractiveData",
"tools": []
}
參考:知識庫 - 建立或更新。
Troubleshooting
如需更完整的疑難排解,請參閱 「使用 retrieve 動作或 MCP 端點查詢知識庫」。
清除範例資源
移除工具並不會刪除知識庫或其來源。 只刪除您為此範例建立的資源,依相依順序:知識庫、知識來源,然後索引。
index_client.delete_knowledge_base(knowledge_base_name)
index_client.delete_knowledge_source(knowledge_source_name)
index_client.delete_index(index_name)
await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
await indexClient.DeleteIndexAsync(indexName);
### Delete the owned sample KB
DELETE {{searchEndpoint}}/knowledgebases/{{knowledgeBaseName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}
### Delete the owned sample knowledge source
DELETE {{searchEndpoint}}/knowledgesources/{{knowledgeSourceName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}
### Delete the owned sample index
DELETE {{searchEndpoint}}/indexes/{{indexName}}?api-version=2026-11-01-preview
Authorization: Bearer {{searchAccessToken}}