Realizar a pesquisa de similaridade vetorial com a Vertex AI

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

A base desse recurso sã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. O Data Connect usa a extensão pgvector do PostgreSQL para essa capacidade.

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

Você pode usar 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 o 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 é compatível apenas com alguns locais do Cloud SQL para PostgreSQL. Confira 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 Google Cloud CLI.

Configuração

Você pode escolher entre um fluxo de desenvolvimento local (se 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 Data Connect de produção e a instância do Cloud SQL para PostgreSQL dele para desenvolvimento.

Observação: seja trabalhando localmente ou com seu projeto de produção, você está usando a Vertex AI e vai gerar custos de uso da Vertex AI.

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

Integrar com o PostgreSQL local

1. Configure uma instância local do PostgreSQL.
2. Conceda a si mesmo o papel do IAM de usuário da Vertex AI.
3. Configure as credenciais padrão do aplicativo do Google Cloud no seu ambiente.
4. Instale a extensão pgvector na sua instância local do PostgreSQL.
5. Ative a extensão usando CREATE EXTENSION vector de acordo com as instruções do repositório pgvector.

Integrar com o IDX

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

Projetar seu esquema

Para fazer uma pesquisa vetorial, adicione um novo campo do tipo Vector ao seu 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 campo description.

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)
 // ...
}

Observação :verifique se a dimensão do embedding de vetor foi fornecida usando a diretiva de esquema @col(size: X), já que a pesquisa de embedding de vetor só pode comparar vetores de mesmas dimensões. Os embeddings de vetor gerados usando a Vertex AI têm tamanho 768.

Gerar e recuperar embeddings

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

Observação: os embeddings de vetor gerados de diferentes versões de modelo geralmente são considerados incompatíveis. Portanto, para todas as operações em um campo (consultas ou mutações), a prática recomendada é usar embeddings de vetor gerados com o mesmo modelo. A lista de modelos da Vertex AI compatíveis está disponível na documentação.

Mutações

Gerar e armazenar um embedding usando Data Connect

No seu app de pesquisa vetorial, provavelmente você vai querer solicitar que os embeddings sejam gerados assim que você adicionar registros ao banco de dados. Esta mutação createMovie adiciona um registro de filme à tabela Movie e também transmite uma descrição de filme com uma incorporação model especificada.

mutation createMovie($movieData: Movie_Data! @pick(fields: ["title", "genre", "description"])) {
  movie_insert(data: {
    ...movieData,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $movieData.description}
  })
}

Em alguns casos, talvez seja necessário atualizar a descrição e a incorporação 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 { updateMovieDescriptionWithEmbed } from 'lib/dataconnect-sdk/';

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

// Use the response

Consultas

Extraia embeddings de vetor usando uma consulta como esta. O descriptionEmbedding retornado pela consulta é uma matriz de números de ponto flutuante, que geralmente não é legível. Assim, os SDKs gerados pelo Data Connect não permitem o retorno direto.

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

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

Realizar pesquisa por similaridade

Agora podemos fazer uma pesquisa de similaridade.

Para cada campo Vector, o Data Connect gera uma função GraphQL que implementa a pesquisa de similaridade. O nome dessa função gerada é ${pluralType}_${vectorFieldName}_similarity. Ele aceita 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 valor do servidor _embed direciona Data Connect para gerar os embeddings de vetor usando as APIs Embedding da Vertex AI, neste caso para criar embeddings da 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 é semanticamente mais próxima da consulta de entrada. O conjunto de resultados é classificado em ordem crescente de 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, funcionam bem na maioria dos casos de uso. No entanto, se você notar que a consulta retorna resultados muito diferentes ou não inclui os que você quer, tente ajustar esses parâmetros.

Para encontrar um valor adequado para within, adicione _metadata.distance aos campos selecionados para ver a distância de cada resultado do vetor de consulta. Com base nos valores distance retornados, é possível 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
        }
      }
  }

Você também pode 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
        }
      }
  }

Diferentes métodos retornam valores muito diferentes para a distância. Se você definiu within, precisará ajustar esse valor novamente depois de mudar method.

Chamar a consulta de similaridade

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

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

const response = await searchMovieDescriptionUsingL2similarity({ query });

// Use the response

Usar incorporações personalizadas

O Data Connect também permite trabalhar diretamente com incorporações como Vectors em vez de usar o valor do servidor _embed para gerá-las.

Armazenar um embedding personalizado

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

Em seguida, transmita a matriz de números de ponto flutuante retornada para um Vector e passe para a operação de atualização do 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

Faça a mesma operação para extrair embeddings de termos de pesquisa e transmita-os para 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 de uma iteração típica de Data Connect é implantar seus recursos na produção.

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

firebase deploy --only dataconnect

Se você quiser ativar a compatibilidade com incorporação na sua instância do Cloud SQL manualmente ou encontrar um erro da CLI, siga estas instruções.

Sintaxe da pesquisa vetorial

Extensões de esquema

O tipo de dados Vector do 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 simples no PostgreSQL.

Em 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.

Observação: os números JavaScript são compatíveis com a coerção de ponto flutuante.

Use o parâmetro "size" 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 por 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 compatíveis no momento são um subconjunto dos 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.