共用方式為

自訂 Web API 向量化工具

  • 發行項

自訂 Web API 向量化工具可讓您設定搜尋查詢，以呼叫 Web API 端點，以在查詢時產生內嵌。 本文件會進一步說明在提供的端點中實作所需的 JSON 承載結構。 您的資料會在模型部署所在的地理位置中處理。

向量化程式會在查詢時間使用，但在索引定義中指定，並透過向量配置檔在向量欄位上參考。 自訂 Web API 向量化程式會在 API 中呼叫 WebApiVectorizer 。

向量化工具參數

這些參數會區分大小寫。

參數名稱 描述
uri JSON 承載會傳送的目標 Web API URI。 僅允許 https URI 配置。
httpMethod 傳送承載時使用的方法。 允許的方法為 PUT 和 POST
httpHeaders 機碼值組的集合，其中機碼代表標頭名稱，而值代表將與承載一起傳送至 Web API 的標頭值。 下列標頭禁止加入此集合：Accept、Accept-Charset、Accept-Encoding、Content-Length、Content-Type、Cookie、Host、TE, Upgrade、Via。
authResourceId (選用) 如果設定字串，則指出此向量化工具應該在裝載程式碼的函數或應用程式連線上使用受控身分識別。 此屬性會採用 Microsoft Entra ID 中的應用程式 (用戶端) 識別碼或應用程式的註冊 (採用以下任一格式：api://<appId>、<appId>/.default、api://<appId>/.default)。 此值會用來設定索引子所擷取的驗證權杖範圍，並與自訂 Web API 要求一起傳送至函數或應用程式。 設定此屬性需要您的搜尋服務已針對受控身分識別進行設定，而且您的 Azure 函數應用程式已針對 Microsoft Entra 登入進行設定。
authIdentity (選擇性) 搜尋服務用來連線至裝載程式碼之函式或應用程式的使用者受控識別。 您可以使用系統或使用者受控的識別。 若要使用系統管理身分識別，請將 authIdentity 保留為空白。
timeout (選擇性) 指定時，表示進行 API 呼叫的 http 用戶端逾時。 其必須格式化為 XSD "dayTimeDuration" 值 ( ISO 8601 持續時間 值的受限子集)。 例如，PT60S 為 60 秒。 如果沒有設定，則選擇的預設值為 30 秒。 逾時最高可設定為 230 秒，最低 1 秒。

支援的向量查詢類型

自訂 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": "0000000000000000000000000000000000000"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        },
    }
]

JSON 承載結構

搭配自訂 Web API 向量化工具使用端點時，預期端點所需的 JSON 承載結構與自訂 Web API 技能相同，此技能文件會更詳細地討論。

實作 Web API 端點以搭配自訂 Web API 向量化工具使用時，有下列其他考慮。

  • 向量化工具在向端點提出要求時，一次只會在 values 陣列中傳送一筆記錄。

  • 向量化工具會將資料傳遞至要求承載中 data JSON 物件中特定索引鍵中要向量化的資料。 該金鑰為 text、imageUrl 或 imageBinary，取決於所要求的向量查詢類型。

  • 向量化工具預期產生的內嵌會在回應承載中 data JSON 物件中的 vector 金鑰底下。

  • 向量化工具會忽略端點傳回的任何錯誤或警告，而且無法用於查詢時進行偵錯。

  • 如果要求 imageBinary 向量查詢，則傳送至端點的要求承載如下:

    {
    "values": [
        {
            "recordId": "0",
            "data":
            {
                "imageBinary": {
                    "data": "<base 64 encoded image binary data>"
                }
            }
        }
    ]
}

另請參閱