No Azure AI Search, 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 o espaço de incorporação e configurações em definições de campo vetorial 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 vetoriais para indexação e pesquisa
Este artigo explica o fluxo de trabalho e usa REST para ilustrar cada etapa. Cada versão recente da API REST adiciona novas funcionalidades. Depois de entender o fluxo de trabalho básico e o que cada versão da API fornece, continue com os exemplos de código do SDK do Azure no repositório azure-search-vector-samples para obter orientação sobre como usar esses recursos no código de teste e produção.
Gorjeta
Use o portal do Azure para criar um índice de vetores e experimentar a vetorização integrada.
Pré-requisitos
Azure AI Search, em qualquer região e em qualquer camada. A maioria dos serviços existentes suporta pesquisa vetorial. Para serviços criados antes de janeiro de 2019, há um pequeno subconjunto que não pode criar um índice vetorial. Nessa situação, um novo serviço deve ser criado.
Incorporações vetoriais pré-existentes em seus documentos de origem se você estiver usando a versão geralmente disponível dos SDKs do Azure e APIs REST. Para obter mais informações, consulte Gerar incorporações. Uma alternativa é a vetorização integrada (visualização).
Você deve saber o limite de dimensões do modelo usado para criar as incorporações e como a semelhança é calculada. No Azure OpenAI, para text-embedding-ada-002, o comprimento do vetor numérico é 1536. A semelhança é calculada usando cosine. Os valores válidos são de 2 a 3072 dimensões.
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 uma carga útil do documento que inclua campos de dados vetoriais e não vetoriais. A estrutura do documento deve estar em conformidade com o esquema de índice.
Certifique-se de que os seus documentos:
Forneça um campo ou uma propriedade de metadados que identifique 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 possa identificá-lo exclusivamente no índice. Este campo de origem deve ser mapeado para um campo de índice do tipo Edm.String e key=true no índice de pesquisa.
Forneça dados vetoriais (uma matriz de números de ponto flutuante de precisão única) em campos de origem.
Os campos vetoriais contêm dados numéricos gerados por modelos de incorporação, uma incorporação por campo. Recomendamos os modelos de incorporação no Azure OpenAI, como text-embedding-ada-002 para documentos de texto ou a API REST de recuperação de imagem para imagens. Apenas campos vetoriais de nível superior de índice são suportados: subcampos vetoriais não são suportados no momento.
Forneça outros campos com conteúdo alfanumérico legível por humanos para a resposta da consulta e para cenários de consulta híbridos que incluam pesquisa de texto completo ou classificação semântica na mesma solicitaçã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 não é especialmente útil. A pesquisa por palavras-chave, a pesquisa geográfica ou os filtros seriam a melhor escolha. Um índice de pesquisa que inclui uma coleção de campo abrangente de dados vetoriais e não vetoriais fornece a máxima flexibilidade para a construção de consultas e composição de respostas.
Um pequeno exemplo de uma carga útil de documentos que inclui campos vetoriais e não vetoriais está na seção de dados vetoriais de carga deste artigo.
Adicionar uma configuração de pesquisa vetorial
Uma configuração vetorial especifica o algoritmo de pesquisa vetorial e os parâmetros usados durante a indexação para criar informações de "vizinho mais próximo" entre os nós vetoriais:
Pequeno Mundo Navegável Hierárquico (HNSW)
KNN exaustivo
Se você escolher HNSW em um campo, poderá optar por KNN exaustivo no momento da consulta. Mas a outra direção não funciona: se você escolher exaustiva, não poderá solicitar posteriormente a pesquisa HNSW porque as estruturas de dados extras que permitem a pesquisa aproximada não existem.
Procurando orientação de migração de versão de visualização para estável? Consulte Atualizar APIs REST para conhecer as etapas.
Nome da configuração. O nome deve ser exclusivo dentro do índice.
profiles Adicione uma camada de abstração para acomodar definições mais ricas. Um perfil é definido em e, em vectorSearchseguida, referenciado pelo nome em cada campo vetorial.
"hnsw" e "exhaustiveKnn" são os algoritmos ANN (Approximate Nearest Neighbors) usados para organizar o conteúdo vetorial durante a indexação.
"m" (contagem de links bidirecional) o padrão é 4. O intervalo é de 4 a 10. Valores mais baixos devem retornar menos ruído nos resultados.
"efConstruction" o padrão é 400. O intervalo é de 100 a 1.000. É o número de vizinhos mais próximos usado durante a indexação.
"efSearch" O padrão é 500. O intervalo é de 100 a 1.000. É o número de vizinhos mais próximos usado durante a pesquisa.
"metric" deve ser "cosseno" 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, euclidean.
2024-05-01-Preview é a versão mais recente. Ele adiciona mais opções de codificação, mas a configuração de pesquisa vetorial (vectorSearch estrutura) é praticamente idêntica à visualização 2024-03-01.
Adiciona hamming distância como uma métrica para a pesquisa de vizinhos mais próximos sobre dados binários. Para obter mais informações, consulte Indexar dados binários para pesquisa vetorial.
Expande a vetorização integrada com mais opções de modelos de incorporação. Para se beneficiar desse recurso, você deve depender de um indexador e de um conjunto de habilidades. Consulte Carregar dados vetoriais e a seção APIs de pull para obter uma lista das novas habilidades de incorporação.
Use a API REST Criar ou Atualizar Visualização de Índice para criar o índice.
Inclusive de 2023-11-01 vectorSearch.algorithms e vectorSearch.profiles.
Use a API REST Criar ou Atualizar Visualização de Índice para criar o índice.
Adicione uma vectorSearch seção no índice que especifique as configurações de compactação e os algoritmos de pesquisa usados para criar o espaço de incorporação. Para obter mais informações, consulte Configurar quantização vetorial e armazenamento reduzido.
vectorSearch.compressions.kind deve ser scalarQuantization.
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 é verdadeiro.
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.
quantizedDataType deve ser definido como int8. Este é o único tipo de dados primitivo suportado no momento. Esta propriedade é opcional. A predefinição é int8.
2023-10-01-Preview adiciona vetorização interna, mas a configuração de pesquisa vetorial (vectorSearch estrutura) é praticamente idêntica à versão 2023-11-01.
Use a API REST Criar ou Atualizar Visualização de Índice para criar o índice.
Adicione uma vectorSearch seção no índice que especifique os algoritmos de pesquisa usados para criar o espaço de incorporação.
Nome da configuração. O nome deve ser exclusivo dentro do índice.
profiles são novos nesta pré-visualização. Eles adicionam uma camada de abstração para acomodar definições mais ricas. Um perfil é definido em e, em vectorSearchseguida, como uma propriedade em cada campo vetorial.
hnsw e "exhaustiveKnn" são os algoritmos ANN (Approximate Nearest Neighbors) usados para organizar o conteúdo vetorial durante a indexação.
m (contagem de links bidirecional) o padrão é 4. O intervalo é de 4 a 10. Valores mais baixos devem retornar menos ruído nos resultados.
efConstruction o padrão é 400. O intervalo é de 100 a 1.000. É o número de vizinhos mais próximos usado durante a indexação.
efSearch O padrão é 500. O intervalo é de 100 a 1.000. É o número de vizinhos mais próximos usado durante a pesquisa.
metric deve ser "cosseno" 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, euclidean.
Importante
2023-07-01-Preview foi a primeira versão da API REST a suportar vetores. Ele usa estruturas obsoletas que foram substituídas em visualizações mais recentes. Recomendamos migrar para uma API REST mais recente.
Esta pré-visualização adicionou:
vectorSearch.algorithmConfigurations para especificar o algoritmo HNSW.
hnsw algoritmo vizinho mais próximo para indexação de conteúdo vetorial.
Use a API REST Criar ou Atualizar Índice para criar o índice.
Adicione uma vectorSearch seção no índice que especifique o algoritmo de pesquisa usado para criar o espaço de incorporação.
Nome da configuração. O nome deve ser exclusivo dentro do índice.
hnsw é o algoritmo ANN (Approximate Nearest Neighbors) usado para criar o gráfico de proximidade durante a indexação. Apenas o mundo pequeno navegável hierárquico (HNSW) é suportado nesta versão da API.
m (contagem de links bidirecional) o padrão é 4. O intervalo é de 4 a 10. Valores mais baixos devem retornar menos ruído nos resultados.
efConstruction o padrão é 400. O intervalo é de 100 a 1.000. É o número de vizinhos mais próximos usado durante a indexação.
efSearch O padrão é 500. O intervalo é de 100 a 1.000. É o número de vizinhos mais próximos usado durante a pesquisa.
metric deve ser "cosseno" 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, euclidean.
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 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 vetorial.
Defina um campo vetorial com os seguintes atributos. Você pode armazenar uma incorporação gerada por campo. Para cada campo vetorial:
type deve estar Collection(Edm.Single) nesta versão da API.
dimensions é o número de dimensões geradas pelo modelo de incorporação. Para text-embedding-ada-002, é 1536.
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 (1536 deles) como texto simples e consome espaço de armazenamento. Defina como true se você estiver passando um resultado vetorial para um aplicativo downstream.
filterable, facetable, sortable deve ser falso.
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.
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 de vetor para título e conteúdo ("titleVector", "contentVector") que são equivalentes a vetores. Ele também fornece campos para conteúdo textual equivalente ("título", "conteúdo") útil para classificar, filtrar e ler em um resultado de pesquisa.
As definições de campo vetorial são as mesmas que 2024-03-01-preview, com exceção de um novo tipo de dados binários. Para obter mais informações, consulte Indexar dados binários para pesquisa vetorial.
Use a API REST Create or Update Index Preview para definir a coleção de campos de um índice.
Esta versão da API baseia-se no 2023-10-01-preview adicionando suporte para tipos de dados estreitos e quantização escalar.
Use a API REST Create or Update Index Preview para definir a coleção de campos de um índice.
Adicione campos vetoriais à coleção de campos. Você pode armazenar uma incorporação gerada por campo de documento. Para cada campo vetorial:
type pode ser Collection(Edm.Single), Collection(Edm.Half), Collection(Edm.Int16), , Collection(Edm.SByte)
dimensions é o número de dimensões geradas pelo modelo de incorporação. Para text-embedding-ada-002, é 1536.
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 (1536 deles) como texto simples e consome espaço de armazenamento. Defina como true se você estiver passando um resultado vetorial para um aplicativo downstream. False é necessário se stored for false.
stored é uma nova propriedade booleana que se aplica apenas a campos vetoriais. True armazena uma cópia dos vetores retornados nos resultados da pesquisa. False descarta essa cópia durante a indexação. Você pode pesquisar em vetores, mas não pode retornar vetores nos resultados.
No exemplo da API REST a seguir, "title" e "content" contêm conteúdo textual usado na pesquisa de texto completo e classificação semântica, enquanto "titleVector" e "contentVector" contêm dados vetoriais. Nesta versão da API, você pode usar indexadores e um conjunto de habilidades para preencher o campo vetorial usando vetorização integrada. A definição de índice não muda, mas você pode adicionar indexadores e habilidades à sua solução para preencher os campos.
Use a API REST Create or Update Index Preview para definir a coleção de campos de um índice.
Adicione campos vetoriais à coleção de campos. Você pode armazenar uma incorporação gerada por campo de documento. Para cada campo vetorial:
type deve ser Collection(Edm.Single).
dimensions é o número de dimensões geradas pelo modelo de incorporação. Para text-embedding-ada-002, é 1536.
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 (1536 deles) como texto simples e consome espaço de armazenamento. Defina como true se você estiver passando um resultado vetorial para um aplicativo downstream.
filterable, facetable, sortable deve ser falso.
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](vector-search-how-to-query.md
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 de vetor para título e conteúdo ("titleVector", "contentVector") que são equivalentes a vetores. Ele também fornece campos para conteúdo textual equivalente ("título", "conteúdo") útil para classificar, filtrar e ler em um resultado de pesquisa.
As definições de campo vetorial para esta versão são obsoletas em versões posteriores. Recomendamos migrar para uma API REST mais recente.
2023-07-01-Preview foi a primeira versão da API REST a suportar cenários vetoriais.
No exemplo da API REST a seguir, "title" e "content" contêm conteúdo textual usado na pesquisa de texto completo e classificação semântica, enquanto "titleVector" e "contentVector" contêm dados vetoriais que foram gerados externamente.
Use a API REST Create or Update Index Preview para definir a coleção de campos de um índice.
Adicione campos vetoriais à coleção de campos. Você pode armazenar uma incorporação gerada por campo de documento. Para cada campo vetorial:
Atribua o tipo de Collection(Edm.Single) dados.
Forneça o nome da configuração do algoritmo de pesquisa vetorial.
Forneça o número de dimensões geradas pelo modelo de incorporação.
Definir atributos:
"pesquisável" deve ser "verdadeiro".
"recuperável" definido como "true" permite que você exiba os vetores brutos (por exemplo, como uma etapa de verificação), mas isso aumenta o armazenamento. Defina como "false" se não precisar retornar vetores brutos. Você não precisa retornar vetores para uma consulta, mas se estiver passando um resultado vetorial para um aplicativo downstream, defina "recuperável" como "true".
Os atributos "filtrável", "facetable", "classificável" devem ser "false". Não os defina como "true" porque esses comportamentos não se aplicam no contexto de campos vetoriais e a solicitação falhará.
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 de vetor para título e conteúdo ("titleVector", "contentVector") que são equivalentes a vetores. Ele também fornece campos para conteúdo textual equivalente ("título", "conteúdo") útil para classificar, filtrar e ler em um resultado de pesquisa.
Uma definição de índice com os elementos descritos tem esta aparência:
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 alfanumérico.
Você pode usar metodologias push ou pull para ingestão de dados.
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=2023-11-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
"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"
}
. . .
]
}
Todas as versões de visualização mais recentes usam APIs pull (indexadores e conjuntos de habilidades) para vetorização integrada durante a indexação e o tempo de consulta.
Os indexadores podem recuperar e indexar campos vetoriais em documentos de origem, assumindo um esquema de índice que atenda aos requisitos de campo vetorial e à API REST de visualização. As fontes de dados fornecem os vetores em qualquer formato suportado pela fonte de dados (como cadeias de caracteres em JSON). O indexador assume que os campos digitados como Collection(Edm.Single) contêm vetores e indexará esse conteúdo como índices vetoriais.
Nenhuma alteração no comportamento de mapeamento de campo ou deteção de alterações para vetores. Os comportamentos para indexação de texto também se aplicam a vetores.
Se os dados vetoriais forem originados em arquivos, recomendamos um não padrão parsingMode , como json, jsonLinesou csv com base na forma dos dados.
Para fontes de dados, os indexadores de blob do Azure e os indexadores do Azure Cosmos DB para NoSQL com um dos parsingModes acima mencionados foram testados e confirmados para funcionar.
O SQL do Azure não fornece uma maneira de armazenar uma coleção nativamente como uma única coluna SQL. Uma solução alternativa não foi identificada no momento.
As dimensões de todos os vetores da fonte de dados devem ser as mesmas e corresponder à definição de índice para o campo para o qual estão mapeando. O indexador lança um erro em todos os documentos que não correspondem.
Habilidades e vetorizadores são usados para gerar incorporações. Para vetorização durante a indexação, escolha entre as seguintes habilidades:
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 campo "titleVector", você poderá selecionar "title" para os resultados da pesquisa.
Os campos devem ser atribuídos como "recuperáveis" para serem incluídos nos resultados.
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.
O exemplo de API REST a seguir é uma consulta vetorial, mas retorna apenas campos não vetoriais (título, conteúdo, categoria). Apenas os campos marcados como "recuperáveis" podem ser devolvidos nos resultados da pesquisa.
Para atualizar um repositório vetorial, modifique o esquema e, se necessário, 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.
Soltar e reconstruir geralmente é necessário para atualizações e exclusão de campos existentes.
No entanto, você pode atualizar um esquema existente com as seguintes modificações, sem necessidade 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á foram vetorizados.
Altere "recuperável" (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.
Exemplos de código no repositório azure-search-vector demonstram fluxos de trabalho de ponta a ponta que incluem definição de esquema, vetorização, indexação e consultas.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.