Partilhar via

Criar um índice de vetores

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

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

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

  • Comece com uma definição básica de esquema.
  • Adicione algoritmos vetoriais e compressão opcional.
  • Adicione definições de campo vetorial.
  • Carregue dados pré-vetorizados como uma etapa separada ou use vetorização integrada para fragmentação e incorporaçã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 orientação sobre o uso de vetores no código de teste e produção.

Gorjeta

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

Pré-requisitos

  • Um serviço Azure AI Search em qualquer região e em qualquer camada. Se você planeja usar vetorização integrada com habilidades e vetorizadores de IA do Azure, a Pesquisa de IA do Azure deve estar na mesma região que os modelos de incorporação hospedados no Azure AI Vision.

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

  • Você deve saber o limite de dimensões do modelo que cria as incorporações para poder atribuir esse limite ao campo vetorial. Para text-embedding-ada-002, as dimensões são fixadas em 1536. Para text-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 semelhança usar. Para incorporar modelos no Azure OpenAI, a semelhança é calculada 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 conseguem criar um índice vetorial. Se isso se aplicar a você, crie um novo serviço para usar vetores.

Preparar documentos para indexação

Antes da indexação, monte uma carga útil do 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.

Certifique-se de que 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. Todos os índices de pesquisa requerem uma chave de documento. Para satisfazer os 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 a 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. Este 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 vetorial 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 bate-papo, a maioria dos modelos como o ChatGPT espera texto legível por humanos e não aceita vetores brutos como entrada.
Conteúdo vetorial Uma representação vetorizada do seu conteúdo não vetorial 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 incorporação. Cada campo vetorial contém uma matriz gerada por modelo. Há um embedding por campo, sendo este um campo de nível superior (não parte de um tipo aninhado ou complexo). Para uma integração simples, recomendamos a incorporação de modelos no Azure OpenAI, como a incorporação de texto-3 para documentos de texto ou a API REST de recuperação de imagem para imagens e incorporações multimodais.

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 de entrada podem ser texto ou imagens, que são convertidos em matrizes vetoriais durante a indexação.

Seu índice de pesquisa deve incluir campos e conteúdo para todos os cenários de consulta aos quais você deseja oferecer suporte. Suponha que você queira pesquisar ou filtrar nomes, versões, metadados ou endereços de produtos. Neste caso, a pesquisa de semelhança vetorial não é especialmente útil. Pesquisa de palavras-chave, pesquisa geográfica ou filtros que iteram sobre o conteúdo literal seriam uma escolha melhor. Um índice de pesquisa que inclui campos vetoriais e não vetoriais fornece a máxima flexibilidade para a construção de consultas e composição de respostas.

Para obter um pequeno exemplo de uma carga útil de documentos que inclui campos vetoriais e não vetoriais, consulte a seção de dados vetoriais de carga deste artigo.

Comece 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 vetorial e campos vetoriais. 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 obrigatório, uma chave de documento necessária ("key": true) e campos para conteúdo legível por pessoas em texto sem formatação. É comum ter uma versão legível por humanos de qualquer conteúdo que você pretenda vetorizar. Por exemplo, se você tiver um pedaço de texto de um arquivo PDF, seu esquema de índice deverá ter um campo para blocos de texto sem formatação e um segundo campo para blocos vetorizados.

Aqui está um índice básico com um "name", uma "fields" coleção e algumas outras construções para configuração adicional.

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 pesquisa vetorial

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

Uma configuração vetorial inclui:

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

2024-07-01 está disponível em geral. Ele suporta uma configuração vetorial que tem:

  • Algoritmo Hierárquico Navigable Small World (HNSW).
  • Algoritmo exaustivo K-Nearest Neighbor (KNN).
  • Compressão escalar.
  • Compressão binária, que está disponível apenas em 2024-07-01 e em pacotes mais recentes do SDK do Azure.
  • Sobreamostragem.
  • Reclassificação com vetores originais.

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

Certifique-se de ter uma estratégia para vetorizar seu conteúdo. Recomendamos vetorização integrada e vetorizadores em tempo de consulta para codificação integrada.

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

  2. Adicione uma vectorSearch seção no índice que especifique os algoritmos de pesquisa usados para criar o espaço de incorporaçã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 compressão, algoritmo e perfil devem ser exclusivos para seu tipo dentro do índice.

    • vectorSearch.compressions pode ser scalarQuantization ou binaryQuantization. A quantização escalar compacta valores flutuantes em tipos de dados mais estreitos. A quantização binária converte flutuações em valores binários de 1 bit.

    • vectorSearch.compressions.rerankWithOriginalVectors usa os vetores originais não compactados para recalcular a semelhança e reclassificar os principais resultados retornados pela consulta de pesquisa inicial. Os vetores não compactados existem no índice de pesquisa, mesmo que stored seja falso. Esta propriedade é opcional. A predefinição é verdadeira.

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

    • vectorSearch.compressions.scalarQuantizationParameters.quantizedDataType deve ser definido como int8. Este é o único tipo de dados primitivo suportado no momento. Esta propriedade é opcional. A predefinição é int8.

    • vectorSearch.algorithms é hnsw ou exhaustiveKnn. Estes são os algoritmos ANN (Approximate Nearest Neighbors) usados para organizar o conteúdo vetorial durante a indexação.

    • vectorSearch.algorithms.m é a contagem de ligações bidirecionais. O padrão é 4. O intervalo é de 4 a 10. 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 usado 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 semelhança associada ao modelo de incorporação que você está usando. Os valores suportados são cosine, dotProduct, euclideane hamming (usados para indexar dados binários).

    • vectorSearch.profiles Adicione uma camada de abstração para acomodar definições mais ricas. Um perfil é definido em vectorSearch e referenciado pelo nome em cada campo vetorial. É uma combinação de compressão e configurações de algoritmo. Você atribui essa propriedade a um campo vetorial e ela determina o algoritmo e a compactação dos campos.

Adicionar um campo vetorial à coleção de campos

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

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

2024-07-01 está disponível em 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 seguintes atributos. Você pode armazenar uma incorporação gerada por campo. Para cada campo vetorial:

    • type deve ser um tipo de dados vetoriais. Collection(Edm.Single) é o mais comum para incorporar modelos.
    • dimensions é o número de dimensões geradas pelo modelo de incorporação. Para text-embedding-ada-002, é fixado 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 incorporação para gerar vetores, verifique se essa propriedade está definida com o mesmo valor de dimensões usado pela habilidade de incorporação.
    • vectorSearchProfile é o nome de um perfil definido em outra parte do índice.
    • searchable deve ser verdade.
    • retrievable pode ser verdadeiro ou falso. True retorna os vetores brutos (1.536 deles) como texto simples e consome espaço de armazenamento. Defina como true se você estiver passando um resultado vetorial para um aplicativo downstream.
    • stored pode ser verdadeiro ou falso. 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 set to true, se quiser invocar pré-filtragem ou pós-filtragem na consulta vetorial.

  4. Adicione outros campos que definam 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 que sejam úteis na consulta ou em sua resposta. O exemplo a seguir mostra campos vetoriais 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 classificar, filtrar e ler em um resultado de pesquisa.

    O exemplo seguinte 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 contendo conteúdo não vetorial.

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

Use Documents - Index para carregar dados vetoriais e não vetoriais em um índice. As APIs push para indexação são idênticas em todas as versões estáveis e de visualização. 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 seu índice para 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 de API REST. Como a Pesquisa de IA do Azure não pode converter um vetor em texto legível por humanos, tente retornar campos do mesmo documento que forneçam evidências da correspondência. Por exemplo, se a consulta vetorial tiver como alvo o titleVector campo, você poderá selecionar title os resultados da pesquisa.

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

  • Revise os índices em 'Gestão de Pesquisa' e > para exibir o tamanho total do índice e o tamanho do índice vetorial. Um tamanho de índice vetorial positivo indica que os vetores estão presentes.

  • Use o Search Explorer para consultar um índice. O Search Explorer tem dois modos de exibição: modo de exibição de consulta (padrão) e modo de exibição JSON.

    • Definir opções>de consulta Oculte valores vetoriais nos resultados da pesquisa para obter resultados mais legíveis.

    • Use o modo de exibição JSON para consultas vetoriais. Você pode colar uma definição JSON da consulta vetorial que deseja executar. Se o índice tiver uma atribuição de vetorizador, você também poderá usar a conversão interna de texto para vetor ou de imagem para vetor. Para obter mais informações sobre a pesquisa de imagens, consulte Guia de início rápido: pesquisar imagens no Search Explorer.

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

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

Atualizar um índice vetorial

Para atualizar um índice vetorial, modifique o esquema e recarregue documentos para preencher novos campos. As APIs para atualizações de esquema incluem Create or Update Index (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 orientações padrão sobre como atualizar um índice, consulte Atualizar ou reconstruir um índice.

Os pontos-chave incluem:

  • A remoção e a reconstrução completa do índice são frequentemente necessárias para atualizações e exclusão de campos existentes.

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

    • Adicione novos campos a uma coleção de campos.
    • Adicione novas configurações vetoriais, atribuídas a novos campos, mas não a campos existentes que já estão vetorizados.
    • Alterar retrievable (os valores são true ou false) em um campo existente. Os campos vetoriais devem ser pesquisáveis e recuperáveis, mas se você quiser desabilitar o acesso a um campo vetorial em situações em que soltar e reconstruir não é viável, você pode definir recuperável como falso.

Próximos passos

Como próxima etapa, recomendamos Criar uma consulta vetorial.

Exemplos de código no repositório azure-search-vector-samples demonstram fluxos de trabalho completos que incluem definição de esquema, vetorização, indexação e consultas.

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