Logs et enregistrement d’agents IA (Model Serving)

info

Pour les nouveaux cas d’utilisation, Databricks recommande de déployer des agents sur Databricks Apps pour un contrôle total sur le code d’agent, la configuration du serveur et le workflow de déploiement. Consultez Créer un agent IA et le déployer sur Databricks Apps. Pour migrer un agent existant, consultez Migrer un agent de Model Serving vers Databricks Apps.

Enregistrer les agents IA à l'aide d'agents personnalisés. L’enregistrement d’un agent constitue la base du processus de développement. La journalisation capture un « instantané » du code et de la configuration de l'agent afin que vous puissiez en évaluer la qualité.

Exigences

Créez un agent d'IA avant de le journaliser.

Databricks recommande d'installer la dernière version de databricks-sdk.

Python

% pip install databricks-sdk

Journalisation basée sur le code

Databricks recommande d'utiliser la fonctionnalité Modèles à partir du code de MLflow lors de la journalisation des agents.

Dans cette approche, le code de l'agent est capturé en tant que fichier Python et l'environnement Python est capturé en tant que liste de packages. Lorsque l'agent est déployé, l'environnement Python est restauré et le code de l'agent est exécuté pour charger l'agent en mémoire afin qu'il puisse être invoqué lorsque l'endpoint est appelé.

Vous pouvez associer cette approche à l'utilisation d'APIs de validation avant déploiement comme mlflow.models.predict() pour garantir que l'agent fonctionne de manière fiable lorsqu'il est déployé pour le service.

Pour voir un exemple de journalisation basée sur le code, consultez les notebooks d'exemple de création de ResponsesAgent.

Déduire la signature du modèle lors de l'enregistrement

remarque

Databricks vous recommande d'élaborer un agent en utilisant l'interface ResponsesAgent. Si vous utilisez ResponsesAgent, vous pouvez ignorer cette section ; MLflow déduit automatiquement une signature valide pour votre agent.

Si vous n'utilisez pas l'interface ResponsesAgent, vous devez utiliser l'une des méthodes suivantes pour spécifier le Model Signature MLflow de votre agent au moment de la journalisation :

1. Définir la signature manuellement
2. Utilisez les capacités d'inférence de signature de modèle de MLflow pour générer automatiquement la signature de l'agent en fonction d'un exemple d'entrée que vous fournissez. Cette approche est plus pratique que de définir manuellement la signature.

La signature de modèle MLflow valide les entrées et les sorties pour s'assurer que l'agent interagit correctement avec des outils en aval comme AI Playground et l'application d'examen. Il guide également d'autres applications sur la manière d'utiliser l'agent de manière efficace.

Les exemples LangChain et PyFunc ci-dessous utilisent l'inférence de signature de modèle.

Si vous souhaitiez plutôt définir explicitement une signature de modèle vous-même au moment de l'enregistrement, consultez MLflow docs - Comment enregistrer des modèles avec des signatures.

Journalisation basée sur le code avec LangChain

Les instructions et l'exemple de code suivants vous montrent comment enregistrer un agent avec LangChain.

1. Créez un notebook ou un fichier Python avec votre code. Pour cet exemple, le notebook ou le fichier est nommé agent.py. Le notebook ou le fichier doit contenir un agent LangChain, désigné ici par lc_agent.

2. Incluez mlflow.models.set_model(lc_agent) dans le notebook ou le fichier.

3. Créez un nouveau notebook pour servir de notebook Driver (appelé driver.py dans cet exemple).

4. Dans le notebook Driver, utilisez le code suivant pour exécuter agent.py et enregistrer les résultats dans un modèle MLflow :

   Python

   mlflow.langchain.log_model(lc_model="/path/to/agent.py", resources=list_of_databricks_resources)

   Le paramètre resources déclare les ressources gérées par Databricks nécessaires pour servir l'agent, telles qu'un index de recherche IA ou un endpoint de service qui sert un modèle de fondation. Pour plus d'informations, consultez Implémentez le passthrough d'authentification automatique.

5. Déployez le modèle. Consultez Déployer un agent pour les applications d'IA générative (Model Serving).

6. Lorsque l'environnement de service est chargé, agent.py est exécuté.

7. Lorsqu'une demande de service arrive, lc_agent.invoke(...) est appelé.

Python

import mlflow

code_path = "/Workspace/Users/first.last/agent.py"
config_path = "/Workspace/Users/first.last/config.yml"

# Input example used by MLflow to infer Model Signature
input_example = {
  "messages": [
    {
      "role": "user",
      "content": "What is Retrieval-augmented Generation?",
    }
  ]
}

# example using langchain
with mlflow.start_run():
  logged_agent_info = mlflow.langchain.log_model(
    lc_model=code_path,
    model_config=config_path, # If you specify this parameter, this configuration is used by agent code. The development_config is overwritten.
    artifact_path="agent", # This string is used as the path inside the MLflow model where artifacts are stored
    input_example=input_example, # Must be a valid input to the agent
    example_no_conversion=True, # Required
  )

print(f"MLflow Run: {logged_agent_info.run_id}")
print(f"Model URI: {logged_agent_info.model_uri}")

# To verify that the model has been logged correctly, load the agent and call `invoke`:
model = mlflow.langchain.load_model(logged_agent_info.model_uri)
model.invoke(example)

Journalisation basée sur le code avec PyFunc

Les instructions et l'exemple de code suivants vous montrent comment enregistrer un agent avec PyFunc.

1. Créez un notebook ou un fichier Python avec votre code. Pour cet exemple, le notebook ou le fichier est nommé agent.py. Le Notebook ou le fichier doit contenir une classe PyFunc, nommée PyFuncClass.

2. Incluez mlflow.models.set_model(PyFuncClass) dans le notebook ou le fichier.

3. Créez un nouveau notebook pour servir de notebook Driver (appelé driver.py dans cet exemple).

4. Dans le notebook du driver, utilisez le code suivant pour exécuter agent.py et utilisez log_model() pour journaliser les résultats dans un modèle MLflow :

   Python

   mlflow.pyfunc.log_model(python_model="/path/to/agent.py", resources=list_of_databricks_resources)

   Le paramètre resources déclare les ressources gérées par Databricks nécessaires pour servir l'agent, telles qu'un index de recherche IA ou un endpoint de service qui sert un modèle de fondation. Pour plus d'informations, consultez Implémentez le passthrough d'authentification automatique.

5. Déployez le modèle. Consultez Déployer un agent pour les applications d'IA générative (Model Serving).

6. Lorsque l'environnement de service est chargé, agent.py est exécuté.

7. Lorsqu'une demande de service arrive, PyFuncClass.predict(...) est appelé.

Python

import mlflow
from mlflow.models.resources import (
    DatabricksServingEndpoint,
    DatabricksVectorSearchIndex,
)

code_path = "/Workspace/Users/first.last/agent.py"
config_path = "/Workspace/Users/first.last/config.yml"

# Input example used by MLflow to infer Model Signature
input_example = {
  "messages": [
    {
      "role": "user",
      "content": "What is Retrieval-augmented Generation?",
    }
  ]
}

with mlflow.start_run():
  logged_agent_info = mlflow.pyfunc.log_model(
    python_model=agent_notebook_path,
    artifact_path="agent",
    input_example=input_example,
    resources=resources_path,
    example_no_conversion=True,
    resources=[
      DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
      DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
    ]
  )

print(f"MLflow Run: {logged_agent_info.run_id}")
print(f"Model URI: {logged_agent_info.model_uri}")

# To verify that the model has been logged correctly, load the agent and call `invoke`:
model = mlflow.pyfunc.load_model(logged_agent_info.model_uri)
model.invoke(example)

Authentification pour les ressources Databricks

Les agents d'IA ont souvent besoin de s'authentifier auprès d'autres Ressources pour accomplir des tâches. Par exemple, un agent déployé pourrait avoir besoin d'accéder à un index de recherche AI pour query des données non structurées, ou d'accéder au Registre des prompts pour charger des prompts dynamiques.

L'authentification automatique transparente et l'authentification au nom de nécessitent une configuration lors de la journalisation de l'agent.

Enregistrer l'agent dans Unity Catalog

Avant de déployer l'agent, vous devez l'enregistrer dans Unity Catalog. L’enregistrement de l’agent le package en tant que modèle dans Unity Catalog. Par conséquent, vous pouvez utiliser les autorisations Unity Catalog pour l'autorisation des ressources de l'agent.

Python

import mlflow

mlflow.set_registry_uri("databricks-uc")

catalog_name = "test_catalog"
schema_name = "schema"
model_name = "agent_name"

model_name = catalog_name + "." + schema_name + "." + model_name
uc_model_info = mlflow.register_model(model_uri=logged_agent_info.model_uri, name=model_name)

Voir mlflow.register_model().

Ressources supplémentaires

• Ajouter des traces à un agent d'IA.
• Déployer un agent IA.