Implementación de un agente para una aplicación de IA generativa
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 API deploy() de databricks.agents.
Requisitos
MLflow 2.13.1 o versiones posteriores para implementar agentes mediante la API de
deploy()desdedatabricks.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 API 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.
- Las tablas de inferencia están habilitadas en estos puntos de conexión de servicio del modelo. Consulte Tablas de inferencia para supervisar y depurar modelos.
- Las credenciales de autenticación se pasan automáticamente a todos los recursos administrados por Databricks que requiere el agente como se especifica al registrar el modelo. Databricks crea una entidad de servicio que tiene acceso a estos recursos y la pasa automáticamente al punto de conexión. Consulte Autenticación para recursos dependientes.
- Si tiene dependencias de recursos que no están administradas por Databricks, por ejemplo, con Pinecone, puede pasar variables de entorno con secretos a la API de
deploy(). Consulte Configurar el acceso a recursos desde puntos de conexión de servicio de modelos.
- Las tablas de inferencia están habilitadas en estos puntos de conexión de servicio del modelo. Consulte Tablas de inferencia para supervisar y depurar modelos.
- 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
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.
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