Generar y gestionar incrustaciones de vectores

En esta página se describe cómo generar y almacenar incrustaciones de vectores en base a un modelo.

Para obtener más información, consulta el artículo Desarrollar aplicaciones de IA generativa con Cloud SQL.

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

Cloud SQL implementa las inserciones como arrays de valores real. Puedes usar las inserciones generadas como entradas para las funciones de extensión de pgvector.

Antes de empezar

Algunos requisitos varían en función de si quieres usar Cloud SQL para generar las inserciones o si solo necesitas trabajar con las inserciones que se almacenan en tu base de datos desde otra fuente.

Restricciones regionales

Para generar inserciones de Vertex AI con Cloud SQL, tu instancia debe residir en una región en la que se admitan modelos fundacionales de IA generativa. Los modelos de Vertex AI que Cloud SQL puede usar para las inserciones, text-embedding y textembedding-gecko, se encuentran en esa región.

Extensiones de base de datos obligatorias

Para trabajar con las inserciones, instala la extensión google_ml_integration en tu instancia de Cloud SQL. En el caso de los modelos de Vertex AI, instala la versión 1.2 o una posterior. En el caso de los modelos de terceros o personalizados, instala la versión 1.4.2 o una posterior.

Si quieres almacenar estas inserciones y usar funciones y operadores vectoriales con ellas, 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 Configurar extensiones de PostgreSQL.

Configurar el acceso a modelos

Antes de generar inserciones a partir de una instancia de Cloud SQL, debes configurar Cloud SQL para que funcione con un modelo de inserciones de texto.

Para trabajar con el modelo text-embedding o textembedding-gecko basado en la nube, debes integrar Cloud SQL con Vertex AI.

Conceder acceso a los usuarios de la base de datos para generar inserciones

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

  1. Conecta un cliente psql a la instancia principal, tal como se describe en Conectarse mediante un cliente psql.

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

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    Haz los cambios siguientes:

    • DB_NAME: el nombre de la base de datos para la que vas a conceder permisos

    • USER_NAME: el nombre del usuario al que vas a conceder permisos

Generar inserciones

Cloud SQL proporciona una función que te permite traducir texto en una inserción de vector. Después, puedes almacenar esa inserción en tu base de datos como datos de vector y, opcionalmente, usar funciones pgvector para ejecutar consultas en ella.

Generar una inserción

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

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

Haz las siguientes sustituciones:

  • MODEL_ID: ID del modelo que se va a consultar.

    Si usas Vertex AI Model Garden, especifica text-embedding-004 o
    text-multilingual-embedding-002. Estos son los modelos basados en la nube que Cloud SQL puede usar para las inserciones de texto. Para obtener más información, consulta Inserciones de texto.

  • VERSION_TAG (opcional): etiqueta de versión del modelo que se va a consultar. En las versiones de textembedding-gecko anteriores a text-embedding-004 o text-multilingual-embedding-002, añade @ al principio de la etiqueta.

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

  • TEXT: el texto que se va a traducir a una incrustación de vector.

En el siguiente ejemplo se usa el modelo text-embedding-004 para generar una inserción basada en una cadena literal proporcionada:

SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

Almacenar una inserción generada

El valor devuelto de la función embedding() es una matriz de valores real. Para almacenar este valor en una tabla, añade una columna real[]:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];

Haz las siguientes sustituciones:

  • TABLE: el nombre de la tabla

  • EMBEDDING_COLUMN: el nombre de la nueva columna de inserciones

  • DIMENSIONS: número de dimensiones que admite el modelo.

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

Si has instalado la extensión pgvector, puedes almacenar las inserciones como valores vector:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Después de crear una columna para almacenar las inserciones, puede rellenarla en función de los valores que ya estén almacenados en otra columna de la misma tabla:

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

Haz las siguientes sustituciones:

  • TABLE: el nombre de la tabla.

  • EMBEDDING_COLUMN: el nombre de la columna de inserciones.

  • MODEL_ID: ID del modelo que se va a consultar.

    Si usas Vertex AI Model Garden, especifica text-embedding-004 o
    text-multilingual-embedding-002. Estos son los modelos basados en la nube que Cloud SQL puede usar para las inserciones de texto. Para obtener más información, consulta Inserciones de texto.

  • VERSION_TAG (Opcional): etiqueta de versión del modelo que se va a consultar. En las versiones de textembedding-gecko anteriores a text-embedding-004 o text-multilingual-embedding-002,Prepend the tag with@`.

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

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

El comando anterior funciona tanto para las columnas de real[] como para las de vector. Si la columna de inserciones es de tipo vector, Cloud SQL convierte implícitamente el valor devuelto de embedding() de una matriz real a un valor vector.

En el ejemplo siguiente se usa el modelo text-embedding-004 para rellenar la columna messages.message_vector con las inserciones basadas en el contenido de la columna messages.message:

UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);

Consultar e indexar incrustaciones con pgvector

La extensión pgvector PostgreSQL te permite usar operadores y funciones específicos de vectores cuando almacenas, indexas y consultas incrustaciones 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 implican inserciones.

Crear un índice de vecinos más cercanos

pgvector admite búsquedas de vecinos más cercanos aproximados (ANN) mediante la indexación.

Para crear un índice HNSW, usa la función hnsw, como se muestra en el siguiente ejemplo:

CREATE INDEX ON TABLE
  USING hnsw (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

Haz las siguientes sustituciones:

  • TABLE: la tabla a la que vas a añadir el índice.

  • EMBEDDING_COLUMN: una columna que almacena datos de vector.

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

    • Distancia L2: vector_l2_ops

    • Producto interior: vector_ip_ops

    • Distancia del coseno: vector_cosine_ops

  • M (opcional): número máximo de conexiones con puntos de datos vecinos en un gráfico. Recomendamos un intervalo de entre 5 y 48. El valor predeterminado es 16.

  • EF_CONSTRUCTION (opcional): tamaño de la lista que contiene los candidatos más cercanos durante el recorrido del gráfico al crear el índice. Cuanto más altos sean los valores, más candidatos tendrá en cuenta el algoritmo, lo que permitirá crear un índice mejor. El tamaño predeterminado es 64.

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

CREATE INDEX ON TABLE
  USING hnsw ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS))) DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

Sustituye DIMENSIONS por el ancho dimensional de la columna de inserción.

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

Hacer una consulta de vecinos más cercanos con un texto determinado

Una vez que hayas almacenado e indexado las inserciones en tu base de datos, podrás usar todas las pgvectorfunciones de consulta.

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

Como embedding() devuelve una matriz real, debes convertir la llamada embedding() a 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

Haz las siguientes sustituciones:

  • RESULT_COLUMNS: las columnas que se van a mostrar de las filas semánticamente similares.

  • TABLE: la tabla que contiene la inserción con la que comparas el texto.

  • EMBEDDING_COLUMN: la columna que contiene las inserciones almacenadas.

  • MODEL_ID: ID del modelo que se va a consultar.

    Si usas Vertex AI Model Garden, especifica text-embedding-004 o
    text-embedding-multilingual-002. Estos son los modelos basados en la nube que Cloud SQL puede usar para las inserciones de texto. Para obtener más información, consulta Inserciones de texto.

  • VERSION_TAG (Opcional): etiqueta de versión del modelo que se va a consultar. Añade el prefijo @ a la etiqueta.

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

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

  • ROW_COUNT: número de filas que se van a devolver. Si solo quiere obtener la mejor coincidencia, especifique 1 como valor de este parámetro.

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

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

Usar etiquetas de versión del modelo para evitar errores

Cloud SQL recomienda encarecidamente que siempre utilices una versión estable del modelo de inserciones que elijas. En la mayoría de los modelos, esto significa definir 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álido sintácticamente, pero puede dar lugar a errores.

Si omites la etiqueta de versión al usar un modelo en Vertex AI Model Garden, Vertex AI usará la versión más reciente del modelo. Puede que no sea la última versión estable. Para obtener más información sobre las versiones de modelos de Vertex AI disponibles, consulta Versiones de modelos.

Una versión de modelo de Vertex AI siempre devuelve la misma embedding()respuesta a una entrada de texto determinada. Si no especificas la versión del modelo en tus llamadas de inserción, es posible que una versión del modelo publicada recientemente cambie de forma abrupta el vector devuelto para una entrada determinada. Esto puede provocar errores u otro comportamiento inesperado en tus aplicaciones.

Siguientes pasos