Creación de puntos de conexión e índices de búsqueda vectorial

En este artículo se describe cómo crear puntos de conexión e índices de búsqueda vectorial mediante la búsqueda vectorial de mosaico de IA.

Puede crear y administrar componentes de búsqueda vectorial, como un punto de conexión de búsqueda vectorial e índices de búsqueda vectorial, mediante la interfaz de usuario, el SDK de Python de o la API REST de .

Para obtener cuadernos de ejemplo que ilustran cómo crear y consultar puntos de conexión de búsqueda vectorial, consulte Cuadernos de ejemplo de búsqueda vectorial. Para obtener información de referencia, consulte la referencia del SDK de Python.

Requisitos

• Área de trabajo habilitada para el catálogo de Unity.
• Computación sin servidor habilitada. Para obtener instrucciones, consulte Conectar a la computación sin servidor.
• En el caso de los puntos de conexión estándar, la tabla de origen debe tener habilitado el flujo de cambios de datos. Vea Uso de la fuente de distribución de datos de cambios de Delta Lake en Azure Databricks.
• Para crear un índice de búsqueda vectorial, debe tener CREATE TABLE privilegios en el esquema de catálogo donde se creará el índice.
• Para consultar un índice que sea propiedad de otro usuario, debe tener privilegios adicionales. Consulte Cómo consultar un índice de búsqueda vectorial.

El permiso para crear y administrar puntos de conexión de búsqueda vectorial se configura mediante listas de control de acceso. Consulte ACL de punto de conexión de vector de búsqueda.

Installation

Para usar el SDK de búsqueda vectorial, debe instalarlo en el cuaderno. Use el código siguiente para instalar el paquete:

%pip install databricks-vectorsearch
dbutils.library.restartPython()

A continuación, use el siguiente comando para importar VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

Para obtener información sobre la autenticación, consulte Protección y autenticación de datos.

Crear un endpoint de búsqueda vectorial

Puede crear un punto de conexión de búsqueda vectorial mediante la interfaz de usuario de Databricks, el SDK de Python o la API.

Creación de un punto de conexión de búsqueda vectorial mediante la interfaz de usuario

Siga estos pasos para crear un punto de conexión de búsqueda vectorial mediante la interfaz de usuario.

1. En la barra lateral izquierda, haga clic en Proceso.

2. Haga clic en la pestaña Búsqueda de vectores y después haga clic en Crear.

   

3. Se abre el formulario Crear punto de conexión. Escriba un nombre para este punto de conexión.

   

4. En el campo Tipo , seleccione Estándar o Optimizado para almacenamiento. Consulte Opciones de punto de conexión.

5. (Opcional) En Configuración avanzada, seleccione una directiva de presupuesto. Consulte Mosaic AI Vector Search: Budget policies (Búsqueda de vectores de IA de mosaico: directivas presupuestarias).

6. Haga clic en Confirmar.

Creación de un punto de conexión de búsqueda vectorial mediante el SDK de Python

En el ejemplo siguiente se usa la función create_endpoint() SDK para crear un punto de conexión de búsqueda vectorial.

# The following line automatically generates a PAT Token for authentication
client = VectorSearchClient()

# The following line uses the service principal token for authentication
# client = VectorSearchClient(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD" # or "STORAGE_OPTIMIZED"
)

Creación de un punto de conexión de búsqueda vectorial mediante la API REST

Consulte la documentación de referencia de la API REST: POST /api/2.0/vector-search/endpoints.

(Opcional) Creación y configuración de un punto de conexión para atender el modelo de inserción

Si decide hacer que Databricks calcule las inserciones, puede usar un punto de conexión de api de Foundation Model preconfigurado o crear un punto de conexión de servicio de modelo para atender el modelo de inserción que prefiera. Consulte API de Modelo base de pago por token o Creación de puntos de conexión de modelo de servicio base para obtener instrucciones. Para cuadernos de ejemplos, consulte Cuadernos de ejemplo de búsqueda vectorial.

Al configurar un punto de conexión de inserción, Databricks recomienda quitar la selección predeterminada de Escalar a cero. Los puntos de conexión de servicio pueden tardar un par de minutos en preparación y la consulta inicial en un índice con un punto de conexión de reducción vertical podría tardar un tiempo de espera.

Nota:

La inicialización del índice de vector de búsqueda puede agotar el tiempo de espera si el punto de conexión de inserción no está configurado correctamente para el conjunto de datos. Solo debe usar puntos de conexión de CPU para pequeños conjuntos de datos y pruebas. Para conjuntos de datos más grandes, use un punto de conexión de GPU para obtener un rendimiento óptimo.

Crear un índice de búsqueda vectorial

Puede crear un índice de búsqueda vectorial mediante la interfaz de usuario, el SDK de Python o la API REST. La interfaz de usuario es el enfoque más sencillo.

Hay dos tipos de índices:

• El índice de sincronización delta se sincroniza automáticamente con una tabla delta de origen, actualizando automáticamente e incrementalmente el índice a medida que cambian los datos subyacentes de la tabla Delta.
• Direct Vector Access Index admite lectura directa y escritura de vectores y metadatos. El usuario es responsable de actualizar esta tabla mediante la API REST o el SDK de Python. Este tipo de índice no se puede crear mediante la interfaz de usuario. Debe usar la API REST o el SDK.

Nota:

El nombre de la columna _id está reservado. Si la tabla de origen tiene una columna denominada _id, cámbiela antes de crear un índice de búsqueda vectorial.

Crear índice mediante la interfaz de usuario

1. En la barra lateral izquierda, haga clic en Catálogo para abrir la interfaz de usuario del Explorador de catálogos.

2. Vaya a la tabla Delta que desea usar.

3. Haga clic en el botón Crear en la esquina superior derecha y seleccione Índice de búsqueda vectorial en el menú desplegable.

   

4. Use los selectores del cuadro de diálogo para configurar el índice.

   

   Nombre: nombre que se va a usar para la tabla en línea en el catálogo de Unity. El nombre requiere un espacio de nombres de tres niveles, <catalog>.<schema>.<name>. Solo se permiten caracteres alfanuméricos y caracteres de subrayado.

   Clave principal: columna que se va a usar como clave principal.

   Columnas que se van a sincronizar: seleccione las columnas que se van a sincronizar con el índice vectorial. Si deja este campo en blanco, todas las columnas de la tabla de origen se sincronizan con el índice. La columna de clave principal y la columna de origen de inserción o columna de vector de inserción siempre se sincronizan.

   Fuente de embeddings: indique si desea que Databricks calcule embeddings para una columna de texto en la tabla Delta (Calcular embeddings) o si su tabla Delta contiene embeddings precalculadas (usar una columna de embeddings existente).

   • Si seleccionó Incrustaciones de proceso, seleccione la columna para la que desea que se calcule la inserción y el modelo de inserción que se va a usar para el cálculo. Solo se admiten columnas de texto.

     • Para las aplicaciones de producción que usan puntos de conexión estándar, Databricks recomienda usar el modelo fundacional databricks-gte-large-en con un punto de conexión con rendimiento aprovisionado.

     • Para las aplicaciones de producción que usan puntos de conexión optimizados para almacenamiento con modelos hospedados en Databricks, use el nombre del modelo directamente (por ejemplo, databricks-gte-large-en) como punto de conexión del modelo de inserción. Los puntos de conexión optimizados para almacenamiento utilizan ai_query con inferencia por lotes durante la entrada de datos, proporcionando un alto rendimiento para la tarea de incrustación. Si prefiere usar un punto de conexión de rendimiento aprovisionado para realizar consultas, especifíquelo en el model_endpoint_name_for_query campo al crear el índice.

   • Si seleccionó Usar columna de inserción existente, seleccione la columna que contiene las incrustaciones precaladas y la dimensión de inserción. El formato de la columna de incrustación precomputada debe ser array[float]. Para los puntos de conexión optimizados para almacenamiento, la dimensión de incrustación debe ser divisible uniformemente por 16.

   Sincronizar incrustaciones calculadas: Active o desactive esta opción para guardar las incrustaciones generadas en una tabla de Unity Catalog. Para obtener más información, consulte Guardar tabla de inserción generada.

   Punto de conexión de búsqueda vectorial: seleccione el punto de conexión de búsqueda vectorial para almacenar el índice.

   Modo de sincronización: continua mantiene el índice sincronizado con segundos de latencia. Sin embargo, tiene un costo mayor asociado, ya que se aprovisiona un clúster de proceso para ejecutar la canalización de streaming de sincronización continua.

   • En el caso de los puntos de conexión estándar, tanto continuos como desencadenados realizan actualizaciones incrementales, por lo que solo se procesan los datos que han cambiado desde la última sincronización.
   • En el caso de los puntos de conexión optimizados para almacenamiento, cada sincronización vuelve a generar parcialmente el índice. En el caso de los índices administrados en sincronizaciones posteriores, las inserciones generadas en las que la fila de origen no ha cambiado se reutilizan y no es necesario volver a calcularla. Consulte Limitaciones de los puntos de conexión optimizados para almacenamiento.

   Con el modo de sincronización desencadenado , se usa el SDK de Python o la API REST para iniciar la sincronización. Consulte Actualización de un índice de sincronización delta.

   En el caso de los puntos de conexión optimizados para almacenamiento, solo se admite el modo de sincronización activado.

   Configuración avanzada: (opcional)

   • Puede aplicar una directiva de presupuesto al índice. Consulte Mosaic AI Vector Search: Budget policies (Búsqueda de vectores de IA de mosaico: directivas presupuestarias).

   • Si seleccionó Incrustaciones de cálculo, puede especificar un modelo de incrustación independiente para consultar su índice de búsqueda vectorial. Esto puede ser útil si necesita un punto de conexión de alto rendimiento para la ingesta, pero un punto de conexión de latencia inferior para consultar el índice. El modelo especificado en el campo Modelo de inserción siempre se usa para la ingesta y también se usa para realizar consultas, a menos que especifique un modelo diferente aquí. Para especificar un modelo diferente, haga clic en Elegir modelo de inserción independiente para consultar el índice y seleccionar un modelo en el menú desplegable.

     

5. Cuando haya terminado de configurar el índice, haga clic en Crear.

Creación de un índice mediante el SDK de Python

En el ejemplo siguiente se crea un índice de sincronización delta con incrustaciones calculadas por Databricks. Para más información, consulte la referencia del SDK de Python.

En este ejemplo también se muestra el parámetro model_endpoint_name_for_queryopcional , que especifica un modelo de inserción independiente que sirve el punto de conexión que se usará para consultar el índice.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_source_column="text",
  embedding_model_endpoint_name="e5-small-v2", # This model is used for ingestion, and is also used for querying unless model_endpoint_name_for_query is specified.
  model_endpoint_name_for_query="e5-mini-v2"   # Optional. If specified, used only for querying the index.
)

En el ejemplo siguiente se crea un índice de sincronización delta con incrustaciones autoadministradas.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector"
)

De forma predeterminada, todas las columnas de la tabla de origen se sincronizan con el índice. Para seleccionar un subconjunto de columnas que se van a sincronizar, use columns_to_sync. La clave principal y las columnas de inserción siempre se incluyen en el índice.

Para sincronizar solo la clave principal y la columna de inserción, debe especificarlas en columns_to_sync como se muestra:

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

Para sincronizar columnas adicionales, especifíquelas como se muestra. No es necesario incluir la clave principal y la columna de inserción, ya que siempre se sincronizan.

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["revisionId", "text"] # to sync the `revisionId` and `text` columns in addition to the primary key and embedding column.
)

En el ejemplo siguiente se crea un índice de acceso vectorial directo.

client = VectorSearchClient()

index = client.create_direct_access_index(
  endpoint_name="storage_endpoint",
  index_name=f"{catalog_name}.{schema_name}.{index_name}",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector",
  schema={
    "id": "int",
    "field2": "string",
    "field3": "float",
    "text_vector": "array<float>"}
)

Creación de un índice mediante la API REST

Consulte la documentación de referencia de la API REST: POST /api/2.0/vector-search/indexes.

Guardar tabla de inserción generada

Si Databricks genera las inserciones, puede guardar las inserciones generadas en una tabla del catálogo de Unity. Esta tabla se crea en el mismo esquema que el índice vectorial y está vinculado desde la página de índice vectorial.

El nombre de la tabla es el nombre del índice de búsqueda vectorial, anexado por _writeback_table. El nombre no se puede editar.

Puede acceder a la tabla y consultarla como cualquier otra tabla del catálogo de Unity. Sin embargo, no debe quitar ni modificar la tabla, ya que no está pensado para actualizarse manualmente. La tabla se elimina automáticamente si se elimina el índice.

Actualización de un índice de búsqueda vectorial

Actualizar un índice de sincronización delta

Los índices creados con el modo de sincronización continua se actualizan automáticamente cuando cambia la tabla Delta de origen. Si usa el modo de sincronización desencadenado , puede iniciar la sincronización mediante la interfaz de usuario, el SDK de Python o la API REST.

Interfaz de usuario de Databricks

1. En el Explorador de catálogos, vaya al índice de búsqueda vectorial.

2. En la pestaña Información general , en la sección Ingesta de datos , haga clic en Sincronizar ahora.

   

SDK de Python

Para más información, consulte la referencia del SDK de Python.

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

index.sync()

REST API

Consulte la documentación de referencia de la API REST: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Actualizar un índice de acceso vectorial directo

Puede usar el SDK de Python o la API REST para insertar, actualizar o eliminar datos de un índice de acceso vectorial directo.

SDK de Python

Para más información, consulte la referencia del SDK de Python.

index.upsert([
    {
        "id": 1,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.0] * 1024
    },
    {
        "id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1] * 1024
    }
])

REST API

Consulte la documentación de referencia de la API REST: POST /api/2.0/vector-search/indexes.

Para las aplicaciones de producción, Databricks recomienda utilizar credenciales de servicio en lugar de tokens de acceso personal. El rendimiento se puede mejorar en hasta 100 ms por consulta.

En el siguiente ejemplo de código se ilustra cómo actualizar un índice utilizando un principal de servicio.

export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...

# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "WriteVectorIndex"}'

# Generate OAuth token
export TOKEN=$(curl -X POST --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')

# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')

# Upsert data into vector search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/upsert-data --data '{"inputs_json": "[...]"}'

# Delete data from vector search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/delete-data --data '{"primary_keys": [...]}'

En el ejemplo de código siguiente se muestra cómo actualizar un índice mediante un token de acceso personal (PAT).

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Upsert data into vector search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/upsert-data --data '{"inputs_json": "..."}'

# Delete data from vector search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/delete-data --data '{"primary_keys": [...]}'

Cómo realizar cambios de esquema sin tiempo de inactividad

Si cambia el esquema de las columnas existentes en la tabla de origen, debe volver a generar el índice. Si la tabla de reescritura está habilitada, también debe volver a generar el índice cuando se agregan nuevas columnas a la tabla de origen. Si la tabla de reescritura no está habilitada, las nuevas columnas no requieren volver a generar el índice.

Siga estos pasos para recompilar e implementar el índice sin tiempo de inactividad:

1. Realice el cambio de esquema en la tabla de origen.
2. Cree un nuevo índice.
3. Una vez listo el nuevo índice, cambie el tráfico al nuevo índice.
4. Elimine el índice original.