Trabaja con incorporaciones vectoriales

En esta página, se muestra cómo usar Cloud SQL para PostgreSQL a fin de realizar las siguientes acciones:

  • Generar y almacenar embeddings de vectores según un modelo.

  • Indexa y consulta embeddings con la extensión pgvector.

Para obtener más información, consulta Compila aplicaciones de IA generativa con Cloud SQL.

Cloud SQL te permite usar un modelo de embedding alojado por Vertex AI para traducir una string de texto a una embedding, que es la representación del modelo del significado semántico del texto dado como un vector numérico.

Cloud SQL implementa las embeddings como arrays de valores real. Esto te permite usar embeddings generadas como entradas para las funciones de extensión pgvector.

Antes de comenzar

Algunos requisitos difieren en función de si deseas usar Cloud SQL para generar embeddings o si solo necesitas trabajar con embeddings almacenadas en tu base de datos desde otra fuente.

Restricciones regionales

Para generar embeddings con Cloud SQL, tu instancia debe residir en la región us-central1. El modelo de Vertex AI que Cloud SQL puede usar para las embeddings, textembedding-gecko, se encuentra en esa región.

Extensiones de base de datos obligatorias

Para trabajar con embeddings, necesitas la extensión google_ml_integration, versión 1.2 o posterior, instalada en tu instancia de Cloud SQL.

De forma opcional, si deseas almacenar estas embeddings y usar funciones y operadores vectoriales con las embeddings, también necesitas la extensión pgvector.

Cloud SQL tiene ambas extensiones. Puedes instalarlos en cualquier base de datos de tu instancia. Para obtener más información, consulta Configura extensiones de PostgreSQL.

Configura el acceso al modelo

Antes de generar embeddings desde una instancia de Cloud SQL, debes configurar Cloud SQL para que funcione con un modelo de embeddings de texto.

Para trabajar con el modelo textembeddings-gecko basado en la nube, debes integrar Cloud SQL a Vertex AI.

Otorga acceso a los usuarios de la base de datos para generar embeddings

Otorga permiso a los usuarios de la base de datos para que usen la función embedding a fin de ejecutar predicciones:

  1. Conecta un cliente psql a la instancia principal, como se describe en Conéctate con un cliente psql.

  2. En el símbolo del sistema de psql, conéctate a la base de datos y otorga permisos:

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    Reemplaza lo siguiente:

    • DB_NAME: el nombre de la base de datos para la que otorgas permisos

    • USER_NAME: el nombre del usuario al que le otorgas permisos

Genera embeddings

Cloud SQL proporciona una función que te permite traducir texto en una embedding de vector. Luego, puedes almacenar esa embedding en tu base de datos como datos vectoriales y, de forma opcional, usar funciones pgvector para ejecutar consultas en ella.

Genera una embedding

Para generar una embedding mediante Cloud SQL, usa la función embedding() que proporciona la extensión google_ml_integration:

SELECT embedding( 'MODEL_IDVERSION_TAG', 'TEXT');

Realiza los siguientes reemplazos:

  • MODEL_ID: el ID del modelo que se consultará.

    Si usas Vertex AI Model Garden, especifica textembedding-gecko o
    textembedding-gecko-multilingual. Estos son los modelos basados en la nube que Cloud SQL puede usar para las embeddings de texto. Para obtener más información, consulta Embeddings de texto.

  • VERSION_TAG (opcional): es la etiqueta de la versión del modelo que se consultará. Agrega @ a la etiqueta.

    Si usas uno de los modelos textembedding-gecko con Vertex AI, especifica una de las etiquetas de versión enumeradas en Versiones del modelo.

  • TEXT: es el texto que se traducirá en una embedding de vector.

En el siguiente ejemplo, se usa la versión 001 del modelo textembedding-gecko para generar una embedding basada en una string literal proporcionada:

SELECT embedding( 'textembedding-gecko@001', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

Almacena una embedding generada

El valor que se muestra de la función embedding() es un array de valores real. Para almacenar este valor en una tabla, agrega una columna real[]:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];

Realiza los siguientes reemplazos:

  • TABLE: el nombre de la tabla

  • EMBEDDING_COLUMN: el nombre de la columna de embedding nueva

  • DIMENSIONS: la cantidad de dimensiones que admite el modelo.

    Si usas uno de los modelos textembedding-gecko con Vertex AI, especifica 768.

De forma opcional, si instalaste la extensión pgvector, puedes almacenar las embeddings como valores vector:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Después de crear una columna para almacenar embeddings, puedes propagarla en función de los valores ya almacenados en otra columna de la misma tabla:

UPDATE TABLE SET EMBEDDING_COLUMN = embedding('MODEL_IDVERSION_TAG', SOURCE_TEXT_COLUMN);

Realiza los siguientes reemplazos:

  • TABLE: el nombre de la tabla.

  • EMBEDDING_COLUMN: el nombre de la columna de embedding.

  • MODEL_ID: el ID del modelo que se consultará.

    Si usas Vertex AI Model Garden, especifica textembedding-gecko o
    textembedding-gecko-multilingual. Estos son los modelos basados en la nube que Cloud SQL puede usar para las embeddings de texto. Para obtener más información, consulta Embeddings de texto.

  • VERSION_TAG (opcional): es la etiqueta de la versión del modelo que se consultará. Agrega @ a la etiqueta.

    Si usas uno de los modelos textembedding-gecko con Vertex AI, especifica una de las etiquetas de versión enumeradas en Versiones del modelo.

  • SOURCE_TEXT_COLUMN: es el nombre de la columna que almacena el texto. Traduces este texto a embeddings.

El comando anterior funciona para las columnas de embedding real[] y vector. Si tu columna de embedding es del tipo vector, Cloud SQL convierte el valor de retorno de embedding() de un array real en un valor vector de forma implícita.

En el siguiente ejemplo, se usa la versión 001 del modelo textembedding-gecko para propagar la columna messages.message_vector con embeddings basadas en el contenido de la columna messages.message:

UPDATE messages SET message_vector = embedding( 'textembedding-gecko@001', message);

Consulta embeddings y, luego, indexa con pgvector

La extensión pgvector de PostgreSQL te permite usar operadores y funciones específicos de vectores cuando almacenas, indexas y consultas embeddings de texto en tu base de datos. Cloud SQL tiene sus propias optimizaciones para trabajar con pgvector, lo que te permite crear índices que pueden acelerar las consultas que involucran embeddings.

Crea un índice de vecino más cercano optimizado

pgvector admite la búsqueda de vecino más cercano aproximado mediante la indexación. Cloud SQL agrega a esta compatibilidad una característica de cuantización escalar que puedes especificar cuando creas un índice. Cuando habilitas esta función, la cuantización escalar puede acelerar las consultas que tienen vectores dimensionales más grandes. Además, esta función te permite almacenar vectores con hasta 8,000 dimensiones.

Para habilitar la cuantización escalar en un índice basado en pgvector, especifica ivf como el método de índice y SQ8 como el cuantizador:

CREATE INDEX ON TABLE
  USING ivf (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT, quantizer = 'SQ8');

Realiza los siguientes reemplazos:

  • TABLE: Es la tabla a la que agregas el índice.

  • EMBEDDING_COLUMN: Es una columna que almacena datos vector.

  • DISTANCE_FUNCTION: es la función de distancia que se usará con este índice. Elige una de estas opciones:

    • Distancia de L2: vector_l2_ops

    • Producto interno: vector_ip_ops

    • Distancia de coseno: vector_cosine_ops

  • LIST_COUNT: Es la cantidad de listas que se usarán con este índice.

Para crear este índice en una columna de embedding que use el tipo de datos real[] en lugar de vector, convierte la columna en el tipo de datos vector:

CREATE INDEX ON TABLE
  USING ivf ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)))'}} DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT, quantizer = 'SQ8');

Reemplaza DIMENSIONS por el ancho dimensional de la columna de embedding.

En la siguiente sección, se muestra un ejemplo de este tipo de índice.

Realiza una consulta de vecino más cercano con texto determinado

Una vez que almacenes y, también, indexes las embeddings en tu base de datos, el rango completo de funcionalidad de consulta de pgvector estará disponible para ti.

Para encontrar los vecinos semánticos más cercanos a un fragmento de texto, usa la función embedding() a fin de traducir el texto a un vector. En la misma consulta, aplica este vector al operador de vecino más cercano pgvector, <->, para encontrar las filas de la base de datos con las embeddings semánticamente más similares.

Debido a que embedding() muestra un array real, debes convertir la llamada embedding() en vector para usar estos valores con operadores pgvector.

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Realiza los siguientes reemplazos:

  • RESULT_COLUMNS: las columnas que se mostrarán desde filas similares semánticamente.

  • TABLE: la tabla que contiene la embedding con la que comparas el texto.

  • EMBEDDING_COLUMN: la columna que contiene las embeddings almacenadas.

  • MODEL_ID: el ID del modelo que se consultará.

    Si usas Vertex AI Model Garden, especifica textembedding-gecko o
    textembedding-gecko-multilingual. Estos son los modelos basados en la nube que Cloud SQL puede usar para las embeddings de texto. Para obtener más información, consulta Embeddings de texto.

  • VERSION_TAG (opcional): es la etiqueta de la versión del modelo que se consultará. Agrega @ a la etiqueta.

    Si usas uno de los modelos textembedding-gecko con Vertex AI, especifica una de las etiquetas de versión enumeradas en Versiones del modelo.

  • TEXT: es el texto que deseas para poder encontrar los vecinos semánticos almacenados más cercanos.

  • ROW_COUNT: cantidad de filas que se mostrarán. Si solo deseas la mejor coincidencia, especifica 1 como el valor para este parámetro.

Para ejecutar esta consulta con una columna de embeddings almacenada que usa el tipo de datos real[] en lugar de vector, convierte la columna en el tipo de datos vector:

  SELECT RESULT_COLUMNS::vector FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Usa etiquetas de versión del modelo para evitar errores

Google recomienda que siempre uses una versión estable del modelo de embeddings elegido. En la mayoría de los modelos, esto significa configurar una etiqueta de versión de forma explícita.

Llamar a la función embedding() sin especificar la etiqueta de versión del modelo es válida en términos sintácticos, pero también es propenso a errores.

Si omites la etiqueta de versión cuando usas un modelo en Vertex AI Model Garden, entonces Vertex AI usa la versión más reciente del modelo. Es posible que esta no sea la última versión estable. Para obtener más información sobre las versiones disponibles de modelos de Vertex AI, consulta Versiones de modelos.

Una versión determinada del modelo de Vertex AI siempre muestra la misma respuesta embedding() a una entrada de texto determinada. Si no especificas las versiones del modelo en tus llamadas a embedding(), una nueva versión del modelo publicada puede cambiar el vector que se muestra para una entrada determinada de forma abrupta. Esto puede causar errores o cualquier otro comportamiento inesperado en tus aplicaciones.

Para evitar estos problemas, especifica siempre la versión del modelo.

¿Qué sigue?