Receber embeddings de texto da Agent Platform

Nesta página, descrevemos como usar a API de embedding de texto da Gemini Enterprise Agent Platform para gerar, armazenar e atualizar embeddings de texto para dados armazenados em repositórios de dados do Spanner para bancos de dados de dialeto GoogleSQL e PostgreSQL.

Um embedding de texto é uma representação vetorial de dados de texto e é usado de várias maneiras para encontrar itens semelhantes. Você interage com eles sempre que faz uma Pesquisa Google ou vê recomendações ao fazer compras on-line. Ao criar embeddings de texto, você recebe representações vetoriais de texto natural como matrizes de números de ponto flutuante. Isso significa que é atribuída uma representação numérica a todo o texto de entrada. Ao comparar a distância numérica entre as representações vetoriais de duas partes de texto, um aplicativo pode determinar a semelhança entre o texto ou os objetos representados pelo texto.

Com a API de embeddings de texto da Agent Platform, é possível criar um embedding de texto com a IA generativa. Neste tutorial, você vai usar o modelo de embedding de texto da Agent Platform para gerar embeddings de texto para os dados armazenados no Spanner.

Para saber mais sobre embeddings de texto e modelos compatíveis, consulte Receber embeddings de texto.

Objetivo

Neste tutorial, você aprenderá a realizar as seguintes tarefas:

  • Registre um modelo de embedding de texto da Agent Platform em um esquema do Spanner usando instruções DDL.
  • Faça referência ao modelo registrado usando consultas SQL para gerar embeddings com base nos dados armazenados no Spanner.

Preços

Neste tutorial, usamos componentes faturáveis do Google Cloud, incluindo:

  • Spanner
  • Plataforma de Agentes

Para mais informações sobre os custos do Spanner, consulte a página de preços do Spanner.

Para mais informações sobre os custos da Agent Platform, consulte a página de preços da Agent Platform.

gerar e armazenar embeddings de texto

Dependendo do modelo usado, a geração de embeddings pode levar algum tempo. Para cargas de trabalho mais sensíveis ao desempenho, a prática recomendada é evitar a geração de embeddings em transações de leitura e gravação. Em vez disso, gere os embeddings em uma transação somente leitura usando os exemplos de SQL a seguir.

GoogleSQL

Registrar um modelo de embeddings de texto no Spanner

No GoogleSQL, é preciso registrar um modelo antes de usá-lo com a função ML.PREDICT. Para registrar o modelo de embedding de texto da plataforma de agentes em um banco de dados do Spanner, execute a seguinte instrução de DDL:

CREATE MODEL MODEL_NAME
INPUT(
  content STRING(MAX),
  -- Optional: For models that support specifying task type.
  task_type STRING(MAX),
)
OUTPUT(
  embeddings
    STRUCT<
      statistics STRUCT<truncated BOOL, token_count FLOAT64>,
      values ARRAY<FLOAT64>>
)
REMOTE OPTIONS (
  endpoint = '//aiplatform.googleapis.com/projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME'
);

Substitua:

  • MODEL_NAME: o nome do modelo de embedding de texto da Agent Platform.
  • PROJECT: o projeto que hospeda o endpoint da plataforma de agentes.
  • LOCATION: o local do endpoint da Plataforma de Agentes.

O Spanner concede as permissões apropriadas automaticamente. Caso contrário, revise o controle de acesso ao endpoint do modelo.

A descoberta e a validação de esquemas não estão disponíveis para modelos de IA generativa. É necessário fornecer cláusulas INPUT e OUTPUT que correspondam ao esquema de modelos. Para ver o esquema completo do modelo de embedding de texto, consulte Receber embeddings de texto.

Gerar embeddings de texto

Para gerar embeddings, transmita um texto diretamente para a função ML.PREDICT usando o seguinte SQL:

SELECT embeddings.values
FROM ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT "A product description" as content)
);

Para gerar embeddings para dados armazenados em uma tabela, use o seguinte SQL:

SELECT id, embeddings.values
FROM ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT id, description as content FROM Products)
);

Para especificar o tipo de tarefa e as dimensões de saída:

UPDATE Products p
SET description_embedding = (
  SELECT embeddings.values
  FROM ML.PREDICT(
    MODEL MODEL_NAME,
    (SELECT p.description as content, "RETRIEVAL_DOCUMENT" as task_type),
    STRUCT(768 AS outputDimensionality)
  ));

SELECT p.product_id, p.name, p.description, COSINE_DISTANCE(
    p.description_embedding,
    (
      SELECT embeddings.values 
      FROM ML.PREDICT(
        MODEL MODEL_NAME,
        (SELECT @user_query as content, "RETRIEVAL_QUERY" as task_type),
        STRUCT(768 AS outputDimensionality)
      ) 
    )
  ) AS distance
FROM Products p
ORDER BY distance
LIMIT 5;

Armazenar embeddings de texto

Depois de gerar os embeddings em uma transação somente leitura, armazene-os no Spanner para que possam ser gerenciados com seus dados operacionais. Para armazenar os embeddings, use uma transação de leitura/gravação.

Para cargas de trabalho menos sensíveis ao desempenho, é possível gerar e inserir embeddings com o SQL a seguir em uma transação de leitura e gravação. Especificar vector_length é opcional para armazenar embeddings, recomendado para pesquisa KNN e obrigatório para índices de vetor. Substitua VECTOR_LENGTH pela dimensão de saída do modelo, como 3072 ou 768, ou omita vector_length se a coluna armazenar vetores de dimensões variadas:

CREATE TABLE Products(
  id INT64 NOT NULL,
  description STRING(MAX),
  embeddings ARRAY<FLOAT32>(vector_length=>VECTOR_LENGTH),
) PRIMARY KEY(id);

INSERT INTO Products (id, description, embeddings)
SELECT @Id, @Description, embeddings.values
FROM ML.PREDICT(
  MODEL MODEL_NAME,
  (SELECT @Description as content)
);

PostgreSQL

Gerar embeddings de texto

Para gerar embeddings, transmita um texto diretamente para a função spanner.ML_PREDICT_ROW usando o seguinte SQL:

SELECT
  spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    '{"instances": [{"content": "A product description"}]}'::jsonb
  ) ->'predictions'->0->'embeddings'->'values';

Substitua:

  • PROJECT: o projeto que hospeda o endpoint da plataforma de agentes.
  • LOCATION: o local do endpoint da Plataforma de Agentes.
  • MODEL_NAME: o nome do modelo de embedding de texto da Agent Platform.

Para gerar embeddings para dados armazenados em uma tabela, use o seguinte SQL:

SELECT id, spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', description))))
  ) -> 'predictions'->0->'embeddings'->'values'
FROM Products;

Substitua:

  • PROJECT: o projeto que hospeda o endpoint da plataforma de agentes.
  • LOCATION: o local do endpoint da Plataforma de Agentes.
  • MODEL_NAME: o nome do modelo de embedding de texto da Agent Platform.

Para especificar o tipo de tarefa e as dimensões de saída:

UPDATE Products p
SET description_embedding = spanner.float64_array(
  spanner.ML_PREDICT_ROW(
   'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT(
      'instances', JSONB_BUILD_ARRAY(
        JSONB_BUILD_OBJECT(
          'content', p.description,
          'task_type', 'RETRIEVAL_DOCUMENT'
        )
      ),
      'parameters', JSONB_BUILD_OBJECT('outputDimensionality', 768)
    )
  )->'predictions'->0->'embeddings'->'values'
);

SELECT p.product_id, p.name, p.description, spanner.COSINE_DISTANCE(
    p.description_embedding,
    spanner.float64_array(
      spanner.ML_PREDICT_ROW(
        'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
        JSONB_BUILD_OBJECT(
          'instances', JSONB_BUILD_ARRAY(
            JSONB_BUILD_OBJECT(
              'content', $1,
              'task_type', 'RETRIEVAL_QUERY'
            )
          ),
          'parameters', JSONB_BUILD_OBJECT('outputDimensionality', 768)
        )
      )->'predictions'->0->'embeddings'->'values'
    )
  ) AS distance
FROM Products p
ORDER BY distance
LIMIT 5;

Substitua:

  • PROJECT: o projeto que hospeda o endpoint da plataforma de agentes.
  • LOCATION: o local do endpoint da Plataforma de Agentes.
  • MODEL_NAME: o nome do modelo de embedding de texto da Agent Platform.

Armazenar embeddings de texto

Depois de gerar os embeddings em uma transação somente leitura, armazene-os no Spanner para que possam ser gerenciados com seus dados operacionais. Para armazenar os embeddings, use uma transação de leitura/gravação.

Para cargas de trabalho menos sensíveis ao desempenho, é possível gerar e inserir embeddings com o SQL a seguir em uma transação de leitura e gravação. Especificar VECTOR LENGTH é opcional para armazenar embeddings, recomendado para pesquisa KNN e obrigatório para índices de vetor. Substitua VECTOR_LENGTH pela dimensão de saída do modelo, como 3072 ou 768, ou omita VECTOR LENGTH se a coluna armazenar vetores de dimensões variadas:

CREATE TABLE Products (
  id INT8 NOT NULL,
  description TEXT,
  embeddings REAL[] VECTOR LENGTH VECTOR_LENGTH,
  PRIMARY KEY(id)
);

INSERT INTO Products (id, description, embeddings)
SELECT @Id, @Description, spanner.FLOAT32_ARRAY(spanner.ML_PREDICT_ROW(
    'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
    JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', @Description)))
  ) -> 'predictions'->0->'embeddings'->'values'
));

Substitua:

  • PROJECT: o projeto que hospeda o endpoint da plataforma de agentes.
  • LOCATION: o local do endpoint da Plataforma de Agentes.
  • MODEL_NAME: o nome do modelo de embedding de texto da Agent Platform.

Atualizar embeddings de texto

Para atualizar os embeddings ou ingerir dados em tempo real, use a instrução UPDATE (GoogleSQL e PostgreSQL).

Para atualizar a tabela Products no exemplo anterior, use o seguinte SQL:

GoogleSQL 

UPDATE Products
SET
  description = @description,
  embeddings = (SELECT embeddings.values
                  FROM ML.PREDICT(MODEL MODEL_NAME, (SELECT @description as content))
              )
WHERE id = @id;

Substitua:

  • MODEL_NAME: o nome do modelo de embedding de texto da Agent Platform.

PostgreSQL 

UPDATE
  Products
SET
  description = $1,
  embeddings = spanner.FLOAT32_ARRAY(
    spanner.ML_PREDICT_ROW(
      'projects/PROJECT/locations/LOCATION/publishers/google/models/$MODEL_NAME',
      JSONB_BUILD_OBJECT('instances', JSONB_BUILD_ARRAY(JSONB_BUILD_OBJECT('content', $1)))
    ) -> 'predictions'->0->'embeddings'->'values')
WHERE
  id = $2;

Substitua:

  • PROJECT: o projeto que hospeda o endpoint da plataforma de agentes.
  • LOCATION: o local do endpoint da Plataforma de Agentes.
  • MODEL_NAME: o nome do modelo de embedding de texto da Agent Platform.

A seguir