Compartir a través de

Implementación de un agente para aplicaciones de IA generativas

En este artículo se muestra cómo implementar el agente de IA en Mosaic AI Model Serving mediante la deploy() función de la API de Python de Agent Framework.

La implementación de agentes en Mosaic AI Model Serving proporciona las siguientes ventajas:

  • Model Serving administra el escalado automático, el registro, el control de versiones y el control de acceso, lo que le permite centrarse en el desarrollo de agentes de calidad.
  • Los expertos en la materia pueden usar la aplicación de revisión para interactuar con el agente implementado y proporcionar comentarios que puede incorporar en la supervisión y las evaluaciones.
  • Puede supervisar el agente mediante la ejecución de la evaluación en el tráfico activo. Aunque el tráfico de usuario no incluirá la verdad del suelo, los jueces de LLM (y la métrica personalizada que ha creado) realizan una evaluación no supervisada.

Requisitos

  • MLflow 2.13.1 o posterior para implementar agentes mediante la deploy() API de databricks.agents.

  • Registro de un agente de IA en el catálogo de Unity. Consulte Registro del agente en Unity Catalog.

  • La implementación de agentes desde fuera de un cuaderno de Databricks requiere databricks-agents SDK versión 0.12.0 o posterior.

  • El creador del punto de conexión (el usuario que implementa el agente) debe tener CREATE VOLUME permisos en el esquema del catálogo de Unity seleccionado para almacenar las tablas de inferencia en el momento de la implementación. Esto garantiza que se puedan crear tablas de evaluación y registro pertinentes en el esquema. Consulte Habilitación y deshabilitación de tablas de inferencia.

  • Instale el databricks-agents SDK.

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

Implementación de un agente mediante deploy()

Utiliza deploy() para implementar tu agente en un endpoint de servicio de modelo.

from databricks import agents

deployment = agents.deploy(uc_model_name, uc_model_info.version)

# Retrieve the query endpoint URL for making API requests
deployment.query_endpoint

La deploy() función realiza las siguientes acciones de forma predeterminada:

Acción deploy() Descripción
Crear puntos de conexión de servicio de modelos de CPU Hace que el agente sea accesible para las aplicaciones orientadas al usuario al darle servicio a través de un punto de conexión de servicio del modelo.
Generar credenciales temporales para la entidad de servicio Databricks proporciona automáticamente credenciales de corta duración con permisos mínimos para acceder a los recursos administrados por Databricks definidos al registrar el modelo.
Databricks comprueba que el propietario del punto de conexión tiene los permisos necesarios antes de emitir las credenciales para evitar la elevación de privilegios y el acceso no autorizado. Consulte Autenticación para recursos dependientes.
Si su agente depende de recursos no gestionados por Databricks, puede pasar variables de entorno que contengan secretos a deploy(). Consulte Configurar el acceso a recursos desde puntos de conexión de servicio de modelos.
Habilitación de la aplicación de revisión Permite a las partes interesadas interactuar con el agente y proporcionar comentarios. Consulte Utilice la aplicación de revisión para las revisiones humanas de una aplicación de IA generativa (MLflow 2).
Habilitación de tablas de inferencia Supervise y depure los agentes mediante el registro de entradas y respuestas de solicitudes.
Registrar solicitudes de API REST y revisar comentarios de la aplicación Registra las solicitudes de API y los comentarios en una tabla de inferencia.
  • Cree un modelo de comentarios para aceptar y registrar comentarios de la aplicación de revisión.
  • Este modelo se sirve en el mismo modelo de CPU que sirve el punto de conexión que el agente implementado.
Habilitación de la supervisión de Lakehouse para Gen AI (beta) Requiere la inscripción en la beta de Supervisión de Lakehouse para la IA generativa. La supervisión básica se habilita automáticamente para los seguimientos de agentes implementados.
Habilitación del seguimiento y la supervisión en tiempo real con MLflow 3 (beta) Requiere registrarse en la versión beta de Lakehouse Monitoring para Gen AI y utilizar MLflow 3.0 o una versión superior.
Además de registrar seguimientos de agentes implementados en tablas de inferencia para el almacenamiento a largo plazo, Databricks registra los seguimientos de los agentes desplegados en un experimento de MLflow para lograr visibilidad en tiempo real. Esto reduce las latencias de supervisión y depuración.
  • Al crear un nuevo punto de conexión a través de agents.deploy(), la supervisión y el seguimiento se configuran para leer y escribir desde el experimento de MLflow actualmente activo.
    • Configure el experimento para un punto de conexión determinado llamando mlflow.set_experiment() a antes de invocar agents.deploy() para crear el punto de conexión.
  • Los seguimientos de todos los agentes servidos en el punto de conexión (incluidos los agentes añadidos a este a través de llamadas posteriores a agents.deploy()) se escriben en este experimento.
  • La monitorización calcula las métricas de calidad en los seguimientos de este experimento.
  • De forma predeterminada, solo se configuran las métricas de supervisión básicas. Para agregar jueces de LLM y mucho más, consulte Configuración de la supervisión.

Nota:

La implementación puede tardar hasta 15 minutos en completarse. Las cargas JSON sin procesar tardan entre 10 y 30 minutos en llegar y los registros con formato se procesan desde las cargas sin procesar aproximadamente cada hora.

Personalización de la implementación

Para personalizar la implementación, puede pasar argumentos adicionales a deploy(). Por ejemplo, puede habilitar la escala en cero para los puntos de conexión inactivos pasando scale_to_zero_enabled=True. Esto reduce los costos, pero aumenta el tiempo para atender las consultas iniciales.

Para más parámetros, consulte API de Python de agentes de Databricks.

Recuperación y eliminación de implementaciones de agentes

Recuperar o administrar implementaciones de agente existentes:

from databricks.agents import list_deployments, get_deployments, delete_deployment

# Print all current deployments
deployments = list_deployments()
print(deployments)

# Get the deployment for a specific agent model name and version
agent_model_name = ""  # Set to your Unity Catalog model name
agent_model_version = 1  # Set to your agent model version
deployment = get_deployments(model_name=agent_model_name, model_version=agent_model_version)

# Delete an agent deployment
delete_deployment(model_name=agent_model_name, model_version=agent_model_version)

Autenticación para recursos dependientes

A menudo, los agentes de inteligencia artificial necesitan autenticarse en otros recursos para completar tareas. Por ejemplo, un agente puede necesitar acceder a un índice de búsqueda vectorial para consultar datos no estructurados.

El agente puede usar uno de los métodos siguientes para autenticarse en los recursos dependientes al servirlo detrás de un modelo de puntos de conexión de servicio:

  1. Paso de autenticación automática: declara las dependencias de recursos de Databricks para el agente durante el registro. Databricks puede aprovisionar, rotar y administrar automáticamente las credenciales de corta duración cuando el agente se implementa para acceder de forma segura a los recursos. Databricks recomienda usar el paso de autenticación automática siempre que sea posible.
  2. Autenticación en nombre del usuario: permite el uso de credenciales de usuario final del agente para acceder a las API rest y los recursos de Databricks.
  3. Autenticación Manual: especifica manualmente las credenciales de larga duración durante la implementación del agente. Utiliza la autenticación manual para los recursos de Databricks que no admiten el paso automático de autenticación, o para acceder a APIs externas.

Paso automático de autenticación

Modelo de servicio admite el paso de autenticación automática para los tipos más comunes de recursos de Databricks que utilizan los agentes.

Para habilitar el paso de autenticación automática, debes especificar las dependencias durante el registro del agente.

A continuación, al atender al agente detrás de un punto de conexión, Databricks realiza los pasos siguientes:

  1. Comprobación de permisos: Databricks comprueba que el creador del punto de conexión puede acceder a todas las dependencias especificadas durante el registro del agente.

  2. Creación y concesión de permisos de entidad de servicio: se crea una entidad de servicio para la versión del modelo del agente y se concede automáticamente acceso de lectura a los recursos del agente.

    Nota:

    La entidad de servicio generada por el sistema no aparece en las listas de la API ni de la interfaz de usuario. Si la versión del modelo del agente se quita del punto de conexión, también se elimina la entidad de servicio.

  3. Aprovisionamiento y rotación de credenciales: las credenciales de corta duración (un token de OAuth de M2M) para la entidad de servicio se insertan en el punto de conexión, lo que permite que el código del agente acceda a los recursos de Databricks. Databricks también rota las credenciales, asegurando que el agente tenga acceso continuo y seguro a los recursos dependientes.

Este comportamiento de autenticación es similar al comportamiento de "Ejecutar como propietario" para los paneles de Databricks: se accede a los recursos de nivel inferior, como las tablas del catálogo de Unity, mediante las credenciales de una entidad de servicio con acceso con privilegios mínimos a los recursos dependientes.

En la tabla siguiente se enumeran los recursos de Databricks que admiten el paso directo de autenticación automática y los permisos que debe tener el creador del punto de conexión al implementar el agente.

Nota:

Los recursos del catálogo de Unity también requieren USE SCHEMA en el esquema primario y USE CATALOG en el catálogo primario.

Tipo de recurso Permiso
SQL Warehouse Uso del punto de conexión
Modelo de puntos de conexión de servicio Puede consultar
Función de catálogo de Unity Ejecute
Espacio de Genie Can Run (Puede ejecutar)
Índice de búsqueda vectorial Can Use (Puede usar)
Tabla de catálogos de Unity SELECT

Autenticación en nombre del usuario

La autenticación en nombre del usuario permite a los desarrolladores del agente acceder a recursos confidenciales de Databricks mediante las credenciales de usuario final del agente. Para habilitar el acceso en nombre del usuario a los recursos, hay dos pasos:

  1. En el código del agente, asegúrese de que se accede a un recurso de Databricks con un cliente que tenga habilitada la autenticación en nombre del usuario. Consulte Implementación de un agente mediante la autenticación en nombre de usuario para obtener más información.
  2. En el momento del registro del agente, especifique los ámbitos de la API REST del usuario final (por ejemplo, vectorsearch.vector-search-endpoints) requeridos por el agente. Cuando el agente se implementa posteriormente, puede acceder a los recursos de Databricks en nombre del usuario final, pero solo mediante los ámbitos especificados. Para más información sobre los ámbitos de API, consulte Autenticación en nombre del usuario.

Autenticación manual

También puede proporcionar manualmente credenciales mediante variables de entorno basadas en secretos. La autenticación manual puede resultar útil en los siguientes escenarios:

  • El recurso dependiente no admite la transferencia automática de autenticación.
  • El agente tiene acceso a un recurso o API externo.
  • El agente debe usar credenciales distintas de las del implementador del agente.

Por ejemplo, para usar el SDK de Databricks en el agente para acceder a otros recursos dependientes, puede establecer las variables de entorno descritas en autenticación unificada de cliente de Databricks.

Supervisión de agentes implementados

Una vez implementado un agente en Databricks Model Serving, puede usar tablas de inferencia de AI Gateway para supervisar el agente implementado. Las tablas de inferencia contienen registros detallados de solicitudes, respuestas, seguimientos del agente y comentarios del agente de la aplicación de revisión. Esta información le permite depurar problemas, supervisar el rendimiento y crear un conjunto de datos dorado para la evaluación sin conexión.

Importante

Si MLflow 3 está instalado en el entorno de desarrollo al llamar a agents.deploy(), el punto de conexión registrará seguimientos de MLflow en tiempo real en el experimento de MLflow activado en el momento de la llamada a agents.deploy(). Puede llamar mlflow.set_experiment() para cambiar el experimento activo antes de la implementación.

Consulte los documentos de MLflow para obtener más información.

Consulte Depurar y observar su aplicación con seguimiento.

Obtención de aplicaciones implementadas

A continuación se muestra cómo obtener los agentes implementados.

from databricks.agents import list_deployments, get_deployments

# Get the deployment for specific model_fqn and version
deployment = get_deployments(model_name=model_fqn, model_version=model_version.version)

deployments = list_deployments()
# Print all the current deployments
deployments

Consulte la Python API de Databricks Agents.

Proporcionar comentarios sobre un agente implementado (experimental)

Al implementar el agente con agents.deploy(), el marco del agente también crea e implementa una versión de modelo de "comentarios" dentro del mismo punto de conexión, que puede consultar para proporcionar comentarios sobre la aplicación del agente. Las entradas de comentarios aparecen como filas de solicitud dentro de la tabla de inferencia asociada al puntos de conexión de servicio del agente.

Tenga en cuenta que este comportamiento es experimental: Databricks puede proporcionar una API de primera clase para proporcionar comentarios sobre un agente implementado en el futuro y la funcionalidad futura puede requerir la migración a esta API.

Entre las limitaciones de esta API se incluyen:

  • La API de comentarios carece de validación de entrada: siempre responde correctamente, incluso si se ha pasado una entrada no válida.
  • La API de comentarios requiere proporcionar el request_id generado por Databricks de la solicitud de punto de conexión del agente sobre la cual desea proporcionar comentarios. Para obtener databricks_request_id, incluya {"databricks_options": {"return_trace": True}} en su solicitud original al puntos de conexión de servicio del agente. A continuación, la respuesta del punto de conexión del agente incluirá la databricks_request_id asociada a la solicitud para que pueda volver a pasar ese identificador de solicitud a la API de comentarios al proporcionar comentarios sobre la respuesta del agente.
  • Los comentarios se recopilan mediante tablas de inferencia. Consulte limitaciones de la tabla de inferencia.

La solicitud de ejemplo siguiente proporciona retroalimentación sobre el punto de conexión del agente denominado "your-agent-endpoint-name", y supone que la DATABRICKS_TOKEN variable de entorno está configurada en un token de API REST de Databricks.

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '
      {
          "dataframe_records": [
              {
                  "source": {
                      "id": "user@company.com",
                      "type": "human"
                  },
                  "request_id": "573d4a61-4adb-41bd-96db-0ec8cebc3744",
                  "text_assessments": [
                      {
                          "ratings": {
                              "answer_correct": {
                                  "value": "positive"
                              },
                              "accurate": {
                                  "value": "positive"
                              }
                          },
                          "free_text_comment": "The answer used the provided context to talk about Lakeflow Declarative Pipelines"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

Puede pasar pares clave-valor adicionales o diferentes en los campos text_assessments.ratings y retrieval_assessments.ratings para proporcionar diferentes tipos de comentarios. En el ejemplo, la carga de comentarios indica que la respuesta del agente a la solicitud con el identificador 573d4a61-4adb-41bd-96db-0ec8cebc3744 era correcta, precisa y basada en el contexto obtenido por una herramienta de recuperación.

Recursos adicionales