Referencia de asistencia de vectores

MySQL   |  PostgreSQL   |  SQL Server

Versión preliminar — Vector Assist

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Puedes tratar datos personales para esta función, como se describe en el Anexo de Tratamiento de Datos de Cloud, con sujeción a las obligaciones y restricciones descritas en el acuerdo en virtud del cual accedes a Google Cloud. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En esta página, se proporciona información detallada sobre todas las funciones de asistencia vectorial disponibles y 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 aumentar 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)	Es un ID único para la especificación de vector que defines.
table_name	¿Es obligatorio?	Es el nombre de la tabla que se usará en la configuración de la carga de trabajo de vectores.
schema_name	Opcional	Es el esquema que contiene la tabla que se usará en la carga de trabajo de vectores. El esquema se infiere automáticamente en función de la ruta de búsqueda del esquema.
vector_column_name	Opcional u obligatorio	Es el nombre de la columna que contiene las incorporaciones de vectores. Esta columna es obligatoria si usas más de una columna de vectores y no se declara text_column_name. Si solo usas una columna de vectores, este parámetro es opcional.
text_column_name	Opcional u obligatorio	Es el nombre de la columna de texto. Si tu carga de trabajo de vectores requiere la generación de incorporaciones 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 embeddings a partir de la columna de texto proporcionada.
vector_index_type	Opcional	Es el tipo de índice vectorial. Los valores aceptables son los siguientes: HNSW IVFFlat SCANN
embeddings_available	Opcional	Es un valor booleano que verifica si existen embeddings de vectores en la tabla seleccionada. Este campo se establece en FALSE si no se detectan columnas de vectores y se establece el parámetro text_column_name.
embedding_model	Opcional u obligatorio	Es el ID del modelo de google_ml.models que se usará para generar las incorporaciones. Este campo es opcional, a menos que el parámetro embeddings_available sea FALSE o NULL.
num_vectors	Opcional	Es la cantidad de vectores en la tabla.
dismensionality	Opcional	Dimensión de los vectores proporcionados.
distance_func	Opcional	Es la función de distancia que se usará para comparar el vector. Los valores aceptables incluyen cosine, ip, l2 o l1.
quantization	Opcional	Es la cuantización para los índices vectoriales. Los valores aceptables incluyen none, halfvec o bit.
prefilter_column_names	Opcional	Crea un índice para la columna especificada para el prefiltrado. Esto podría ayudar a mejorar el rendimiento de las consultas con un filtro de alta selectividad en la columna.
memory_budget_kb	Opcional	Es la memoria máxima (en KB) para la creación de índices.
target_recall	Opcional	Es la recuperación objetivo para las búsquedas vectoriales estándares.
target_top_k	Opcional	Son los K valores de coincidencia principales que se recuperarán para el cálculo de la recuperación. Este valor se usa si se especifica el parámetro target_recall.
tune_vector_index	Opcional	Ajusta los índices vectoriales en tu carga de trabajo. Si está habilitado, Vector Assist ajusta automáticamente el índice de vectores o la búsqueda con la especificación de vectores y calcula los parámetros óptimos de la base de datos y el índice. Los valores aceptables incluyen TRUE o FALSE.

Valor que se muestra

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

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

La tabla de recomendaciones contiene las siguientes columnas:

Nombre de la columna	Tipo	Descripción
recommendation_id	Texto	Es el ID de la recomendación. La recomendación se aplica con este ID.
vector_spec_id	Texto	Es el ID de la especificación del vector asociado a la recomendación.
table_name	Texto	Es el nombre de la tabla asociada a la recomendación.
schema_name	Texto	Nombre del esquema que contiene la tabla especificada.
query	Texto	Es la consulta en SQL ejecutable que se debe ejecutar para lograr el resultado de la recomendación.
recommendation	Texto	Es 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 búsqueda según sea necesario y volver a generar recomendaciones.
applied	Booleano	Muestra si se aplicó la recomendación.
modified	Booleano	Muestra si el usuario modificó la recomendación.
created_at	Marca de tiempo con zona horaria	Es la fecha y hora en 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 del vector actual para 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?	Es el nombre de la tabla para la que se recupera la especificación del vector.
column_name	Opcional	Es el nombre de la columna por la que se 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 columnas de texto o vector que coinciden con este nombre de columna.

Valor que se muestra

Devuelve una tabla de especificaciones para la tabla determinada y, de manera opcional, el nombre de la columna.

vector_assist.modify_spec

Modifica una especificación de vector existente. Cuando se modifica la especificación de vector, se vuelven a generar las recomendaciones asociadas 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)	Es un ID único para la especificación de vector que defines.
table_name	¿Es obligatorio?	Es el nombre de la tabla que se usará en la configuración de la carga de trabajo de vectores.
schema_name	Opcional	Es el esquema que contiene la tabla que se usará en la carga de trabajo de vectores. El esquema se infiere automáticamente en función de la ruta de búsqueda del esquema.
vector_column_name	Opcional u obligatorio	Es el nombre de la columna que contiene las incorporaciones de vectores. Esta columna es obligatoria si usas más de una columna de vectores y no se declara text_column_name. Si solo usas una columna de vectores, este parámetro es opcional.
text_column_name	Opcional u obligatorio	Es el nombre de la columna de texto. Si tu carga de trabajo de vectores requiere la generación de incorporaciones 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 embeddings a partir de la columna de texto proporcionada.
vector_index_type	Opcional	Es el tipo de índice vectorial. Los valores aceptables son los siguientes: HNSW IVFFlat SCANN
embeddings_available	Opcional	Es un valor booleano que verifica si existen embeddings de vectores en la tabla seleccionada. Este campo se establece en FALSE si no se detectan columnas de vectores y se establece el parámetro text_column_name.
embedding_model	Opcional u obligatorio	Es el ID del modelo de google_ml.models que se usará para generar las incorporaciones. Este campo es opcional, a menos que el parámetro embeddings_available sea FALSE o NULL.
num_vectors	Opcional	Es la cantidad de vectores en la tabla.
dismensionality	Opcional	Dimensión de los vectores proporcionados.
distance_func	Opcional	Es la función de distancia que se usará para comparar el vector. Los valores aceptables incluyen cosine, ip, l2 o l1.
quantization	Opcional	Es la cuantización para los índices vectoriales. Los valores aceptables incluyen none, halfvec o bit.
prefilter_column_names	Opcional	Identifica las columnas que están disponibles para el prefiltrado en las consultas de búsqueda vectorial.
memory_budget_kb	Opcional	Es la memoria máxima (en KB) para la creación de índices.
target_recall	Opcional	Es la recuperación objetivo para las búsquedas vectoriales estándares.
target_top_k	Opcional	Son los K valores de coincidencia principales que se recuperarán para el cálculo de la recuperación. Este valor se usa si se especifica el parámetro target_recall.
tune_vector_index	Opcional	Ajusta los índices vectoriales en tu carga de trabajo. Si está habilitado, Vector Assist ajusta automáticamente el índice de vectores o la búsqueda con la especificación de vectores y calcula los parámetros óptimos de la base de datos y el índice. Los valores aceptables incluyen TRUE o FALSE.

Valor que se muestra

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

La tabla de recomendaciones contiene las siguientes columnas:

Nombre de la columna	Tipo	Descripción
recommendation_id	Texto	Es el ID de la recomendación. La recomendación se aplica con este ID.
vector_spec_id	Texto	Es el ID de la especificación del vector asociado a la recomendación.
table_name	Texto	Es el nombre de la tabla asociada a la recomendación.
schema_name	Texto	Nombre del esquema que contiene la tabla especificada.
query	Texto	Es la consulta en SQL ejecutable que se debe ejecutar para lograr el resultado de la recomendación.
recommendation	Texto	Es 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 búsqueda según sea necesario y volver a generar recomendaciones.
applied	Booleano	Muestra si se aplicó la recomendación.
modified	Booleano	Muestra si el usuario modificó la recomendación.
created_at	Marca de tiempo con zona horaria	Es la fecha y hora en que se generó la recomendación.

vector_assist.get_recommendations

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

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 que se muestra

Devuelve una tabla de las recomendaciones solicitadas.

La tabla de recomendaciones contiene las siguientes columnas:

Nombre de la columna	Tipo	Descripción
recommendation_id	Texto	Es el ID de la recomendación. La recomendación se aplica con este ID.
vector_spec_id	Texto	Es el ID de la especificación del vector asociado a la recomendación.
table_name	Texto	Es el nombre de la tabla asociada a la recomendación.
schema_name	Texto	Nombre del esquema que contiene la tabla especificada.
query	Texto	Es la consulta en SQL ejecutable que se debe ejecutar para lograr el resultado de la recomendación.
recommendation	Texto	Es 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 búsqueda según sea necesario y volver a generar recomendaciones.
applied	Booleano	Muestra si se aplicó la recomendación.
modified	Booleano	Muestra si el usuario modificó la recomendación.
created_at	Marca de tiempo con zona horaria	Es la fecha y hora en que se generó la recomendación.

vector_assist.apply_recommendation

Aplica una sola recomendación con 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 aplicará.

Valor que se muestra

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

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

vector_assist.apply_spec

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

Se 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 para el vector spec_id determinado.
table_name	Opcional	Aplica todas las recomendaciones para la tabla determinada.
schema_name	Opcional	Es el esquema que contiene la tabla especificada.
column_name	Opcional	Identifica el text_column_name o el vector_column_name que se usará si la tabla contiene varias especificaciones de vectores.

Valor que se muestra

Devuelve un valor booleano que confirma si se aplicaron correctamente todas las recomendaciones y establece el valor en la columna de la tabla vector_assist.RECOMMENDATIONS applied en TRUE para todas las recomendaciones.

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

vector_assist.modify_recommendation

Modifica la búsqueda de una recomendación específica y establece el campo modified en la tabla vector_assist.RECOMMENDATIONS de la recomendación asociada en 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 modificará.
modified_query	¿Es obligatorio?	Es una consulta en SQL modificada por el usuario para la recomendación.

Valor que se muestra

Devuelve un valor booleano que confirma si se actualizó correctamente una recomendación y establece la columna de la tabla vector_assist.RECOMMENDATIONS modified en TRUE.

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

vector_assist.generate_query

Genera una búsqueda de vectores optimizada en función de la especificación de vectores y los parámetros de búsqueda definidos. Esta función podría ajustar el valor de ef_search para cumplir con el valor de target_recall establecido, si corresponde.

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 el que se generará la consulta.
table_name	Opcional	Especifica el nombre de la tabla para la que se generará la búsqueda si no se proporciona spec_id. Si una tabla contiene varias especificaciones, el parámetro muestra un error.
column_name	Opcional	Especifica el nombre de la columna para la que se generará la búsqueda si no se proporciona spec_id. Si la columna contiene varias especificaciones, el parámetro muestra un error. El column_name puede ser el text_column_name o el vector_column_name.
output_column_name	Opcional	Nombres de las columnas que se recuperarán en la consulta de salida. Para recuperar todas las columnas, establece este parámetro en NULL.
search_text	Opcional	Es el texto de búsqueda para el que se generarán las incorporaciones. Requiere el embedding_model en la especificación del vector. El embedding se genera con el modelo de la especificación. Solo puedes establecer el parámetro search_text o el search_vector.
search_vector	Opcional	Es el vector de la búsqueda. Solo puedes establecer el parámetro search_text o el parámetro search_vector.
top_k	Opcional	Es la cantidad de vecinos más cercanos que se devolverán.
filter_expressions	Opcional	Son las expresiones de filtro que se aplicarán en la búsqueda. Los filtros se pueden aplicar a los campos de la tabla, como precio < 100.
iterative_index_search	Opcional	Establece si se debe realizar una búsqueda de índice iterativa para las búsquedas filtradas.Este parámetro anula la configuración en la especificación del vector.
target_recall	Opcional	Es la recuperación objetivo solo para la búsqueda. Este parámetro anula la configuración en la especificación del vector y ajusta ef_search.

Valor que se muestra

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

vector_assist.evaluate_query_recall

Evalúa la recuperación del índice de vectores para una búsqueda determinada. Esta función usa la base de datos y las configuraciones de í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?	Es la consulta en SQL para la que se debe evaluar la recuperación. Esta consulta debe ser una consulta de pgvector ANN.
vector_search_configurations	Opcional	Son los parámetros de configuración que se pueden establecer para la búsqueda de ANN. Este parámetro debe estar en formato JSON.

Valor que se muestra

Devuelve una tabla que evalúa la recuperación del índice de vectores para la búsqueda determinada.

La tabla contiene las siguientes columnas:

Nombre de la columna	Tipo	Descripción
recall	Número de punto flotante	Es el porcentaje de vectores que devuelve el índice y que son vecinos más cercanos verdaderos. Esta métrica se utiliza para cuantificar la calidad de la búsqueda. Esta función te permite ajustar los parámetros para devolver los resultados esperados de recuperación de la búsqueda vectorial.
ann_execution_time	Número de punto flotante	Es el tiempo que tarda en ejecutarse una búsqueda de vectores con análisis de índices.
ground_truth_execution_time	Número de punto flotante	Es el tiempo que tarda la consulta en ejecutarse con un análisis secuencial.

Ejemplo

En el siguiente ejemplo, se evalúa la recuperación para 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}'
);