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 de la cadena en el catálogo de Unity.

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

Requisitos de permisos para los recursos dependientes

Al implementar un modelo con recursos dependientes, el creador del punto de conexión debe tener los permisos siguientes en función del tipo de recurso:

Tipo de recurso Permiso
Sql Warehouse Uso del punto de conexión
Punto de conexión de servicio de modelos Puede consultar
Función de catálogo de Unity Ejecutar
Espacio de Genie Ejecutar
Índice de búsqueda vectorial ReadVectorIndex
Tabla de catálogos de Unity Puede leer

Autenticación para recursos dependientes

Al crear el punto de conexión del modelo para la implementación del agente, Databricks verifica que el creador del punto de conexión tiene permisos para acceder a todos los recursos de los que depende el agente.

En el caso de los agentes personalizados con LangChain, los recursos dependientes se deducen de manera automática durante la creación y el registro del agente. Esos recursos se registran en el archivo resources.yaml en el artefacto del modelo registrado. Durante la implementación, databricks.agents.deploy crea de manera automática los tokens de OAuth de M2M necesarios para acceder a estas dependencias de recursos inferidas y comunicarse con ellas.

En el caso de los agentes personalizados con PyFunc, debe especificar manualmente las dependencias de recursos durante el registro del agente implementado en el parámetro resources. Consulte Especificar recursos para el agente PyFunc o LangChain. Durante la implementación, databricks.agents.deploy crea un token de OAuth de M2M con acceso a los recursos especificados en el parámetro resources y lo implementa en el agente implementado.

Paso automático de autenticación

En la tabla siguiente se enumeran las características que admiten el paso automático de autenticación. El paso automático de autenticación usa las credenciales del creador de la implementación para autenticarse automáticamente con las características admitidas.

Característica Versión mínima mlflow
Índices de vector de búsqueda Requiere mlflow 2.13.1 o superior
Puntos de conexión del servicio de modelos Requiere mlflow 2.13.1 o superior
Almacenes de SQL Requiere mlflow 2.16.1 o superior
Funciones de catálogo de Unity Requiere mlflow 2.16.1 o superior

Autenticación manual

Si tiene un recurso dependiente que no admite el paso automático de autenticación, o si desea usar credenciales distintas de las del creador de la implementación, puede proporcionar manualmente credenciales mediante variables de entorno basadas en secretos. Por ejemplo, si usa el SDK de Databricks en el agente para acceder a otros tipos de recursos dependientes, puede establecer las variables de entorno descritas en Autenticación unificada del 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_options": {"return_trace": True}} en la databricks_request_idsolicitud 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, de modo 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