Compartilhar via

Criar um índice de vetor

No Azure AI Search, você pode usar a API REST (Criar ou Atualizar Índice) para armazenar vetores em um índice de pesquisa. Um índice de vetor é definido por um esquema de índice que tem campos de vetor, campos não vetoriais e uma seção de configuração de vetor.

Ao criar um índice de vetor, você cria implicitamente um espaço de inserção que serve como o corpus para consultas de vetor. O espaço de inserção consiste em todos os campos de vetor preenchidos com inserções do mesmo modelo de inserção. No momento da consulta, o sistema compara a consulta de vetor com os vetores indexados, retornando resultados com base na similaridade semântica.

Para indexar vetores no Azure AI Search, siga estas etapas:

  • Comece com uma definição básica de esquema.
  • Adicione algoritmos de vetor e compactação opcional.
  • Adicionar definições de campo de vetor.
  • Carregue dados pré-configurados como uma etapa separada ou use a vetorização integrada para agrupamento e inserção de dados durante a indexação.

Este artigo usa REST para ilustração. Depois de entender o fluxo de trabalho básico, continue com os exemplos de código do SDK do Azure no repositório azure-search-vector-samples , que fornece diretrizes sobre como usar vetores no código de teste e produção.

Dica

Você também pode usar o portal do Azure para criar um índice de vetor e experimentar o agrupamento e a vetorização de dados integrados.

Pré-requisitos

  • Um serviço do Azure AI Search em qualquer região e em qualquer camada. Se você planeja usar a vetorização integrada com as habilidades e vetores de IA do Azure, o Azure AI Search deverá estar na mesma região que os modelos de inserção hospedados na Visão de IA do Azure.

  • Seus documentos de origem devem ter inserções de vetor para carregar no índice. Você também pode usar a vetorização integrada para esta etapa.

  • Você deve saber o limite de dimensões do modelo que cria as inserções para que você possa atribuir esse limite ao campo de vetor. Para text-embedding-ada-002, as dimensões são fixadas em 1536. Para texto-embedding-3-small ou text-embedding-3-large, as dimensões variam de 1 a 1536 e de 1 a 3072, respectivamente.

  • Você deve saber qual métrica de similaridade usar. Para inserir modelos no Azure OpenAI, a similaridade é computada usando cosine.

  • Você deve saber como criar um índice. Um esquema sempre inclui um campo para a chave do documento, campos para pesquisa ou filtros e outras configurações para comportamentos necessários durante a indexação e consultas.

Limitações

Alguns serviços de pesquisa criados antes de janeiro de 2019 não podem criar um índice de vetor. Se isso se aplica a você, crie um novo serviço para usar vetores.

Preparar documentos para indexação

Antes de indexar, monte uma carga de documento que inclua campos de dados vetoriais e não vetoriais. A estrutura do documento deve estar em conformidade com a coleção de campos do esquema de índice.

Verifique se os documentos de origem fornecem o seguinte conteúdo:

Conteúdo Descrição
Identificador exclusivo Um campo ou uma propriedade de metadados que identifica 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 o identifique exclusivamente no índice. Se você estiver indexando blobs, pode ser o metadata_storage_path que identifica exclusivamente cada blob. Se você estiver indexando a partir de um banco de dados, pode ser a chave primária. Esse campo de origem deve ser mapeado para um campo de índice do tipo Edm.String e key=true no índice de pesquisa.
Conteúdo não vetor Forneça outros campos com conteúdo legível por humanos. O conteúdo legível por humanos é útil para a resposta da consulta e para consultas híbridas que incluem pesquisa de texto completo ou classificação semântica na mesma solicitação. Se você estiver usando um modelo de conclusão de chat, a maioria dos modelos como ChatGPT espera texto legível por humanos e não aceita vetores brutos como entrada.
Conteúdo do vetor Uma representação vetorizada do conteúdo não vetor para uso no momento da consulta. Um vetor é uma matriz de números de ponto flutuante de precisão única gerados por um modelo de inserção. Cada campo de vetor contém uma matriz gerada por modelo. Há 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). Para uma integração simples, recomendamos a inserção de modelos no Azure OpenAI, como a inserção de texto-3 para documentos de texto ou a API REST de Recuperação de Imagem para imagens e inserções multimodal.

Se você puder usar indexadores e conjuntos de habilidades, considere a vetorização integrada, que codifica imagens e texto durante a indexação. Suas definições de campo são para campos vetoriais, mas os dados de origem recebidos podem ser texto ou imagens, que são convertidos em matrizes vetoriais durante a indexaçã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 de vetor não é especialmente útil. Pesquisa de palavra-chave, pesquisa geográfica ou filtros que iteram sobre conteúdo literal seria uma opção melhor. Um índice de pesquisa que inclui campos vetoriais e não vetoriais oferece flexibilidade máxima para a construção de consultas e composição de respostas.

Para obter um breve exemplo de conteúdo de documentos que inclui campos de vetor e não vetor, consulte a seção dados de vetor de carga deste artigo.

Começar com um índice básico

Comece com um esquema mínimo para que você tenha uma definição para trabalhar antes de adicionar uma configuração de vetor e campos de vetor. Um índice simples pode ser o exemplo a seguir. Para obter mais informações sobre um esquema de índice, consulte Criar um índice de pesquisa.

Observe que o índice tem um nome necessário, uma chave de documento necessária ("key": true) e campos para conteúdo legível por humanos em texto sem formatação. É comum ter uma versão legível por humanos de qualquer conteúdo que você pretende vetorizar. Por exemplo, se você tiver uma parte de texto de um arquivo PDF, seu esquema de índice deverá ter um campo para partes de texto sem formatação e um segundo campo para partes vetorizadas.

Aqui está um índice básico com um "name", uma "fields" coleção e alguns outros constructos para configuração extra:

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "example-index",
  "fields": [
    { "name": "documentId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "myHumanReadableNameField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "myHumanReadableContentField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
  ],
  "analyzers": [ ],
  "scoringProfiles": [ ],
  "suggesters": [ ],
  "vectorSearch": [ ]
}

Adicionar uma configuração de busca em vetores

Em seguida, adicione uma "vectorSearch" configuração ao esquema. É útil especificar uma configuração antes das definições de campo, pois os perfis definidos aqui se tornam parte da definição do campo de vetor. No esquema, a configuração de vetor normalmente é inserida após a coleção de campos, talvez após "analyzers", "scoringProfiles"e "suggesters". No entanto, a ordem não importa.

Uma configuração de vetor inclui:

  • vectorSearch.algorithms usado durante a indexação para criar informações de "vizinho mais próximo" entre os nós de vetor.
  • vectorSearch.compressions para quantização escalar ou binária, superamostragem e reclassificação com vetores originais.
  • vectorSearch.profiles para especificar várias combinações de configurações de algoritmo e compactação.

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

  • Algoritmo HNSW (Navigable Small World) hierárquico.
  • Algoritmo exaustivo de K-Nearest Neighbor (KNN).
  • Compactação escalar.
  • Compactação binária, que está disponível somente em 2024-07-01 e em pacotes mais recentes do SDK do Azure.
  • Excesso de sobrecarga.
  • Reclassificado com vetores originais.

Se você escolher HNSW em um campo, poderá optar por KNN exaustivo no momento da consulta. No entanto, o oposto não funciona. Se você escolher exaustivo para indexação, não poderá solicitar posteriormente a pesquisa HNSW porque as estruturas de dados extras que habilitam a pesquisa aproximada não existem.

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

  1. Use a API REST 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 pode ser scalarQuantization ou binaryQuantization. A quantização escalar comprime valores flutuantes em tipos de dados mais restritos. A quantização binária converte floats em valores binários de 1 bit.

    • vectorSearch.compressions.rerankWithOriginalVectors usa os vetores originais e não compactados para recalcular a similaridade e reorganizar 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 é true.

    • vectorSearch.compressions.defaultOversampling considera um conjunto mais amplo de resultados potenciais para compensar a redução na informação da quantizaçã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 reclassificador, 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 é 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.efSearch é 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, dotProducte euclideanhamming (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 referenciado pelo seu nome em cada campo vetorial. É uma combinação de configurações de compactação e algoritmo. Você atribui essa propriedade a um campo de vetor e determina o algoritmo e a compactação dos campos.

Adicionar um campo vetorial à coleção de campos

Depois de ter uma configuração de vetor, você poderá adicionar um campo de vetor à coleção de campos. Lembre-se de que a coleção de campos deve incluir um campo para a chave do documento, campos de vetor e quaisquer outros campos não vetoriais necessários para cenários de pesquisa híbrida ou preenchimento de modelo de chat em cargas de trabalho RAG.

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

2024-07-01 está em disponibilidade geral.

  1. Use a API REST Criar ou Atualizar Índice para criar o índice e adicionar um campo de vetor à coleção de campos.

    {
  "name": "example-index",
  "fields": [
    {
        "name": "contentVector",
        "type": "Collection(Edm.Single)",
        "searchable": true,
        "retrievable": false,
        "stored": false,
        "dimensions": 1536,
        "vectorSearchProfile": "vector-profile-1"
    }
  ]
}

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

    • type deve 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, o valor é fixo em 1536. Para a série de modelos text-embedding-3, há um intervalo de valores. Se você estiver usando vetorização integrada e uma habilidade de inserção para gerar vetores, verifique se essa propriedade está definida para o mesmo valor de dimensões usado pela habilidade de inserção.
    • vectorSearchProfile é o nome de um perfil definido em outro lugar no índice.
    • searchable deve ser verdadeiro.
    • retrievable deve ser true ou false. True retorna os vetores brutos (1.536 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, facetablee sortable deve ser falso.

  3. Adicione campos não vetoriais filtráveis à coleção, como title com filterable definido como true, se você quiser invocar pré-filtragem ou pós-filtragem na consulta de vetor.

  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 de vetor para título e conteúdo (titleVector e contentVector) que são equivalentes a vetores. Ele também fornece campos para conteúdo textual equivalente (title e content) que são úteis para classificação, filtragem e leitura em um resultado de 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.

Para ingestão de dados, você pode usar metodologias push ou pull.

Use Documentos – Índice para carregar dados vetoriais e não vetoriais 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"
        }
        . . .
    ]
}

Consultar o índice para obter conteúdo de vetor

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 de vetor for direcionada ao campo titleVector, você poderá selecionar os resultados da pesquisa title.

Os campos devem ser atribuídos retrievable a 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 de vetor. Você pode colar uma definição JSON da consulta de vetor que deseja executar. Se o índice tiver uma atribuição de vetor, você também poderá usar a conversão interna de texto para vetor ou imagem para vetor. 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 visualização de consulta destina-se à 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.

Para obter mais informações, consulte Criar uma consulta de vetor.

Atualizar um índice de vetor

Para atualizar um índice de vetor, modifique o esquema e 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.

Para obter diretrizes padrão sobre como atualizar um índice, consulte Atualizar ou recompilar um índice.

Os pontos-chave incluem o seguinte:

  • A remoção e recriação completa do índice geralmente é necessária para atualizações e exclusão de campos existentes.

  • Você pode fazer as seguintes modificações sem nenhum requisito de recompilação:

    • Adicionar novos campos a uma coleção de campos.
    • Adicione novas configurações de vetor, atribuídas a novos campos, mas não campos existentes que já estão vetorizados.
    • Altere retrievable (os valores são verdadeiro ou falso) 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 criar uma consulta de vetor.

Os exemplos de código no repositório azure-search-vector-samples demonstram 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.