Referencias de funciones de Vector Assist

Selecciona una versión de la documentación: 18.4.0

• Actual (18.4.0)
• 18.4.0
• 18.3.0
• 18.1.0

Consulta las siguientes funciones detalladas de asistencia de vectores para simplificar tus cargas de trabajo de vectores de AlloyDB Omni.

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.

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

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	Opcional, generado de forma automática si no se proporciona	Es un ID único para la especificación de vectores que definas.
table_name	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 según la ruta de búsqueda del esquema.
vector_column_name	Consulta la descripción	Es el nombre de la columna que contiene los embeddings 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	Consulta la descripción	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: (Valor predeterminado) HNSW IVFFlat
embeddings_available	Opcional	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	Consulta la descripción	Es el ID del modelo que se usó para generar los embeddings. Este campo es opcional, a menos que el parámetro embeddings_available sea FALSE o NULL. El valor predeterminado es text-embedding-005.
num_vectors	Opcional	Es la cantidad de vectores en la tabla.
dismensionality	Opcional	La dimensión de los vectores dados.
distance_func	Opcional	Es la función de distancia que se usará para comparar el vector. Los valores aceptables incluyen los siguientes: cosine: Es el valor predeterminado cuando quantization no se establece en bit. ip l2 l1 jaccard hamming: Es el valor predeterminado cuando quantization se establece en bit.
quantization	Opcional	La cuantización de los índices vectoriales. Los valores aceptables son los siguientes: none: Es el valor predeterminado cuando dimensionality es menor que 2000. halfvec: Es el valor predeterminado cuando dimensionality está entre 2000 y 4000. bit: Valor predeterminado cuando dimensionality es mayor que 4,000
prefilter_column_names	Opcional	Recomienda 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. El valor predeterminado es el 60% de la memoria de la instancia.
target_recall	Opcional	Es la recuperación objetivo para las consultas vectoriales estándar.
target_top_k	Opcional	Son los valores de coincidencia de Top-K 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, el asistente de vectores ajusta automáticamente el índice de vectores y la consulta de búsqueda para los objetivos de recuperación de destino con la especificación de vectores, y calcula los parámetros óptimos de la base de datos y del índice. Los valores aceptables son los siguientes: (Predeterminado)FALSE: Ajusta solo el parámetro de búsqueda (ef_search). Se usan los valores predeterminados de los parámetros de tiempo de compilación del índice (m, ef_construction). TRUE: Ajusta los parámetros de tiempo de compilación de búsqueda y de índice.

Valor que se muestra

Devuelve una tabla de recomendaciones, que incluye el ID de la especificación de vectores recién creada.

vector_assist.list_specs

Devuelve la especificación de vectores 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	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 vectores que coinciden con este nombre de columna.

Valor que se muestra

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

vector_assist.modify_spec

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

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	Es un ID único para la especificación de vector que defines.
table_name	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 según la ruta de búsqueda del esquema.
vector_column_name	Consulta la descripción	Es el nombre de la columna que contiene los embeddings 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	Consulta la descripción	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
embeddings_available	Opcional	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	Consulta la descripción	Es el ID del modelo que se usó para generar los embeddings. Este campo es opcional, a menos que el parámetro embeddings_available sea FALSE o NULL. El valor predeterminado es text-embedding-005.
num_vectors	Opcional	Es la cantidad de vectores en la tabla.
dismensionality	Opcional	La dimensión de los vectores dados.
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 de los índices vectoriales. Los valores aceptables incluyen none, halfvec o bit.
prefilter_column_names	Opcional	Identifica las columnas que están disponibles para el filtrado previo en las consultas de búsqueda de vectores.
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 consultas vectoriales estándar.
target_top_k	Opcional	Son los valores de coincidencia de Top-K 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 de vectores en tu carga de trabajo. Si está habilitado, el asistente de vectores ajusta automáticamente el índice de vectores o la consulta de búsqueda con la especificación de vectores y calcula los parámetros óptimos de la base de datos y del índice. Los valores aceptables incluyen TRUE o FALSE.

Valor que se muestra

Devuelve una tabla actualizada de recomendaciones.

vector_assist.get_recommendations

Devuelve 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	Obligatorio	Obtiene recomendaciones para el vector spec_id especificado.

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é 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 de vector asociada a la recomendación.
table_name	Texto	Es el nombre de la tabla asociada a la recomendación.
schema_name	Texto	Es el nombre del esquema que contiene la tabla determinada.
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.apply_recommendation (
    recommendation_id TEXT
)
RETURNS BOOLEAN;

Parámetros

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

Valor que se muestra

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

Si el asistente de vectores no puede aplicar la recomendación, genera 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.

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

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

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

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 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 todas las recomendaciones se aplicaron correctamente y establece el valor en la columna applied de la tabla vector_assist.RECOMMENDATIONS en TRUE para todas las recomendaciones.

Si el asistente de vectores no puede aplicar la recomendación, genera un mensaje de error.

vector_assist.modify_recommendation

Modifica la consulta para una recomendación específica y establece el campo modified en la tabla vector_assist.RECOMMENDATIONS para 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	Obligatorio	Es el ID de la recomendación que se modificará.
modified_query	Obligatorio	Es una consulta en SQL modificada por el usuario para la recomendación.

Valor que se muestra

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

Si el asistente de vectores no puede actualizar la recomendación, genera un mensaje de error.

vector_assist.generate_query

Genera una consulta de Vector Search optimizada en función de la especificación de vectores y los parámetros de búsqueda definidos. Esta función puede ajustar el valor de ef_search para cumplir con el 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

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

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 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 la que se generará la consulta de búsqueda si no se proporciona el spec_id. Si la columna contiene varias especificaciones, el parámetro devuelve un error. El column_name puede ser el text_column_name o el vector_column_name.
output_column_name	Opcional	Son los 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. La incorporación se genera con el embedding_model de la especificación. Solo puedes establecer el parámetro search_text o el parámetro search_vector.
search_vector	Opcional	Es el vector de la búsqueda. Solo puedes establecer el parámetro search_text o search_vector.
top_k	Opcional	Es la cantidad de vecinos más cercanos que se mostrará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.
target_recall	Opcional	Es la recuperación objetivo solo para la búsqueda. Si se establece, la función puede devolver una recomendación para ef_search si encuentra un valor mejor.

Valor que se muestra

Devuelve un texto que contiene la consulta de búsqueda de vectores para los parámetros determinados. Si se especifica target_recall, también se puede incluir una recomendación para ef_search si se encuentra un valor mejor. Esta consulta se puede ejecutar o guardar para ejecutarla más tarde.

vector_assist.evaluate_query_recall

Evalúa la recuperación del índice vectorial para una consulta determinada. Esta función usa los parámetros de configuración 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(
  ann_query text,
  vector_search_configurations json DEFAULT NULL,
  recall float,
  ann_execution_time float,
  ground_truth_execution_time float,
  index_type text)
RETURNS RECORD

Parámetros

Parámetro	¿Es obligatorio?	Descripción
ann_query	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 consulta de ANN. Este parámetro debe estar en formato JSON.

Valor que se muestra

Muestra una tabla que evalúa la recuperación del índice vectorial para la consulta 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 muestra el índice, que son vecinos más cercanos verdaderos. Esta métrica se usa para cuantificar la calidad de la búsqueda. Esta función te permite ajustar los parámetros para mostrar los resultados esperados de la recuperación de consultas vectoriales.
ann_execution_time	Número de punto flotante	Es el tiempo que tarda una consulta vectorial en ejecutarse 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.
index_type	Texto	Es el tipo de índice de vector, como HNSW.

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}'
);