Custom Web API ベクターライザー

  • [アーティクル]

重要

この機能はパブリック プレビュー段階にあり、追加使用条件の下で提供されます。 2023-10-01-Preview REST APIおよび新しいプレビュー REST API はすべて、この機能をサポートしています。

Custom Web API ベクターライザーを使用すると、Web API エンドポイントを呼び出し、クエリ時に埋め込みを生成するよう検索クエリを構成できます。 指定されたエンドポイントに実装するために必要な JSON ペイロードの構造については、このドキュメントで詳しく説明します。 データは、モデルがデプロイされている geo で処理されます。

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

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

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

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

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 ペイロードの構造

Custom Web API ベクターライザーでエンドポイントを使用する場合に必要な JSON ペイロード構造は、Custom Web API スキルと同じです。これについては、スキルのドキュメントで詳しく説明します。

Custom Web API ベクターライザーで使用する Web API エンドポイントを実装する場合は、他にも次の考慮事項があります。

  • ベクターライザーは、エンドポイントに要求を行う場合、values 配列に一度に 1 つのレコードのみを送信します。

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

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

  • エンドポイントによって返されたエラーまたは警告は、ベクターライザーによって無視されるため、クエリ時のデバッグ目的では取得できません。

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

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

関連項目