Déployer un agent pour une application d’IA générative

Cet article explique comment déployer votre agent IA à l’aide de l’API deploy() à partir de databricks.agents.

Spécifications

• MLflow 2.13.1 ou version ultérieure pour déployer des agents à l’aide de l’API deploy() de databricks.agents.

• Inscrire un agent IA dans Unity Catalog. Voir Inscrire la chaîne auprès de Unity Catalog.

• Installer le kit de développement logiciel (SDK) databricks-agents.

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

Déployer un agent à l’aide de deploy()

L’API deploy() effectue les opérations suivantes :

• Crée des points de terminaison de mise en service de modèle de processeurs pour votre agent qui peuvent être intégrés à votre application orientée utilisateur.
  • Les tables d’inférence sont activées sur ces points de terminaison de service de modèle. Consultez Tables d’inférence pour surveiller et déboguer des modèles.
    • Les informations d’authentification sont automatiquement transmises à toutes les ressources managées par Databricks requises par l’agent, comme spécifié lors de la journalisation du modèle. Databricks crée un principal de service qui a accès à ces ressources, puis le transmet automatiquement au point de terminaison. Consultez Authentification pour les ressources dépendantes.
    • Si vous avez des dépendances de ressources qui ne sont pas gérées par Databricks, par exemple à l’aide de Pinecone, vous pouvez transmettre des variables d’environnement avec des secrets à l’API deploy(). Consultez Configurer l’accès aux ressources à partir de points de terminaison de mise en service de modèles.
• Active l’application Review pour votre agent. L’application Review permet à vos parties prenantes de discuter avec l’agent et de donner des commentaires à l’aide de l’interface utilisateur de l’application Review.
• Enregistre chaque demande adressée à l’application de révision ou à l’API REST dans une table d’inférence. Les données journalisées incluent des requêtes, des réponses et des données de trace intermédiaires à partir du suivi MLflow.
• Crée un modèle de commentaires avec le même catalogue et le même schéma que l’agent que vous essayez de déployer. Ce modèle de commentaires est le mécanisme qui permet d’accepter les commentaires de l’application de révision et de le consigner dans une table d’inférence. Ce modèle est servi dans le même modèle de processeur servant le point de terminaison que votre agent(e) déployé(e). Étant donné que ce point de terminaison de service a des tables d’inférence activées, il est possible de consigner les commentaires de l’application de révision vers une table d’inférence.

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

Tables d’inférence améliorées par l’agent

Le deploy() crée trois tables d’inférence pour chaque déploiement afin de journaliser les requêtes et les réponses à destination et en provenance du point de terminaison de service de l'agent. Les utilisateurs peuvent s’attendre à ce que les données se trouvent dans le tableau des charges utiles dans l’heure qui suit l’interaction avec leur déploiement.

Les journaux de demande de charge utile et les journaux d’évaluation peuvent prendre plus de temps à remplir, mais ils sont en fin de compte dérivés du tableau des charges utiles brutes. Vous pouvez extraire vous-même les journaux de demande et d’évaluation de la table de charge utile. Les suppressions et mises à jour de la table de charge utile ne sont pas reflétées dans les journaux de demande de charge utile ou les journaux d’évaluation de charge utile.

L’exemple suivant montre le schéma de la table des journaux de requête.

Voici le schéma de la table des journaux d'évaluation.

Authentification pour les ressources dépendantes

Lors de la création du point de terminaison de service de modèle pour le déploiement de l’agent, Databricks vérifie que le créateur du point de terminaison dispose des autorisations nécessaires pour accéder à toutes les ressources dont dépend l’agent.

Pour les agents à saveur LangChain, les ressources dépendantes sont automatiquement déduites lors de la création et de la journalisation de l’agent. Ces ressources sont consignées dans le fichier resources.yaml dans l’artefact de modèle journalisé. Pendant le déploiement, databricks.agents.deploy crée automatiquement les jetons OAuth M2M requis pour accéder à ces dépendances de ressources déduites et communiquer avec ces dépendances de ressources déduites.

Pour les agents à saveur PyFunc, vous devez spécifier manuellement toutes les dépendances de ressources lors de la journalisation de l’agent déployé dans le paramètre resources. Consultez Spécifier des ressources pour l’agent PyFunc ou LangChain. Pendant le déploiement, databricks.agents.deploy crée un jeton OAuth M2M avec accès aux ressources spécifiées dans le paramètre resources, et le déploie sur l’agent déployé.

Authentification directe automatique

Le tableau suivant répertorie les fonctionnalités qui prennent en charge l’authentification directe automatique. L’authentification directe automatique utilise les informations d’identification du créateur de déploiement pour s’authentifier automatiquement sur les fonctionnalités prises en charge.

Authentification manuelle

Si vous disposez d’une ressource dépendante qui ne prend pas en charge l’authentification directe automatique ou si vous souhaitez utiliser des informations d’identification autres que celles du créateur de déploiement, vous pouvez fournir manuellement des informations d’identification à l’aide de variables d’environnement basées sur des secrets. Par exemple, si vous utilisez le kit de développement logiciel (SDK) Databricks dans votre agent pour accéder à d’autres types de ressources dépendantes, vous pouvez définir les variables d’environnement décrites dans l’authentification unifiée du client Databricks.

Obtenir les applications déployées

L’exemple suivant montre comment obtenir vos agents déployés.

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

Fournir des commentaires sur un agent déployé (expérimental)

Lorsque vous déployez votre agent avec agents.deploy(), l’infrastructure de l’agent crée et déploie également une version de modèle « feedback » dans le même point de terminaison, que vous pouvez interroger pour fournir des commentaires sur votre application agent. Les entrées de commentaires s’affichent sous forme de lignes de requête dans la table d’inférence associée à votre point de terminaison de service agent.

Notez que ce comportement est expérimental : Databricks peut fournir une API de première classe pour fournir des commentaires sur un agent déployé à l’avenir, et les fonctionnalités futures peuvent nécessiter la migration vers cette API.

Les limitations de cette API sont les suivantes :

• L’API de commentaires n’a pas de validation d’entrée : elle répond toujours correctement, même si elle a réussi une entrée non valide.
• L’API de commentaires nécessite la transmission de la requête de point de terminaison de l’agent générée par request_id Databricks sur laquelle vous souhaitez fournir des commentaires. Pour obtenir , databricks_request_idincluez {"databricks_options": {"return_trace": True}} dans votre demande d’origine le point de terminaison de service de l’agent. La réponse du point de terminaison de l’agent inclut ensuite l’associé databricks_request_id à la demande, afin que vous puissiez transmettre cet ID de demande à l’API de commentaires lors de la fourniture de commentaires sur la réponse de l’agent.
• Les commentaires sont collectés à l’aide de tables d’inférence. Consultez les limitations de la table d’inférence.

L’exemple de requête suivant fournit des commentaires sur le point de terminaison de l’agent nommé « your-agent-endpoint-name » et suppose que la DATABRICKS_TOKEN variable d’environnement est définie sur un jeton d’API REST 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

Vous pouvez transmettre des paires clé-valeur supplémentaires ou différentes dans les text_assessments.ratings champs et retrieval_assessments.ratings fournir différents types de commentaires. Dans l’exemple, la charge utile de commentaires indique que la réponse de l’agent à la demande avec l’ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 était correcte, précise et ancrée dans le contexte récupéré par un outil de récupération.

Ressources supplémentaires

• Qu’est-ce que l’évaluation de l’agent Mosaic AI ?
• Obtenir des commentaires sur la qualité d’une application agentique