次の方法で共有

Custom Web API ベクターライザー

カスタム Web API ベクターライザーを使用すると、クエリ時に埋め込みを生成する Web API エンドポイントを呼び出す検索クエリを構成できます。 エンドポイントに必要な JSON ペイロード構造については、この記事で後述します。 データは、モデルがデプロイされている 地域 で処理されます。

ベクター化はクエリ時に使用されますが、インデックス定義で指定し、ベクター プロファイルを使用してベクター フィールドで参照します。 詳細については、「 検索インデックスでベクターライザーを構成する」を参照してください。

カスタム Web API ベクターライザーは、REST API で WebApiVectorizer 呼び出されます。 最新の安定バージョンの インデックス - 作成 (REST API) または機能を提供する Azure SDK パッケージを使用します。

ベクタライザー パラメーター

パラメーターでは大文字と小文字が区別されます。

パラメーター名 説明
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 (省略可能)設定されている場合、このベクターライザーがコードをホストする関数またはアプリへの接続にマネージド ID を使用することを示す文字列。 このプロパティは、Microsoft Entra ID のアプリケーション (クライアント) ID またはアプリの登録を、 api://<appId>、 <appId>/.default、 api://<appId>/.defaultのいずれかの形式で受け取ります。 この値は、クエリ パイプラインによって取得され、カスタム Web API 要求と共に関数またはアプリに送信される認証トークンのスコープを設定します。 このプロパティを設定するには、検索サービスが マネージド ID 用に構成 され、Azure 関数アプリが Microsoft Entra サインイン用に構成されている必要があります。
authIdentity (省略可能)コードをホストする関数またはアプリに接続するために検索サービスによって使用されるユーザーマネージド ID。 システムマネージド ID またはユーザーマネージド ID を使用できます。 システム マネージド ID を使用するには、 authIdentity 空白のままにします。
timeout (省略可能) API 呼び出しを行う HTTP クライアントのタイムアウト。 XSD dayTimeDuration 値 ( ISO 8601 期間 値の制限されたサブセット) として書式設定する必要があります。 たとえば、 PT60S は 60 秒を意味します。 設定しない場合、既定値は 30 秒です。 タイムアウトは 1 ~ 230 秒です。

サポートされているベクター クエリの種類

Custom 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 配列に一度に 1 つのレコードのみを送信します。

  • ベクターライザーは、要求ペイロードにおける data JSON オブジェクト内の特定のキーでベクター化されるデータを渡します。 そのキーは、text、imageUrl、または imageBinary で、要求されたベクター クエリの種類に依存します。

  • ベクターライザーは、結果の埋め込みを応答ペイロードにおける vector JSON オブジェクト内の data キーの下に含めることを期待します。

  • エンドポイントによって返されたエラーまたは警告はベクター化によって無視され、クエリ時間のデバッグには使用できません。

  • imageBinary ベクター クエリが要求された場合、エンドポイントに送信される要求ペイロードは次のようになります。

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

関連項目

  • Last updated on