Referencia de asistencia vectorial

MySQL   |  PostgreSQL   |  SQL Server

Vista previa — Vector Assist

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Puedes tratar datos personales para esta función tal como se indica en la Adenda sobre Tratamiento de Datos de Cloud, de acuerdo con las obligaciones y restricciones descritas en el contrato en virtud del cual accedes a Google Cloud. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

En esta página se proporciona información detallada sobre todas las funciones de asistencia vectorial disponibles, así como sobre sus parámetros obligatorios y opcionales.

vector_assist.define_spec

Define una nueva especificación de vector (o especificación de vector) y devuelve las recomendaciones necesarias para mejorar la carga de trabajo del vector. Esta función aplica las especificaciones proporcionadas por el usuario para generar las recomendaciones.

Función

CREATE OR REPLACE FUNCTION vector_assist.define_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT,
    schema_name TEXT DEFAULT NULL,
    vector_column_name TEXT DEFAULT NULL,
    text_column_name TEXT DEFAULT NULL,
    vector_index_type TEXT DEFAULT NULL, -- Allowed: 'hnsw', 'ivfflat'
    embeddings_available BOOL DEFAULT NULL,
    embedding_model TEXT DEFAULT NULL,
    num_vectors INT DEFAULT NULL,
    dimensionality INT DEFAULT NULL,
    distance_func TEXT DEFAULT NULL, -- Allowed: 'cosine', 'ip', 'l2', 'l1'
    quantization TEXT DEFAULT NULL, -- Allowed: 'none', 'halfvec', 'bit'
    prefilter_column_names TEXT[] DEFAULT NULL,
    memory_budget_kb INT DEFAULT NULL, -- In KB
    target_recall FLOAT DEFAULT NULL,
    target_top_k INT DEFAULT NULL,
    tune_vector_index BOOL DEFAULT FALSE, -- Set to true if target_recall is set
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parámetros

Parámetro	¿Es obligatorio?	Descripción
spec_id	Obligatorio (generado automáticamente)	Un ID único de la especificación de vector que definas.
table_name	¿Es obligatorio?	Nombre de la tabla que se usará en la configuración de la carga de trabajo vectorial.
schema_name	Opcional	El esquema que contiene la tabla que se va a usar en la carga de trabajo vectorial. El esquema se infiere automáticamente en función de la ruta de búsqueda del esquema.
vector_column_name	Opcional u obligatorio	Nombre de la columna que contiene las inserciones de vectores. Esta columna es obligatoria si usa más de una columna de vector y no se ha declarado el text_column_name. Si solo usas una columna de vector, este parámetro es opcional.
text_column_name	Opcional u obligatorio	Nombre de la columna de texto. Si tu carga de trabajo de vectores requiere generar inserciones a partir de una columna de texto, este parámetro es obligatorio. Esta columna es obligatoria si el parámetro vector_column_name es NULL y no hay otras columnas de vectores. Este parámetro usa la extensión google_ml_integration para generar las inserciones a partir de la columna de texto proporcionada.
vector_index_type	Opcional	El tipo de índice de vectores. Entre los valores aceptables se incluyen los siguientes: HNSW IVFFlat SCANN
embeddings_available	Opcional	Un valor booleano que comprueba si hay inserciones de vectores en la tabla seleccionada. Este campo tiene el valor FALSE si no se detectan columnas de vector y se define el parámetro text_column_name.
embedding_model	Opcional u obligatorio	El ID del modelo de google_ml.models que se usará para generar las inserciones. Este campo es opcional, a menos que el parámetro embeddings_available sea FALSE o NULL.
num_vectors	Opcional	Número de vectores de la tabla.
dismensionality	Opcional	La dimensión de los vectores proporcionados.
distance_func	Opcional	Función de distancia que se usará para comparar el vector. Los valores aceptables son cosine, ip, l2 o l1.
quantization	Opcional	Cuantización de los índices vectoriales. Los valores aceptados son none, halfvec o bit.
prefilter_column_names	Opcional	Crea un índice para la columna especificada para el prefiltrado. Esto puede ayudar a mejorar el rendimiento de las consultas con un filtro de alta selectividad en la columna.
memory_budget_kb	Opcional	La memoria máxima (en KB) para la creación de índices.
target_recall	Opcional	El recall objetivo de las consultas de vectores estándar.
target_top_k	Opcional	Los valores de coincidencia principales que se van a recuperar para calcular la recuperación. Este valor se usa si se especifica el parámetro target_recall.
tune_vector_index	Opcional	Ajusta los índices vectoriales de tu carga de trabajo. Si está habilitada, la asistencia de vector ajusta automáticamente el índice de vector o la consulta de búsqueda mediante la especificación de vector y calcula los parámetros óptimos de la base de datos y del índice. Los valores aceptables son TRUE o FALSE.

Valor devuelto

Devuelve una tabla de recomendaciones que se deben aplicar para configurar la carga de trabajo de vector solicitada. Cada fila es una recomendación que contiene una consulta SQL ejecutable y una explicación detallada de por qué se debe aplicar la recomendación. La recomendación se puede aplicar mediante la función apply_recommendation().

Nota: Esta función es una operación de larga duración. Si usas un cliente con un tiempo de espera (como Cloud SQL Studio, que tiene un tiempo de espera de 5 minutos), es posible que se cancele la llamada a la función. Para mitigar este problema, puede aumentar el umbral de tiempo de espera o crear una copia de la tabla que esté usando con solo un subconjunto de datos para cumplir los requisitos de tiempo de espera.

La tabla de recomendaciones contiene las siguientes columnas:

Nombre de la columna	Tipo	Descripción
recommendation_id	Texto	ID de la recomendación. La recomendación se aplica con este ID.
vector_spec_id	Texto	ID de la especificación de vector asociada a la recomendación.
table_name	Texto	Nombre de la tabla asociada a la recomendación.
schema_name	Texto	El nombre del esquema que contiene la tabla indicada.
query	Texto	Consulta de SQL ejecutable que se debe ejecutar para conseguir el resultado de la recomendación.
recommendation	Texto	La explicación de la recomendación, incluido el resultado esperado una vez que se aplique. Esta columna también contiene el motivo y la justificación de la recomendación. Puedes usar este contexto para ajustar la consulta según sea necesario y volver a generar recomendaciones.
applied	Booleano	Indica si se ha aplicado la recomendación.
modified	Booleano	Muestra si el usuario ha modificado la recomendación.
created_at	Marca de tiempo con zona horaria	Hora en la que se generó la recomendación en formato timestamp with time zone. Por ejemplo, 2024-07-18 09:00:00-08.

vector_assist.list_specs

Devuelve la especificación de vector actual de una tabla y una columna determinadas.

Función

CREATE OR REPLACE FUNCTION vector_assist.list_specs(
  table_name      TEXT,
  column_name     TEXT DEFAULT NULL
)
RETURNS SETOF vector_assist.VECTOR_SPECS

Parámetros

Parámetro	¿Es obligatorio?	Descripción
table_name	¿Es obligatorio?	Nombre de la tabla de la que se obtiene la especificación del vector.
column_name	Opcional	Nombre de la columna por la que se debe filtrar la tabla antes de devolver la especificación. Si se especifica el nombre de la columna, se devuelven las especificaciones que contienen nombres de columna de texto o de vector que coinciden con este nombre de columna.

Valor devuelto

Devuelve una tabla de especificaciones de la tabla dada y, opcionalmente, el nombre de la columna.

vector_assist.modify_spec

Modifica una especificación de vector. Cuando se modifica la especificación de vector, las recomendaciones asociadas se vuelven a generar en función de las nuevas especificaciones.

Función

CREATE OR REPLACE FUNCTION vector_assist.modify_spec(
  spec_id                TEXT,
  table_name             TEXT DEFAULT NULL,
  schema_name            TEXT DEFAULT NULL,
  vector_column_name     TEXT DEFAULT NULL,
  text_column_name       TEXT DEFAULT NULL,
  vector_index_type      TEXT DEFAULT NULL,
  embeddings_available   BOOL DEFAULT NULL,
  num_vectors            INT DEFAULT NULL,
  dimensionality         INT DEFAULT NULL,
  embedding_model        TEXT DEFAULT NULL,
  prefilter_column_names TEXT[] DEFAULT NULL,
  distance_func          TEXT DEFAULT NULL,
  quantization           TEXT DEFAULT NULL,
  memory_budget_kb       INT DEFAULT NULL,
  target_recall          FLOAT DEFAULT NULL,
  target_top_k           INT DEFAULT NULL,
  tune_vector_index      BOOL DEFAULT NULL
)
RETURNS SETOF vector_assist.RECOMMENDATIONS

Parámetros

Parámetro	¿Es obligatorio?	Descripción
spec_id	Obligatorio (generado automáticamente)	Un ID único de la especificación de vector que definas.
table_name	¿Es obligatorio?	Nombre de la tabla que se usará en la configuración de la carga de trabajo vectorial.
schema_name	Opcional	El esquema que contiene la tabla que se va a usar en la carga de trabajo vectorial. El esquema se infiere automáticamente en función de la ruta de búsqueda del esquema.
vector_column_name	Opcional u obligatorio	Nombre de la columna que contiene las inserciones de vectores. Esta columna es obligatoria si usa más de una columna de vector y no se ha declarado el text_column_name. Si solo usas una columna de vector, este parámetro es opcional.
text_column_name	Opcional u obligatorio	Nombre de la columna de texto. Si tu carga de trabajo de vectores requiere generar inserciones a partir de una columna de texto, este parámetro es obligatorio. Esta columna es obligatoria si el parámetro vector_column_name es NULL y no hay otras columnas de vectores. Este parámetro usa la extensión google_ml_integration para generar las inserciones a partir de la columna de texto proporcionada.
vector_index_type	Opcional	El tipo de índice de vectores. Entre los valores aceptables se incluyen los siguientes: HNSW IVFFlat SCANN
embeddings_available	Opcional	Un valor booleano que comprueba si hay inserciones de vectores en la tabla seleccionada. Este campo tiene el valor FALSE si no se detectan columnas de vector y se define el parámetro text_column_name.
embedding_model	Opcional u obligatorio	El ID del modelo de google_ml.models que se usará para generar las inserciones. Este campo es opcional, a menos que el parámetro embeddings_available sea FALSE o NULL.
num_vectors	Opcional	Número de vectores de la tabla.
dismensionality	Opcional	La dimensión de los vectores proporcionados.
distance_func	Opcional	Función de distancia que se usará para comparar el vector. Los valores aceptables son cosine, ip, l2 o l1.
quantization	Opcional	Cuantización de los índices vectoriales. Los valores aceptados son none, halfvec o bit.
prefilter_column_names	Opcional	Identifica las columnas que están disponibles para el prefiltrado en las consultas de búsqueda de vectores.
memory_budget_kb	Opcional	La memoria máxima (en KB) para la creación de índices.
target_recall	Opcional	El recall objetivo de las consultas de vectores estándar.
target_top_k	Opcional	Los valores de coincidencia principales que se van a recuperar para calcular la recuperación. Este valor se usa si se especifica el parámetro target_recall.
tune_vector_index	Opcional	Ajusta los índices vectoriales de tu carga de trabajo. Si está habilitada, la asistencia de vector ajusta automáticamente el índice de vector o la consulta de búsqueda mediante la especificación de vector y calcula los parámetros óptimos de la base de datos y del índice. Los valores aceptables son TRUE o FALSE.

Valor devuelto

Devuelve una tabla actualizada de recomendaciones que se deben aplicar para configurar la carga de trabajo de vector solicitada. Cada fila es una recomendación que contiene una consulta SQL ejecutable y una explicación detallada de por qué se debe aplicar la recomendación. La recomendación se puede aplicar mediante la función apply_recommendation().

La tabla de recomendaciones contiene las siguientes columnas:

Nombre de la columna	Tipo	Descripción
recommendation_id	Texto	ID de la recomendación. La recomendación se aplica con este ID.
vector_spec_id	Texto	ID de la especificación de vector asociada a la recomendación.
table_name	Texto	Nombre de la tabla asociada a la recomendación.
schema_name	Texto	El nombre del esquema que contiene la tabla indicada.
query	Texto	Consulta de SQL ejecutable que se debe ejecutar para conseguir el resultado de la recomendación.
recommendation	Texto	La explicación de la recomendación, incluido el resultado esperado una vez que se aplique. Esta columna también contiene el motivo y la justificación de la recomendación. Puedes usar este contexto para ajustar la consulta según sea necesario y volver a generar recomendaciones.
applied	Booleano	Indica si se ha aplicado la recomendación.
modified	Booleano	Muestra si el usuario ha modificado la recomendación.
created_at	Marca de tiempo con zona horaria	Hora en la que se generó la recomendación.

vector_assist.get_recommendations

Devuelve las recomendaciones asociadas a un vector específico spec_id.

Función

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parámetros

Parámetro	¿Es obligatorio?	Descripción
spec_id	¿Es obligatorio?	Obtiene recomendaciones para el vector spec_id especificado.

Valor devuelto

Devuelve una tabla con las recomendaciones solicitadas.

La tabla de recomendaciones contiene las siguientes columnas:

Nombre de la columna	Tipo	Descripción
recommendation_id	Texto	ID de la recomendación. La recomendación se aplica con este ID.
vector_spec_id	Texto	ID de la especificación de vector asociada a la recomendación.
table_name	Texto	Nombre de la tabla asociada a la recomendación.
schema_name	Texto	El nombre del esquema que contiene la tabla indicada.
query	Texto	Consulta de SQL ejecutable que se debe ejecutar para conseguir el resultado de la recomendación.
recommendation	Texto	La explicación de la recomendación, incluido el resultado esperado una vez que se aplique. Esta columna también contiene el motivo y la justificación de la recomendación. Puedes usar este contexto para ajustar la consulta según sea necesario y volver a generar recomendaciones.
applied	Booleano	Indica si se ha aplicado la recomendación.
modified	Booleano	Muestra si el usuario ha modificado la recomendación.
created_at	Marca de tiempo con zona horaria	Hora en la que se generó la recomendación.

vector_assist.apply_recommendation

Aplica una sola recomendación mediante el recommendation_id.

Función

CREATE OR REPLACE FUNCTION vector_assist.get_recommendations (
    spec_id TEXT
)
RETURNS SETOF vector_assist.RECOMMENDATIONS;

Parámetros

Parámetro	¿Es obligatorio?	Descripción
recommenation_id	¿Es obligatorio?	ID de la recomendación de vector que se va a aplicar.

Valor devuelto

Devuelve un valor booleano que confirma si una recomendación se ha aplicado correctamente y actualiza la columna vector_assist.RECOMMENDATIONS de la tabla applied a TRUE.

Si la asistencia vectorial no puede aplicar la recomendación, se muestra un mensaje de error.

vector_assist.apply_spec

Aplica todas las recomendaciones asociadas a un vector spec_id o a un nombre de tabla específico. Esta función analiza todas las recomendaciones y ejecuta la función vector_assist.apply_recommendation en cada una de ellas.

Debe especificar un spec_id o un table_name para ejecutar la función.

Función

CREATE OR REPLACE FUNCTION vector_assist.apply_spec(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL -- text_column_name or vector_column_name
)
RETURNS BOOLEAN;

Parámetros

Parámetro	¿Es obligatorio?	Descripción
spec_id	Opcional	Aplica todas las recomendaciones del vector spec_id.
table_name	Opcional	Aplica todas las recomendaciones de la tabla en cuestión.
schema_name	Opcional	El esquema que contiene la tabla especificada.
column_name	Opcional	Identifica el text_column_name o el vector_column_name que se debe usar si la tabla contiene varias especificaciones de vector.

Valor devuelto

Devuelve un valor booleano que confirma si todas las recomendaciones se han aplicado correctamente y asigna el valor TRUE a la columna de la tabla vector_assist.RECOMMENDATIONS applied de todas las recomendaciones.

Si la asistencia vectorial no puede aplicar la recomendación, se muestra un mensaje de error.

vector_assist.modify_recommendation

Modifica la consulta de una recomendación específica y asigna el valor modified al campo de la tabla vector_assist.RECOMMENDATIONS de la recomendación asociada TRUE.

Función

CREATE OR REPLACE FUNCTION vector_assist.modify_recommendation(
    recommendation_id TEXT,
    modified_query TEXT
)
RETURNS BOOLEAN;

Parámetros

Parámetro	¿Es obligatorio?	Descripción
recommendation_id	¿Es obligatorio?	ID de la recomendación que se va a modificar.
modified_query	¿Es obligatorio?	Consulta de SQL modificada por el usuario para la recomendación.

Valor devuelto

Devuelve un valor booleano que confirma si una recomendación se ha actualizado correctamente y asigna el valor TRUE a la columna modified de la tabla vector_assist.RECOMMENDATIONS.

Si la asistencia vectorial no puede actualizar la recomendación, se muestra un mensaje de error.

vector_assist.generate_query

Genera una consulta de búsqueda de vectores optimizada basada en la especificación de vector y los parámetros de búsqueda definidos. Esta función puede ajustar el valor de ef_search para cumplir el valor de target_recall establecido, si procede.

Función

CREATE OR REPLACE FUNCTION vector_assist.generate_query(
    spec_id TEXT DEFAULT NULL,
    table_name TEXT DEFAULT NULL,
    schema_name TEXT DEFAULT NULL,
    column_name TEXT DEFAULT NULL, -- text_column_name or vector_column_name of the spec
    search_text TEXT DEFAULT NULL,
    search_vector VECTOR DEFAULT NULL, -- e.g. '[1.0,2.0,3.0]'::vector
   output_column_names TEXT[] DEFAULT NULL, -- Columns to retrieve, NULL for SELECT *
    top_k INT DEFAULT NULL,
    filter_expressions TEXT[] DEFAULT NULL,
    target_recall FLOAT DEFAULT NULL, -- Inherited from spec, can be overridden
    iterative_index_search BOOL DEFAULT NULL
)
RETURNS TEXT; -- Returns the text representing the search query

Parámetros

Parámetro	¿Es obligatorio?	Descripción
spec_id	Opcional	Especifica el spec_id para generar la consulta.
table_name	Opcional	Especifica el nombre de la tabla para generar la consulta de búsqueda si no se proporciona spec_id. Si una tabla contiene varias especificaciones, el parámetro devuelve un error.
column_name	Opcional	Especifica el nombre de la columna para generar la consulta de búsqueda si no se proporciona spec_id. Si la columna contiene varias especificaciones, el parámetro devuelve un error. El column_name puede ser text_column_name o vector_column_name.
output_column_name	Opcional	Los nombres de las columnas que se van a obtener en la consulta de salida. Para obtener todas las columnas, asigna el valor NULL a este parámetro.
search_text	Opcional	El texto de búsqueda para el que se van a generar las inserciones. Requiere el embedding_model en la especificación del vector. La inserción se genera con el modelo de la especificación. Solo puedes definir el parámetro search_text o el search_vector.
search_vector	Opcional	El vector de la consulta de búsqueda. Solo puedes definir el parámetro search_text o el parámetro search_vector.
top_k	Opcional	Número de vecinos más cercanos que se devolverán.
filter_expressions	Opcional	Las expresiones de filtro que se aplicarán en la consulta de búsqueda. Los filtros se pueden aplicar a los campos de la tabla, como precio < 100.
iterative_index_search	Opcional	Define si se debe realizar una búsqueda de índice iterativa para las consultas filtradas.Este parámetro anula la configuración de la especificación de vector.
target_recall	Opcional	La precisión de destino de la consulta de búsqueda. Este parámetro anula la configuración de la especificación del vector y ajusta ef_search.

Valor devuelto

Devuelve un texto que contiene la consulta de búsqueda vectorial de los parámetros proporcionados. Esta consulta se puede ejecutar o guardar para ejecutarla más adelante.

vector_assist.evaluate_query_recall

Evalúa la recuperación del índice vectorial de una consulta determinada. Esta función usa las configuraciones de la base de datos y del índice en una cadena JSON como entradas.

Función

CREATE OR REPLACE FUNCTION vector_assist.evaluate_query_recall(
  IN ann_query text,
  IN vector_search_configurations json DEFAULT NULL,
  OUT recall float,
  OUT ann_execution_time float,
  OUT ground_truth_execution_time float,
  OUT index_type text)
RETURNS RECORD

Parámetros

Parámetro	¿Es obligatorio?	Descripción
ann_query	¿Es obligatorio?	Consulta de SQL para la que se debe evaluar la recuperación. Esta consulta debe ser una consulta pgvector ANN.
vector_search_configurations	Opcional	Las configuraciones que se pueden definir para la consulta de ANN. Este parámetro debe estar en formato JSON.

Valor devuelto

Devuelve una tabla que evalúa la recuperación del índice vectorial de la consulta dada.

La tabla contiene las siguientes columnas:

Nombre de la columna	Tipo	Descripción
recall	Flotante	Porcentaje de vectores que devuelve el índice y que son los vecinos más cercanos reales. Esta métrica se usa para cuantificar la calidad de la búsqueda. Esta función te permite ajustar los parámetros para devolver los resultados de recuperación de consultas de vectores esperados.
ann_execution_time	Flotante	Tiempo que tarda en ejecutarse una consulta de vector mediante análisis de índice.
ground_truth_execution_time	Flotante	Tiempo que tarda la consulta en ejecutarse mediante un análisis secuencial.

Ejemplo

En el siguiente ejemplo se evalúa la recuperación de un índice HNSW y se anula el parámetro de configuración HNSW.ef_search:

SELECT * FROM vector_assist.evaluate_query_recall(
  ann_query => 'SELECT id FROM items ORDER BY embedding <=> ''[1,2,3]'' LIMIT 10',
  vector_search_configurations => '{"hnsw.ef_search": 30}'
);