Procedimiento para crear y consultar un índice de vector de búsqueda

En este artículo se describe cómo crear y consultar un índice de vector de búsqueda mediante el Vector de búsqueda de Mosaic AI.

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

Requisitos

• Área de trabajo habilitada para Unity Catalog.
• Proceso sin servidor habilitado. Para obtener instrucciones, consulte Conectarse a equipos sin servidor.
• La tabla de origen debe tener habilitada la fuente de distribución de datos modificados. Para obtener instrucciones, consulte Uso de la fuente de distribución de datos de cambios de Delta Lake en Azure Databricks.
• Para crear un índice, debe tener privilegios CREATE TABLE en esquemas de catálogo para crear índices. Para consultar un índice que sea propiedad de otro usuario, debe tener privilegios adicionales. Vea Consulta de un punto de conexión de vector de búsqueda.
• Si desea usar tokens de acceso personal (no recomendado para cargas de trabajo de producción), compruebe que los tokens de acceso personal están habilitados. Para usar un token de entidad de servicio en su lugar, páselo explícitamente mediante llamadas DE SDK o API.

Para usar el SDK, debe instalarlo en el cuaderno. Use el código siguiente:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Creación de un punto de conexión de vector de búsqueda

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

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

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

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

2. Haga clic en la pestaña Vector de búsqueda y haga clic en Crear.

   

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

4. Haga clic en Confirmar.

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

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

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

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

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

Creación de un punto de conexión de vector de búsqueda mediante la API de 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 al modelo de inserción que prefiera. Consulte API de Foundation Model de pago por token o Creación de puntos de conexión de servicio del modelo de IA generativa para obtener instrucciones. Para obtener cuadernos de ejemplo, vea Ejemplos de cuaderno para llamar a un modelo de inserción.

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.

Crear un índice de vector de búsqueda

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

Hay dos tipos de índices:

• Índice de sincronización Delta 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 de REST o el SDK de Python. Este tipo de índice no se puede crear mediante la interfaz de usuario. Debe usar la API de REST o el SDK.

Creación de un í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 vector de búsqueda en el menú desplegable.

   

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

   

   Nombre: Nombre que se usará para la tabla en línea en Catalog Explorer. 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.

   Punto de conexión: selecciona el punto de conexión de vector de búsqueda que quieres usar.

   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.

   Insertar origen: Indique si quiere que Databricks calcule las incrustaciones de una columna de texto en la tabla Delta (inserción de proceso), o si la tabla Delta contiene incrustaciones precalculadas (Usar columna de inserción existente).

   • Si seleccionó inserción de proceso, seleccione la columna para la que desea insertar y el punto de conexión para el que sirve el modelo de inserción. Solo se admiten columnas de texto.
   • Si seleccionó Usar columna de inserción existente, seleccione la columna que contiene las incrustaciones precalculada y la dimensión de inserción. El formato de la columna de inserción precalculada debería ser array[float].

   Inserciones calculadas de sincronización: cambie esta configuración para guardar las inserciones generadas en una tabla de Unity Catalog. Para obtener más información, consulte Guardar tabla de inserción generada.

   Modo de sincronización: Continuo 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. Para Continua y Desencadenado, la actualización solo es datos incrementales: que han cambiado desde que se procesa la última sincronización.

   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.

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.

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"
)

En el siguiente ejemplo se crea un índice de sincronización delta con incrustaciones autoadministradas. En este ejemplo también se muestra el uso del parámetro opcional columns_to_sync para seleccionar solo un subconjunto de columnas que se van a usar en 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_dimension=1024,
  embedding_vector_column="text_vector"
)

De manera predeterminada, todas las columnas de la tabla de origen se sincronizan con el índice. Para sincronizar solo un subconjunto de columnas, 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="{catalog_name}.{schema_name}.{index_name}",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector",
  schema={
    "id": "int",
    "field2": "str",
    "field3": "float",
    "text_vector": "array<float>"}
)

Creación de un índice mediante la API de 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 de Unity Catalog. 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 del vector de búsqueda, anexado por _writeback_table. El nombre no se puede editar.

Puede acceder a la tabla y consultarla como cualquier otra tabla de Unity Catalog. Sin embargo, no debe quitar ni modificar la tabla, ya que no está pensada 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 modo de sincronizaciónContinua se actualizan automáticamente cuando cambia la tabla Delta de origen. Si usa el modo de sincronización desencadenado , use el SDK de Python o la API REST para iniciar la sincronización.

SDK de Python

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 de REST para insertar, actualizar o eliminar datos de un índice de acceso vectorial directo.

SDK de Python

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

REST API

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

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": [...]}'

En el ejemplo de código siguiente se muestra cómo actualizar un índice mediante una entidad 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": [...]}'

Consulta de un punto de conexión de vector de búsqueda

Solo se puede consultar el punto de conexión de vector de búsqueda mediante el SDK de Python, la API REST o la función de IA de SQL vector_search().

Para realizar una búsqueda de similitud de palabras clave híbrida, establezca el parámetro query_type en hybrid. El valor predeterminado es ann (vecino más próximo aproximado).

SDK de Python

# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
    )

REST API

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

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

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

# Query Vector Search index with `query_vector`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query Vector Search index with `query_text`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

En el ejemplo de código siguiente se muestra cómo consultar un índice mediante una entidad 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": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint (TODO: link), then you need to have additional authorization details to invoke the serving endpoint
# export EMBEDDING_MODEL_SERVING_ENDPOINT_ID=...
# export AUTHORIZATION_DETAILS="$AUTHORIZATION_DETAILS"',{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/'"$EMBEDDING_MODEL_SERVING_ENDPOINT_ID"'","actions": ["query_inference_endpoint"]}'

# 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 '"')

# Query Vector Search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query Vector Search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

SQL

Para usar esta función de IA, consulte vector_search función.

Uso de filtros en consultas

Una consulta puede definir filtros basados en cualquier columna de la tabla Delta. similarity_search devuelve solo las filas que coinciden con los filtros especificados. Se admiten los siguientes filtros:

Consulte los ejemplos de código siguientes:

SDK de Python

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title": ["Ares", "Athena"]},
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title OR id": ["Ares", "Athena"]},
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title NOT": "Hercules"},
    num_results=2
    )

REST API

Vea POST /api/2.0/vector-search/indexes/{index_name}/query.

Cuadernos de ejemplo

En los ejemplos de esta sección se muestra el uso del SDK de Python del vector de búsqueda.

Ejemplos de LangChain

Consulte Uso de LangChain con Vector de búsqueda de Mosaic AI para usar Vector de búsqueda de Mosaic AI en integración con paquetes LangChain.

En el cuaderno siguiente se muestra cómo convertir los resultados de búsqueda de similitud en documentos LangChain.

Vector de búsqueda con el cuaderno del SDK de Python

Obtener el cuaderno

Ejemplos de cuadernos para llamar a un modelo de inserción

En los siguientes cuadernos se muestra cómo configurar un punto de conexión de servicio de modelo de IA de Mosaic para la generación de inserciones.

Llamada a un modelo de inserciones de OpenAI mediante el cuaderno de modelos de IA de Mosaic

Obtener el cuaderno

Llamada a un modelo de inserciones de GTE mediante el cuaderno de Mosaic AI Model Serving

Obtener el cuaderno

Registro y servicio de un cuaderno de modelos de inserción del software de código abierto

Obtener el cuaderno