Partilhar via

Vetorizador de API Web personalizado

  • Artigo

Importante

Esta funcionalidade está em pré-visualização pública em Termos de Utilização Suplementares. A API REST 2023-10-01-Preview e todas as APIs REST de visualização mais recentes suportam esse recurso.

O vetorizador de API da Web personalizado permite que você configure suas consultas de pesquisa para chamar um ponto de extremidade da API da Web para gerar incorporações no momento da consulta. A estrutura da carga JSON necessária para ser implementada no endpoint fornecido é descrita mais abaixo neste documento. Seus dados são processados na área geográfica onde seu modelo é implantado.

Parâmetros do vetorizador

Os parâmetros diferenciam maiúsculas de minúsculas.

Nome do parâmetro Description
uri O URI da API Web para a qual a carga JSON é enviada. Somente o esquema de URI https é permitido.
httpMethod O método a utilizar durante o envio da carga. Os métodos permitidos são PUT ou POST
httpHeaders Uma coleção de pares chave-valor em que as chaves representam nomes de cabeçalho e valores representam valores de cabeçalho que são enviados para sua API da Web junto com a carga útil. Os seguintes cabeçalhos são proibidos de estar nesta coleção: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TEUpgrade, . Via
authResourceId (Opcional) Uma cadeia de caracteres que, se definida, indica que esse vetorizador deve usar uma identidade gerenciada na conexão com a função ou aplicativo que hospeda o código. Esta propriedade leva um ID de aplicativo (cliente) ou registro do aplicativo no Microsoft Entra ID, em um formato suportado: api://<appId>. Esse valor é usado para definir o escopo do token de autenticação recuperado pelo indexador e é enviado junto com a solicitação de API da Web personalizada para a função ou aplicativo. A definição dessa propriedade requer que seu serviço de pesquisa esteja configurado para identidade gerenciada e seu aplicativo de função do Azure esteja configurado para uma entrada do Microsoft Entra.
authIdentity (Opcional) Uma identidade gerenciada pelo usuário usada pelo serviço de pesquisa para se conectar à função ou aplicativo que hospeda o código. Você pode usar uma identidade gerenciada pelo sistema ou pelo usuário. Para usar uma identidade gerenciada pelo sistema, deixe authIdentity em branco.
timeout (Opcional) Quando especificado, indica o tempo limite para o cliente http que faz a chamada de API. Ele deve ser formatado como um valor XSD "dayTimeDuration" (um subconjunto restrito de um valor de duração ISO 8601). Por exemplo, PT60S durante 60 segundos. Se não estiver definido, será escolhido um valor padrão de 30 segundos. O tempo limite pode ser definido para um máximo de 230 segundos e um mínimo de 1 segundo.

Tipos de consulta vetorial suportados

O vetorizador de API da Web personalizada suporta textconsultas vetoriais e imageUrl, , imageBinary .

Definição da amostra

"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
        },
    }
]

Estrutura de carga útil JSON

A estrutura de carga JSON necessária esperada para um ponto de extremidade ao usá-lo com o vetorizador de API da Web personalizado é a mesma da habilidade de API da Web personalizada, que é discutida com mais detalhes na documentação da habilidade.

Há as seguintes outras considerações a serem feitas ao implementar um ponto de extremidade de API da Web para usar com o vetorizador de API da Web personalizado.

  • O vetorizador envia apenas um registro de cada vez na values matriz ao fazer uma solicitação para o ponto de extremidade.

  • O vetorizador passa os dados a serem vetorizados em uma chave específica no data objeto JSON na carga útil da solicitação. Essa chave é text, imageUrlou , dependendo imageBinarydo tipo de consulta vetorial solicitada.

  • O vetorizador espera que a incorporação resultante esteja sob a vector chave no data objeto JSON na carga útil de resposta.

  • Quaisquer erros ou avisos retornados pelo ponto de extremidade são ignorados pelo vetorizador e não podem ser obtidos para fins de depuração no momento da consulta.

  • Se uma imageBinary consulta vetorial foi solicitada, a carga útil da solicitação enviada para o ponto de extremidade é a seguinte:

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

Consulte também