Migrace agenta z modelové obsluhy do aplikací Databricks

Migrujte existujícího agenta AI z koncového bodu služby Model Serving do služby Databricks Apps.

Databricks doporučuje vytvářet agenty v Databricks Apps, protože poskytuje následující výhody oproti poskytování modelu:

Rychlá iterace: Iterujte na kódu agenta a konfiguraci nasazení během několika sekund, s možností místního ladění a plnou viditelností do protokolů a chování agenta.
Verzování založené na Git a CI/CD: Balení a verzování modulárního Python agenta pomocí Gitu a nasazení pomocí deklarativních automatizačních balíčků.
Podpora pomocníka s kódováním AI: Využijte pomocníky pro kódování AI k vývoji a migraci agenta místně.
Škálovatelné asynchronní agenty: Vytvářejte asynchronní agenty s nativními asynchronními vzory Pythonu pro zajištění vyšší souběžnosti.
Přizpůsobení flexibilního serveru: Použijte libovolnou architekturu nebo zásobník, přidejte vlastní trasy a middleware a nakonfigurujte ověřování uživatelů a agentů do koncových bodů a nástrojů LLM.
Trasování MLflow: K monitorování chování agenta použijte protokolované modely založené na gitu MLflow a trasování v reálném čase.
Integrované uživatelské rozhraní chatu: Šablony konverzačních agentů zahrnují připravené rozhraní chatu se streamováním, ověřováním a trvalou historií.

Požadavky

Existující agent nasazený v koncovém bodu obsluhy modelu
Rozhraní příkazového řádku Databricks je nainstalované a ověřené. Viz Instalaci nebo aktualizaci rozhraní příkazového řádku Databricks.
Python 3.11 nebo novější.
Správce uv balíčků. Podívejte se na UV instalaci.
Aplikace Databricks povolené ve vašem pracovním prostoru Viz Nastavení pracovního prostoru Databricks Apps a vývojového prostředí.

Klonování šablony migrace

Šablona migrace poskytuje podpůrnou strukturu pro vývoj a nasazení agenta v Databricks Apps, spolu se soubory dovedností agenta, které učí asistenty pro kódování AI, jak provádět jednotlivé kroky migrace.

Naklonujte šablonu a přejděte do složky:

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

Složka šablony obsahuje:

AGENTS.md: Pokyny pro pomocníky s kódováním AI popisující pracovní postup migrace
skills/: Soubory dovedností pro každý krok migrace spuštěné v pořadí pomocníkem
agent_server/: Základní kostra cílového agenta Databricks Apps se zástupným kódem pro obslužné rutiny @invoke() a @stream()
databricks.yml: Šablona konfigurace deklarativních balíčků automatizace se zástupnými deklaracemi prostředků

Migrace s asistencí umělé inteligence (doporučeno)

Migrace s asistencí AI je doporučený způsob použití této šablony. Asistent pro kódování s umělou inteligencí čte soubory AGENTS.md a dovedností a automaticky zpracovává změny kódu a konfigurace.

Otevřete složku šablony v pomocníkovi pro kódování AI, jako je Kurzor, GitHub Copilot nebo Claude.
Požádejte asistenta, aby migraci provedl zadáním názvu koncového bodu:

"Migrate my Model Serving endpoint `my-agent-endpoint` to a Databricks App"

Pomocník vygeneruje plán migrace a provede každý krok:

Snímek obrazovky s pomocníkem pro kódování AI zobrazující podrobný seznam úkolů pro migraci agenta z modelové obsluhy do Databricks Apps

Ruční migrace

Databricks doporučuje k provedení migrace používat pomocníky pro kódování AI. Pokud chcete migrovat bez pomocníka pro kódování AI, popisují tento proces následující základní kroky.

Important

Tyto kroky představují základní přehled a nezabývají se všemi scénáři migrace, jako jsou stavové agenty, kompromisy mezi asynchronními a synchronními operacemi, přístup k artefaktům Unity Catalog nebo složité konfigurace prostředků.

Využijte asistenta pro kódování s umělou inteligencí k pomoci s migrací nebo si prohlédněte dovednost v šabloně pro podrobnější informace.

Krok 1. Stáhnout artefakty agenta

Získejte název a verzi modelu z koncového bodu:

databricks serving-endpoints get <endpoint-name> --output json

Vyhledejte served_entities[0].entity_name (název modelu) a entity_version v odpovědi stáhněte artefakty:

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

Stažená složka obsahuje:

MLmodel — deklarace prostředků pro původního agenta
code/ – zdrojové soubory agenta Python
artifacts/ — volitelné konfigurační soubory a výzvy
input_example.json — ukázková žádost o testování

Krok 2. Migrace kódu agenta

Zkopírujte všechny soubory Pythonu z code/ do agent_server/ a všechny artefakty z artifacts/ do agent_server/artifacts/.

Po přesunutí souborů aktualizujte všechny relativní importy a pevně zakódované cesty k souborům tak, aby odrážely novou strukturu složek. Potom přepište agent_server/agent.py tak, aby používal vzor zobrazený v kroku 3.

Krok 3. Transformovat kód agenta

Při poskytování modelu používají agenti třídy založené na metodách ResponsesAgent, predict() a predict_stream(). V Databricks Apps poskytuje MLflow AgentServer funkce na úrovni modulu označené @invoke() a @stream().

Při migraci zvolte jeden z následujících vzorů:

Async (doporučeno): Používá Python async def a await ke souběžnému zpracování více požadavků. Zatímco jeden požadavek čeká na odpověď LLM, server zpracuje jiné požadavky.
Synchronizace: Udržuje synchronní vzory Pythonu od agenta obsluhy modelů. Tuto možnost vyberte pro minimální migraci nebo pokud váš kód spoléhá na synchronní knihovny.

Nasazení modelu (předchozí)

Původní struktura agenta založená na třídě.

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

Aplikace – asynchronní (doporučeno)

Primární logika agenta se nachází v streaming(). Funkce non_streaming() shromáždí svůj výstup a vrátí ji jako jedinou odpověď.

from mlflow.genai.agent_server import invoke, stream
from mlflow.types.responses import (
  ResponsesAgentRequest,
  ResponsesAgentResponse,
  ResponsesAgentStreamEvent,
)

@invoke()
async def non_streaming(request: ResponsesAgentRequest) -> ResponsesAgentResponse:
  # Async implementation - typically calls streaming() and collects results
  outputs = [
    event.item
    async for event in streaming(request)
    if event.type == "response.output_item.done"
  ]
  return ResponsesAgentResponse(output=outputs)

@stream()
async def streaming(request: ResponsesAgentRequest) -> AsyncGenerator[ResponsesAgentStreamEvent, None]:
  # Async generator
  async for event in ...:
    yield event

Aplikace – synchronizace

Extrahujte metody třídy do označených funkcí na úrovni modulu s minimálními strukturálními změnami.

from mlflow.genai.agent_server import invoke, stream
from mlflow.types.responses import (
  ResponsesAgentRequest,
  ResponsesAgentResponse,
  ResponsesAgentStreamEvent,
)

@invoke()
def non_streaming(request: ResponsesAgentRequest) -> ResponsesAgentResponse:
  # Same sync logic from original predict(), extracted from the class
  ...
  return ResponsesAgentResponse(output=outputs)

@stream()
def streaming(request: ResponsesAgentRequest):
  # Same sync generator from original predict_stream(), extracted from the class
  for chunk in ...:
    yield ResponsesAgentStreamEvent(...)

Krok 4. Nastavení aplikace

Nainstalujte závislosti. Tím se vyřeší závislosti v souboru pyproject.toml a vytvoří soubor uv.lock, který je uzamkne pro reprodukovatelné instalace:
```
uv sync
```
Spuštěním skriptu pro rychlý start nakonfigurujte ověřování, vytvořte experiment MLflow a vygenerujte .env soubor:
```
uv run quickstart
```

Potvrďte vygenerovaný uv.lock soubor tak, aby aplikace Databricks při nasazování nainstalovala stejné připnuté závislosti.

Krok 5. Místní testování

Spusťte aplikační server a před nasazením ověřte, že agent správně reaguje.

Otestujte původní input_example.json pomocí nástroje curl a poté jej nasaďte, jakmile agent reaguje podle očekávání.

Krok 6. Konfigurace prostředků

Agenti obsluhující model deklarují prostředky v MLmodel souboru. Agenti Databricks Apps deklarují prostředky v konfiguračním souboru databricks.yml pomocí Deklarativní automatizační balíčky.

Viz Ověřování pro agenty AI.

Namapujte deklarace prostředků na ekvivalentní formát deklarativních automatizačních balíčků.

Typ prostředku MLmodel	`databricks.yml` Ekvivalentní	Povolení
`serving_endpoint`	`serving_endpoint`	`CAN_QUERY`
`lakebase`	`database`	`CAN_CONNECT_AND_CREATE`
`vector_search_index`	`uc_securable` (typ_zabezpečitelný: `TABLE`)	`SELECT`
`function`	`uc_securable` (typ_zabezpečitelný: `FUNCTION`)	`EXECUTE`
`table`	`uc_securable` (typ_zabezpečitelný: `TABLE`)	`SELECT` nebo `MODIFY`
`uc_connection`	`uc_securable` (typ_zabezpečitelný: `CONNECTION`)	`USE_CONNECTION`
`sql_warehouse`	`sql_warehouse`	`CAN_USE`
`genie_space`	`genie_space`	`CAN_RUN`

Krok 7. Nasazení agenta pomocí deklarativních sad automatizace

Nasaďte agenta do aplikací Databricks pomocí deklarativních automatizačních sad.

Před nasazením ověřte, že struktura složek vypadá takto:

<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
    └── ...

Note

Azure Databricks doporučuje uv (pyproject.toml + uv.lock) pro správu závislostí Python, která poskytuje rychlejší instalace a reprodukovatelné buildy. Pokud vaše aplikace obsahuje pyproject.toml a uv.lock ne requirements.txt, databricks Apps používá uv k instalaci závislostí. requirements.txt zůstává podporováno: pokud je k dispozici, vždy má přednost a aplikace Databricks Místo toho používá pip . Podívejte se na osvědčené postupy pro Databricks Apps a definujte Python závislostí pomocí uv.

Ověřte konfiguraci sady:
```
databricks bundle validate
```
Nasaďte sadu do pracovního prostoru (bundle deploy nahraje soubory, ale nespustí aplikaci):
```
databricks bundle deploy
```

Spusťte aplikaci:

databricks bundle run <app-resource-name>

Další zdroje informací

Po migraci agenta vizte:

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-09