Adición de un recurso de índice de AI Search a una aplicación de Databricks

Agregue índices de AI Search como recursos de Databricks Apps para habilitar la búsqueda semántica y la recuperación basada en similitud en las aplicaciones. Los índices de BÚSQUEDA de IA almacenan y consultan incrustaciones de vectores de alta dimensionalidad, lo que potencia los casos de uso, como la generación aumentada por recuperación (RAG), la búsqueda semántica y los sistemas de recomendaciones.

Databricks AI Search se conocía anteriormente como Databricks Vector Search.

Requisitos de privilegios

Para acceder a un índice de búsqueda de IA, el principal de servicio de la aplicación debe tener el privilegio USE CATALOG en el catálogo principal, el privilegio USE SCHEMA en el esquema principal y el privilegio SELECT en el índice. Al agregar el recurso de índice, Azure Databricks concede automáticamente estos privilegios a la entidad de servicio de la aplicación.

Para que esta concesión automática se realice correctamente, uno de los siguientes valores debe ser verdadero para cada privilegio.

• Para USE CATALOG: todos los usuarios de la cuenta tienen el privilegio USE CATALOG en el catálogo, o todos tienen el privilegio MANAGE en el catálogo.
• Para USE SCHEMA: todos los usuarios de la cuenta tienen el privilegio USE SCHEMA en el esquema, o todos tienen el privilegio MANAGE en el esquema.
• Para SELECT: todos los usuarios de la cuenta tienen el privilegio SELECT en el índice, o todos tienen el privilegio MANAGE en el índice.

Si el índice utiliza un modelo de incrustación gestionado por Databricks en un endpoint de throughput provisionado o de servicio personalizado, también añade ese endpoint como recurso de aplicación con permiso Can query, además de cualquier endpoint de embedding de consulta separado (model_endpoint_name_for_query). get_index() lee estos endpoints y falla sin acceso. Los endpoints de las APIs de Foundation Model de pago por token, como databricks-gte-large-en, no necesitan un recurso de aplicación a menos que tu cuenta restrinja los modelos Foundation con permisos del Catálogo de Unity, en cuyo caso el principal de servicio necesita EXECUTE en el modelo. Consulte Configurar una entidad de servicio.

Para obtener más información sobre cómo consultar índices de BÚSQUEDA de IA con estos permisos, consulte Consulta de un índice de BÚSQUEDA de IA.

Consulte Referencia de privilegios de Unity Catalog.

Adición de un recurso de índice de AI Search

Antes de agregar un índice de AI Search como recurso, revise los requisitos previos de los recursos de la aplicación.

1. En la sección Recursos de la aplicación al crear o editar una aplicación, haga clic en + Agregaríndice de búsqueda de vectores>.
2. Elija un índice de Búsqueda con IA entre los índices disponibles en el área de trabajo. El índice ya debe existir en el catálogo de Unity.
3. Seleccione el nivel de permiso de la aplicación:
   • Puede seleccionar: Concede permiso a la aplicación para consultar el índice de búsqueda de IA para búsquedas de similitud. Corresponde al SELECT privilegio.
4. (Opcional) Especifique una clave de recurso personalizada, que es la forma en que hace referencia al índice en la configuración de la aplicación. La clave predeterminada es vector-search-index.

Variables de entorno

Al implementar una aplicación con un recurso de índice de AI Search, Azure Databricks expone el nombre completo de tres niveles a través de variables de entorno a las que puede hacer referencia mediante el campo valueFrom.

Configuración de ejemplo:

env:
  - name: VECTOR_SEARCH_INDEX
    valueFrom: vector-search-index # Use your custom resource key if different

Utilizando el índice en su aplicación:

Consulta el índice con el databricks-ai-search SDK de Python y las credenciales del principal de servicio de la app. Cuando el espacio de trabajo cumple con los requisitos de la URL de índice, el SDK envía consultas a la URL de índice, que puede usar la capacidad extra de un punto final con un objetivo de consultas por segundo (QPS). Las consultas enviadas con WorkspaceClient().vector_search_indexes.query_index utilizan la URL de consulta de espacio de trabajo, que está limitada a unas pocas decenas de QPS.

Añade la versión 0.81 o superior de databricks-ai-search a las dependencias de tu app. Consulte Administración de dependencias para una aplicación de Databricks.

import os
from databricks.ai_search.client import AISearchClient

# DATABRICKS_HOST can be set without a scheme, and the SDK requires one.
host = os.environ["DATABRICKS_HOST"]
if not host.startswith(("https://", "http://")):
    host = f"https://{host}"

# Pass the app's service principal credentials so queries use the index URL.
client = AISearchClient(
    workspace_url=host,
    service_principal_client_id=os.environ["DATABRICKS_CLIENT_ID"],
    service_principal_client_secret=os.environ["DATABRICKS_CLIENT_SECRET"],
)

# Create the index object when the app starts and reuse it for every query.
index = client.get_index(index_name=os.environ["VECTOR_SEARCH_INDEX"])

results = index.similarity_search(
    query_text="What is machine learning?",  # Or pass query_vector for self-managed embeddings.
    columns=["id", "text"],
    num_results=10,
)

# Each row lists values in the same order as the manifest columns.
column_names = [column["name"] for column in results["manifest"]["columns"]]
for row in results["result"]["data_array"]:
    print(dict(zip(column_names, row)))

Sustituye columns por las columnas de tu índice. Para alcanzar un mayor rendimiento, establece un QPS objetivo en un punto final estándar.

Para obtener más información, consulte Uso de variables de entorno para acceder a los recursos.

Eliminación de un recurso de índice de AI Search

Al quitar un recurso de índice de AI Search de una aplicación, la entidad de servicio de la aplicación pierde el acceso al índice. El propio índice permanece sin cambios y sigue estando disponible para otros usuarios y aplicaciones que tienen los permisos adecuados.

procedimientos recomendados

Tenga en cuenta lo siguiente al trabajar con recursos de índice de Búsqueda de IA:

• Asegúrese de que la entidad de servicio de la aplicación tiene acceso a orígenes de datos subyacentes si el índice hace referencia a otras tablas.
• Supervise el rendimiento de las consultas y ajuste la configuración del índice o la inserción de modelos si los tiempos de respuesta se degradan.
• Considere las programaciones de actualización de índices para mantener las incrustaciones sincronizadas con los datos de origen.
• Utilice las métricas de similitud adecuadas (coseno, euclidiana, producto punto) en función del modelo de incrustación.
• Un endpoint puede estar en línea antes de que sus índices estén listos para ser consultados. Para comprobar un índice sin bloqueo, lea ready y detailed_state en el campo status que devuelve index.describe(). Para esperar un índice, llame a index.wait_until_ready(), que sondea cada 30 segundos y genera un error si el índice se desconecta o pasa el tiempo de espera.