Aller au contenu principal
Dernière mise à jour le

Migrer un agent de Model Serving vers Databricks Apps

Migrez un agent IA existant d'un endpoint Model Serving vers Databricks Apps.

Databricks recommande de créer des agents sur Databricks Apps car cela offre les avantages suivants par rapport à Model Serving :

  • Itération rapide : itérez sur le code de l'agent et la configuration du déploiement en quelques secondes, avec le debugging local et une transparence totale sur les logs et le comportement de l'agent.
  • Gestion de version basée sur Git et CI/CD : Packagez et versionnez le code d'agent Python modulaire avec Git, et déployez-le avec des Declarative Automation Bundles.
  • **Prise en charge de l'assistant de codage IA** : utilisez les assistants de codage IA pour développer et migrer votre agent localement.
  • Agents asynchrones évolutifs : Créez des agents asynchrones avec des modèles asynchrones Python natifs pour une high concurrency plus élevée.
  • Personnalisation flexible du serveur : Utilisez n’importe quel framework ou pile, ajoutez des routes et des middlewares personnalisés, et configurez l’authentification des utilisateurs et des agents aux Endpoint et outils LLM.
  • Traçage MLflow : utilisez les modèles journalisés basés sur Git de MLflow et le traçage en temps réel pour surveiller le comportement de l'agent.
  • Interface utilisateur de chat intégrée : Les templates d'agent conversationnel incluent une interface de chat prête à l'emploi avec streaming, authentification et historique persistant.

Exigences​

Cloner le Template de migration​

Le template de migration fournit la base pour développer et déployer un agent sur Databricks Apps, ainsi que les fichiers de compétences d'agent qui enseignent aux assistants de code IA comment effectuer chaque étape de migration.

Clonez le Template et accédez au dossier :

Bash
git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-migration-from-model-serving

Le dossier Template contient :

  • AGENTS.mdInstructions pour les assistants de codage IA décrivant le workflow de migration
  • skills/: fichiers de compétences pour chaque étape de migration, exécutés séquentiellement par l'assistant
  • agent_server/: La structure de l'agent Databricks Apps cible avec du code de remplacement pour les gestionnaires @invoke() et @stream()
  • databricks.yml: Un template de configuration Declarative Automation Bundles avec des déclarations de ressources d'espace réservé

Migration assistée par l'IA (recommandé)​

La migration assistée par l'IA est la méthode recommandée pour utiliser ce Template. Un assistant de codage IA lit AGENTS.md et les fichiers de compétences et gère automatiquement les modifications de code et de configuration.

  1. Ouvrez le dossier Template dans un assistant de codage IA tel que Cursor, GitHub Copilot ou Claude.
  2. Demandez à l’assistant d’effectuer la migration en fournissant le nom de votre Endpoint :
Prompt
"Migrate my Model Serving endpoint `my-agent-endpoint` to a Databricks App"
  1. L'assistant génère un plan de migration et exécute chaque étape :

Capture d'écran d'un assistant de codage d'IA affichant une liste de tâches étape par étape pour migrer un agent de Model Serving vers Databricks Apps.

Migration manuelle​

Databricks recommande d'utiliser des assistants de codage IA pour effectuer la migration. Si vous préférez migrer sans assistant de codage IA, les étapes générales suivantes décrivent le processus.

important

Ces étapes sont un aperçu général et ne couvrent pas tous les scénarios de migration, tels que les agents à états, les compromis asynchrones/synchrones, l'accès aux artefacts Unity Catalog ou les configurations de ressources complexes.

Utilisez un assistant de codage IA pour aider à la migration ou consultez la compétencemigrate-from-model-serving dans le template pour plus d'informations détaillées.

Étape 1. Download les artefacts de l'agent​

  1. Obtenez le nom et la version du modèle à partir de votre endpoint :
Bash
databricks serving-endpoints get <endpoint-name> --output json
  1. Trouvez served_entities[0].entity_name (nom du modèle) et entity_version dans la réponse, puis download les artefacts :
Bash
DATABRICKS_CONFIG_PROFILE=<profile> uv run --no-project \
  --with "mlflow[databricks]>=2.15.0" \
  python3 << 'EOF'
import mlflow
mlflow.set_tracking_uri("databricks")
mlflow.artifacts.download_artifacts(
    artifact_uri="models:/<model-name>/<version>",
    dst_path="./original_mlflow_model"
)
EOF

Le dossier téléchargé contient :

  • MLmodel — déclarations de ressources pour l'agent d'origine
  • code/ — les fichiers sources Python de l’agent
  • artifacts/ — fichiers de configuration et invites optionnels
  • input_example.json — une requête d'échantillon pour les tests

Étape 2. Migrer le code de l'agent​

Copiez tous les fichiers Python de code/ vers agent_server/ et tous les artéfacts de artifacts/ vers agent_server/artifacts/.

Après avoir déplacé les fichiers, mettez à jour toutes les importations relatives et les chemins de fichiers codés en dur pour refléter la nouvelle structure de dossiers. Ensuite, réécrivez agent_server/agent.py pour utiliser le modèle présenté à l'étape 3.

Étape 3. Transformer le code de l'agent​

Sur Model Serving, les agents utilisent un ResponsesAgent basé sur une classe avec des méthodes predict() et predict_stream(). Sur Databricks Apps, le MLflow AgentServer dessert les fonctions de niveau module décorées avec @invoke() et @stream().

Lorsque vous migrez, choisissez l'un des modèles suivants :

  • Async (recommandé) : utilise Python async def et await pour traiter plusieurs requêtes simultanément. Pendant qu'une requête attend une réponse du LLM, le serveur traite d'autres requêtes.
  • Sync : Conserve les modèles Python synchrones de votre agent Model Serving. Choisissez cette option pour une migration minimale ou si votre code repose sur des bibliothèques uniquement synchrones.

La structure d'agent d'origine basée sur les classes.

Python
from mlflow.pyfunc import ResponsesAgent, ResponsesAgentRequest, ResponsesAgentResponse

class MyAgent(ResponsesAgent):
  def predict(self, request: ResponsesAgentRequest, params=None) -> ResponsesAgentResponse:
    # Synchronous implementation
    ...
    return ResponsesAgentResponse(output=outputs)

  def predict_stream(self, request: ResponsesAgentRequest, params=None):
    # Synchronous generator
    for chunk in ...:
      yield ResponsesAgentStreamEvent(...)

Étape 4. Configurez l'application.​

  1. Installer les dépendances. Ceci résout les dépendances dans pyproject.toml et crée le fichier uv.lock qui les pin pour des installations reproductibles :

    Bash
    uv sync

  2. Exécutez le script de démarrage rapide pour configurer l'authentification, créer l'Experimentation MLflow et générer le fichier .env :

    Bash
    uv run quickstart

Commit le fichier uv.lock généré afin que Databricks Apps installe les mêmes dépendances pinned lorsque vous déployez.

Étape 5. Tester localement​

start the serveur d'applications et vérifiez que l'agent répond correctement avant le déploiement.

Testez avec votre input_example.json original à l'aide de curl, puis déployez une fois que l'agent répond comme prévu.

Étape 6. Configurez les ressources​

Les agents Model Serving déclarent les ressources dans un fichier MLmodel. Les agents Databricks Apps déclarent les ressources dans le fichier de configuration databricks.yml à l'aide des Declarative Automation Bundles.

Consultez Authentification pour les agents IA.

Mappez vos déclarations de ressources au format équivalent de Declarative Automation Bundles :

Type de ressource MLmodel

databricks.yml équivalent

Autorisation

serving_endpoint

serving_endpoint

CAN_QUERY

lakebase

database

CAN_CONNECT_AND_CREATE

vector_search_index

uc_securable (securable_type : TABLE)

SELECT

function

uc_securable (securable_type : FUNCTION)

EXECUTE

table

uc_securable (securable_type : TABLE)

SELECT ou MODIFY

uc_connection

uc_securable (securable_type : CONNECTION)

USE_CONNECTION

sql_warehouse

sql_warehouse

CAN_USE

genie_space

genie_space

CAN_RUN

Type de ressource MLmodel

databricks.yml équivalent

Autorisation

serving_endpoint

serving_endpoint

CAN_QUERY

lakebase

database

CAN_CONNECT_AND_CREATE

vector_search_index

uc_securable (securable_type : TABLE)

SELECT

function

uc_securable (securable_type : FUNCTION)

EXECUTE

table

uc_securable (securable_type : TABLE)

SELECT ou MODIFY

uc_connection

uc_securable (securable_type : CONNECTION)

USE_CONNECTION

sql_warehouse

sql_warehouse

CAN_USE

genie_space

genie_space

CAN_RUN

Étape 7. Déployez l'agent à l'aide des Declarative Automation Bundles​

Déployez votre agent sur Databricks Apps à l'aide des Declarative Automation Bundles.

Avant le déploiement, vérifiez que votre structure de dossiers ressemble à ceci :

<working-directory>/
├── original_mlflow_model/    # Downloaded artifacts from Model Serving
│   ├── MLmodel
│   ├── code/
│   │   └── agent.py
│   ├── input_example.json
│   └── requirements.txt
│
└── <app-name>/               # New Databricks App (ready to deploy)
    ├── agent_server/
    │   ├── agent.py          # Migrated agent code
    │   └── ...
    ├── app.yaml
    ├── databricks.yml        # Bundle config with resources
    ├── pyproject.toml        # Python dependencies (uv)
    ├── uv.lock               # Pinned dependencies for reproducible installs
    └── ...
remarque

Databricks recommande uv (pyproject.toml + uv.lock) pour la gestion des dépendances Python, ce qui permet des installations plus rapides et des builds reproductibles. Lorsque votre application inclut un pyproject.toml et un uv.lock et aucun requirements.txt, Databricks Apps utilise uv pour installer les dépendances. requirements.txt reste pris en charge : si l'un est présent, il prévaut toujours et Databricks Apps utilise pip à la place. Consultez Meilleures pratiques pour les Databricks Apps et Définir les dépendances Python avec uv.

  1. Validez la configuration du bundle :

    Bash
    databricks bundle validate

  2. Déployez le bundle sur votre Workspace (bundle deploy upload les fichiers, mais ne start pas l'application) :

    Bash
    databricks bundle deploy

  3. start l’application :

    Bash
    databricks bundle run <app-resource-name>

Ressources supplémentaires​

Après la migration de votre agent, consultez :

Sur cette page