Partager via

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

  • Article

Important

Cette fonctionnalité est disponible en préversion publique.

Cet article explique comment déployer votre agent IA à l’aide de la deploy() fonction à partir de l’API Python Agent Framework.

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. Consultez Inscrire l’agent au catalogue Unity.

  • Le déploiement d’agents en dehors d’un notebook Databricks nécessite databricks-agents SDK version 0.12.0 ou ultérieure.

  • 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()

La fonction 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.

    Remarque

    Pour les journaux de réponses en continu, seuls les champs et traces compatibles avec ChatCompletion sont agrégés.

  • Active l’application Review pour votre agent. L’application de révision permet aux parties prenantes de discuter avec l’agent et de donner des commentaires à l’aide de l’interface utilisateur de l’application de révision.

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

Remarque

Le déploiement peut prendre jusqu’à 15 minutes. Les charges utiles JSON brutes mettent 10 à 30 minutes à arriver et les journaux mis en forme sont traités à partir des charges utiles brutes environ toutes les heures.


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.

Remarque

Si le pare-feu du Stockage Azure est activé, contactez l’équipe du compte Databricks afin d’activer les tables d’inférence pour vos points de terminaison.

Table Exemple de nom de table d’Unity Catalog Qu’est-ce qui se trouve dans chaque table ?
Charge utile {catalog_name}.{schema_name}.{model_name}_payload Charges utiles brutes de requête et de réponse JSON
Journaux des requêtes de charge utile {catalog_name}.{schema_name}.{model_name}_payload_request_logs Requête et réponses mises en forme, traces MLflow
Journaux d’évaluation de la charge utile {catalog_name}.{schema_name}.{model_name}_payload_assessment_logs Commentaires mis en forme, comme fournis dans l’application Review, pour chaque requête

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

Nom de la colonne Type Description
client_request_id Chaîne ID de requête client, généralement null.
databricks_request_id Chaîne ID de requête Databricks.
date Date Date de la demande.
timestamp_ms Long Timestamp en millisecondes.
timestamp Timestamp Horodatage de la demande.
status_code Integer Code d’état du point de terminaison.
execution_time_ms Long Nombre total de millisecondes d’exécution.
conversation_id Chaîne ID de conversation extrait des journaux de requête.
request Chaîne Dernière requête utilisateur depuis la conversation de l’utilisateur. Ceci est extrait de la requête RAG.
response Chaîne Dernière réponse à l’utilisateur. Ceci est extrait de la requête RAG.
request_raw Chaîne Représentation de la chaîne de la requête.
response_raw Chaîne Représentation de la chaîne de la réponse.
trace Chaîne Représentation sous forme de chaîne de trace extraite de databricks_options du Struct de réponse.
sampling_fraction Double Fraction d’échantillonnage.
request_metadata Map[String, String] Mappage des métadonnées liées au point de terminaison de mise en service de modèle associé à la requête. Ce mappage contient le nom du point de terminaison, le nom du modèle et la version du modèle utilisées pour votre point de terminaison.
schema_version Chaîne Entier pour la version du schéma.

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

Nom de la colonne Type Description
request_id Chaîne ID de requête Databricks.
step_id Chaîne Dérivé de l’évaluation de la récupération.
source Struct Champ de struct contenant les informations sur le créateur de l’évaluation.
timestamp Timestamp Horodatage de la demande.
text_assessment Struct Champ de struct contenant les données des commentaires sur les réponses de l’agent à partir de l’application d’évaluation.
retrieval_assessment Struct Champ de struct contenant les données des commentaires sur les documents récupérés pour une réponse.

Authentification pour les ressources dépendantes

Les agents IA doivent souvent s’authentifier auprès d’autres ressources pour effectuer des tâches. Par exemple, un agent peut avoir besoin d’accéder à un index Recherche vectorielle pour interroger des données non structurées.

Votre agent peut utiliser l’une des méthodes suivantes pour s’authentifier auprès des ressources dépendantes quand vous le placez derrière un point de terminaison de mise en service de modèles :

  1. Transmission automatique d’authentification : déclarez les dépendances de ressources Databricks pour votre agent lors de la journalisation. Databricks peut provisionner, faire pivoter et gérer automatiquement des informations d’identification de courte durée lorsque votre agent est déployé pour accéder en toute sécurité aux ressources. Databricks recommande d’utiliser le passthrough d’authentification automatique si possible.
  2. Authentification manuelle: spécifiez manuellement les informations d’identification de longue durée pendant le déploiement de l’agent. Utilisez l’authentification manuelle pour les ressources Databricks qui ne prennent pas en charge la transmission directe d’authentification automatique ou pour l’accès à l’API externe.

Authentification directe automatique

Model Serving prend en charge la passe d’authentification automatique pour les types de ressources Databricks les plus courants utilisés par les agents.

Pour activer le passage d’authentification automatique, vous devez spécifier des dépendances lors de la connexion de l’agent.

Ensuite, lorsque vous servez l’agent derrière un point de terminaison, Databricks effectue les étapes suivantes :

  1. Vérification d’autorisation : Databricks vérifie que le créateur du point de terminaison peut accéder à toutes les dépendances spécifiées lors de la journalisation de l'agent.

  2. Création de principal de service et octrois: un principal de service est créé pour la version du modèle de l'agent et reçoit automatiquement l'accès en lecture aux ressources de l'agent.

    Remarque

    Le principal de service généré par le système n’apparaît pas dans les listes d’API ou d’interface utilisateur. Si la version du modèle d’agent est supprimée du point de terminaison, le principal de service est également supprimé.

  3. Provisionnement et rotation des informations d’identification : informations d’identification de courte durée (un jeton OAuth M2M M2M) pour le principal de service sont injectées dans le point de terminaison, ce qui permet au code de l’agent d’accéder aux ressources Databricks. Databricks fait également pivoter les informations d’identification, ce qui garantit que votre agent a continué d’accéder en toute sécurité aux ressources dépendantes.

Ce comportement d’authentification est similaire au comportement « Exécuter en tant que propriétaire » pour les tableaux de bord Databricks : les ressources en aval telles que les tables du catalogue Unity sont accessibles à l’aide des informations d’identification d’un principal de service disposant d’un accès avec des privilèges minimum aux ressources dépendantes.

Le tableau suivant répertorie les ressources Databricks qui prennent en charge la passe d’authentification automatique et les autorisations dont le créateur de point de terminaison doit disposer lors du déploiement de l’agent.

Remarque

Les ressources du catalogue Unity nécessitent également USE SCHEMA sur le schéma parent et USE CATALOG sur le catalogue parent.

Type de ressource Autorisation
SQL Warehouse Utiliser le point de terminaison
Points de terminaison de mise en service de modèles Peut demander
Unity Catalog, fonction EXÉCUTER
Espace Génie Peut exécuter
Index de recherche vectorielle Peut utiliser
Table de catalogue Unity SELECT

Authentification manuelle

Vous pouvez également fournir manuellement des informations d’identification en utilisant les variables d'environnement basées sur des secrets . L’authentification manuelle peut être utile dans les scénarios suivants :

  • La ressource dépendante ne prend pas en charge la passe d’authentification automatique.
  • L’agent accède à une ressource externe ou à une API.
  • L’agent doit utiliser des informations d’identification autres que celles de l’agent de déploiement.

Par exemple, pour utiliser le Kit de développement logiciel (SDK) Databricks dans votre agent pour accéder à d’autres 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 inclura ensuite le databricks_request_id associé à la demande pour que vous puissiez soumettre cet ID de demande à l'API de commentaires lorsque vous fournissez des retours 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