自定义 Web API 矢量器

使用自定义 Web API 矢量器，可以将搜索查询配置为调用在查询时生成嵌入的 Web API 终结点。 本文稍后将介绍终结点所需的 JSON 有效负载结构。 您的数据在模型部署的地理位置中进行处理。

尽管矢量化器在查询时使用，但您需要在索引定义中指定它们，并通过矢量概况在向量字段上引用它们。 有关详细信息，请参阅 在搜索索引中配置向量器。

自定义 Web API 向量器在 REST API 中被称为 WebApiVectorizer。 使用最新的稳定版 Indexes - 创建 （REST API） 或提供该功能的Azure SDK包。

矢量器参数

参数区分大小写。

支持的矢量查询类型

自定义 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 向量化器中的每个 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 更新同一个现有向量器，保持其 uri 不变，并针对对应的标头名称重新提交哨兵值：

{
    "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> 与其他现有标头的实际替换值混用。 为每个已添加或重命名的标头提供实际值，因为 sentinel 仅适用于同一向量器上具有相同名称的现有标头。

如果更改了 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 阵列中一次只发送一条记录。

• 矢量器将要矢量化的数据传递到请求有效负载中 data JSON 对象的特定键中。 键为 text、imageUrl 或 imageBinary，具体取决于请求的矢量查询类型。

• 矢量器期望得到的嵌入位于响应有效负载中 vector JSON 对象的 data 键下。

• 向量器忽略终结点返回的任何错误或警告。 这些错误和警告不适用于查询时调试。

• 如果请求了 imageBinary 矢量查询，则发送到终结点的请求有效负载如下：

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

另请参阅

• 集成矢量化
• 如何在搜索索引中配置矢量器
• 自定义 Web API 技能
• Hugging Face 嵌入生成器功能技能（也可用于自定义 Web API 向量化器）