Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
自訂 Web API 向量器允許你設定搜尋查詢,呼叫一個在查詢時產生嵌入的網頁 API 端點。 該端點所需的 JSON 有效載荷結構將在本文後面說明。 你的資料會在模型部署的地理區域中處理。
雖然在查詢時使用向量化器,但您可以在索引定義中指定它們,並透過向量設定檔在向量欄位上參考它們。 如需詳細資訊,請參閱 在搜尋索引中設定向量化器。
自訂 Web API 向量化器會在 REST API 中呼叫 WebApiVectorizer 。 使用最新穩定版的 Indexes - Create (REST API) 或提供此功能的 Azure SDK 套件。
向量化工具參數
參數區分大小寫。
| 參數名稱 | 描述 |
|---|---|
uri |
將 JSON 負載傳送至的 Web API 之 URI。 僅允許 https URI 配置。 GET 與 LIST 回應會遮蔽敏感查詢值,包括 sig 和 code。 若要更新向量器而不更改儲存的 URI,請將整個 uri 設定為 <unchanged>。 關於回傳的佔位符與匹配規則,請參見 URI 遮蔽與憑證保留更新。 |
httpMethod |
傳送有效載荷的方法。 允許的方法是 PUT 或 POST。 |
httpHeaders |
由鍵值組成的集合,其中索引鍵是標頭名稱,而值會傳送至您的 Web API。 以下標頭不允許使用:Accept、Accept-Charset、Accept-Encoding、Content-Length、Content-Type、Cookie、Host、TE、Upgrade和 Via。 GET 和 LIST 回應會對每個標頭值回傳 <redacted> 。 如需瞭解更新需求,請參閱 GET 後更新標頭值。 |
authResourceId |
(可選)若設定為字串,表示該向量器使用管理身份來連接承載該程式碼的函式或應用程式。 此屬性可接收 Microsoft Entra ID 的應用程式(用戶端)ID 或應用程式註冊,以下列格式之一:api://<appId>、<appId>/.default、api://<appId>/.default。 此值會界定查詢管線所擷取的驗證權杖範圍,並隨自訂 Web API 要求傳送至函式或應用程式。 設定此屬性需要將您的 Foundry IQ 服務設定為管理身份,且您的 Azure 函式應用程式已設定為 Microsoft Entra 登入。 |
authIdentity |
(選用)由 Foundry IQ 服務用來連接承載程式碼的函式或應用程式的使用者管理身份。 你可以使用 系統管理身份或使用者管理身份。 若要使用系統管理身份,請留 authIdentity 空。 |
timeout |
(可選) 執行 API 呼叫的 HTTP 用戶端的逾時。 它必須格式化為 XSD dayTimeDuration 值(ISO 8601 持續時間 值的受限子集)。 例如,PT60S 代表 60秒。 如果沒設定,預設是 30 秒。 逾時時間可介於1至230秒之間。 |
支援的向量查詢類型
自訂 Web API 向量化工具支援 text、imageUrl 和 imageBinary 向量查詢。
範例定義
"vectorizers": [
{
"name": "my-custom-web-api-vectorizer",
"kind": "customWebApi",
"customWebApiParameters": {
"uri": "https://contoso.embeddings.com",
"httpMethod": "POST",
"httpHeaders": {
"api-key": "<your-header-value>"
},
"timeout": "PT60S",
"authResourceId": null,
"authIdentity": null
}
}
]
在 GET 後更新標頭值
當你用 GET 取得索引定義或用 LIST 列出索引時,服務會針對自訂 Web API 向量器中的每個 httpHeaders 值回傳 <redacted>。 例如:
{
"name": "my-custom-web-api-vectorizer",
"kind": "customWebApi",
"customWebApiParameters": {
"uri": "https://contoso.embeddings.com",
"httpMethod": "POST",
"httpHeaders": {
"api-key": "<redacted>"
},
"timeout": "PT60S",
"authResourceId": null,
"authIdentity": null
}
}
若要重用儲存 api-key 值,請用相同的 name、 kind、 和 endpoint 更新同一現有的向量器。 重新提交與相符標頭名稱對應的傳回預留位置:
{
"name": "my-custom-web-api-vectorizer",
"kind": "customWebApi",
"customWebApiParameters": {
"uri": "https://contoso.embeddings.com",
"httpMethod": "POST",
"httpHeaders": {
"api-key": "<redacted>"
},
"timeout": "PT60S",
"authResourceId": null,
"authIdentity": null
}
}
對於相同且現有的向量器和端點,你可以混合使用 <redacted> 或 <unchanged> 作為保留的標頭值與實際替換值。 明確的值優先於佔位符。 為每個新增或重新命名的標頭提供實際值,因為佔位符需要明確且無歧義的既有來源文字。 關於 URI 查詢變更,請參見 URI 遮蔽與保留憑證的更新。
如果你更改端點,請在同一更新中提供實際的 URI 和標頭密鑰。 該服務不會將已儲存的機密重複用於不同的端點:
{
"name": "my-custom-web-api-vectorizer",
"kind": "customWebApi",
"customWebApiParameters": {
"uri": "https://new.contoso.embeddings.com",
"httpMethod": "POST",
"httpHeaders": {
"api-key": "<new-header-value>"
},
"timeout": "PT60S",
"authResourceId": null,
"authIdentity": null
}
}
如果憑證無法取得且必須更改端點,請在外部端點輪換或重新產生憑證。 然後把新值 uri 和標頭值一起提交。
<redacted> 值是服務哨兵值,而非認證憑證。 它無法建立向量器,也無法取回或重用儲存在另一個向量器中的標頭值。
對於新的索引、重新命名的向量化器或不同的服務,請提供目標 URI 查詢與標頭憑證。 對於受管理身份,請明確設定支援的驗證屬性及目標授權。
URI 遮蔽與憑證保留更新
這種 URI 查詢行為適用於所有 API 版本。
當您使用 GET 擷取索引或以 LIST 擷取清單索引時,Foundry IQ 會遮蔽敏感的自訂 Web API URI 查詢值,包括 sig 和 code、 及 HTTP 標頭值。 這些已遮蔽的值可保護共用存取簽章(SAS)簽章、函式金鑰及標頭憑證。
若要保留儲存的祕密,請更新相同的索引與向量器,並使用相同的向量器名稱、類型與端點。 在管理 PUT 要求的完整索引定義中提交回傳的 <redacted> 或 <unchanged> 佔位符。 保留的標頭必須與現有標頭名稱相符。 此 PUT 更新了索引定義;它不是由向量器 httpMethod控制的端點調用。 你也可以將整個 uri 設定為 <unchanged> 來保留儲存的 URI。
秘密值不會被帶到其他端點或複製到新的資源中。 變更端點、複製已遮蔽的定義,或以其他方式變更資源指向的端點,都必須明確提供機密值。
如果服務無法辨識預留位置所對應的唯一明確現有來源,PUT 要求就會因 400 Bad Request 而失敗,並要求提供實際的機密值。 未解析或已保存的預留位置並非可用的憑證。 秘密還原是原子性的:失敗的還原不會部分套用 URI 或標頭變更。
你可以隨時提供替代的 URI 或標頭秘密。 明確的值優先於佔位符。
URI 查詢更新遵循以下規則:
- 對於 Azure 函式
code參數,你可以更新其他非秘密查詢參數,同時保留同一端點的函式金鑰。 - 對於 SAS
sig參數,簽名綁定於周圍的非秘密查詢配置。 若範圍、權限、到期日、資源、版本、排序、大小寫或編碼有變更,則提供新的簽章。 即使是語意等價的重新排序或重新編碼的查詢文字,也需要新的簽章。
秘密查詢參數名稱可在不區分大小寫且在經百分比編碼時被識別。 該服務會保留你的 URI 表示,而不是將其標準化。 重複的機密參數會依出現順序進行比對。 如果它們的出現模式不再與儲存的 URI 對齊,請提供實際值。
使用 <redacted> 或 <unchanged> 的現有 GET-then-PUT 工作流程仍受支援。 關於標頭範例,請參見 GET 之後更新標頭值。
關於自訂技能,請參見 自訂 Web API 技能 URI 遮蔽與憑證保留更新。
這些 URI 與標頭規則並未建立對其他向量器類型或屬性的保留支援。 關於目標相依性檢查及安全還原程序,請參閱 備份、還原或複製索引。
JSON 承載結構
與自訂 Web API 向量化工具搭配使用之端點所需的 JSON 承載資料結構,與自訂 Web API 技能所使用的結構相同。 欲了解更多資訊,請參閱 技能文件。
在為自訂 Web API 向量器實作網頁 API 端點時,請考慮以下幾點:
向量化工具在向端點提出要求時,一次只會在
values陣列中傳送一筆記錄。向量化工具會在要求承載的
dataJSON 物件中,以特定金鑰傳遞要向量化的資料。 該金鑰為text、imageUrl或imageBinary,取決於所要求的向量查詢類型。向量化工具預期回傳的嵌入位於回應承載的
vectorJSON 物件中的data金鑰下。向量器會忽略端點回傳的任何錯誤或警告。 這些錯誤與警告無法用於查詢時偵錯。
如果要求
imageBinary向量查詢,發送至端點的請求有效負載如下:{ "values": [ { "recordId": "0", "data": { "imageBinary": { "data": "<base 64 encoded image binary data>" } } } ] }