使用 API 管理服務搭配 Foundry IQ(Azure AI 搜尋服務)模型呼叫

Note

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

Important

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

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

有關使用支援的非 Microsoft 模型時適用的術語,請參閱「第三方模型」。 如果您設定 API Management 以導向支援的第三方閘道,請參閱 「透過 API 管理建立第三方閘道」。

使用 Azure API 管理 作為支援的 Foundry IQ(Azure AI 搜尋服務)模型呼叫的閘道,集中管理路由、節流、負載平衡與監控。 支援取決於 Search 工作負載及其模型協定、驗證與執行環境。

從 2026-11-01-preview 開始,與 OpenAI 相容的知識庫型 LLM 可用於代理式擷取,並接受完整的端點 URL。 這些端點可以是 API Management、客戶閘道,或是直接設定的相容第三方提供者。 此知識庫設定不需要 API 管理。 Azure OpenAI 設定與相容的知識庫設定有不同的契約。

Prerequisites

  • Foundry IQ 服務以及設定工作負載的權限。 例如,指派 搜尋服務貢獻者 建立或更新索引與知識庫。 請參閱 「使用角色連線」。
  • 一個模型端點,實作工作負載所需的協定與功能,包括結構化輸出與工具呼叫(如有需要)。
  • 針對 API 管理,需設定閘 道 API 與後端,並對搜尋至閘道與閘道至後端連線進行獨立驗證。
  • 對於相容的知識庫 LLM 與原生 GPT-6 KB 設定檔,請在知識庫建立、更新及擷取請求中設定 api-version=2026-11-01-preview。 請依照 11 月預覽版的知識庫設定 與 擷取驗證。 其他配置請使用現有的工作負載 API 版本。
  • 對於受控識別,需有已啟用的 Foundry IQ 服務身分識別、接收端點的授權,以及指派任何必要角色的權限。

選擇支援的工作負載與 API

下表描述的是模型連線,而非所有私有網路拓撲的認證。 請參閱 「私有連線」 以了解網路條件。

[工作負載] 搜尋 API 可用性 通訊協定與模型選擇 端點與認證
Azure OpenAI 嵌入技能 原生支援 2023-10-01-preview; 穩定 2024-07-01。 可配置的現代模型維度,來自 2024-05-01-preview 或穩定 2024-07-01。 嵌入;三個 嵌入設定檔。 原生資源 URI 加上部署 ID;支援預設及自訂 API 管理閘道網域。 原生金鑰或管理身份。
Azure OpenAI vectorizer 原生支援來自 2023-10-01-preview;穩定 2024-07-01。 用於文字查詢的嵌入;三個嵌入型態。 原生資源 URI 加上部署 ID;支援預設及自訂 API 管理閘道網域。 原生金鑰或管理身份。
生成式AI提示技能 來自 2025-05-01-preview;GA 2026-04-01。 使用支援技能輸入與生成參數的端點和模型進行聊天完成作業。 完整 uri;預設或自訂 API 管理閘道網域。 原生金鑰/身份屬性。
內容理解選用 LLM 基礎技能 GA 2026-04-01;選修 LLM 屬性 GA 2026-10-01。 在附加資源中使用支援模型進行內容理解操作。 技能集附帶的 Foundry 資源中的模型與部署設定。
原生 KB 擷取模型 現有原生 KB 合約;GPT-6 回應檔案需要 2026-11-01-preview。 搜尋會從模型設定中選擇聊天完成或回應。 原生資源/部署設定。 這些設定不支援 API 管理;使用獨立支援的相容 KB 預覽版來進行閘道連線。
相容的 KB 擷取模型 2026-11-01-preview。 個人檔案選擇的聊天完成或回應;支援 21 種 KB 設定檔。 完整 HTTPS POST URL;標頭或自訂對象的受控識別。 不支援 Web 知識來源。
原生知識來源擷取聊天 現有的受管理擷取合約。 非內容理解的影像口語化會建立 Chat Completions 要求;內容理解採用自己的操作方式。 原生擷取模型與部署設定。
原生知識來源嵌入 現有的管理式攝取合約。 原生嵌入。 原生資源與部署設定。

API 管理不支援作為 內容理解 分析請求或可選的影像描述模型呼叫的閘道。

相容的 KB 預覽僅適用於擷取模型設定。 它不會改變知識來源匯入模型的配置,也不會將原生嵌入技能與向量化器擴展至相容的提供者協定。

對於受權限保護的內容,獨立的 GenAI 提示(聊天完成)技能不會使 API 管理成為受支援的目的地。 僅需 ACL 擷取,這項技能需要支援的第一方 Microsoft 端點,而非 API 管理。 使用 sensitivity-label ingestion 時,這項技能不受支援。 在設定豐富功能前,請先檢視 SharePoint ACL 的限制;驗證或私有路由並不會移除這些限制。

搜尋資料平面 API 版本、搜尋管理 API 版本、API Management 管理版本、下游模型 API 版本及已部署模型版本彼此獨立。 更改搜尋 API 版本並不會改變下游 API 或部署不同的模型。

了解端點與協定需求

原生端點

對於 Azure OpenAI 嵌入技能與向量器,請設定resourceUri為資源基底 URI 或 HTTPS API 管理閘道基底 URI。 您可以同時使用預設閘道主機名稱(例如 https://<apim-name>.azure-api.net,)以及已設定的自訂網域(例如 https://apim.contoso.com)。 請另外設定 deploymentId。 自訂領域支援不會改變原生嵌入協定,也不會新增對任意相容提供者的支援。

Search 會為這些原生嵌入呼叫建構 /openai/deployments/<deploymentId>/embeddings?api-version=2023-05-15。 設定閘道 API 與原則,以接受該路徑和查詢字串,並將其路由至目標 Azure OpenAI 部署。 如果後端需要不同的路徑、部署名稱或 API 版本,請在 API 管理中重寫。 不要在 resourceUri 中放置完整的嵌入作業 URL。

以下參數片段使用預設閘道網域。 把它當作嵌入技能的參數,或是放在向量器 azureOpenAIParameters. 它使用 Foundry IQ 服務的系統指派身分,因為省略了 apiKey 和 authIdentity。

{
  "resourceUri": "https://contoso-models.azure-api.net",
  "deploymentId": "my-text-embedding-3-small",
  "modelName": "text-embedding-3-small"
}

針對自訂閘道網域,僅將 resourceUri 變更為 https://apim.contoso.com。 在 API 管理閘道上設定該主機名稱及其 TLS 憑證。 部署設定與模型設定維持分開。 如需完整定義及使用者自訂身份選擇,請參閱 嵌入技能 與 向量化器 範例。

對於 GenAI 提示技能,請提供完整的模型叫用 uri,其中包括作業路徑和任何必要的查詢參數。 支援 API 管理預設與自訂閘道網域。 僅僅是閘道基礎 URL,並不構成完整的生成式 AI 操作 URL。

原生 KB 聊天完成呼叫會使用部署路徑,例如 https://<resource-name>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-08-01-preview。 原生 GPT-6 KB 設定檔使用 https://<resource-name>.openai.azure.com/openai/v1/responses,其部署 ID 位於請求主體中 model。

相容端點

針對用於檢索的相容知識庫 LLM:

  1. 在 uri 中提供完整的絕對 HTTPS POST URL,包括其路徑和查詢參數。 例如:
    • 聊天補全: https://<apim-name>.azure-api.net/openai/deployments/<deployment>/chat/completions?api-version=<downstream-api-version>。
    • 回覆: https://<gateway-host>/openai/v1/responses。
  2. 設定端點以接受所選協定。 搜尋會原樣傳送 URL:不會附加部署路徑、作業或 api-version。
  3. 不要在 URL 中嵌入憑證或片段。 搜尋不會跟隨重定向,包括指向同一主機的重新導向。
  4. 在 URL 或閘道處設定路由。 相容的知識庫請求本文省略 model。 若提供者需要 model 識別碼,閘道必須提供該識別碼。

自訂閘道網域與直接的第三方相容端點使用相同合約。 如果提供者 URL 需要在請求主體中指定模型,您需要一個閘道器或介面卡來提供該值。

modelName 選擇搜尋的設定檔與功能。 它不會選擇或驗證實際的下游部署,不會辨識過時的提供者模型版本,也不會讓任意提供者協定相容。 相容的知識庫配置中沒有公開協定選擇器。

在 Responses 知識庫檢索中,請保留無狀態的延續結構、函式呼叫的輸入與輸出,以及加密的推理內容。 搜尋會傳送 store:false。 接受模型名稱字串或簡單的文字請求並不構成足夠的相容性。 閘道器上的協定轉換並不代表下游協定是原生的搜尋協定。

設定 Search 到閘道的驗證

將應用程式到搜尋服務的身分驗證與搜尋到閘道的身分驗證分開。 您用來建立或查詢搜尋物件的認證,並不是用於外寄模型呼叫時使用的憑證。

原生驗證

原生 Azure OpenAI 嵌入設定使用 apiKey 或 Search 受控識別。 金鑰驗證會 api-key輸出 ,但不會自動 Ocp-Apim-Subscription-Key輸出 。 設定 API 管理的訂閱金鑰標頭或政策,使其與工作負載所傳送的標頭相符。

原生受控識別會為認知服務對象(https://cognitiveservices.azure.com)取得權杖。 若為系統指派身分識別,請省略 apiKey 和 authIdentity;若為附加的使用者指派身分識別,請使用工作負載的身分識別物件。 只設定一種驗證方式。 請參閱每個工作負載參考以了解其支援的身份屬性。

設定閘道以驗證令牌並授權所選的搜尋身分,包括簽章、發行者、認知服務受眾、租戶、有效期及所需權限。 原生身分驗證不會為自訂閘道應用程式受眾取得權杖。 在 情境 2:用戶端應用程式授權 API 管理時,使用用戶端到閘道模式,並為此工作負載實際傳送的受眾設定驗證。 情境 3 描述的是對 SaaS 後端的憑證管理員授權,而非此連線。

相容的認證

當您建立相容的知識庫 LLM 連線時,請在 openAICompatibleParameters 中指定一種有效的驗證模式:

Mode Configuration 接收端點需求
已儲存標頭 一個非空的 headers 映射。 標頭名稱與值為機密。 接受並驗證已設定的憑證。 對於 API Management 而言,此要求可包含其訂閱標頭。
受控識別 managedIdentityAudience,可選擇搭配 authIdentity。 驗證並授權供客戶應用程式受眾使用的搜尋身分。

managedIdentityAudience必須是標準的裸 Microsoft Entra 應用程式 GUID,例如 11111111-2222-3333-4444-555555555555。 不要使用 api://、/.default、範圍或認知服務受眾。 省略 authIdentity,以使用 Foundry IQ 服務的系統指派身分。

若要選擇附加的使用者指派身分識別,請將此身分識別物件與 managedIdentityAudience 一併加入:

{
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  }
}

這個屬性片段並不是完整的連線。 兩種模式同時使用、建立時未啟用任何模式、空的標頭映射,或有 authIdentity 但沒有 managedIdentityAudience,都是無效的。 權杖取得或驗證失敗不會退回至匿名驗證。

設定閘道對後端的驗證

獨立保護後端連線。 對於由 Microsoft 營運的 Azure OpenAI 後端,一種常見的模式是在 API Management 終止認證,接著使用 API Management 本身系統指派或使用者指派的受控識別進行驗證。 將該身份指派為 Azure OpenAI 或承載後端部署並擁有其端點的父 Foundry 資源上的 Cognitive Services OpenAI 使用者。 設定後端政策以使用該身份。 當 API 管理終止其認證流程並使用自己的身分識別時,Search 身分識別不需要在該後端具備任何角色。

或者,將後端金鑰儲存在 API 管理 的命名值 中,並使用政策將其傳送到後端。 後端金鑰不是搜尋至閘道訂閱金鑰。

對於客戶或第三方後端,請設定後端所需的授權、路由及協定適配。 從搜尋到閘道的受控識別不會在該後端建立授權。

請參閱 服務端驗證選項、API 管理受控識別,以及 生成式 AI 閘道功能。

選擇角色範圍與身份

對於直接呼叫 Azure OpenAI 或有意進行令牌直通,請將Cognitive Services OpenAI User指派給所選的搜尋受控識別。 將指派範圍設定為承載部署並擁有端點的 Azure OpenAI 或父 Foundry 資源。

例如,若專案contoso-project在父資源 my-text-embedding-3-small上使用部署contoso-foundry,則角色範圍為 /subscriptions/<model-subscription-id>/resourceGroups/<model-resource-group>/providers/Microsoft.CognitiveServices/accounts/contoso-foundry。 對於名為 contoso-models 的獨立 Azure OpenAI 資源,請使用以 /Microsoft.CognitiveServices/accounts/contoso-models 結尾的對應資源 ID。 這兩個範圍皆不包含 /projects/<project-name> 或部署名稱。

有關身分識別碼與角色指派步驟,請參閱 「指派角色」。 對於 API 管理自訂網域,請從閘道器的後端設定中識別模型託管資源,而非從閘道主機名稱中識別。

在模型託管資源的 存取控制(IAM) 頁面上,將角色指派給正確的對象。 如果搜尋與模型資源屬於同一 Microsoft Entra 租戶中的不同資源群組或訂閱,請在角色指派範圍內使用模型資源的訂閱與資源群組。 請確保您在該範圍內擁有角色指派權限。 請參閱 Azure RBAC 範圍。 受控識別不支援 跨目錄存取。

針對 401 或 403 錯誤,請檢查所選的身分識別、資源範圍、角色指派傳播狀態,以及每個驗證環節。 如果模型資源的本地驗證被停用,請使用授權的管理身份,而非金鑰。 RBAC 授與授權;它不會設定 DNS、防火牆或私有路由。

使用相容的知識庫模型

如需完整的 REST 配置、精確的 21 KB 模型設定檔,以及個別的聊天完成與回應範例,請參閱「 使用 OpenAI 相容模型(預覽)」。

您可以將現有的知識庫從原生的 Azure OpenAI 或 Microsoft Foundry 模型端點切換到 APIM 或自訂網域端點,而無需重新建立知識庫。 請使用 2026-11-01-preview 或較晚支援的預覽版本,並遵循 模型連線更新需求。

在知識庫的 models 集合下設定擷取用 LLM,使用 kind: "openAICompatible" 和 openAICompatibleParameters。 具備網頁知識來源的知識庫需要原生 Azure OpenAI 聊天設定。

設定完成後,請在同一 KB上2026-11-01-preview。 使用 LLM 支援的擷取與檢視非機密的模型活動及閘道路由。 僅僅成功建立或 GET 並不能驗證模型呼叫。

支援的 Azure OpenAI 嵌入模型

嵌入設定檔

Azure OpenAI 嵌入技能與向量化器支援以下模型。 使用現有的工作負載配置,其中包含 resourceUri、deploymentId 和 modelName。

Profile 預設尺寸 可接受的尺寸
text-embedding-ada-002 1536 只有1536
text-embedding-3-small 1536 1–1536
text-embedding-3-large 3072 1–3072

有效輸出維度必須與向量場相符。 在匯入與查詢時使用相同的嵌入模型與設定;僅僅等維度並不能建立一個共享的語意空間。 完整設定請參閱嵌入技能及Azure OpenAI 向量化工具參考資料。

更新認證與模型設定

對於相容的知識基礎大型語言模型,headers 屬性為僅寫入。 公開回應則完全省略該屬性,包括標頭名稱。 它們不會回傳遮罩值, {}或 null。

對於相同的知識庫與模型繫結,若更新中省略了 headers,則只有在端點、模型設定檔及驗證身分完全相同的情況下,才能保留已儲存的憑證。

Update 必要行動
未變更的讀取至輸入 保留相同的資源/綁定以及連線/設定檔/身份設定。 省略的標頭可保留已儲存的憑證。
變更目的地、設定檔或身份 提供新的認證。 不要將省略的祕密轉移到已變更的權限範圍。
從讀取結果複製、重新命名或建立 明確提供驗證;遺漏不會繼承其他物件的憑證。
旋轉標頭憑證 在同一模型繫結中傳送完整有效的替換標頭映射。
切換標頭/受管理識別模式 提供新的有效模式,並從請求中移除舊模式。
遭拒絕的更新 現有儲存的憑證保持不變。

例如,透過傳送現有完整 KB 定義並附上替換 headers 對應圖來輪替 KB 標頭。 後續的 GET 會省略 headers;若該讀取結果的 PUT 不變,則可保留該替換內容。 不要更改該讀取結果中的 uri,並期待遺漏的密鑰會隨之保留。

在輪換後,以及在讀取後轉為 PUT 且未變更的更新之後,重複進行LLM 支援的檢索驗證。 確認閘道接受替換認證,且擷取仍成功,且不會記錄標頭名稱、值或權杖。

設定私人連線能力

API Management 私有端點是指向其 Gateway 執行階段子資源的輸入連線。 Gateway 不是層級。 管理、入口網站及開發人員文件 URL 並非模型叫用端點,也不在此 Gateway Private Link 連線的涵蓋範圍內。

API 管理層級與拓撲結構

層級或拓撲 API 管理能力 搜尋條件
標準 v2 入站私有端點與出站虛擬網路整合。 請分別驗證搜尋工作負載的執行路徑。
Premium v2 入站私有端點與虛擬網路整合/注入選項。 API Management 功能並不保證每個注入的拓撲都能與搜尋共用 Shared Private Link 相容。
Classic Premium,非 VNet 注入 支援入站私有端點。 不要把所有 classic Premium 執行個體一概視為不受支援。
經典高級版,內部 VNet 注入 私有端點不受支援。 此共享私有連結設計不支援。
Classic Premium,外部 VNet 注入 私有端點不受支援。 此共享私有連結設計不支援。
Classic Developer、Basic、Standard 包含在 API 管理私有端點適用範圍內,但受其限制限制。 並非對搜尋工作負載路徑進行全面認證。
自架設或工作區閘道 不支援文件記載的入站私有端點連線。 此限制僅涉及私密連線,並非所有公用通訊協定情況。

請參閱 API 管理 v2 層級 與 私有端點限制。 API 管理 v2 功能使用其管理 API 2024-05-01 或更高版本。 此版本無法選取搜尋資料平面或管理 API。

經典高級版仍持續支援,且尚未被淘汰。 API Management 目前沒有自動化工具,可以將現有的經典層實例(包括 Premium 版本)遷移到 v2 層實例。 v2 層級適用於新建立的實例。 請參閱 API Management v2 遷移及經典層常見問題集。

例如,具備內部 VNet 注入及搜尋共享私有連結鎖定功能的 Microsoft.ApiManagement/service / Gateway 經典 Premium 實例不 被支援。 外部 VNet 注入也有同樣的限制。 正確的資源 ID、核准的連線請求或自訂網域都不會解除此拓撲限制。

對於符合資格的索引器強化,請依照「 透過共用私有連結建立外發連線」:

  1. 確認搜尋層級、雲端、工作負載及私有執行是否符合資格。
  2. 建立一個目標為資源類型 Microsoft.ApiManagement/service 且群組 ID 為 Gateway 的共用私人連結。 現有的搜尋指南使用管理 API 2025-05-01;這不是下游模型的 API 版本。
  3. 在 API Management 上核准連線,並確認佈建與核准成功。
  4. 將符合資格的索引器 parameters.configuration.executionEnvironment 設定為 "private"。
  5. 從實際執行環境中驗證 DNS 解析、TLS 與路由。 在模型 URI 中請使用已設定的閘道主機名稱,而非私人 IP 位址。 其憑證必須與該主機名稱相符。 對於自訂網域,請為該名稱設定 DNS 以及預設 privatelink.azure-api.net 的私人 DNS 設定。 標準 v2 與高級版 v2 也要求自訂閘道名稱必須是公開可解析的;請參閱 自訂網域 DNS 限制。
  6. 只有在私有端點設定完成且私有路由已驗證後,才停用 API 管理的公開網路存取。 對於公開的 Search-to-APIM 連線,請依其網路政策保持閘道器的公開端點可存取。 搜尋、API 管理與後端的公開網路設定是獨立的。
  7. 獨立保護 API Management 與後端之間的網路連線。

不要將索引器執行屬性新增至 KB 擷取或查詢向量化請求。 註冊 API 管理閘道目標並不會為每個 KB 或查詢向量器執行主機建立私有路由支援。 支援私有目的地位址並不代表會配置路由。 API 管理支援也不會對任意 Microsoft.Network/privateLinkServices 目標建立一般性的支援。

安全性注意事項

Foundry IQ 會將模型輸入與已設定的驗證資料傳送至所選端點。 只設定您信任且可控,且預期會接收這些輸入與認證資訊的端點。 僅靠主機名稱或受眾 GUID 並不能建立端點所有權、授權或私有連線。

在接收端驗證受控識別權杖,包括簽章、發行者、受眾、租戶、存續時間及所需權限。 對搜尋與 API 管理身份皆套用最小權限。 限制修改索引定義、知識庫、知識來源及閘道原則的權限。

在啟用連線前,請先檢視路由、下游提供者、記錄、保留、地理處理及存取控制。 將 Search 到閘道的驗證與閘道到後端的驗證分別加以保護。 管理身份並不代表客戶或第三方後端是 Microsoft 營運的。

搜尋管理設定 properties.dataExfiltrationProtections 使用公開值 ["BlockAll"]。 它會阻擋相容的知識庫模型呼叫。 不要把這個值當成可停用所有 Azure OpenAI 向量器的開關。 檢視 Azure OpenAI 向量器安全性指引及特定工作負載的網路控制措施。

排除不支援的組合

症狀或配置 要檢查的事項
未找到作業或已重新導向 提供完整且相容的 POST URL 及正確的查詢參數。 搜尋不會附加路徑,也不會遵循重新導向。
缺少提供者模型 相容的 KB 內容主體省略了 model。 設定 URL 路由或閘道注入; modelName 不是提供者部署選擇器。
Responses KB 失敗 使用具備 11 月預覽支援及必要延續結構的回應 KB 設定檔與端點。 不保證提供 Chat Completions 備援機制。
身分驗證被拒絕 只使用一種有效的模式。 檢查原生應用程式與自訂應用程式受眾、權杖驗證、標頭名稱,以及兩個驗證環節。
讀取物件後更新失敗 為變更範圍提供新的憑證。 不要因省略而複製僅寫入的憑證。
Azure OpenAI 嵌入請求失敗 使用支援的嵌入模型、匹配尺寸,以及技能或向量器所描述的資源 URI 與部署設定。
私人要求失敗 獨立驗證工作負載執行路由是否符合條件、核准、DNS、TLS、API 管理層級/拓撲及後端連線。
具有相容 KB 模型的 Web 知識來源 使用原生 Azure OpenAI 聊天設定。