設定檢索推理的努力程度（預覽）

註

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

Important

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

在代理檢索中，你可以指定大型語言模型（LLM）處理的層級，用於查詢規劃與答案表述。使用 擷取推理強度（預覽）來設定會影響成本與延遲的 LLM 處理層級。額外的 LLM 處理能提升相關性，但也花更長時間，且使用可計費的 LLM 資源。

你可以在知識庫或擷取請求中設定這個屬性。知識庫設定會為所有查詢建立預設值，而 retrieve request 設定則會依查詢逐一覆蓋預設值。若兩個設定皆不存在，服務則使用 low。

使用支援

Azure portal	Microsoft Foundry 入口網站	.NET SDK	Python SDK	Java 開發套件	JavaScript SDK	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

先決條件

一個至少包含一個知識來源和模型配置的現有知識庫。
允許更新與查詢知識庫。建議使用分配給使用者帳號的搜尋服務貢獻者與搜尋索引資料閱讀器角色來設定無金鑰認證，或使用管理員 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

搜尋服務 REST API 的 2026-08-01 預覽版。
對於無金鑰認證，請在Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。

選擇推理程度

根據您希望在延遲、成本和檢索深度之間取得的權衡，選擇適當的推理強度。

推理努力程度

等級	描述	推薦	界限
`minimal`	停用以大型語言模型（LLM）為基礎的查詢規劃，以達到代理檢索過程中最低的成本和延遲。它會在知識庫中列出的知識來源之間進行直接的文字與向量搜尋，並回傳最匹配的段落。由於知識庫中的所有知識來源都會被搜尋，且不進行查詢擴充，行為可預測且易於控制。這也代表擷取請求時的 `alwaysQueryKnowledgeSource` 屬性會被忽略。	用於 `minimal` 從搜尋 API 遷移，或是想自己管理查詢規劃時使用。	`outputMode` 必須設定為 `extractiveData`。不支援答案綜合（預覽）和網頁知識。每個知識庫最多可有 10 個知識來源。
`low`	Agent 擷取的預設模式，執行一次 LLM 型查詢規劃與知識來源選取項目。代理檢索引擎會產生子查詢，並將其分散到選定的知識來源，然後將結果合併。你可以啟用答案合成（預覽），產生帶有內嵌引用的貼近自然語言回應。	當你想要在最低延遲和更深入的處理之間取得平衡時使用 `low` 。	5,000個答案代幣。語意排序最多可達 50 份文件，若語意排序器採用 L3 分類，則最多可達 10 份文件。
`medium`	為代理檢索增加更深層的搜尋功能及強化的檢索堆疊，以最大化完整性。首次搜尋後，高精度語意分類器會評估檢索的文件。若初步結果不夠相關，服務會使用修訂後的查詢計畫進行一次後續迭代。	使用 `medium` 將 LLM 輔助的知識檢索效用最大化。	一萬個答案代幣。語意排序最多可達 50 份文件，若語意排序器使用 L3 分類，則最多可達 20 份文件。僅限部分地區。
`auto`	從輕量級的檢索階段開始。如果第一次處理已提供足夠的依據，服務就會回傳結果。否則，系統會繼續進行以 LLM 為基礎的查詢規劃，投入程度最高為中等。	當您想讓服務針對每次要求平衡檢索深度與延遲時，請使用 `auto`。	需要 2026-08-01-preview REST API。需要在知識庫中建立一個模型。適用於所有支援代理檢索的地區。早期 API 版本回傳 `400 Bad Request`。

媒介檢索的迭代搜尋

中等擷取推理程度會在初始結果不夠相關時提供反覆搜尋。會呼叫一個額外的 語意分類器模型 來判斷是否需要第二次迭代。

語意分類器：

可以識別出足夠的上下文來回答問題。
在結果不足的情況下重試，並利用現有資訊作為背景。新的查詢可能會深入挖掘更具體的細節，或擴大搜尋範圍。回應中的操作記錄顯示生成的查詢，以用於提供更全面的答案。
使用L3分類重新評分。這個範圍與L2等級相同，絕對範圍為0到4.0。

只有一次重試。每次迭代都會增加延遲和成本，因此系統會限制重試只能通過一次。第二次迭代則將輸入標記加入查詢管線，增加整體可計費輸入標記數。

迭代可以重複使用現有的知識來源或選擇不同的來源。第二遍則選擇最有潛力的知識來源來補足缺失的資訊。

存儲媒體檢索的區域支援

如果您的搜尋服務位於以下地區之一，您可以設定中等檢索推理努力：

美國東部 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)

參考資料：知識庫

@api-version = 2026-08-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);

參考資料：KnowledgeBaseRetrievalRequest

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)

參考資料：KnowledgeBaseRetrievalRequest

@api-version = 2026-08-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"
}

參考資料：知識檢索 - 檢索

檢索請求會根據知識庫中設定的知識來源回傳一個有根據的答案。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17