Gerar e gerenciar embeddings de vetor automáticos para tabelas grandes

Selecione uma versão da documentação:

É possível gerar e gerenciar embeddings de vetor para uma coluna inteira de uma tabela, o que oferece uma solução escalonável para a criação de embeddings de vetor em grande escala. Essa solução é útil para facilitar a pesquisa semântica e a geração aumentada por recuperação (RAG) em conteúdo de texto, incluindo:

  • Como criar o embedding de vetor inicial para uma nova tabela
  • Gerar embeddings após uma importação de dados grande
  • Atualizar embeddings após mudanças significativas nos dados
  • Manter embeddings de forma incremental

Entender os embeddings de vetor automáticos

Os embeddings de vetores automáticos no AlloyDB Omni oferecem uma maneira escalonável de automatizar a geração e a manutenção de embeddings de vetores para seus dados. Em vez de gerar manualmente embeddings para cada texto novo ou atualizado, você pode configurar embeddings de vetor automáticos para lidar com esse processo. Isso é especialmente útil para aplicativos que dependem de embeddings atualizados para pesquisa semântica, geração aumentada de recuperação (RAG) e outros recursos com tecnologia de IA.

Com os embeddings de vetor automáticos, é possível fazer o seguinte:

  • Inicializar embeddings para uma tabela inteira: gere embeddings para todos os dados em uma coluna de tabela com um único comando.
  • Mantenha os embeddings sincronizados: atualize automaticamente os embeddings quando os dados de origem mudarem, garantindo que seus aplicativos de IA sempre trabalhem com as informações mais atuais.
  • Gerar embeddings em grande escala: crie embeddings de maneira eficiente para tabelas grandes com milhões de linhas.
  • Configure e gerencie embeddings para várias colunas na mesma tabela chamando as funções de gerenciamento de cada coluna de embedding.

Esse recurso simplifica o desenvolvimento e a manutenção de aplicativos de IA ao abstrair a complexidade da criação e manutenção de incorporações vetoriais.

Antes de começar

Antes de gerar e gerenciar embeddings de vetor para tabelas grandes, siga estas etapas:

  • Verifique e aumente as cotas da Vertex AI: para garantir o desempenho ideal e evitar operações lentas, QPS baixo ou várias novas tentativas, verifique e, se necessário, aumente as cotas da Vertex AI.

    Para verificar e aumentar suas cotas, siga estas etapas:

    1. No console Google Cloud , acesse a página Cotas.
    2. Filtre as seguintes métricas relevantes para seu modelo e região:
      • Para solicitações por minuto (RPM): Regional online prediction requests per base model per minute per region per base_model
      • Para tokens do Gemini: Embed content input tokens per minute per region per base_model
    3. Se os limites atuais forem insuficientes para o tamanho da sua tabela, encontre o valor da cota que você quer atualizar e marque a caixa de seleção ao lado dela.

    4. Clique em Editar. A caixa de diálogo Mudanças de cota é exibida.

      Para mais informações, consulte Solicitar um ajuste de cota.

    Para limites de modelos de embedding da Vertex AI, consulte Limite de tokens do modelo de embedding do Gemini.

    Para uma lista completa de cotas, consulte Cotas e limites da Vertex AI.

  • Conecte-se ao banco de dados usando psql como o usuário postgres.

  • Verifique se a extensão google_ml_integration está instalada e se a versão dela é 1.5.6 ou mais recente.

  • Verifique se as flags google_ml_integration.enable_model_support e google_ml_integration.enable_faster_embedding_generation estão definidas como on.

  • Antes de gerar embeddings de um banco de dados do AlloyDB Omni, configure o AlloyDB Omni para trabalhar com a Vertex AI. Para mais informações, consulte Integrar seu banco de dados à Vertex AI.

  • Para gerenciar e monitorar a geração automática de incorporações, os usuários têm acesso Select às tabelas google_ml.embed_gen_progress e google_ml.embed_gen_settings por padrão.

    Para permitir que um usuário gerencie a geração de incorporação automática, conceda as permissões INSERT, UPDATE e DELETE nas tabelas google_ml.embed_gen_progress e google_ml.embed_gen_settings:

    GRANT INSERT, UPDATE, DELETE ON google_ml.embed_gen_progress TO 'USER_NAME';

    Substitua:

    • USER_NAME: o nome do usuário para quem as permissões são concedidas.

  • Conclua a configuração inicial descrita em Gerar embeddings de texto.

  • Verifique se AUTOCOMMIT está definido como ON no cliente PostgreSQL que você usa.

Verificar a versão da extensão

Para verificar a versão da extensão google_ml_integration, execute o seguinte comando:

SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

Se você precisar atualizar a extensão, execute o seguinte comando:

ALTER EXTENSION google_ml_integration UPDATE;

Verifique se as flags do banco de dados estão definidas como on

Para verificar se as flags do banco de dados estão definidas corretamente, execute os seguintes comandos:

SHOW google_ml_integration.enable_model_support;
SHOW google_ml_integration.enable_faster_embedding_generation;

Se essas flags estiverem definidas como off, consulte Configurar flags de banco de dados de uma instância. Para mais informações sobre essas flags, consulte Flags de banco de dados compatíveis.

Preparar a tabela

Antes de gerar embeddings automáticos, crie uma coluna na tabela para armazenar os vetores resultantes. Essa coluna normalmente usa o tipo vector(DIMENSION) e precisa ter um valor DEFAULT NULL.

Por exemplo, para adicionar uma coluna para embeddings de 768 dimensões a uma tabela chamada user_reviews:

ALTER TABLE user_reviews ADD COLUMN IF NOT EXISTS content_embeddings vector(768) DEFAULT NULL;

Inicializar embeddings para uma tabela

As funções para gerenciar incorporações de vetor automático estão disponíveis nos esquemas ai e google_ml. O esquema ai oferece uma interface simplificada para os recursos de IA mais recentes do AlloyDB Omni.

Use a função SQL ai.initialize_embeddings() para gerar embeddings para uma coluna de conteúdo de uma tabela. Essa é uma chamada de bloqueio, ou seja, a sessão do banco de dados aguarda a conclusão da operação antes de retornar um resultado e permitir que você emita novos comandos nessa sessão. No entanto, outras conexões com o banco de dados não são bloqueadas e podem continuar funcionando com a tabela:

  • Se a função retornar sucesso, a criação do embedding de vetor será concluída.
  • A função tenta se recuperar automaticamente de problemas temporários, como erros de cota do modelo. Uma falha será retornada somente se essas tentativas de recuperação não forem bem-sucedidas. Para problemas persistentes, como um batch_size mal configurado que faz com que a solicitação exceda os limites de tamanho, ou se a operação foi cancelada manualmente, é necessário emitir a chamada de novo manualmente.

Essa função é compatível com modelos fornecidos pelo Google, como o text-embedding-005 da Vertex AI, e com modelos personalizados registrados.

Realizar a geração em lote

Por padrão, o AlloyDB Omni usa o processamento em lote para gerar embeddings de várias entradas de texto em uma única solicitação, o que melhora a eficiência. Se você não fornecer um tamanho de lote específico, o AlloyDB Omni vai aplicar um valor padrão determinado automaticamente.

Tamanho do lote de sugestões

O parâmetro batch_size em ai.initialize_embeddings permite orientar o otimizador de consultas do AlloyDB Omni sugerindo um tamanho de lote preferencial para modelos com suporte direto. O AlloyDB Omni pode reduzir dinamicamente esse tamanho com base em limites ou cotas do modelo, mas a dica ajuda a influenciar o plano de execução da consulta.

CALL ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'user_reviews',
    content_column => 'content',
    embedding_column => 'content_embeddings',
    batch_size => 50
);

Usar um modelo de embedding personalizado com suporte a lotes

Se você quiser usar um modelo personalizado ou com suporte externo que aceite o processamento em lote, defina as funções de transformação em lote e especifique-as como model_batch_in_transform_fn e model_batch_out_transform_fn ao criar um modelo. Também é possível especificar um batch_size na chamada initialize_embeddings. Para modelos que oferecem suporte ao agrupamento em lotes, recomendamos usar um batch_size maior que 1 para melhorar a performance.

  1. Defina as funções de entrada, saída e transformação em lote do seu modelo personalizado.

    -- Scalar input transform functions
CREATE OR REPLACE FUNCTION acme_text_input_transform(model_id TEXT, input TEXT) RETURNS JSON;
CREATE OR REPLACE FUNCTION acme_text_output_transform(model_id TEXT, model_output JSON) RETURNS real[];
CREATE OR REPLACE FUNCTION acme_generate_headers(model_id TEXT, input TEXT) RETURNS JSON;
-- Batch input transform functions
CREATE OR REPLACE FUNCTION acme_text_batch_input_transform(model_id TEXT, input TEXT[]) RETURNS JSON;
CREATE OR REPLACE FUNCTION acme_text_batch_output_transform(model_id TEXT, model_output JSON) RETURNS real[][];

  2. Para criar o modelo, especifique as funções de transformação em lote.

    CALL
  ai.create_model(
    model_id => 'custom-embedding-model',
    model_request_url => 'https://acme.com/models/text/embeddings/v1',
    model_type => 'text_embedding',
    model_in_transform_fn => 'acme_text_input_transform',
    model_out_transform_fn => 'acme_text_output_transform',
    generate_headers_fn => 'acme_generate_headers',
    model_batch_in_transform_fn => 'acme_text_batch_input_transform',
    model_batch_out_transform_fn => 'acme_text_batch_output_transform'
  );

  3. Gere embeddings de vetor com seu modelo personalizado.

    CALL
  ai.initialize_embeddings(
    model_id => 'custom-embedding-model',
    table_name => 'user_reviews',
    content_column => 'content',
    embedding_column => 'content_embeddings',
    batch_size => 10
);

Também é possível usar o recurso de incorporação automática com modelos personalizados que não oferecem suporte nativo ao agrupamento em lote. Para fazer isso, ainda é necessário definir as funções de transformação em lote model_batch_in_transform_fn e model_batch_out_transform_fn. Para um modelo sem agrupamento em lote, defina essas funções para processar uma entrada por vez da matriz de entrada. Ao chamar ai.initialize_embeddings para esse modelo, defina batch_size como 1.

Usar dimensionalidade personalizada com suporte a lotes

Para usar uma função de transformação de entrada de lote personalizada com o parâmetro OUTPUT_DIMENSIONALITY, defina uma função que especifique as dimensões selecionadas nos parâmetros da solicitação. Isso é útil para otimizar a geração de embeddings para modelos que aceitam tamanhos de saída variáveis.

Por exemplo, a função a seguir define uma transformação de entrada em lote personalizada para um modelo que exige uma dimensionalidade de saída de 768:

CREATE OR REPLACE FUNCTION google_ml.vertexai_text_embedding_batch_input_transform_with_768_dims(model_id VARCHAR(100), input_list TEXT[])
RETURNS JSON
LANGUAGE SQL
AS $$
  SELECT pg_catalog.json_build_object(
    'instances',
    pg_catalog.json_agg(pg_catalog.json_build_object('content', content)),
    'parameters',
    pg_catalog.json_build_object('outputDimensionality', 768)
  ) FROM unnest(input_list) AS content;
$$;

Usar a otimização JSONB com modelos personalizados

Você pode usar o tipo de dados JSONB nas funções de transformação de saída personalizadas para melhorar a performance. Ao criar um modelo personalizado com suporte em lote, a extensão google_ml_integration procura e usa automaticamente uma variante JSONB das suas funções de transformação.

Essa otimização pode melhorar significativamente o desempenho da geração automática de incorporações porque JSONB é um formato binário mais eficiente para armazenar e processar dados JSON no PostgreSQL.

Para aproveitar esse recurso, você precisa fornecer outra versão da função de transformação que aceite um argumento JSONB em vez de JSON.

Por exemplo, se você tiver uma função de transformação de saída em lote com a seguinte assinatura:

CREATE OR REPLACE FUNCTION my_batch_output_transform(model_id TEXT, model_output JSON) RETURNS real[][];

Você pode criar uma variante JSONB assim:

CREATE OR REPLACE FUNCTION my_batch_output_transform(model_id TEXT, model_output JSONB) RETURNS real[][];

A extensão detecta automaticamente a presença da versão JSONB da função e a usa para processamento em lote. Se você já criou um registro de modelo que usa uma função de transformação JSON, não é necessário atualizar a chamada ai.create_model. Desde que a nova função JSONB use exatamente o mesmo nome da função JSON atual, a extensão detecta e usa de forma transparente a variante JSONB para o processamento em lote.

Atualizar embeddings de forma incremental

Quando você atualiza um encadeamento, ele é regenerado com base no valor mais recente da coluna de conteúdo de entrada.

Para oferecer controle sobre consistência e performance, o AlloyDB Omni é compatível com vários modos de atualizações incrementais de incorporação. É possível selecionar um modo usando o argumento de enumeração incremental_refresh_mode em ai.initialize_embeddings(). Confira abaixo uma lista de modos possíveis:

  • transactional: os embeddings são atualizados como parte da transação que atualiza a coluna de conteúdo. Esse processo, que geralmente usa um mecanismo semelhante a um gatilho de banco de dados para gerar incorporações automaticamente quando a coluna de conteúdo é atualizada, pode gerar sobrecarga e diminuir a velocidade das operações de atualização. A sobrecarga introduzida é uma troca para manter a semântica transacional e garantir que os embeddings estejam sincronizados com o conteúdo. Esse modo depende das funções de transformação escalar do seu modelo. Portanto, você precisa definir model_in_transform_fn e model_out_transform_fn ao criar o modelo. Para usar o modo transactional, você precisa ter a função de proprietário na tabela.

    CALL
  ai.initialize_embeddings(
    model_id => 'text-embedding-005',
    table_name => 'user_reviews',
    content_column => 'content',
    embedding_column => 'content_embeddings',
    batch_size => 10,
    incremental_refresh_mode => 'transactional'
);

    No modo transactional, a função ai.refresh_embeddings() é desativada porque as incorporações são mantidas sincronizadas automaticamente usando acionadores. Para regenerar incorporações para toda a tabela ou se recuperar de uma chamada ai.initialize_embeddings() interrompida nesse modo, primeiro descarte a configuração usando a função ai.drop_embedding_config() e depois reemita a chamada ai.initialize_embeddings().

    Esse modo automatizado é útil para demonstrações, conjuntos de dados pequenos ou tabelas em que o volume de inserções e atualizações é baixo em comparação com a carga inicial, por exemplo, algumas centenas de atualizações diárias em uma tabela de um milhão de linhas. É adequado quando manter a consistência imediata dos dados é mais importante do que a latência adicional introduzida durante as operações de atualização.

  • manual: este é o modo padrão. Nesse modo, uma nova coluna booleana de rastreamento é adicionada à tabela para rastrear embeddings desatualizados. Chamar a função ai.refresh_embeddings() realiza uma atualização incremental periódica, gerando apenas incorporações para linhas novas ou atualizadas. Recomendamos esse modo para usuários que precisam de mais controle sobre a performance, especialmente ao lidar com um grande número de inserções ou atualizações após o carregamento inicial. É útil para cenários em que minimizar a latência de gravação é uma prioridade e ter incorporações temporariamente desatualizadas ou nulas é aceitável até que uma atualização incremental periódica seja acionada usando ai.refresh_embeddings. Para atualizar linhas novas ou desatualizadas, use a função ai.refresh_embeddings(), conforme descrito na seção Atualizar todos os embeddings de uma tabela.

Escolher um modo de atualização

A tabela a seguir compara os dois modos de atualização incremental para ajudar você a escolher a melhor abordagem para seu aplicativo.

Modo Descrição Consistência e desempenho Ideal para
transactional As incorporações são atualizadas como parte da transação do banco de dados usando um mecanismo semelhante a um gatilho. ai.refresh_embeddings() está desativado nesse modo. Consistência imediata. Alta sobrecarga de latência de gravação, já que cada INSERT ou UPDATE aciona uma geração de incorporação. Demonstrações, pequenos conjuntos de dados ou tabelas em que a consistência dos dados é fundamental.
manual (padrão) Usa uma coluna de rastreamento booleana para monitorar linhas desatualizadas ou novas. Chame ai.refresh_embeddings() para acionar uma atualização incremental periódica. Consistência posterior. Latência mínima de gravação, já que os embeddings são gerados em massa no momento que você escolher. Grandes conjuntos de dados, ambientes de produção com alta frequência de gravação ou aplicativos sensíveis ao desempenho.

Atualizar todos os embeddings de uma tabela

Depois de executar ai.initialize_embeddings() em uma tabela usando o modo de atualização incremental manual, é possível fazer uma atualização incremental periódica dos seus embeddings, que é acionada usando ai.refresh_embeddings. É possível usar uma operação de atualização para atualizar incorporações de linhas modificadas simultaneamente durante a chamada initialize_embeddings inicial ou para realizar uma atualização incremental periódica.

Se o processo de criação de incorporação for interrompido no modo manual, por exemplo, por pg_cancel, chame a função ai.refresh_embeddings() para concluir a geração das linhas restantes.

A função de atualização reutiliza as configurações da chamada inicial. Portanto, você só precisa especificar a tabela e a coluna de incorporação. Você também pode fornecer um batch_size opcional para substituir o valor padrão.

CALL ai.refresh_embeddings(
    table_name => 'user_reviews',
    embedding_column => 'content_embeddings',
    batch_size => 50  -- Optional override
);

Trabalhar com dados de tabela durante a criação de embeddings de vetor

Embora ai.initialize_embeddings() seja uma chamada de bloqueio para a sessão em que é executada, outras conexões podem continuar trabalhando com a tabela. O processo de embedding de vetor automático atualiza as linhas em lotes usando o bloqueio padrão no nível da linha. Isso significa que operações simultâneas de linguagem de modificação de dados (DML), como UPDATE ou DELETE, de outras conexões só são bloqueadas brevemente se tentarem modificar as mesmas linhas segmentadas pela tarefa de incorporação ativa. As consultas SELECT que não fazem modificações não são bloqueadas.

Excluir configurações de embeddings de vetor automáticos

Se você precisar remover a configuração de embedding de vetor automático para uma combinação específica de tabela e coluna de embedding, use a função ai.drop_embedding_config(). Essa função pode ser útil para limpeza ou quando você reconfigura o gerenciamento de incorporações para uma coluna.

CALL
  ai.drop_embedding_config(
    table_name => 'user_reviews',
    embedding_column => 'content_embeddings');

Trabalhar com tabelas particionadas

O recurso de embedding de vetor automático é compatível com tabelas particionadas. Isso permite gerenciar incorporações de conjuntos de dados grandes e particionados de maneira eficiente. Confira os casos de uso comuns para trabalhar com tabelas particionadas.

Inicializar embeddings em uma tabela particionada

Só é possível inicializar embeddings na partição raiz de uma tabela. Essa é uma operação única para toda a tabela particionada.

CALL ai.initialize_embeddings(
    model_id => 'text-embeddings-005',
    table_name => 'documents', -- This is the root partitioned table
    content_column => 'content',
    embedding_column => 'content_embeddings'
);

Atualizar embeddings em uma tabela particionada

Após a inicialização, é possível atualizar os encodings em qualquer partição, incluindo a raiz, subpartições ou partições de folha individuais. Para conjuntos de dados grandes, é possível melhorar a performance atualizando incorporações para partições distintas em paralelo de diferentes conexões de banco de dados:

  • Para atualizar a tabela inteira, execute o seguinte:
CALL ai.refresh_embeddings(
    table_name => 'documents', -- This is the root partitioned table
    embedding_column => 'content_embeddings'
);
  • Para atualizar uma única partição, execute o seguinte:
CALL ai.refresh_embeddings(
    table_name => 'documents_eu',
    embedding_column => 'content_embeddings'
);

Atualizar incorporações para partições recém-adicionadas ou anexadas

O recurso de incorporação automática é compatível com a geração de incorporações para partições incorporadas à sua tabela principal após a configuração inicial. As etapas específicas dependem de você estar adicionando uma partição completamente nova ou anexando uma tabela preexistente.

  • Partição recém-adicionada: se você adicionar uma nova partição à tabela, poderá gerar incorporações para ela chamando ai.refresh_embeddings na nova partição.
-- Add a new partition
CREATE TABLE documents_africa PARTITION OF documents
    FOR VALUES IN ('africa');

-- Refresh embeddings for the new partition
CALL ai.refresh_embeddings(
    table_name => 'documents_africa',
    embedding_column => 'content_embeddings'
);
  • Partição recém-anexada: para anexar uma tabela como uma partição, primeiro use o procedimento ai.embedding_prepare_partition para garantir que o esquema dela seja compatível com a tabela particionada. O recurso de incorporação automática permite adicionar ou anexar partições em qualquer nível de uma configuração de partição hierárquica. O procedimento ai.embedding_prepare_partition garante que o esquema seja compatível com qualquer tabela mãe na hierarquia.

Para anexar uma tabela como uma partição, primeiro use o procedimento ai.embedding_prepare_partition para garantir que o esquema dela seja compatível com a tabela particionada:

-- Prepare the table to be attached
CALL ai.embedding_prepare_partition(
    parent_table => 'documents',
    child_table => 'documents_misc'
);

-- Attach the partition
ALTER TABLE documents ATTACH partition documents_misc DEFAULT;

-- Refresh embeddings for the newly attached partition
CALL ai.refresh_embeddings(
    table_name => 'documents_misc',
    embedding_column => 'content_embeddings'
);

O recurso de incorporação automática permite adicionar ou anexar partições em qualquer nível de uma configuração de partição hierárquica. O procedimento ai.embedding_prepare_partition garante que o esquema seja compatível com qualquer tabela mãe na hierarquia:

-- Prepare a sub-partition for a non-root parent table
CALL ai.embedding_prepare_partition(
    parent_table => 'documents_eu', -- An existing partition
    child_table => 'documents_eu_germany'
);

-- Attach the new sub-partition
ALTER TABLE documents_eu ATTACH PARTITION documents_eu_germany
    FOR VALUES IN ('germany');

-- Refresh embeddings for the new sub-partition
CALL ai.refresh_embeddings(
    table_name => 'documents_eu_germany',
    embedding_column => 'content_embeddings'
);

Monitorar o progresso da geração de embeddings

É possível monitorar o status em tempo real das chamadas initialize_embeddings e refresh_embeddings ativas consultando o ai.embedding_progress_view. Essa visualização fornece detalhes sobre o progresso da operação, incluindo a porcentagem concluída, o tempo decorrido e o tempo restante estimado.

Para verificar o progresso, execute a seguinte consulta:

SELECT
  table_name,
  content_column,
  embedding_column,
  model_id,
  percent_progress,
  status,
  elapsed_time,
  rows_processed,
  partition_root
FROM
  ai.embedding_progress_view;

A visualização fornece as seguintes informações:

Coluna Descrição
table_name O nome da tabela ou partição que está sendo processada.
content_column A coluna que contém o conteúdo de origem para o encadeamento.
embedding_column A coluna em que os embeddings estão sendo armazenados.
model_id O modelo usado para geração.
percent_progress A porcentagem da operação que foi concluída.
status O status atual da operação (por exemplo, em execução, sucesso).
elapsed_time O tempo decorrido desde o início da operação.
rows_processed O número de linhas processadas até o momento.
partition_root O nome da tabela particionada raiz.

Exemplos de geração de embeddings no modo automático

Nesta seção, mostramos exemplos de como gerar embeddings automaticamente usando endpoints de modelo registrados.

Modelo de embedding da OpenAI

Para gerar embeddings usando o endpoint de modelo text-embedding-3-small registrado fornecido pela OpenAI, execute a seguinte instrução:

CALL ai.initialize_embeddings(
    model_id => 'text-embedding-3-small',
    table_name => 'user_reviews',
    content_column => 'content',
    embedding_column => 'content_embeddings'
);

Modelos de embedding personalizados

Para modelos próprios ou com suporte externo, defina funções de transformação de entrada e saída e registre-as com ai.create_model. Se você planeja usar o recurso de incorporação automática, especifique as funções de transformação escalar (por exemplo, acme_text_input_transform, acme_text_output_transform) e em lote (por exemplo, acme_text_batch_input_transform, acme_text_batch_output_transform).

A seguir