Cómo 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 Databricks.
Puede crear y administrar componentes de vector de búsqueda, como un punto de conexión de vector de búsqueda y índices de vector de búsqueda mediante la interfaz de usuario, el SDK de Pythono la API de REST.
Requisitos
- Área de trabajo habilitada para Unity Catalog.
- Proceso sin servidor habilitado.
- La tabla de origen debe tener habilitada la fuente de distribución de datos modificados.
- 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.
En la barra lateral izquierda, haga clic en Proceso.
Haga clic en la pestaña Vector de búsqueda y haga clic en Crear.
Se abre el formulario Crear punto de conexión. Escriba un nombre para este punto de conexión.
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
Vea 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 que Databricks calcule las inserciones, debe configurar un punto de conexión de servicio de modelo para atender el modelo. Consulte Creación de un modelo de base que atiende los puntos de conexión 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.
Nota:
La inicialización del índice de búsqueda vectorial 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 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
En la barra lateral izquierda, haga clic en Catálogo para abrir la interfaz de usuario del Explorador de catálogos.
Vaya a la tabla Delta que desea usar.
Haga clic en el botón Crear en la esquina superior derecha y seleccione índice de vector de búsqueda en el menú desplegable.
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: Seleccione el punto de conexión de servicio del modelo que desea usar.
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.
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. El desencadenado es más rentable, pero debe iniciarse manualmente mediante la API. Para Continua y Desencadenado, la actualización solo es datos incrementales: que han cambiado desde que se procesa la última sincronización.
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 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
Vea 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 modo de sincronización Desencadenado, puede usar el SDK de Python o la API de REST para iniciar la sincronización.
Sdk de Python
index.sync()
API de REST
Vea API de 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]
}
])
API de REST
Vea API de REST (POST /api/2.0/vector-search/indexes).
Consultar un punto de conexión de vector de búsqueda
Solo puede consultar el punto de conexión de vector de búsqueda mediante el SDK de Python o la API de REST.
Nota:
Si el usuario que consulta el punto de conexión no es el propietario del índice de vector de búsqueda, el usuario debe tener los siguientes privilegios de UC:
- USE CATALOG en el catálogo que contiene el índice de vector de búsqueda.
- USE SCHEMA en el esquema que contiene el índice de vector de búsqueda.
- SELECT en el índice de vector de búsqueda.
Sdk de Python
results = index.similarity_search(
query_text="Greek myths",
columns=["id", "text"],
num_results=2
)
results
API de REST
Vea POST /api/2.0/vector-search/indexes/{index_name}/query.
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:
| Operador de filtro | Comportamiento | Ejemplos |
|---|---|---|
NOT |
Niega el filtro. La clave debe terminar con "NOT". Por ejemplo, "color NOT" con el valor "rojo" coincide con documentos donde el color no es rojo. | {"id NOT": 2} {“color NOT”: “red”} |
< |
Comprueba si el valor del campo es menor que el valor de filtro. La clave debe terminar con " <". Por ejemplo, "precio <" con el valor 100 coincide con documentos en los que el precio es inferior a 100. | {"id <": 200} |
<= |
Comprueba si el valor del campo es menor o igual que el valor de filtro. La clave debe terminar con " <=". Por ejemplo, "precio <=" con el valor 100 coincide con documentos donde el precio es menor o igual que 100. | {"id <=": 200} |
> |
Comprueba si el valor del campo es mayor que el valor de filtro. La clave debe terminar con " >". Por ejemplo, "precio >" con el valor 100 coincide con documentos donde el precio es mayor que 100. | {"id >": 200} |
>= |
Comprueba si el valor del campo es mayor o igual que el valor del filtro. La clave debe terminar con " >=". Por ejemplo, "precio >=" con el valor 100 coincide con documentos donde el precio es mayor o igual que 100. | {"id >=": 200} |
OR |
Comprueba si el valor del campo coincide con cualquiera de los valores de filtro. La clave debe contener OR para separar varias subclaves. Por ejemplo, color1 OR color2 con el valor ["red", "blue"] coincide con documentos donde color1 es red o color2 es blue. |
{"color1 OR color2": ["red", "blue"]} |
LIKE |
Coincide con cadenas parciales. | {"column LIKE": "hello"} |
| No se ha especificado ningún operador de filtro | El filtro busca una coincidencia exacta. Si se especifican varios valores, coincide con cualquiera de los valores. | {"id": 200} {"id": [200, 300]} |
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
)
API de REST
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 para Vector de búsqueda.
Ejemplos de LangChain
Consulte Uso de LangChain con Vector de búsqueda de Databricks para usar el Vector de búsqueda de Databricks como 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
Ejemplos de cuadernos para llamar a un modelo de inserción
En los cuadernos siguientes se muestra cómo configurar un punto de conexión de servicio de modelos de Databricks para la generación de inserciones.
Llamada a un modelo de inserciones de OpenAI mediante el cuaderno de servicio de modelos de Databricks
Llamada a un modelo de inserciones de BGE mediante el cuaderno de servicio de modelos de Databricks
Registro y servicio de un cuaderno de modelos de inserción del software de código abierto
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de