註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
Important
本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。
有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽條款,請參閱預覽功能。
在代理式檢索中,利用 檢索推理強度 來控制在知識庫擷取內容前,查詢規劃的程度。 GA 2026-10-01 REST API 支援 minimal、low 和 medium。
auto 是預覽功能,需要使用支援預覽的 API 版本。 在 2026-11-01-preview REST API 中,推理工作也可以應用在 Microsoft Retriever 1 查詢規劃上。 如需更多資訊,請參閱使用 Microsoft Retriever 1。
在知識庫或擷取請求中設定此屬性。 請求設定會覆蓋知識庫設定。 請明確設定,而非依賴服務預設值,因為預設值會因啟用的功能而異。 規劃努力與答案彙整是兩回事。
使用支援
| Azure portal | Microsoft Foundry 入口網站 | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
先決條件
一個至少包含一個知識來源的現有 知識庫 。
medium、auto、low(預覽)、答案綜合或網頁摘要需要模型,但無模型的最小萃取則不需要。允許更新與查詢知識庫。 建議使用分配給使用者帳號的搜尋服務貢獻者與搜尋索引資料閱讀器角色來設定無金鑰認證,或使用管理員 API 金鑰。
最新的
Azure.Search.Documents預覽套件:dotnet add package Azure.Search.Documents --prerelease對於無鑰匙認證,套件如下
Azure.Identity:dotnet add package Azure.Identity
最新的
azure-search-documents預覽套件:pip install --pre azure-search-documents對於無鑰匙認證,套件如下
azure-identity:pip install azure-identity
2026-10-01搜尋 REST API 的 GA 工作量等級 對於auto,REST 範例使用 2026-11-01-preview,而 SDK 範例則保留其現有的預覽套件合約。對於無金鑰認證,請在
Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。
選擇推理程度
根據您希望在延遲、成本和檢索深度之間取得的權衡,選擇適當的推理強度。
推理努力程度
在 2026-11-01-preview REST API 中,將 Microsoft Retriever 1({"kind":"microsoftRetriever1"})新增至知識庫會改變 Minimal 與 Auto Plan 查詢的方式。 有關設定步驟,請參閱使用 Microsoft Retriever 1。
Minimal:僅支援 Microsoft Retriever 1 的知識庫支援 Minimal,但不支援自動、低或中。
- 只要只有一個語意意圖包含完整問題,Minimal 就可以使用 Microsoft Retriever 1 來進行查詢規劃。
- 在多個語意意圖下,Minimal 跳過 Microsoft Retriever 1 的規劃,對每個意圖執行一般最小化檢索,然後合併結果。
自動(預覽):需要兩組模型:恰好一個 Microsoft Retriever 1 模型與一個外部
azureOpenAI或openAICompatible規劃模型,順序不限。 Microsoft Retriever 1 僅負責擷取規劃,因此答案合成需要外部模型。- 對於符合條件且具有單一語意意圖的請求,Auto 會先進行初始信心評估,並能立即回傳結果。 如果不是這樣,Auto 可以先用 Microsoft Retriever 1 進行更深入的檢索,然後再升級至外部模型的 Medium 級別。
- 當有多個語意意圖時,Auto 會跳過初始掃描與 Microsoft Retriever 1,而是從外部模型的 Medium 開始。
| 等級 | 描述 | 推薦 | 界限 |
|---|---|---|---|
minimal |
Ordinary Minimal 跳過基於模型的規劃,直接搜尋所有候選知識來源。
alwaysQuerySource: false 不會排除某個來源。 |
在你自己規劃時,請帶著語意意圖使用 minimal 。 |
|
low |
執行一次基於 LLM 的規劃與來源選擇,然後合併結果。 答案合成是可選的。 | 使用 low 進行模型支援的規劃,而無需進行更深入的迭代流程。 |
需要模型。 輸出預算取決於設定與啟用的功能,而非固定的綜合答案長度。 |
medium |
增加更深入的檢索,並評估是否需要後續迭代。 | 使用 medium 進行更深入的模型輔助檢索。 |
需要模型。 僅限 部分地區。 |
auto (預覽) |
從輕量級擷取流程開始,並可進一步採用基於模型的規劃。 | 使用 auto 讓服務為請求選擇工作量。 |
需要模型及支援的預覽 API,例如 2026-08-01-preview 或 2026-11-01-preview。
2026-10-01 中不支援。 |
如需含明確指定努力程度的 GA REST 範例,請參閱 使用 2026-10-01 REST 擷取。 另一個 2026-11-01-preview 範例請參閱〈 在 REST 中使用答案合成〉。
媒介檢索的迭代搜尋
中等擷取推理程度會在初始結果不夠相關時提供反覆搜尋。 會呼叫一個額外的 語意分類器模型 來判斷是否需要第二次迭代。
語意分類器:
可以識別出足夠的上下文來回答問題。
在結果不足的情況下重試,並利用現有資訊作為背景。 新的查詢可能會深入挖掘更具體的細節,或擴大搜尋範圍。 回應中的操作記錄顯示生成的查詢,以用於提供更全面的答案。
使用L3分類重新評分。 這個範圍與L2等級相同,絕對範圍為0到4.0。
只有一次重試。 每次迭代都會增加延遲和成本,因此系統會限制重試只能通過一次。 第二次迭代則將輸入標記加入查詢管線,增加整體可計費輸入標記數。
迭代可以重複使用現有的知識來源或選擇不同的來源。 第二遍則選擇最有潛力的知識來源來補足缺失的資訊。
存儲媒體檢索的區域支援
如果您的 Foundry IQ 服務位於下列任一區域,您可以將中型擷取的推理強度設為中等:
- 美國東部 2
- 美國東部
- 美國中南部
- 美國西部 3
- 美國西部 2
- 美國西部
- 德國中西部
- 北歐
- 瑞士北部
- 瑞典中部
- 西班牙中部
- 英國南部
- 南韓中部
- 日本東部
- 東南亞
將推理努力放在知識庫中
在知識庫定義中設定 retrievalReasoningEffort 以建立查詢的預設值。
auto 推理作業需要模型設定。 以下範例保留現有 knowledgeSources 的配置 models ,將推理努力設定為 auto,並更新知識庫。
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
var endpoint = new Uri("<search-endpoint>");
var credential = new DefaultAzureCredential();
var knowledgeBaseName = "<knowledge-base-name>";
var indexClient = new SearchIndexClient(endpoint, credential);
var knowledgeBase = (
await indexClient.GetKnowledgeBaseAsync(knowledgeBaseName)).Value;
knowledgeBase.RetrievalReasoningEffort =
new KnowledgeRetrievalAutoReasoningEffort();
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
參考資料:知識庫
若要使用其他層級,請將 KnowledgeRetrievalAutoReasoningEffort 替換為 KnowledgeRetrievalLowReasoningEffort、KnowledgeRetrievalMinimalReasoningEffort 或 KnowledgeRetrievalMediumReasoningEffort。
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.knowledgebases.models import (
KnowledgeRetrievalAutoReasoningEffort,
)
endpoint = "<search-endpoint>"
credential = DefaultAzureCredential()
knowledge_base_name = "<knowledge-base-name>"
index_client = SearchIndexClient(endpoint, credential)
knowledge_base = index_client.get_knowledge_base(knowledge_base_name)
knowledge_base.retrieval_reasoning_effort = (
KnowledgeRetrievalAutoReasoningEffort()
)
index_client.create_or_update_knowledge_base(knowledge_base)
參考資料:知識庫
若要使用其他層級,請將 KnowledgeRetrievalAutoReasoningEffort 替換為 KnowledgeRetrievalLowReasoningEffort、KnowledgeRetrievalMinimalReasoningEffort 或 KnowledgeRetrievalMediumReasoningEffort。
@api-version = 2026-11-01-preview
@knowledge-base-url = {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}
PUT {{knowledge-base-url}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
{
"name": "{{knowledge-base-name}}",
"knowledgeSources": [
{
"name": "{{knowledge-source-name}}"
}
],
"models": [
{
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"authIdentity": null,
"deploymentId": "{{model-deployment-name}}",
"modelName": "{{model-name}}"
}
}
],
"retrievalReasoningEffort": {
"kind": "auto"
}
}
參考資料:知識庫 - 建立或更新
若要使用其他層級,請設 retrievalReasoningEffort.kind 為 minimal、 low或 medium。
在取回請求中設定推理努力
在擷取請求中設定 retrievalReasoningEffort 以覆蓋該請求的知識庫預設。 以下範例會傳送訊息,用 low 來覆寫前一節的預設值 auto ,並啟用答案合成(預覽)。
using Azure.Identity;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;
var endpoint = new Uri("<search-endpoint>");
var credential = new DefaultAzureCredential();
var knowledgeBaseName = "<knowledge-base-name>";
var kbClient = new KnowledgeBaseRetrievalClient(
endpoint, knowledgeBaseName, credential);
var request = new KnowledgeBaseRetrievalRequest
{
RetrievalReasoningEffort =
new KnowledgeRetrievalLowReasoningEffort(),
OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis
};
request.Messages.Add(
new KnowledgeBaseMessage(
content: new[] {
new KnowledgeBaseMessageTextContent("What is the return policy?")
}
) { Role = "user" }
);
var result = await kbClient.RetrieveAsync(request);
from azure.identity import DefaultAzureCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
KnowledgeBaseMessage,
KnowledgeBaseMessageTextContent,
KnowledgeBaseRetrievalRequest,
KnowledgeRetrievalOutputMode,
KnowledgeRetrievalLowReasoningEffort,
)
endpoint = "<search-endpoint>"
credential = DefaultAzureCredential()
knowledge_base_name = "<knowledge-base-name>"
kb_client = KnowledgeBaseRetrievalClient(
endpoint,
credential,
knowledge_base_name=knowledge_base_name,
)
request = KnowledgeBaseRetrievalRequest(
messages=[
KnowledgeBaseMessage(
role="user",
content=[
KnowledgeBaseMessageTextContent(
text="What is the return policy?"
)
],
)
],
retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort(),
output_mode=KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
)
result = kb_client.retrieve(request)
@api-version = 2026-11-01-preview
@retrieve-url = {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}/retrieve
POST {{retrieve-url}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is the return policy?"
}
]
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"outputMode": "answerSynthesis"
}
參考資料:知識檢索 - 擷取
檢索請求會根據知識庫中設定的知識來源回傳一個有根據的答案。