Generar y gestionar incrustaciones vectoriales

Esta página describe cómo generar y almacenar incrustaciones vectoriales basadas en un modelo.

Para obtener más información, consulte Crear aplicaciones de IA generativas con Cloud SQL .

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

Cloud SQL implementa incrustaciones como matrices de valores real . Puede usar las incrustaciones generadas como entradas para las funciones de extensión pgvector .

Antes de empezar

Algunos requisitos difieren dependiendo de si desea utilizar Cloud SQL para generar incrustaciones o si solo necesita trabajar con incrustaciones almacenadas en su base de datos desde otra fuente.

Restricciones regionales

Para generar incrustaciones de Vertex AI con Cloud SQL, su instancia debe residir en una región compatible con los modelos fundamentales de IA generativa . Los modelos de Vertex AI que Cloud SQL puede usar para incrustaciones ( text-embedding y textembedding-gecko ) se encuentran en esa región.

Extensiones de base de datos requeridas

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

Opcionalmente, si desea almacenar estas incrustaciones y utilizar funciones y operadores vectoriales con las incrustaciones, también necesitará la extensión pgvector .

Cloud SQL cuenta con ambas extensiones. Puedes instalarlas en cualquier base de datos de tu instancia. Para más información, consulta Configurar extensiones de PostgreSQL .

Configurar el acceso al modelo

Antes de poder generar incrustaciones desde una instancia de Cloud SQL, debe configurar Cloud SQL para que funcione con un modelo de incrustación de texto.

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

Otorgar a los usuarios de la base de datos acceso para generar incrustaciones

Otorgar permiso a los usuarios de la base de datos para utilizar la función embedding para ejecutar predicciones:

  1. Conecte un cliente psql a la instancia principal, como se describe en Conectarse usando un cliente psql .

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

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    Reemplace lo siguiente:

    • DB_NAME : el nombre de la base de datos para la que estás otorgando permisos

    • USER_NAME : el nombre del usuario al que le estás otorgando permisos

Generar incrustaciones

Cloud SQL ofrece una función que permite traducir texto a una incrustación vectorial. Posteriormente, puede almacenar dicha incrustación en su base de datos como datos vectoriales y, opcionalmente, usar funciones pgvector para ejecutar consultas en ella.

Generar una incrustación

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

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

Realice las siguientes sustituciones:

  • MODEL_ID : el ID del modelo a consultar.

    Si está utilizando Vertex AI Model Garden , especifique text-embedding-004 o
    text-multilingual-embedding-002 . Estos son los modelos basados ​​en la nube que Cloud SQL puede usar para incrustaciones de texto. Para más información, consulte Incrustaciones de texto .

  • VERSION_TAG (opcional): la etiqueta de versión del modelo que se consultará. Para versiones de textembedding-gecko anteriores a text-embedding-004 o text-multilingual-embedding-002 , anteponga @ a la etiqueta.

    Si está utilizando uno de los modelos textembedding-gecko con Vertex AI, especifique una de las etiquetas de versión que aparecen en Versiones del modelo .

  • TEXT : el texto a traducir en una incrustación vectorial.

El siguiente ejemplo utiliza el modelo text-embedding-004 para generar una incrustación basada en una cadena literal proporcionada:

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

Almacenar una incrustación generada

El valor de retorno de la función embedding() es un array de valores real . Para almacenar este valor en una tabla, agregue una columna real[] `:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];

Realice las siguientes sustituciones:

  • TABLE : el nombre de la tabla

  • EMBEDDING_COLUMN : el nombre de la nueva columna de incrustación

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

    Si está utilizando uno de los modelos de text-embedding o textembedding-gecko con Vertex AI, especifique 768 .

Opcionalmente, si ha instalado la extensión pgvector , puede almacenar incrustaciones como valores vector :

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Después de crear una columna para almacenar incrustaciones, puede completarla 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);

Realice las siguientes sustituciones:

  • TABLE : el nombre de la tabla.

  • EMBEDDING_COLUMN : el nombre de la columna de incrustación.

  • MODEL_ID : el ID del modelo a consultar.

    Si está utilizando Vertex AI Model Garden , especifique text-embedding-004 o
    text-multilingual-embedding-002 . Estos son los modelos basados ​​en la nube que Cloud SQL puede usar para incrustaciones de texto. Para más información, consulte Incrustaciones de texto .

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

    Si está utilizando uno de los modelos textembedding-gecko con Vertex AI, especifique una de las etiquetas de versión que aparecen en Versiones del modelo .

  • SOURCE_TEXT_COLUMN : el nombre de la columna que almacena el texto. Este texto se traduce en incrustaciones.

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

El siguiente ejemplo utiliza el modelo text-embedding-004 para completar la columna messages.message_vector con incrustaciones basadas en el contenido de la columna messages.message :

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

Incrustaciones de consultas e índices mediante pgvector

La extensión pgvector de PostgreSQL permite usar operadores y funciones específicos de vectores al almacenar, indexar y consultar incrustaciones de texto en la base de datos. Cloud SQL cuenta con sus propias optimizaciones para trabajar con pgvector , lo que permite crear índices que aceleran las consultas que incluyen incrustaciones.

Crear un índice de vecino más cercano

pgvector admite búsquedas de vecino más cercano aproximado (ANN) a través de indexación .

Para crear un índice HNSW , utilice 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);

Realice las siguientes sustituciones:

  • TABLE : la tabla a la que estás agregando el índice.

  • EMBEDDING_COLUMN : una columna que almacena datos vector .

  • DISTANCE_FUNCTION : la función de distancia que se usará con este índice. Elija una de las siguientes:

    • Distancia L2 : vector_l2_ops

    • Producto interno : vector_ip_ops

    • Distancia del coseno : vector_cosine_ops

  • M (opcional): el número máximo de conexiones con puntos de datos adyacentes en un gráfico. Recomendamos un rango de 5 a 48. El valor predeterminado es 16.

  • EF_CONSTRUCTION (opcional): el tamaño de la lista que contiene los candidatos más cercanos durante el recorrido del grafo al construir el índice. Valores más altos hacen que el algoritmo considere más candidatos, lo que permite crear un índice más preciso. El tamaño predeterminado es 64.

Para crear este índice en una columna de incrustación que utiliza el tipo de datos real[] en lugar de vector , convierta 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);

Reemplace DIMENSIONS con el ancho dimensional de la columna de incrustación.

La siguiente sección muestra un ejemplo de este tipo de índice.

Realizar una consulta de vecino más cercano con el texto dado

Después de almacenar e indexar incrustaciones en su base de datos, tendrá a su disposición toda la funcionalidad de consulta de pgvector .

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

Debido a que embedding() devuelve una matriz real , debe convertir la llamada embedding() a vector para usar estos valores con los operadores pgvector . 

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

Realice las siguientes sustituciones:

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

  • TABLE : la tabla que contiene la incrustación con la que se compara el texto.

  • EMBEDDING_COLUMN : la columna que contiene las incrustaciones almacenadas.

  • MODEL_ID : el ID del modelo a consultar.

    Si está utilizando Vertex AI Model Garden , especifique text-embedding-004 o
    text-embedding-multilingual-002 . Estos son los modelos basados ​​en la nube que Cloud SQL puede usar para incrustaciones de texto. Para más información, consulte Incrustaciones de texto .

  • VERSION_TAG (Opcional): la etiqueta de versión del modelo a consultar. Antepóngala con @ .

    Si está utilizando uno de los modelos textembedding-gecko con Vertex AI, especifique una de las etiquetas de versión que aparecen en Versiones del modelo .

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

  • ROW_COUNT : el número de filas que se devolverán. Si solo desea la mejor coincidencia, especifique 1 como valor para este parámetro.

Para ejecutar esta consulta con una columna de incrustación almacenada que utiliza el tipo de datos real[] en lugar de vector , convierta 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

Utilice etiquetas de versión del modelo para evitar errores

Cloud SQL recomienda encarecidamente usar siempre una versión estable del modelo de incrustaciones elegido. Para la mayoría de los modelos, esto implica configurar una etiqueta de versión explícitamente.

Llamar a la función embedding() sin especificar la etiqueta de versión del modelo es válido sintácticamente, pero puede ser propenso a errores.

Si omite 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. Es posible que no sea la versión estable más reciente. Para obtener más información sobre las versiones disponibles de los modelos de Vertex AI, consulte Versiones de modelo .

Una versión dada del modelo Vertex AI siempre devuelve la misma respuesta embedding() a una entrada de texto dada. Si no especifica la versión del modelo en sus llamadas de incrustación, es posible que una versión recién publicada del modelo cambie abruptamente el vector devuelto para una entrada dada. Esto puede causar errores u otros comportamientos inesperados en sus aplicaciones.

¿Qué sigue?