Compartilhar via

Criar um índice de vetor

  • Artigo

Na Pesquisa de IA do Azure, um repositório de vetores tem um esquema de índice que define campos vetoriais e não vetoriais, uma configuração de vetor para algoritmos que criam e compactam o espaço de inserção e configurações em definições de campo de vetor que são usadas em solicitações de consulta.

A API Criar ou Atualizar Índice cria o repositório de vetores. Siga estas etapas para indexar dados vetoriais:

  • Definir um esquema com algoritmos de vetor e compactação opcional
  • Adicionar definições de campo de vetor
  • Carregue os dados vetoriais como uma etapa separada ou use a vetorização integrada para agrupamento e codificação de dados durante a indexação

Este artigo explica o fluxo de trabalho e usa REST para ilustração. Depois de entender o fluxo de trabalho básico e o que cada versão da API fornece, siga para os exemplos de código do SDK do Azure no repositório azure-search-vector-samples para obter diretrizes sobre como usar esses recursos no código de teste e produção.

Dica

Use o portal do Azure para criar um índice de vetor e experimentar o agrupamento e vetorização de dados integrados.

Pré-requisitos

  • IA do Azure Search, em qualquer região e camada. A maioria dos serviços existentes dá suporte à busca em vetores. Para serviços criados antes de janeiro de 2019, há um pequeno subconjunto que não pode criar um índice de vetor. Nessa situação, um novo serviço deve ser criado. Se você estiver usando a vetorização integrada (conjuntos de habilidades que chamam a IA do Azure), a Pesquisa de IA do Azure precisará estar na mesma região que o OpenAI do Azure ou os serviços de IA do Azure.

  • Inserções de vetor pré-existentes ou usar a vetorização integrada, em que os modelos de inserção são chamados do pipeline de indexação.

  • Você deve saber o limite de dimensões do modelo usado para criar as inserções. Os valores válidos são 2 a 3072 dimensões. No Azure OpenAI, em text-embedding-ada-002, o comprimento do vetor numérico é 1536. Para text-embedding-3-small ou text-embedding-3-large, o comprimento do vetor é 3072.

  • Você também deve saber quais são as métricas de similaridade com suporte. Para o OpenAI do Azure, a similaridade é computada usando cosine.

  • Você deve estar familiarizado com a criação de um índice. O esquema deve incluir um campo para a chave do documento, outros campos que você deseja pesquisar ou filtrar e outras configurações para comportamentos necessários durante a indexação e consultas.

Preparar documentos para indexação

Antes da indexação, monte um payload de documento que inclua campos de dados vetoriais e não vetoriais. A estrutura do documento deve estar em conformidade com o esquema de índice.

Verifique se os documentos:

  1. Fornecem um campo ou uma propriedade de metadados que identifique exclusivamente cada documento. Os índices de pesquisa exigem uma chave de documento. Para atender aos requisitos de chave do documento, um documento de origem deve ter um campo ou propriedade que possa identificá-lo exclusivamente no índice. Esse campo de origem deve ser mapeado para um campo de índice do tipo Edm.String e key=true no índice de pesquisa.

  2. Forneça dados vetoriais (uma matriz de números de ponto flutuante de precisão simples) nos campos de origem.

    Os campos de vetor contêm uma matriz gerada pela inserção de modelos, uma inserção por campo, em que o campo é um campo de nível superior (não faz parte de um tipo aninhado ou complexo). Recomendamos os modelos de inserção no OpenAI do Azure, como text-embedding-ada-002, para documentos de texto ou a API REST de Recuperação de Imagem para imagens.

    Se você puder usar uma dependência de indexadores e conjuntos de habilidades, considere usar a vetorização integrada que codifica imagens e conteúdo textual durante a indexação. Suas definições de campo são para campos de vetor, mas os dados de origem recebidos podem ser texto ou imagens, representados como matrizes de vetor criadas durante a indexação.

  3. Fornecem outros campos com conteúdo legível para os usuários para a resposta da consulta e nos cenários de consulta híbrida que incluem pesquisa de texto completo ou classificação semântica na mesma solicitação.

O índice de pesquisa deve incluir campos e conteúdo para todos os cenários de consulta aos quais você deseja dar suporte. Suponha que você queira pesquisar ou filtrar nomes de produtos, versões, metadados ou endereços. Nesse caso, a pesquisa de similaridade não é especialmente útil. Pesquisa de palavra-chave, pesquisa geográfica ou filtro seria uma opção melhor. Um índice de pesquisa que inclui uma coleção abrangente de campos de dados vetoriais e não vetoriais fornece o máximo de flexibilidade para a construção de consultas e composição de respostas.

Um breve exemplo de um payload de documentos que inclui campos vetoriais e não vetoriais está na seção dados do vetor de carga deste artigo.

Adicionar uma configuração de busca em vetores

Uma configuração de vetor especifica os parâmetros usados durante a indexação para criar as informações do "vizinho mais próximo" entre os nós vetoriais:

  • HNSW (Hierarchical Navigable Small World)
  • KNN completo

Se você escolher o HNSW em um campo, poderá optar pelo KNN completo no momento da consulta. Mas a outra direção não funcionará: se você escolher a opção “completo”, não poderá solicitar posteriormente a pesquisa de HNSW, pois as estruturas de dados extras que habilitam a pesquisa aproximada não existem.

Uma configuração de vetor também especifica métodos de compartimentalização para reduzir o tamanho do vetor:

  • Escalar
  • Binário (disponível somente no pacote do SDK do Azure 2024-07-01 e em pacotes mais recentes)

Para obter instruções sobre como migrar para a versão mais recente, consulte Atualizar a API REST.

2024-07-01 está em disponibilidade geral. Ela dá suporte a uma configuração de vetor que tem:

  • vectorSearch.algorithms dão suporte a HNSW e KNN exaustivo.
  • vectorSearch.compressions dão suporte à compartimentalização escalar e binária, à sobreamostragem e à reclassificação com vetores originais.
  • vectorSearch.profiles fornecem várias combinações de configurações de algoritmo e compactação.

Tenha uma estratégia para vetorizar o conteúdo. Recomendamos vetorização integrada e vetorizadores de tempo de consulta para codificação interna.

  1. Use a API Criar ou Atualizar Índice para criar o índice.

  2. Adicione uma seção vectorSearch no índice que especifica os algoritmos de pesquisa usados para criar o espaço de inserção.

     "vectorSearch": {
     "compressions": [
         {
             "name": "scalar-quantization",
             "kind": "scalarQuantization",
             "rerankWithOriginalVectors": true,
             "defaultOversampling": 10.0,
                 "scalarQuantizationParameters": {
                     "quantizedDataType": "int8"
                 }
         },
         {
             "name": "binary-quantization",
             "kind": "binaryQuantization",
             "rerankWithOriginalVectors": true,
             "defaultOversampling": 10.0,
         }
     ],
     "algorithms": [
         {
             "name": "hnsw-1",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 4,
                 "efConstruction": 400,
                 "efSearch": 500,
                 "metric": "cosine"
             }
         },
         {
             "name": "hnsw-2",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 8,
                 "efConstruction": 800,
                 "efSearch": 800,
                 "metric": "hamming"
             }
         },
         {
             "name": "eknn",
             "kind": "exhaustiveKnn",
             "exhaustiveKnnParameters": {
                 "metric": "euclidean"
             }
         }

     ],
     "profiles": [
       {
         "name": "vector-profile-hnsw-scalar",
         "compression": "scalar-quantization",
         "algorithm": "hnsw-1"
       }
     ]
 }

    Pontos principais:

    • Os nomes para cada configuração de compactação, algoritmo e perfil precisam ser exclusivos para o tipo dela dentro do índice.

    • vectorSearch.compressions.kind pode ser scalarQuantization ou binaryQuantization.

    • vectorSearch.compressions.rerankWithOriginalVectors usa os vetores originais e não compactados para recalcular a similaridade e recalcular os principais resultados retornados pela consulta de pesquisa inicial. Os vetores não compactados existem no índice de pesquisa mesmo que stored seja false. Essa propriedade é opcional. O padrão é verdadeiro.

    • vectorSearch.compressions.defaultOversampling considera um conjunto mais amplo de resultados potenciais para compensar a redução das informações da compartimentalização. A fórmula para resultados potenciais consiste em k na consulta, com um multiplicador de sobreamostragem. Por exemplo, se a consulta especificar um k de 5, e a sobrecarga for 20, a consulta solicitará efetivamente 100 documentos para uso no reclassificado, usando o vetor não compactado original para essa finalidade. Somente os principais k resultados reclassificados são retornados. Essa propriedade é opcional. O padrão é 4.

    • vectorSearch.compressions.scalarQuantizationParameters.quantizedDataType deve ser definido como int8. Esse é o único tipo de dados primitivo com suporte no momento. Essa propriedade é opcional. O padrão é int8.

    • vectorSearch.algorithms.kind são "hnsw" ou "exhaustiveKnn". Esses são os algoritmos ANN (Vizinhos Mais Próximos Aproximados) usados para organizar o conteúdo de vetor durante a indexação.

    • vectorSearch.algorithms.m é a contagem de vínculo bidirecional. O padrão é 4. O intervalo é de 4 a 10. Os valores mais baixos devem retornar menos ruído nos resultados.

    • vectorSearch.algorithms.efConstruction é o número de vizinhos mais próximos usados durante a indexação. O padrão é 400. O intervalo é de 100 a 1.000.

    • "vectorSearch.algorithms.fSearch é o número de vizinhos mais próximos usados durante a pesquisa. O padrão é 500. O intervalo é de 100 a 1.000.

    • vectorSearch.algorithms.metric deve ser "cosine" se você estiver usando o Azure OpenAI. Caso contrário, use a métrica de similaridade associada ao modelo de inserção que você está usando. Os valores com suporte são cosine, dotProduct, euclidean e hamming (usados para indexar dados binários).

    • vectorSearch.profiles adicionam uma camada de abstração para receber definições mais avançadas. Um perfil é definido em vectorSearch e, em seguida, referenciado pelo nome em cada campo vetorial. É uma combinação de configurações de compactação e algoritmo. Essa é a propriedade que você atribui a um campo de vetor e ela determina o algoritmo e a compactação dos campos.

Adicionar um campo vetorial à coleção de campos

A coleção de campos deve incluir um campo para a chave do documento, campos vetoriais e quaisquer outros campos necessários para cenários de pesquisa híbrida.

Os campos de vetor são caracterizados por seu tipo de dados, uma propriedade dimensions baseada no modelo de inserção usado para gerar os vetores e um perfil de vetor.

2024-07-01 está em disponibilidade geral.

  1. Use Criar ou Atualizar Índice para criar o índice.

  2. Defina um campo vetorial com os atributos a seguir. Você pode armazenar uma inserção gerada por campo. Para cada campo vetorial:

    • type precisa ser um tipo de dados de vetor. Collection(Edm.Single) é o mais comum para inserir modelos.
    • dimensions é o número de dimensões geradas pelo modelo de inserção. Para text-embedding-ada-002, é 1536.
    • vectorSearchProfile é o nome de um perfil definido em outro lugar no índice.
    • searchable deve ser true.
    • retrievable deve ser true ou false. True retorna os vetores brutos (1536 deles) como texto sem formatação e consome espaço de armazenamento. Defina como true, se você estiver passando um resultado de vetor para um aplicativo downstream.
    • stored deve ser true ou false. Ele determina se uma cópia extra de vetores é armazenada para recuperação. Para obter mais informações, consulte Reduzir o tamanho do vetor.
    • filterable, facetable e sortable devem ser false.

  3. Adicione campos não vetoriais filtráveis à coleção, como "título" com filterabledefinido como verdadeiro, se você deseja invocar a pré-filtragem ou pós-filtragem na consulta vetorial.

  4. Adicione outros campos que definem a substância e a estrutura do conteúdo textual que você está indexando. No mínimo, você precisa de uma chave de documento.

    Você também deve adicionar campos úteis na consulta ou na resposta da consulta. O exemplo a seguir mostra campos vetoriais para título e conteúdo ("titleVector", "contentVector") que são equivalentes a vetores. Ele também fornece campos para o conteúdo textual equivalente ("title", "content") útil para classificação, filtragem e leitura em um resultado da pesquisa.

    O exemplo a seguir mostra a coleção de campos:

    PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2024-07-01&allowIndexDowntime=true
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "filterable": true
        },
        {
            "name": "title",
            "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        }
    ],
    "vectorSearch": {
        "algorithms": [
            {
                "name": "hnsw-1",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ],
        "profiles": [
            {
                "name": "vector-profile-1",
                "algorithm": "hnsw-1"
            }
        ]
    }
}

Carregar dados vetoriais para indexação

O conteúdo fornecido para indexação deve estar em conformidade com o esquema de índice e incluir um valor de cadeia de caracteres exclusivo para a chave do documento. Os dados pré-vetorizados são carregados em um ou mais campos vetoriais, que podem coexistir com outros campos que contêm conteúdo não vetorial.

Você pode usar metodologias de push ou pull para ingestão de dados.

Use Documentos – Índice para carregar dados de vetor e não de vetor em um índice. As APIs de push para indexação são idênticas em todas as versões estáveis e versões prévias. Use qualquer uma das seguintes APIs para carregar documentos:

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version=2024-07-01

{
    "value": [
        {
            "id": "1",
            "title": "Azure App Service",
            "content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
            "category": "Web",
            "titleVector": [
                -0.02250031754374504,
                 . . . 
                        ],
            "contentVector": [
                -0.024740582332015038,
                 . . .
            ],
            "@search.action": "upload"
        },
        {
            "id": "2",
            "title": "Azure Functions",
            "content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
            "category": "Compute",
            "titleVector": [
                -0.020159931853413582,
                . . .
            ],
            "contentVector": [
                -0.02780858241021633,
                 . . .
            ],
            "@search.action": "upload"
        }
        . . .
    ]
}

Verificar o índice em busca de conteúdo vetorial

Para fins de validação, você pode consultar o índice usando o Gerenciador de Pesquisa no portal do Azure ou uma chamada à API REST. Como o Azure AI Search não pode converter um vetor em texto legível para os usuários, tente retornar campos do mesmo documento que fornecem evidências da correspondência. Por exemplo, se a consulta vetorial for direcionada ao campo "titleVector", você poderá selecionar "title" para os resultados da pesquisa.

Os campos devem ser atribuídos como "retrievable" para serem incluídos nos resultados.

  • Examine os índices em Gerenciamento de pesquisa>Índices para exibir o tamanho total do índice e o tamanho do índice de vetor. Um tamanho de índice de vetor positivo indica que há vetores presentes.

  • Você pode usar o Gerenciador de Pesquisa para consultar um índice. O Gerenciador de Pesquisa tem duas exibições: visualização da consulta (padrão) e exibição JSON.

    • Definir Opções de consulta>Ocultar valores de vetor nos resultados da pesquisa para obter resultados mais legíveis.

    • Use a exibição JSON para consultas e vetor. Você pode colar em uma definição JSON da consulta de vetor que deseja executar ou usar a conversão interna de texto para vetor ou imagem para vetor se o índice tiver uma atribuição de vetorizador. Para obter mais informações sobre a pesquisa de imagens, confira Início Rápido: Pesquisar imagens no Gerenciador de Pesquisa.

    • Use a exibição de Consulta padrão para uma confirmação rápida de que o índice contém vetores. A exibição de consulta é para pesquisa de texto completo. Embora você não possa usá-la para consultas vetoriais, você pode enviar uma pesquisa vazia (search=*) para verificar se há conteúdo. O conteúdo de todos os campos, inclusive campos vetoriais, é retornado como texto sem formatação.

    • Confira Criar uma consulta de vetor para obter mais detalhes.

Atualizar um repositório de vetores

Para atualizar um repositório de vetores, modifique o esquema e, se necessário, recarregue documentos para preencher novos campos. As APIs para atualizações de esquema incluem Criar ou atualizar índice (REST), CreateOrUpdateIndex no SDK do Azure para .NET, create_or_update_index no SDK do Azure para Python e métodos semelhantes em outros SDKs do Azure.

As diretrizes padrão para atualizar um índice são abordadas em Atualizar ou recompilar um índice.

Os pontos-chave incluem o seguinte:

  • A remoção e a recompilação geralmente são necessárias para atualizações e exclusão de campos existentes.

  • No entanto, você pode atualizar um esquema existente com as seguintes modificações, sem a necessidade de recompilação:

    • Adicionar novos campos a uma coleção de campos.
    • Adicionar novas configurações de vetor, atribuídas a novos campos, mas não campos existentes que já foram vetorizados.
    • Alterar "retrievable" (os valores são true ou false) em um campo existente. Os campos de vetor precisam ser pesquisáveis e recuperáveis, mas se você quiser desabilitar o acesso a um campo de vetor em situações em que a remoção e a recompilação não são viáveis, você pode definir retrievable como false.

Próximas etapas

Como próxima etapa, recomendamos Consultar dados vetoriais em um índice de pesquisa.

Os exemplos de código no repositório azure-search-vector demonstram os fluxos de trabalho de ponta a ponta que incluem definição de esquema, vetorização, indexação e consultas.

Há um código de demonstração para Python, C# e JavaScript.