Vetorizador de API Web personalizada

  • Artigo

O vetorizador de API Web personalizada permite que você configure suas consultas de pesquisa para chamar um ponto de extremidade de API Web a fim de gerar inserções no momento da consulta. A estrutura do conteúdo JSON necessária para ser implementada no ponto de extremidade fornecido é descrita mais adiante neste documento. Seus dados são processados na área geográfica em que o modelo é implantado.

Os vetorizadores são usados no momento da consulta, mas especificados em definições de índice e referenciados em campos vetoriais por meio de um perfil vetorial. O vetorizador de API Web personalizado é chamado WebApiVectorizer na API.

Parâmetros do vetorizador

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

Nome do parâmetro Descrição
uri O URI da API Web para o qual o conteúdo JSON é enviado. Somente o esquema do URI https é permitido.
httpMethod O método a ser usado ao enviar o conteúdo. Os métodos permitidos são PUT ou POST
httpHeaders Uma coleção de pares chave-valor em que as chaves representam os nomes de cabeçalho e os valores representam valores de cabeçalho que são enviados para sua API Web, juntamente com o conteúdo. Os seguintes cabeçalhos são proibidos de estarem nesta coleção: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, Via.
authResourceId (Opcional) Uma cadeia de caracteres que, se configurada, indica que esse vetorizador deve usar uma identidade gerenciada na conexão com a função ou o aplicativo que hospeda o código. Essa propriedade usa uma ID do aplicativo (cliente) ou o registro do aplicativo no Microsoft Entra ID, em um desses formatos: api://<appId>, <appId>/.default, api://<appId>/.default. Esse valor será usado para definir o escopo do token de autenticação recuperado pelo indexador e enviado junto com a solicitação de API Web personalizada para a função ou aplicativo. Definir essa propriedade requer que seu serviço de pesquisa esteja configurado para identidade gerenciada e seu aplicativo de funções do Azure esteja configurado para um logon do Microsoft Entra.
authIdentity (Opcional) Uma identidade gerenciada pelo usuário usada pelo serviço de pesquisa para se conectar à função o aplicativo que hospeda o código. Você pode usar um sistema ou uma identidade gerenciada 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 fez a chamada à API. Ele deve ser formatado como um valor XSD de "dayTimeDuration" (um subconjunto restrito de um valor de duração ISO 8601 ). Por exemplo, PT60S por 60 segundos. Se não for definido, um valor padrão de 30 segundos será escolhido. O tempo limite pode ser definido para um máximo de 230 segundos e um mínimo de 1 segundo.

Tipos de consultas vetoriais com suporte

O vetorizador de API Web Personalizada dá suporte a consultas vetoriais text, imageUrl e imageBinary.

Definição de exemplo

"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 do conteúdo JSON

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

Existem outras considerações a serem feitas ao implementar um ponto de extremidade de API Web para uso com o vetorizador da API Web personalizada.

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

  • O vetorizador aprovado os dados a serem vetorizados em uma chave específica no objeto JSON data no conteúdo da solicitação. Essa chave é text, imageUrl ou imageBinary, dependendo do tipo de consulta vetorial solicitado.

  • O vetorizador espera que a inserção resultante esteja sob a chave vector no objeto JSON data no conteúdo da resposta.

  • Todos os possíveis erros ou avisos retornados pelo ponto de extremidade serão ignorados pelo vetorizador e não estarão disponíveis para fins de depuração no momento da consulta.

  • Se uma consulta vetorial imageBinary foi solicitada, o conteúdo da solicitação enviado para o ponto de extremidade é o seguinte:

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

Confira também