在 Foundry IQ(Azure AI 搜尋服務)中建立知識庫

註

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

重要

本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。

有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽條款,請參閱預覽功能。

當您使用支援的非 Microsoft 模型時,請參閱「第三方模型」。

在 Foundry IQ(Azure AI 搜尋服務)中,知識庫是一個頂層物件,負責協調代理檢索。 它定義要查詢哪些知識來源,以及檢索操作的預設行為。 在查詢時, 檢索方法 會針對知識庫執行已設定的檢索管線。

知識庫規定:

  • 一個或多個指向可搜尋內容的知識來源。

  • 用於查詢規劃、答案合成或 Web 內容摘要的選用 LLM。 支援的任務依 API 版本及知識來源類型而異。

  • 自訂屬性控制路由、來源選擇與物件加密。

使用支援

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

先決條件

  • Foundry IQ 適用於任何 提供代理檢索的區域。 如果您使用 受管理身份 來以角色為基礎存取已部署模型,您的 Foundry IQ 服務必須設定在基本層級或更高等級。

  • 一個或多個 知識來源。 使用 2026-10-01 來處理 GA REST 契約,包括模型支援的規劃與答案綜合。 使用 2026-11-01-preview 來預覽知識來源與功能。

  • (條件式)對於原生 Azure OpenAI 連線,需要 支援的 LLM 部署。 若要查看經由 Azure API 管理 的客戶控制模型端點,請參閱「透過 Azure API 管理 進行連線(預覽版)」。 low 或 medium 規劃、答案整合和網頁摘要需要 LLM。 使用既有搜尋索引或檔案來源的知識庫,可以使用 minimal 心力,且可以使用 extractiveData,而無需模型或擷取與回答指示。

  • 允許建立知識庫。 設定無金鑰驗證,並將搜尋服務參與者角色指派給您的使用者帳戶(建議),或使用管理員 API 金鑰。

  • 若要進行原生 LLM 管理式身分驗證,請在裝載該部署且與相符的父層 Azure OpenAI 或 Microsoft Foundry 資源上,將 Cognitive Services OpenAI 使用者 指派給所選的 resourceUri。 請勿將此模型存取角色指派於 Foundry IQ 服務、Foundry 專案或個別部署。 相容的閘道自訂受眾需要各自的授權設定;不要假設同樣的角色也適用。 請參閱 相容驗證。

  • 必備的 Azure.Search.Documents 套件:

    • 針對 SDK 定義管理範例,最新的預覽套件: 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 套件:

    • 針對 SDK 定義管理範例,最新的預覽套件: 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

    • 對於本文所述的 GA 合約: 2026-10-01。 較舊的 2026-04-01 範例則保留其較狹義的契約。

  • 對於無金鑰認證,請在Authorization每個 HTTP 請求的標頭中加入 Microsoft Entra ID 令牌。

支援的模型

在 Foundry 模型中使用 Azure OpenAI 中的以下 LLM 之一。 Azure OpenAI 會決定你所選擇部署的區域可用性。 部署說明請參見 Foundry 入口網站 中的 部署 Microsoft Foundry 模型。

GPT-4 家族已被棄用。 關於模型生命週期指引、退役日期及現況,請參見「模型退役與淘汰」及「模型退役時程-Microsoft Foundry」。

模型 支援的 API 版本
gpt-4o (已廢止) 2025-11-01-預覽,2026-05-01-預覽,2026-08-01-預覽
gpt-4o-mini (已廢止) 2025-11-01-預覽,2026-05-01-預覽,2026-08-01-預覽
gpt-4.1 (已廢止) 2025-11-01-預覽,2026-05-01-預覽,2026-08-01-預覽
gpt-4.1-mini (已廢止) 2025-11-01-預覽,2026-05-01-預覽,2026-08-01-預覽
gpt-4.1-nano (已廢止) 2025-11-01-預覽,2026-05-01-預覽,2026-08-01-預覽
gpt-5 2025-11-01-預覽,2026-05-01-預覽,2026-08-01-預覽
gpt-5-mini 2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview, 2026-10-01
gpt-5-nano 2025-11-01-preview, 2026-05-01-preview, 2026-08-01-preview, 2026-10-01
gpt-5.1 2026-05-01-預覽,2026-08-01-預覽
gpt-5.2 2026-05-01-預覽,2026-08-01-預覽
gpt-5.4 2026-05-01-preview, 2026-08-01-preview, 2026-10-01
gpt-5.4-mini 2026-05-01-preview, 2026-08-01-preview, 2026-10-01
gpt-5.4-nano 2026-05-01-preview,2026-08-01-preview,2026-10-01
gpt-5.5 2026-08-01-preview, 2026-10-01
gpt-5.6-sol 2026-08-01-preview, 2026-10-01
gpt-5.6-terra 2026-08-01-preview, 2026-10-01
gpt-5.6-luna 2026-08-01-preview, 2026-10-01
gpt-6-astra 2026-11-01-preview
gpt-6-sol 2026-11-01-preview
gpt-6-luna 2026-11-01-preview
gpt-6.1-sol 2026-11-01-preview

前表中所有模型設定檔均支援 2026-11-01-preview。

對於 2026-11-01-preview,Microsoft Retriever 1 是一個無參數的規劃模型,配置為 {"kind":"microsoftRetriever1"}。 它不需要客戶模型連線。 僅使用 Microsoft Retriever 1 的知識庫支援 minimal 推理與擷取輸出,不支援外部答案綜合。 請參閱使用 Microsoft Retriever 1。

對於 GPT-6 家族中的原生 Azure OpenAI 模型,請使用 azureOpenAIParameters.resourceUri、deploymentId 和精確支援的 modelName 來設定現有部署。 部署 ID 與模型名稱為不同的值。

透過 Azure API 管理 連線(預覽版)

註

與 OpenAI 相容的知識庫模型連線需要 2026-11-01-preview。 2026-10-01 不支援它們。

將 kind 設為 azureOpenAI 的知識庫模型需要原生 Azure OpenAI 或 Microsoft Foundry 端點。 對於 API 管理(APIM)或自訂網域端點,請將 kind 設為 openAICompatible,並設定 openAICompatibleParameters。

若要切換現有模型連線,請在同一模型項目中將 azureOpenAIParameters 替換為 openAICompatibleParameters。 提供 uri 和新的驗證資訊,使用下述的 headers 或明示的 managedIdentityAudience。 使用 2026-11-01-preview 或較新的受支援預覽版本來更新現有知識庫;您不需要重新建立它。

設定 uri 為完整的 HTTPS POST 端點,包括其路徑及必要的查詢參數。 搜尋會依照提供的方式發送請求到此網址,且不會跟隨重新導向。

設定 modelName 為支援的搜尋聊天模型設定檔。 它決定的是 Search 的功能、限制與規範,而非閘道器的實際部署。 現有的聊天模型設定檔使用 Chat Completions;GPT-6 設定檔使用 Responses。 端點必須支援所選協定。 搜尋會 model 省略出站檢索請求的主體,因此 URI 或閘道必須選擇實際模型並提供提供者所需的模型識別碼。 不支援嵌入模型和任意提供者協定。

GPT-5.6 聊天完成無法將工具與推理結合。 搜尋對於這些工具請求會省略 reasoning_effort,但 Azure OpenAI 會將省略的值預設為 medium。 如果您的閘道將 GPT-5.6 設定檔導向 Azure OpenAI GPT-5.6 部署,當請求包含工具時,請將 reasoning_effort 設為 none。 請參見 使用推理模型的工具呼叫。

對於 Responses,端點必須支援無狀態工具的延續,而非僅支援初始回應。 搜尋會傳送將 store 設為 false 的內容,並請求 reasoning.encrypted_content。

請選擇一種驗證模式:

Mode 連線設定
標頭 將 headers 設定為非空的字串對字串的端點驗證標頭對應表。 也不要設定 managedIdentityAudience 或 authIdentity。
受管理的識別 設定managedIdentityAudience為您第三方 Microsoft Entra 應用程式的純正典應用程式 GUID,而非 Microsoft 第一方應用程式。 不要加上 api:// 前綴或 /.default 後綴,也不要設定 headers。 省略 authIdentity 以使用 Foundry IQ 服務的系統指派身分。 對於使用者指派的身份,將其設定 @odata.type 為 #Microsoft.Azure.Search.DataUserAssignedIdentity ,且 userAssignedIdentity 設定為完整資源 ID。 該身份必須已指派給 Foundry IQ 服務。

驗證標頭名稱與值皆為秘密、唯寫設定,且不會在 API 表示中回傳。 更新時,省略標頭僅能在相同資源與模型綁定、精確 URI、未變更的支援模型設定檔,以及未變更的驗證身份與模式下繼續。 當綁定變更時,請提供新的憑證;在重新排序 models 陣列後,不要依賴標頭保留。

在具備網頁知識來源的知識庫中,即使端點 URL 看起來像原生的 Azure OpenAI URL,也無法支援相容模型。 當 Foundry IQ 服務 dataExfiltrationProtections 包含 All時,這些連線也會被封鎖。

對於回應設定檔,請使用支援回應與無狀態工具延續的端點。 例如,請以以下內容傳送相同的 PUT 運算:

{
  "name": "<knowledge-base-name>",
  "knowledgeSources": [
    { "name": "<knowledge-source-name>" }
  ],
  "models": [
    {
      "kind": "openAICompatible",
      "openAICompatibleParameters": {
        "uri": "https://<gateway-host>/openai/v1/responses",
        "modelName": "gpt-6.1-sol",
        "managedIdentityAudience": "11111111-2222-3333-4444-555555555555"
      }
    }
  ]
}

將範例 GUID 替換為接收應用程式的標準格式 Microsoft Entra 應用程式 ID。 不要使用 api://(範圍:/.default)或認知服務受眾。 此範例使用 Foundry IQ 服務的系統指派身份。 若要選擇附加的使用者指派身份,請新增 支援的身份物件。

搜尋發送 store:false 與延續結構,包含加密推理內容以及函數呼叫的輸入與輸出。 端點必須保留這些結構。 與相容的聊天完成一樣,搜尋會省略出站 model。 與此相容流程不同,原生 GPT-6 知識庫擷取會傳送部署 ID。model/openai/v1/responses 不要假設會回退到聊天完成。

連線與更新需求

  • 提供完整的絕對 HTTPS POST URL,包括路徑與查詢參數。 搜尋不會附加操作或 API 版本,也不會跟隨重定向,即使是指向同一主機。 不要包含憑證或 URL 片段。
  • 請使用來自 Supported models 的精確正式標準設定檔名稱。 modelName 選擇搜尋功能,而非實際提供者部署。 相容合約沒有任何過期 modelVersion 的屬性。
  • 在建立時提供一個非空的 headers 映射或 managedIdentityAudience。 authIdentity 僅可與後者一同使用。 空標頭、兩種模式,或無模式皆無效。
  • 在 2026-11-01-preview 中,同一 KB 的讀取後 PUT 更新僅適用於現有有效的標頭驗證相容模型綁定,且只能保留已省略的 headers。 保持模型類型、精確 URI(包括路徑與查詢文字)、設定檔及身份設定不變,完全省 headers 略。 明確的 null、空的對應表或各個標頭的遮蔽字串,並非省略屬性的更新模式。
  • 複製、重新命名或變更目的地、設定檔或身份時,需要重新驗證。 若要旋轉標頭,請在完整的 KB 定義中提供替換映射。 若要變更為受控身分,請明確設定 managedIdentityAudience 和所選身分。 被拒絕的更新會保留現有的認證。
  • 私有連線需要一條從實際執行主機出發的路由。 僅靠 API 管理閘道共享私有連結,無法建立相容的 KB 私有路由支援。

GET 輸出缺少相容 headers性;它不會備份這些憑證。 不要把 <redacted> 或 <unchanged> 當作閘道憑證發送。 新 KB 沒有可從複製定義中繼承的標頭。 請在建立前先驗證並提供目標驗證資訊,而不是建立無效的中間知識庫。

首先,使用 Content-Type: application/json、你的 Search 驗證和 PUT https://<search-service>.search.windows.net/knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview 來建立標頭驗證的知識庫。 請將以下內容中的佔位符替換為您的值,省略 description,並新增一個包含閘道驗證標頭與憑證的非空 openAICompatibleParameters.headers 映射。

建立成功後,請將以下內容提交至相同的 PUT URL,使用相同的替換值但省 headers略 。 更新會變更描述並保留已儲存的標頭。 請保持 KB 名稱、來源、模型類型、精確 URI 及設定檔不更改:

{
  "name": "<knowledge-base-name>",
  "description": "Updated description",
  "knowledgeSources": [
    { "name": "<knowledge-source-name>" }
  ],
  "models": [
    {
      "kind": "openAICompatible",
      "openAICompatibleParameters": {
        "uri": "https://<apim-name>.azure-api.net/openai/deployments/<deployment>/chat/completions?api-version=<downstream-api-version>",
        "modelName": "gpt-5.4"
      }
    }
  ]
}

參考資料: 知識庫 - 建立或更新。

有關驗證範例、憑證轉換、安全性責任及疑難排解,請參閱〈 在 Foundry IQ 模型呼叫中使用 API 管理〉。

驗證擷取模型連線

成功建立 KB 或執行 GET 要求可驗證設定,而非外寄模型呼叫。 使用關於知識庫現有知識來源內容的測試題。

  1. 請依照「使用 REST 呼叫擷取動作」以及您先前設定的相同 <knowledge-base-name> 。 使用您現有的搜尋驗證,將 POST 傳送至 https://<search-service>.search.windows.net/knowledgebases('<knowledge-base-name>')/retrieve?api-version=2026-11-01-preview。 請使用十一月預覽版進行此檢查,而非指南中保留的範例版本。
  2. 在請求主體中,提供messages包含role: "user"一個訊息,其content陣列包含type: "text"一個項目以及你在text中的問題。 將 retrievalReasoningEffort 設為 {"kind": "low"}、將 outputMode 設為 "extractiveData",並將 includeActivity 設為 true。 低推理投入可鍛鍊 LLM 的查詢規劃能力;而最少的檢索並未驗證這種關聯。
  3. 確認成功擷取,並檢查活動陣列中modelQueryPlanning及回傳的權杖使用情況。 檢視檢索到的測試問題內容。 對於閘道連線,請在淨化閘道遙測中確認預定的作業路徑、後端路由及設定檔所選協定。 在回應中,確認工具延續成功且不會丟棄加密推理或函式呼叫結構。
  4. 在輪換標頭憑證後,重複相同的擷取請求並確認閘道接受替換。 接著使用 November 預覽,對同一個 KB 的未變更定義進行 GET 和 PUT。 GET中標頭依然缺失;當綁定、精確端點、設定檔及身份未變更時,擷取仍應成功。 如果設定更新被拒絕,請確認擷取是否仍能使用先前儲存的認證進行。

僅記錄非機密結果、狀態碼及活動中繼資料。 不要記錄憑證標頭名稱或值、存取權杖或敏感的請求與回應內容。 這些檢查是驗證您已設定的連線,而非整個供應商的可用性或私有路由資格。

設定存取權限

如果您的知識庫使用 Azure OpenAI 模型,Foundry IQ 需要存取該模型。 我們建議使用 Microsoft Entra ID 進行認證,並以角色為基礎存取授權。 要指派角色,您必須是 擁有者或使用者存取管理員。 如果不能用角色,改用基於金鑰的認證。

  1. 在 Foundry IQ 上啟用角色型存取控制。

  2. 設定 Foundry IQ 以使用受管理身份。

  3. 在您的模型提供者上,將 認知服務使用者 指派給您 Foundry IQ 服務的受控識別。 如果你是在本地測試,請把同樣的角色分配給你的使用者帳號。

  4. 本地測試時,請依照 快速入門中的步驟操作:無需金鑰連接 以登入特定訂閱和租戶。 在 DefaultAzureCredential 每個請求中使用 代替 AzureKeyCredential ,這應該與以下範例相似。

    // Authenticate using roles
    using Azure.Search.Documents.Indexes;
    using Azure.Identity;
    
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
    
  1. 在 Foundry IQ 上啟用基於角色的存取控制。

  2. 設定 Foundry IQ 以使用受管理身份。

  3. 在您的模型提供者上,將 認知服務使用者 指派給您 Foundry IQ 服務的受控識別。 如果你是在本地測試,請把同樣的角色分配給你的使用者帳號。

  4. 本地測試時,請依照 快速入門中的步驟操作:無需金鑰連接 以登入特定訂閱和租戶。 在 DefaultAzureCredential 每個請求中使用 代替 AzureKeyCredential ,這應該與以下範例相似。

    # Authenticate using roles
    from azure.identity import DefaultAzureCredential
    index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())
    
  1. 在 Foundry IQ 上啟用基於角色的存取控制。

  2. 設定 Foundry IQ 以使用受管理身份。

  3. 在您的模型提供者上,將 認知服務使用者 指派給您 Foundry IQ 服務的受控識別。 如果你是在本地測試,請把同樣的角色分配給你的使用者帳號。

  4. 本地測試時,請依照 快速啟動的步驟操作:無鑰匙連線 以獲得特定訂閱和租戶的個人存取權杖。 在每個請求中指定你的存取權杖,應該與以下範例相似。

    # List indexes using roles
    GET {{search-endpoint}}/indexes?api-version=2026-10-01
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}
    

SDK 定義管理範例使用管理 API 金鑰。 關於建議的無金鑰設定,請參閱 「設定存取」。

檢查現有的知識庫

知識庫是一個頂層且可重複使用的物件。 了解現有的知識庫對於重用或命名新物件都很有幫助。

使用定義客戶端列出您所選 API 版本的知識庫。 Python 範例會迭代原生分頁清單。 C# 範例使用前綴搜尋,頁面大小為 10。

using System;
using System.Collections.Generic;
using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
var key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
var indexClient = new SearchIndexClient(
    endpoint, new AzureKeyCredential(key));
var knowledgeBases = new List<KnowledgeBase>();
await foreach (var kb in indexClient.GetKnowledgeBasesAsync(
    search: "sdk-", pageSize: 10, searchType: ListingSearchType.Prefix))
{
    knowledgeBases.Add(kb);
}

參考:SearchIndexClient

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    credential=AzureKeyCredential(os.environ["SEARCH_API_KEY"]),
)
knowledge_bases = list(index_client.list_knowledge_bases())

參考:SearchIndexClient

# List knowledge bases
GET {{search-endpoint}}/knowledgebases?api-version={{api-version}}&$select=name
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

參考資料:知識庫 - 列表

依名稱讀取現有知識庫並檢查所選定義屬性。 使用 SDK 建立範例中的名稱,或以你可以讀取的知識庫取代。

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

var endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
var key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
var indexClient = new SearchIndexClient(
    endpoint, new AzureKeyCredential(key));
var kb = (await indexClient.GetKnowledgeBaseAsync("<knowledge-base-name>")).Value;

參考:SearchIndexClient

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    credential=AzureKeyCredential(os.environ["SEARCH_API_KEY"]),
)
kb = index_client.get_knowledge_base("<knowledge-base-name>")

參考:SearchIndexClient

# Get knowledge base
GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

參考:知識庫 - 取得

以下 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"
  }
}

註

使用目標 API 版本的合約讀取及寫入定義。 僅預覽的屬性不包含在 2026-10-01 結構描述中。 關於版本特定的變更,請參閱 遷移代理式擷取程式碼。

建立知識庫

重要

舊版 2026-04-01 API 支援極簡、擷取式的檢索,但不支援模型支援的規劃或答案生成。 這些功能可在 GA 2026-10-01 REST 合約中使用。 不要僅藉由變更 API 版本來移轉預覽定義。

知識庫會將一或多個知識來源 (可搜尋內容) 連線到 Foundry Models 中來自 Azure OpenAI 的選用 LLM。 省略 models 建立無模型的知識庫。 你設定的屬性會建立查詢執行和檢索回應的預設值。

建立知識庫後,您可以更新其屬性,包括 將原生模型連線切換至 APIM 或自訂網域端點。 如果知識庫正在使用中,更新會在下一次檢索時生效。

使用現有且已填入資料的搜尋索引知識來源,以及具有建立知識庫權限的授權憑證。 將 {{knowledge-source-name}}、{{search-token}} 和 {{search-endpoint}} 替換為你的輸入。 此範例建立不需模型的擷取式檢索知識庫。

PUT {{search-endpoint}}/knowledgebases('core-minimal-kb')?api-version=2026-10-01
Content-Type: application/json
Authorization: Bearer {{search-token}}

{
  "name": "core-minimal-kb",
  "knowledgeSources": [
    { "name": "{{knowledge-source-name}}" }
  ],
  "retrievalReasoningEffort": {
    "kind": "minimal"
  },
  "outputMode": "extractiveData"
}

參考:知識庫 - 建立或更新

在此合約中,每個 knowledgeSources 條目僅包含 name。 將來源設定(例如 searchIndexParameters.baseFilter)儲存在知識來源上。 在擷取時的 failOnError 中設定請求專屬選項,例如 knowledgeSourceParams 和 alwaysQuerySource,而非在 KB 成員項目中。

auto、retrieveDefaults 和 neverQuerySource 不屬於 GA 合約範圍。

接著, 使用 2026-10-01 REST 進行擷取。

設定預設取回限制(預覽)

從 API 版本開始 2026-08-01-preview ,你可以使用可選 retrieveDefaults 物件將請求範圍的預設值儲存在知識庫中。

retrieveDefaults 在 2026-10-01 中無法使用。 在那份 GA 合約中,設定 retrieve 請求的上限,並將 maxOutputSizeInTokens 用於 token 預算。

在預覽範例中,每個儲存屬性僅在請求省略對應請求欄位時才適用:

存放財產 擷取請求欄位
maxRuntimeInSeconds maxRuntimeInSeconds
maxOutputDocuments maxOutputDocuments
maxOutputSizeInTokens maxOutputSize

輸出權杖預算在儲存及覆寫時會使用不同的屬性名稱。 在 retrieveDefaults 中設定 maxOutputSizeInTokens,並在擷取要求中使用 maxOutputSize。

每個物業的有效價值依以下順序獨立確定:

  1. 擷取要求中的對應值。
  2. 知識庫 retrieveDefaults 物件的價值。
  3. 當兩個層級都沒有此屬性時所採用的服務預設值。

以下範例使用一個名為 your-knowledge-source的現有搜尋索引知識來源。 它儲存 45 秒的執行預算,最多可儲存八個輸出文件,以及 12,000 個代幣的輸出預算。

using System;
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

string searchEndpoint = "<search-endpoint>";

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

var knowledgeBase = new KnowledgeBase(
    "your-knowledge-base",
    new[] { new KnowledgeSourceReference("your-knowledge-source") })
{
    Description = "A knowledge base for product support content.",
    RetrieveDefaults = new KnowledgeBaseRetrieveDefaults
    {
        MaxRuntimeInSeconds = 45,
        MaxOutputDocuments = 8,
        MaxOutputSizeInTokens = 12000
    }
};

await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);

參考:SearchIndexClient、 SearchClientOptions.ServiceVersion、 KnowledgeBase

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    KnowledgeBase,
    KnowledgeBaseRetrieveDefaults,
    KnowledgeSourceReference,
)

search_endpoint = "<search-endpoint>"
index_client = SearchIndexClient(
    endpoint=search_endpoint,
    credential=DefaultAzureCredential(),
)

knowledge_base = KnowledgeBase(
    name="your-knowledge-base",
    description="A knowledge base for product support content.",
    knowledge_sources=[
        KnowledgeSourceReference(name="your-knowledge-source"),
    ],
    retrieve_defaults=KnowledgeBaseRetrieveDefaults(
        max_runtime_in_seconds=45,
        max_output_documents=8,
        max_output_size_in_tokens=12000,
    ),
)

index_client.create_or_update_knowledge_base(knowledge_base)

參考:SearchIndexClient, 知識庫

PUT {{search-endpoint}}/knowledgebases/your-knowledge-base?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "your-knowledge-base",
  "description": "A knowledge base for product support content.",
  "knowledgeSources": [
    {
      "name": "your-knowledge-source"
    }
  ],
  "retrieveDefaults": {
    "maxRuntimeInSeconds": 45,
    "maxOutputDocuments": 8,
    "maxOutputSizeInTokens": 12000
  }
}

參考資料:知識庫 - 建立或更新

若要覆寫單一請求的儲存值,請在預覽擷取請求中設定對應 maxRuntimeInSeconds的 、 maxOutputDocuments、 及 maxOutputSize 欄位。

設定 CORS 以瀏覽器為基礎的擷取呼叫

重要

跨來源資源共享(CORS)允許瀏覽器應用程式直接向服務請求資料。 根據您的 CORS 設定,外部網頁可能會利用使用者的瀏覽器上下文存取或調用服務及其資料。 這種存取可能造成安全威脅。 啟用 CORS 風險自負。

自 2026-05-01-preview API 版本起,知識庫可為以瀏覽器為基礎、直接從 JavaScript 呼叫 retrieve 動作的應用程式定義 corsOptions。 CORS 政策會識別哪些瀏覽器來源可以向知識庫發送檢索請求。

CORS 也支援於 2026-10-01。 當您省略 corsOptions時,預設入口網站來源仍被允許,但不允許未設定的自訂來源。 CORS 控制的是瀏覽器存取,而非授權:呼叫者仍需取得存取內容的權限。

使用受信任來源清單,或單一 "*" 值。 不要和其他來源混在一起 "*" 。 maxAgeInSeconds 控制預檢快取,接受非負值,預設為五分鐘。

對於 GA REST,請使用既有且已填充的搜尋索引知識來源,並指定名稱 product-docs-ks 並授權憑證建立知識庫。

PUT {{search-endpoint}}/knowledgebases('browser-chat-kb')?api-version=2026-10-01
Content-Type: application/json
Authorization: Bearer {{search-token}}

{
  "name": "browser-chat-kb",
  "knowledgeSources": [
    { "name": "product-docs-ks" }
  ],
  "retrievalReasoningEffort": {
    "kind": "minimal"
  },
  "outputMode": "extractiveData",
  "corsOptions": {
    "allowedOrigins": ["https://myapp.example.com"],
    "maxAgeInSeconds": 300
  }
}

參考資料:知識庫 - 建立或更新

若要單獨檢查 CORS 政策:

  1. 使用 api-version=2026-10-01,將 OPTIONS 預檢傳送至此知識庫的擷取路徑。 設定 Origin 為 https://myapp.example.com,請求 POST 方法,並指出擷取請求所使用的標頭。
  2. 檢查回應的允許來源與預檢快取標頭。 對於此已設定的來源,預期政策會允許該來源並使用已設定的 300 秒預檢快取存留時間。
  3. 對未設定的自訂來源重複此操作。 預期不會獲得CORS對該來源的許可;不要從特定的拒絕狀態代碼推斷結果。
  4. 請另行發送授權的取回請求。 建立政策或預先檢查不會授予內容存取權。 HTTP 預檢不會決定瀏覽器行為或呼叫者文件的權限。

SDK 範例更新現有的知識庫。 只使用你打算修改的知識庫。 每個範例會讀取現有模型、變更已儲存的配置、儲存後再讀取回來。 這些定義操作不會驗證 HTTP 或瀏覽器對 CORS 的強制執行。

保留現有允許的來源,並將描述及預檢快取時間更改為 120 秒。 知識庫必須已經定義 CorsOptions。

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

var endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
var key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
var indexClient = new SearchIndexClient(
    endpoint, new AzureKeyCredential(key));
var kb = (await indexClient.GetKnowledgeBaseAsync("<knowledge-base-name>")).Value;
kb.Description = "Updated CORS configuration.";
kb.CorsOptions.MaxAgeInSeconds = 120;
var updated = (await indexClient.CreateOrUpdateKnowledgeBaseAsync(kb)).Value;
var readback = (await indexClient.GetKnowledgeBaseAsync(updated.Name)).Value;

參考:CorsOptions, 知識庫

設定預定允許的來源及 60 秒的預檢快取時間。

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import CorsOptions

index_client = SearchIndexClient(
    endpoint=os.environ["SEARCH_ENDPOINT"],
    credential=AzureKeyCredential(os.environ["SEARCH_API_KEY"]),
)
kb = index_client.get_knowledge_base("<knowledge-base-name>")
kb.cors_options = CorsOptions(
    allowed_origins=["https://myapp.example.com"],
    max_age_in_seconds=60,
)
updated = index_client.create_or_update_knowledge_base(kb)
readback = index_client.get_knowledge_base(updated.name)

參考:CorsOptions, 知識庫

PUT {{search-endpoint}}/knowledgebases/browser-chat-kb?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "browser-chat-kb",
  "description": "A knowledge base that allows one browser app origin.",
  "knowledgeSources": [
    {
      "name": "product-docs-ks"
    }
  ],
  "corsOptions": {
    "allowedOrigins": [
      "https://myapp.example.com"
    ],
    "maxAgeInSeconds": 300
  }
}

查詢知識庫

若要驗證已設定的模型連線,請使用相同的 API 版本與知識庫設定呼叫擷取動作。 使用由 LLM 支援的請求,並檢查非機密模型活動及閘道路由(如適用)。 僅僅成功的建立或 GET 請求並不能驗證模型呼叫。 對於一般查詢,請使用 retrieve 動作或 MCP 端點。

刪除知識庫

如果您不再需要知識庫,或需要在您的 Foundry IQ 服務中重建它,請執行以下程式碼刪除該物件。

// Delete a knowledge base
using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(
    new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);

參考:SearchIndexClient

# Delete a knowledge base
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(
    endpoint="<search-endpoint>",
    credential=DefaultAzureCredential(),
)
index_client.delete_knowledge_base("<knowledge-base-name>")

參考:SearchIndexClient

# Delete a knowledge base
DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{search-access-token}}

參考資料:知識庫 - 刪除