Custom Web API ベクターライザー

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

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

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

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

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

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

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": "<your-header-value>"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        }
    }
]

GET 後にヘッダー値を更新する

インデックス定義を取得すると、サービスはカスタム Web API ベクタライザー内のすべての<redacted>値に対して sentinel httpHeadersを返します。 例えば次が挙げられます。

{
    "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で同じ既存のベクターライザーを更新し、その uri を変更せずに、一致するヘッダー名の Sentinel を再送信します。

{
    "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
    }
}

変更されていない uriでは、保持されているヘッダー値の <redacted> と、他の既存のヘッダーの実際の置換値を混在させることができます。 センチネルは同じベクターライザー上の同じ名前の既存のヘッダーにのみ適用されるため、追加または名前が変更されたヘッダーごとに実際の値を指定します。

uriを変更する場合は、同じ更新プログラムのすべてのhttpHeadersエントリに実際の値を指定します。 サービスは、保存されている値を別の 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を変更する必要がある場合は、外部エンドポイントでローテーションまたは再生成します。 次に、新しい uri とヘッダーの値を一緒に送信します。

<redacted>値は、資格情報ではなくサービス センチネルです。 ベクタライザーを作成したり、別のベクターライザーに格納されているヘッダー値を取得したり再利用したりすることはできません。

JSON ペイロードの構造

カスタム Web API ベクターライザーで使用されるエンドポイントに必要な JSON ペイロード構造は、カスタム Web API スキルで使用される構造と同じです。 詳細については、 スキルのドキュメントを参照してください。

カスタム Web API ベクターライザーの Web API エンドポイントを実装する場合は、次の考慮事項に注意してください。

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

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

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

• vectorizer は、エンドポイントによって返されたエラーまたは警告を無視します。 これらのエラーと警告は、クエリ時のデバッグには使用できません。

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

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

関連項目

• 垂直統合
• 検索インデックスでベクタライザーを構成する方法
• Custom Web API スキル