Realizar a pesquisa de similaridade vetorial com a Vertex AI

Bem-vindo à pesquisa de similaridade vetorial de Firebase Data Connect, a implementação do Firebase da pesquisa semântica que se integra à Vertex AI do Google.

No centro desse recurso estão os embeddings de vetor, que são matrizes de números de ponto flutuante que representam o significado semântico de texto ou mídia. Ao executar uma pesquisa de vizinho mais próximo usando um embedding de vetor de entrada, é possível encontrar todo o conteúdo semanticamente semelhante. Data Connect usa a extensão pgvector do PostgreSQL para esse recurso.

Essa pesquisa semântica avançada pode impulsionar casos de uso, como mecanismos de recomendação e mecanismos de pesquisa. Ela também é um componente essencial na geração aumentada de recuperação em fluxos de IA generativa. A documentação da Vertex AI é um ótimo lugar para saber mais.

É possível contar com o suporte integrado do Data Connect para gerar embeddings de vetor automaticamente usando a API Embeddings da Vertex AI, ou usar essa API para gerá-los manualmente.

Pré-requisitos

Configure Data Connect para seu projeto.

Observação: ao trabalhar no fluxo de configuração, saiba que a integração da Vertex AI do Data Connect's é compatível apenas com determinados locais do Cloud SQL para PostgreSQL. Consulte a lista de locais.
Ative as APIs da Vertex AI.

**Observação** :não é necessário criar um projeto separado do Google Cloud nem instalar a CLI do Google Cloud.

Configuração

É possível escolher entre um fluxo de desenvolvimento local (se você for um desenvolvedor da Web, Kotlin Android ou iOS) ou um fluxo do IDX (para desenvolvedores da Web). É possível usar um banco de dados local ou seu projeto de produção Data Connect e a instância do Cloud SQL para PostgreSQL para desenvolvimento.

Estas instruções pressupõem que você criou seu Data Connect projeto seguindo o guia de início rápido.

Integrar com o PostgreSQL local

Configure uma instância local do PostgreSQL.
Conceda a si mesmo o papel do IAM de usuário da Vertex AI.
Configure o Application Default Credentials do Google Cloud no seu ambiente.
Instale a pgvector extensão na instância local do PostgreSQL.
Ative a extensão usando CREATE EXTENSION vector de acordo com as instruções do repositório pgvector.

Integrar com o IDX

Configure seu espaço de trabalho do IDX usando o Data Connect modelo.
Conceda a si mesmo o papel do IAM de usuário da Vertex AI.
Ative a extensão usando CREATE EXTENSION vector de acordo com as instruções do repositório pgvector.

Projetar seu esquema

Para realizar a pesquisa vetorial, adicione um novo campo do tipo Vector ao esquema. Por exemplo, se você quiser fazer uma pesquisa semântica usando descrições de filmes, adicione um campo para armazenar os embeddings de vetor associados à descrição do filme. Nesse esquema, descriptionEmbedding é adicionado para armazenar embeddings de vetor para o description campo.

type Movie @table {
 id: ID! @col(name: "movie_id") @default(id: ID! @col(name: "movie_id") @default(expr: "uuidV4()")
 title: String!
 description: String
 descriptionEmbedding: Vector! @col(size:768)
 // ...
}

Gerar e recuperar embeddings

Data Connect oferece suporte integrado para embeddings de vetor com o _embed valor do servidor. Isso direciona Data Connect para gerar embeddings de vetor chamando internamente as APIs Embedding da Vertex AI. O valor do servidor _embed pode ser usado em mutações e consultas.

Mutações

Gerar e armazenar um embedding pelo Data Connect

No app de pesquisa vetorial, é provável que você queira solicitar que os embeddings sejam gerados assim que adicionar registros ao banco de dados. Esta createMovie mutação adiciona um registro de filme à tabela Movie e também transmite uma descrição de filme com um model de embedding especificado.

mutation createMovie($title: String!, $description: String!) {
  movie_insert(data: {
    title: $title,
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
  })
}

Em alguns casos, talvez seja necessário atualizar a descrição e o embedding do filme.

mutation updateDescription($id: String!, $description: String!) {
  movie_update(id: $id, data: {
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
  })
}

Para chamar a última mutação de um cliente:

import { updateMovieDescription } from 'lib/dataconnect-sdk/';

await updateMovieDescription({ id: movieId, description: description});

// Use the response

Consultas

Busque embeddings de vetor usando uma consulta como a seguinte. O descriptionEmbedding retornado pela consulta é uma matriz de flutuadores, que normalmente não é legível por humanos. Portanto, os SDKs gerados pelo Data Connect não oferecem suporte ao retorno direto.

É possível usar embeddings de vetor retornados para fazer uma pesquisa de similaridade, conforme descrito na próxima seção.

query getMovieDescription($id: String!) @auth(level: PUBLIC) {
 movie(id: $id)
   id
   description
   descriptionEmbedding
}

Realizar pesquisa de similaridade

Agora podemos realizar a pesquisa de similaridade.

Para cada campo Vector, Data Connect gera uma função GraphQL que implementa a pesquisa de similaridade. O nome dessa função gerada é ${pluralType}_${vectorFieldName}_similarity. Ela oferece suporte a alguns parâmetros conforme mostrado nos exemplos a seguir e na lista de referência.

É possível definir uma função GraphQL que invoca a pesquisa de similaridade. Como mencionado acima, o _embed valor do servidor direciona Data Connect para gerar os embeddings de vetor usando as APIs Embedding da Vertex AI, nesse caso para criar embeddings para a string de pesquisa usada para comparação com embeddings de descrição de filmes.

Neste exemplo, a pesquisa de similaridade vai retornar até cinco filmes cuja descrição seja semanticamente mais próxima da consulta de entrada. O conjunto de resultados é classificado em ordem crescente da distância, do mais próximo ao mais distante.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
      }
  }

Ajustar a consulta de similaridade

Os valores padrão para parâmetros de pesquisa, como method e within, têm bom desempenho na maioria dos casos de uso. No entanto, se você notar que a consulta retorna resultados muito diferentes ou está faltando resultados que você quer incluir, tente ajustar esses parâmetros.

Para encontrar um valor adequado para within, podemos adicionar _metadata.distance aos campos selecionados para ver a distância de cada resultado do vetor de consulta. Com base nos valores distance retornados, podemos definir o parâmetro within. Somente os resultados com distância menor que o valor de within serão incluídos:

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      within: 2,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

Também é possível testar diferentes funções de distância definindo o parâmetro method.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      within: .5,
      method: COSINE,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

Observe que métodos diferentes retornam valores muito diferentes para a distância: se você definiu within, será necessário ajustar esse valor novamente após mudar method.

Chamar a consulta de similaridade

Para chamar uma pesquisa de similaridade do código do cliente:

import { searchMovieDescriptionUsingL2similarity} from 'lib/dataconnect-sdk';

const response = await searchMovieDescriptionUsingL2similarity({ query });

// Use the response

Usar embeddings personalizados

Data Connect também permite trabalhar com embeddings diretamente como Vectors em vez de usar o valor do servidor _embed para gerá-los.

Armazenar um embedding personalizado

Usando a API Vertex Embeddings, especifique um modelo correspondente e solicite resultados de embedding da dimensão correta.

Em seguida, converta a matriz de flutuadores retornada em um Vector para transmitir à operação de atualização para armazenamento.

mutation updateDescription($id: String!, $description: String!, $descriptionEmbedding: Vector!) {
  movie_update(id: $id, data: {
    // title, genre...
    description: $description,
    descriptionEmbedding: $descriptionEmbedding
  })
}

Realizar pesquisa de similaridade usando embeddings personalizados

Realize a mesma operação para recuperar embeddings para termos de pesquisa e convertê-los em Vectors.

Em seguida, chame a consulta _similarity para realizar cada pesquisa.

query searchMovieDescriptionUsingL2Similarity($compare: Vector!, $within: Float, $excludesContent: String, $limit: Int) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare: $compare,
      method: L2,
      within: $within,
      where: {content: {ne: $excludesContent}}, limit: $limit)
      {
        id
        title
        description
      }
  }

Implantar para a produção

Implantar seu esquema e conector

A última etapa em uma iteração típica do Data Connect é implantar seus recursos na produção.

Ao implantar seu esquema que contém tipos Vector no CloudSQL usando o firebase deploy comando, a Firebase CLI realiza as etapas necessárias para ativar a geração de embeddings baseada na Vertex AI na instância do CloudSQL.

firebase deploy --only dataconnect

Se você quiser ativar o suporte a embeddings na instância do CloudSQL manualmente ou encontrar um erro da CLI, siga estas instruções.

Sintaxe de pesquisa vetorial

Extensões de esquema

O tipo de dados Vector de Data Connect é mapeado para o tipo vector do PostgreSQL conforme definido pela extensão pgvector. O tipo vector do pgvector é armazenado como uma matriz de números de ponto flutuante de precisão única no PostgreSQL.

No Data Connect, o tipo Vector é representado como uma matriz de números JSON. As entradas são convertidas em uma matriz de valores float32. Se a coerção falhar, um erro será gerado.

Use o parâmetro de tamanho da diretiva @col para definir as dimensões do vetor.

type Question @table {
    text: String!
    category: String!
    textEmbedding: Vector! @col(size: 768)
}

size só é compatível com tipos Vector. As operações Vector, como a pesquisa de similaridade, exigem que todos os Vectors tenham o mesmo número de dimensões.

directive @col(
  # … existing args
  """
  Defines a fixed column size for certain scalar types.

  - For Vector, size is required.
  - For all other types, size is currently unsupported and hence supplying it will result in a schema error.
  """
  size: Int
) on FIELD_DEFINITION

Valor do servidor `_embed` para consultas e mutações

_embed

Esse valor do servidor direciona o serviço Data Connect para gerar e armazenar embeddings usando as APIs Embedding da Vertex AI. Esse valor do servidor pode ser usado em consultas e mutações.

Parâmetros para pesquisa de similaridade

method: COSINE|INNER_PRODUCT|L2

A função de distância usada para pesquisar vizinhos próximos. Os algoritmos com suporte no momento são um subconjunto de algoritmos de pesquisa do pgvector.

within: float

Uma restrição na distância em que a pesquisa de vizinho mais próximo é realizada.

where: FDC filter condition

Consulte o guia de esquemas, consultas e mutações.

limit: int

O número de resultados a serem retornados.