Compartir a través de

Implementación de un agente para una aplicación de IA generativa

  • Artículo

Importante

Esta característica está en versión preliminar pública.

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

Requisitos

  • MLflow 2.13.1 o versiones posteriores para implementar agentes mediante la API de deploy() desde 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.

  • Instale el SDK de databricks-agents.

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

Implementación de un agente mediante deploy()

La función deploy() hace lo siguiente:

  • Crea puntos de conexión de servicio del modelo de CPU para el agente que se pueden integrar en la aplicación orientada al usuario.

    Nota:

    En el caso de los registros de respuesta de streaming, solo se agregan campos y seguimientos compatibles con ChatCompletion.

  • Habilite la Aplicación de revisión para el agente. La aplicación de revisión permite a las partes interesadas chatear con el agente y enviar comentarios mediante la interfaz de usuario de la aplicación de revisión.

  • Registra todas las solicitudes a la API de REST o la aplicación de revisión en una tabla de inferencia. Los datos registrados incluyen solicitudes de consulta, respuestas y datos de seguimiento intermedios del Seguimiento de MLflow.

  • Crea un modelo de comentarios con el mismo catálogo y esquema que el agente que intenta implementar. Este modelo de comentarios es el mecanismo que permite aceptar comentarios de la aplicación de revisión y registrarlos en una tabla de inferencia. Este modelo se sirve en el mismo modelo de CPU que sirve el punto de conexión que el agente implementado. Dado que este punto de conexión de servicio tiene habilitadas las tablas de inferencia, es posible registrar los comentarios de la aplicación de revisión en una tabla de inferencia.

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.


from databricks.agents import deploy
from mlflow.utils import databricks_utils as du

deployment = deploy(model_fqn, uc_model_info.version)

# query_endpoint is the URL that can be used to make queries to the app
deployment.query_endpoint

# Copy deployment.rag_app_url to browser and start interacting with your RAG application.
deployment.rag_app_url

Tablas de inferencia mejoradas por el agente

La deploy() crea tres tablas de inferencia para cada implementación para registrar solicitudes y respuestas hacia y desde el punto de conexión de servicio del agente. Los usuarios pueden esperar que los datos estén en la tabla de carga en un plazo de una hora después de interactuar con su implementación.

Los registros de solicitudes de carga y los registros de evaluación pueden tardar más tiempo en completarse, pero en última instancia se derivan de la tabla de carga sin procesar. Puede extraer los registros de solicitud y evaluación de la tabla de carga usted mismo. Las eliminaciones y actualizaciones de la tabla de carga no se reflejan en los registros de solicitudes de carga o en los registros de evaluaciones de carga.

Nota:

Si tiene habilitado firewall de Azure Storage, póngase en contacto con el equipo de cuentas de Databricks para habilitar las tablas de inferencia de los puntos de conexión.

Tabla Ejemplo de nombre de tabla del catálogo de Unity ¿Qué hay en cada tabla?
Carga útil {catalog_name}.{schema_name}.{model_name}_payload Cargas de solicitud y respuesta JSON sin formato
Registros de solicitudes de carga {catalog_name}.{schema_name}.{model_name}_payload_request_logs Solicitudes y respuestas con formato, seguimientos de MLflow
Registros de evaluación de carga {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Comentarios con formato, tal como se proporciona en la aplicación de revisión, para cada solicitud

A continuación se muestra el esquema de la tabla de registros de solicitudes.

Nombre de la columna Tipo Description
client_request_id Cadena Identificador de solicitud de cliente, normalmente null.
databricks_request_id Cadena Identificación de solicitud de Databricks.
date Date Fecha de solicitud.
timestamp_ms Largo Marca de tiempo en milisegundos.
timestamp Marca de tiempo Marca de tiempo de la solicitud.
status_code Entero Código de estado del punto de conexión.
execution_time_ms Largo Milisegundos de ejecución totales.
conversation_id Cadena Identificador de conversación extraído de los registros de solicitudes.
request Cadena La última consulta de usuario de la conversación del usuario. Esto se extrae de la solicitud de RAG.
response Cadena Última respuesta al usuario. Esto se extrae de la solicitud de RAG.
request_raw Cadena Representación de cadena de la solicitud.
response_raw Cadena Representación de cadena de la respuesta.
trace Cadena Representación de cadena de seguimiento extraída databricks_options de la estructura de respuesta.
sampling_fraction Doble Fracción de muestreo.
request_metadata Map[String, String] Mapa de metadatos relacionados con el punto de conexión de servicio del modelo asociado a la solicitud. Este mapa contiene el nombre del punto de conexión, el nombre del modelo y la versión del modelo que se usa para el punto de conexión.
schema_version Cadena Entero para la versión del esquema.

A continuación se muestra el esquema de la tabla de registro de evaluación.

Nombre de la columna Tipo Description
request_id Cadena Identificación de solicitud de Databricks.
step_id Cadena Derivado de la evaluación de recuperación.
source Estructura Campo de estructura que contiene la información sobre quién creó la evaluación.
timestamp Marca de tiempo Marca de tiempo de la solicitud.
text_assessment Estructura Campo de estructura que contiene los datos de los comentarios sobre las respuestas del agente de la aplicación de revisión.
retrieval_assessment Estructura Campo de estructura que contiene los datos de los comentarios sobre los documentos recuperados para una respuesta.

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 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 EXECUTE
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 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.

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

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 punto 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 pasar la solicitud de punto de conexión del agente generada request_id por Databricks en la que desea proporcionar comentarios. Para obtener , incluya databricks_request_id en la {"databricks_options": {"return_trace": True}}solicitud original al punto 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 comentarios sobre el punto de conexión del agente denominado "your-agent-endpoint-name" y supone que la DATABRICKS_TOKEN variable de entorno está establecida 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 Delta Live Tables"
                      }
                  ],
                  "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 text_assessments.ratings campos 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 en el contexto capturado por una herramienta de recuperación.

Recursos adicionales