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 de Model Serving vers Databricks Apps.

Databricks recommande la création d'agents sur Databricks Apps, car elle offre les avantages suivants par rapport à Model Serving :

  • Itération rapide : Itérez sur le code d'agent et la configuration de déploiement en quelques secondes, avec debugging local et transparence totale des Logs et du comportement de l'agent.
  • **Gestion de versions basée sur Git et CI/CD** : Packagez et versionnez le code d'agent Python modulaire avec Git, et déployez-le avec des Bundles d'automatisation déclaratifs.
  • **Prise en charge des assistants 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 concurrence 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 LLM et aux outils.
  • 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 des agents.
  • Interface utilisateur de chat intégré : les Template d'agents conversationnels incluent une interface de chat prête à l'emploi avec le streaming, l'authentification et un historique persistant.

Exigences​

Clonez le Template de migration​

Le template de migration fournit l'ossature pour le développement et le déploiement d'un agent sur Databricks Apps, ainsi que les fichiers de compétences d'agent qui enseignent aux assistants de codage d'IA comment effectuer chaque étape de migration.

Cloner 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.md: instructions 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/: L'échafaudage de l'agent Databricks Apps cible avec du code d'espace réservé 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ée)​

La migration assistée par 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 du code et de la configuration.

  1. Ouvrez le dossier de template dans un assistant de code 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 IA affichant une liste de tâches pas à pas pour migrer un agent de Model Serving vers Databricks Apps.

Migration manuelle​

Databricks recommande l'utilisation d'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 offrent un aperçu général et ne couvrent pas tous les scénarios de migration, tels que les agents avec état, les compromis entre asynchrone et synchrone, l'accès aux artefacts Unity Catalog ou les configurations de ressources complexes.

Utilisez un assistant de codage IA pour faciliter la migration ou consultez la migrate-from-model-serving compétence dans le Template pour plus d'informations détaillées.

Étape 1. Download les artefacts d'agent​

  1. Obtenez le nom et la version du modèle 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 download contient :

  • MLmodel — déclarations de ressources pour l'agent d'origine
  • code/ — les fichiers source Python de l'agent
  • artifacts/ – fichiers et invites de configuration facultatifs
  • input_example.json — une demande d'échantillon pour les tests

Étape 2. Migrer le code d'agent​

Copier tous les fichiers Python de code/ vers agent_server/ et tous les artefacts 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 illustré à l'étape 3.

Étape 3. Transformer le code d'agent​

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

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

  • Asynchrone (recommandé) : utilise Python async def et await pour gérer plusieurs requêtes simultanément. Pendant qu’une requête attend une réponse de l’LLM, le serveur traite d’autres requêtes.
  • **Synchronisation** : Maintient les modèles Python synchrones à partir 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. Configurer 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'expérimentation MLflow et générer le fichier .env :

    Bash
    uv run quickstart

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

Étape 5. Tester localement​

start the app server et vérifiez que l'agent répond correctement avant de déployer.

Testez avec votre input_example.json d'origine en utilisant curl, puis déployez après que l'agent réponde comme prévu.

Étape 6. Configurer 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 en utilisant des Declarative Automation Bundles.

Consultez Authentification pour les agents IA.

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

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 (type_sécurisable : TABLE)

SELECT

function

uc_securable (type_sécurisable : FUNCTION)

EXECUTE

table

uc_securable (type_sécurisable : TABLE)

SELECT OU MODIFY

uc_connection

uc_securable (type_sécurisable : 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 (type_sécurisable : TABLE)

SELECT

function

uc_securable (type_sécurisable : FUNCTION)

EXECUTE

table

uc_securable (type_sécurisable : TABLE)

SELECT OU MODIFY

uc_connection

uc_securable (type_sécurisable : CONNECTION)

USE_CONNECTION

sql_warehouse

sql_warehouse

CAN_USE

genie_space

genie_space

CAN_RUN

Étape 7. Déployer l'agent à l'aide de Declarative Automation Bundles​

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

Avant le déploiement, vérifiez que la structure de vos dossiers est la suivante :

<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. Quand 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 a toujours la priorité et Databricks Apps utilise pip à la place. Veuillez consulter Bonnes pratiques pour 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 avoir migré votre agent, voir :

Sur cette page