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

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

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.

Exigences d’autorisation pour les ressources dépendantes

Lors du déploiement d’un modèle avec des ressources dépendantes, le créateur du point de terminaison doit disposer des autorisations suivantes en fonction du type de ressource :

Type de ressource Autorisation
Sql Warehouse Utiliser le point de terminaison
Point de terminaison de service de modèle Peut demander
Unity Catalog, fonction Exécuter
Espace Génie Exécuter
Index de recherche vectorielle ReadVectorIndex
Table de catalogue Unity Peut lire

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.

Fonctionnalité Version mlflow minimum
Index de recherche vectorielle Nécessite mlflow 2.13.1 ou supérieur
Points de terminaison de service de modèle Nécessite mlflow 2.13.1 ou supérieur
Entrepôts SQL Nécessite mlflow 2.16.1 ou supérieur
Fonctionnalités de Unity Catalog Nécessite mlflow 2.16.1 ou supérieur

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