Ladění vlastního agenta pro kód

Tato stránka se věnuje tomu, jak řešit běžné problémy s agenty s vlastním kódem nasazenými v Azure Databricks.

Přejít na:

Většina sekcí odlaďování na této stránce se vztahuje na agenty nasazené v Databricks Apps. Pomocí selektorů karet ale můžete najít také informace o ladění agentů nasazených ve službě Model Serving (starší verze ).

Autorizujte agenty pomocí osvědčených postupů

Při vytváření agentů použijte následující osvědčené postupy:

  • Povolte trasování MLflow: Postupujte podle osvědčených postupů při tvorbě AI agenta a jeho nasazení do Databricks Apps. Povolte automatické protokolování trasování MLflow , abyste usnadnili ladění agentů.
  • Jasně zdokumentujte nástroje: Jasné popisy nástrojů a parametrů zajistí, že váš agent rozumí vašim nástrojům a správně je používá. Podívejte se na vylepšení volání nástrojů pomocí jasné dokumentace.
  • Přidání časových limitů a limitů tokenů pro volání LLM: Přidejte limity časových limitů a tokenů do volání LLM v kódu, aby nedocházelo ke zpožděním způsobeným dlouhotrvajícími kroky.
    • Pokud váš agent používá klienta OpenAI k dotazování koncového bodu obsluhy Azure Databricks LLM, nastavte vlastní časové limity pro volání obsluhujícího koncového bodu podle potřeby.
  • Před nasazením ověřte konfiguraci: Spusťte databricks bundle validate před nasazením, abyste zachytili problémy s konfigurací YAML dříve. To pomáhá identifikovat neshodované odkazy na prostředky, neplatná oprávnění a chyby syntaxe.
  • Nejprve nejprve otestujte: Před nasazením použijte místní vývoj k zachycení problémů. Spusťte server agenta místně, otestujte ukázkové požadavky a před nasazením do Databricks Apps ověřte, jestli se trasování MLflow zobrazuje správně.

Ladění problémů s místním vývojem

Otestujte agenta místně a zjistěte problémy před nasazením.

Před místním spuštěním agenta ověřte, že je vaše prostředí správně nakonfigurované:

  1. Zkontrolujte verzi Rozhraní příkazového řádku Databricks: Spuštěním databricks -v ověřte, že máte verzi 0.283.0 nebo novější.

  2. Ověření profilů rozhraní příkazového řádku: Spuštěním databricks auth profiles zobrazíte nakonfigurované profily ověřování.

  3. Ověření konfigurace prostředí: Zkontrolujte, jestli soubor .env obsahuje požadované proměnné, zejména MLFLOW_TRACKING_URI, které musí použít formát databricks://PROFILE_NAME pro zahrnutí profilu rozhraní příkazového řádku.

Běžné chyby místního vývoje

Error Příčina Řešení
The provided MLFLOW_EXPERIMENT_ID does not exist Došlo k odstranění nesprávného formátu identifikátoru URI sledování nebo experimentu. Ověřte, že MLFLOW_TRACKING_URI používá formát databricks://PROFILE_NAME pro název profilu CLI.
Module not found Závislosti nebyly nainstalovány. Spusťte uv sync pro instalaci závislostí
Port already in use Jiný proces používající port Použití --port příznaku k určení jiného portu (např. uv run start-app --port 8001)
Chyby ověřování při místním spuštění Prostředí není nakonfigurováno. Spusťte skript pro rychlý start nebo ručně nakonfigurujte .env soubor s profilem rozhraní příkazového řádku.

Otestujte agenta lokálně

Otestování agenta před nasazením:

  1. Místní spuštění serveru agenta:

    uv run start-app

  2. V jiném terminálu odešlete testovací požadavek:

    curl -X POST http://localhost:8000/invocations \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "hello"}]}'

  3. Zobrazte trasování MLflow v uživatelském rozhraní Azure Databricks a ověřte, že váš agent správně protokoluje trasování.

Problémy s konfigurací ladění

Chyby konfigurace v databricks.yml a app.yaml jsou běžnými zdroji selhání nasazení.

Ověřte konfiguraci deklarativních balíčků automatizace

Před nasazením aplikace ověřte konfiguraci balíčků deklarativní automatizace.

databricks bundle validate

Tento příkaz zkontroluje vaši konfiguraci pro:

  • Syntaktické chyby YAML
  • Chybějící požadovaná pole
  • Neplatné odkazy na prostředky
  • Problémy s konfigurací oprávnění

Běžné neshody konfigurace

Bod konfigurace Pravidlo Postup ladění
valueFrom odkazy v app.yaml Musí přesně odpovídat zdroji name v databricks.yml Vyhledejte přesný řetězec v obou souborech a ověřte, že odpovídají.
Název aplikace Musí začínat předponou agent- (např. agent-data-analyst) Zkontrolujte pole name v části resources.apps v databricks.yml
ID agenta Genie Musí to být 32znakový šestnáctkový řetězec z URL adresy Genie. Extrahování z cesty URL: https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Referenční informace k funkcím katalogu Unity Musí používat formát. catalog.schema.function_name Ověření existence funkce pomocí databricks unity-catalog functions list
Referenční informace k instanci Lakebase V souboru se musí používat value (nevalueFrom)app.yaml Název instance je doslovný řetězec, nikoli odkaz na zdroj.

Řešení problémů s laděním nasazení

Agenti nasazení do aplikací

Chyba aplikace už existuje.

Chyba aplikace už existuje.

Pokud se zobrazí Error: failed to create app - An app with the same name already exists, máte dvě možnosti:

Možnost 1: Vytvoření vazby k existující aplikaci (doporučeno)

# Get existing app configuration
databricks apps get <app-name> --output json

# Sync the configuration to your databricks.yml, then bind
databricks bundle deployment bind <bundle-name> <app-name> --auto-approve

# Deploy
databricks bundle deploy
databricks bundle run <bundle-name>

Možnost 2: Odstranění a opětovné vytvoření

databricks apps delete <app-name>
databricks bundle deploy
databricks bundle run <bundle-name>
Aplikace se po nasazení neaktualizuje

Aplikace se po nasazení neaktualizuje

databricks bundle deploy nahrává soubory pouze do pracovního prostoru. Musíte také spustit databricks bundle run <bundle-name>, aby se aplikace restartovala s novým kódem.

Vždy nasazovat pomocí obou příkazů:

databricks bundle deploy && databricks bundle run <bundle-name>
Zobrazení stavu nasazení a protokolů

Zobrazení stavu nasazení a protokolů

Kontrola stavu nasazení vaší aplikace:

databricks apps get <app-name>

Zobrazení protokolů aplikací v reálném čase:

databricks apps logs <app-name> --follow

Agenti při servisu modelů (starší verze)

Pokud jste svého agenta nasadili pomocí agents.deploy() na koncový bod obsluhy modelů, projděte si průvodce laděním pro obsluhu modelů ohledně problémů specifických pro nasazení.

Pokud chcete ladit chyby modulu runtime, jako jsou pomalé nebo neúspěšné požadavky, podívejte se na sekci Ladění chyb za běhu.

Ladění chyb modulu runtime

Agenti nasazení do aplikací

K identifikaci problémů s nasazeným agentem použijte protokoly aplikací a testování požadavků.

Analýza protokolů aplikací

Zobrazení protokolů v reálném čase z nasazené aplikace:

databricks apps logs <app-name> --follow

Hledejte:

  • Stack trace s chybami kódu
  • Zprávy o odepření přístupových práv k prostředkům
  • Chyby připojení k externím službám
  • Zprávy o vypršení časového limitu

Běžné chyby modulu runtime

Error Příčina Solution
Přesměrování 302 při dotazu na aplikaci Použití osobního přístupového tokenu místo OAuth Získání tokenu OAuth s využitím databricks auth token
Agent nepoužívá dostupné nástroje Nástroje se nevrácely z klienta MCP Ověřte správnost adresy URL serveru MCP a že prostředek má správná oprávnění. databricks.yml
Odpověď streamování se přeruší uprostřed. Časový limit připojení vypršel Zvyšte proměnnou prostředí CHAT_PROXY_TIMEOUT_SECONDS v app.yaml
Agent vracející hlášení 'Paměť není k dispozici' Chybí user_id v žádosti Předat custom_inputs.user_id v datové části žádosti
Prázdné odpovědi nebo chybové odpovědi bez ohledu na stav 200 Během streamované odpovědi došlo k chybě. Zkontrolujte skutečný obsah streamu a protokoly aplikací, nejen stavový kód HTTP.

Agenti při servisu modelů (starší verze)

Pomocí odvozovacích tabulek a trasování MLflow identifikujte problémy s agenty nasazenými do koncových bodů obsluhy modelů.

Identifikace problematických požadavků

Pokud jste při vytváření agenta povolili automatické protokolování trasování MLflow , trasování se automaticky zaprotokoluje v tabulkách odvozování. Pomocí těchto stop identifikujte komponenty agenta, které jsou pomalé nebo selhávají.

  1. V pracovním prostoru přejděte na kartu Obsluha a vyberte název nasazení.
  2. V části Odvozovací tabulky vyhledejte plně kvalifikovaný název tabulky odvození. Například: my-catalog.my-schema.my-table.
  3. V poznámkovém bloku Databricks spusťte následující příkaz: 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
  4. Podrobné informace o trasování najdete ve sloupci Odpověď .
  5. Filtrovat podle request_time, databricks_request_id nebo status_code a zúžit výsledky. 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
WHERE status_code != 200

Analýza problémů s původní příčinou

Po identifikaci neúspěšných nebo pomalých požadavků použijte rozhraní API mlflow.models.validate_serving_input k vyvolání agenta proti neúspěšné vstupní žádosti. Prohlédněte si výsledné trasování a proveďte analýzu původní příčiny u neúspěšné odpovědi.

Pro rychlejší vývojovou smyčku aktualizujte kód agenta přímo a iterujte voláním agenta proti příkladu neúspěšného vstupu.

Ladění chyb ověřování

Agenti nasazení do aplikací

Vyžaduje se ověřování tokenu OAuth.

Vyžaduje se ověřování tokenu OAuth.

K dotazování agentů nasazených do aplikací musíte použít token OAuth Databricks. Při použití tokenu PAT (Personal Access Token) dojde k chybě přesměrování 302.

Získání tokenu OAuth:

databricks auth token

Použijte token v požadavcích na nasazenou aplikaci:

TOKEN=$(databricks auth token | jq -r '.access_token')
curl -X POST <app-url>/invocations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "hello"}]}'
Chyby oprávnění k prostředkům

Chyby oprávnění pro přístup k prostředkům

Pokud váš agent nemá přístup k prostředkům pracovního prostoru, ověřte, že je prostředek správně nakonfigurovaný v databricks.yml. Každý typ prostředku vyžaduje specifická oprávnění:

Error Příčina Solution
Přístup odepřen pro agenta Genie Chybějící genie_space prostředek Přidejte prostředek pomocí genie_spacepermission: 'CAN_RUN'
Index vyhledávání AI není přístupný Chybějící uc_securable prostředek pro index Přidejte uc_securable prostředek s securable_type: 'TABLE' a permission: 'SELECT'
Spuštění funkce Katalogu Unity bylo odepřeno. Chybějící uc_securable prostředek pro funkci Přidejte uc_securable prostředek s securable_type: 'FUNCTION' a permission: 'EXECUTE'
Odepřen přístup ke služebnímu koncovému bodu Chybějící serving_endpoint prostředek Přidejte prostředek pomocí serving_endpointpermission: 'CAN_QUERY'
Odepření přístupu ke službě SQL Warehouse Chybějící sql_warehouse prostředek Přidejte prostředek pomocí sql_warehousepermission: 'CAN_USE'

Příklad konfigurace prostředku v databricks.yml:

resources:
  apps:
    my_agent:
      name: 'agent-my-app'
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '01234567890abcdef01234567890abcd'
            permission: 'CAN_RUN'
        - name: 'my_vector_index'
          uc_securable:
            securable_full_name: 'catalog.schema.index_name'
            securable_type: 'TABLE'
            permission: 'SELECT'
Vlastní oprávnění serveru MCP

Vlastní oprávnění serveru MCP

Pokud se váš agent připojuje k serveru MCP na míru, který běží jako aplikace Databricks, musíte oprávnění udělit ručně, protože aplikace se zatím nepodporují jako závislosti na prostředcích.databricks.yml

# Get your agent app's service principal
AGENT_SP=$(databricks apps get <agent-app-name> --output json | jq -r '.service_principal_name')

# Grant permission on the MCP server app
databricks apps update-permissions <mcp-server-app-name> \
  --json "{\"access_control_list\": [{\"service_principal_name\": \"$AGENT_SP\", \"permission_level\": \"CAN_USE\"}]}"

Agenti při servisu modelů (starší verze)

Pokud váš nasazený agent při přístupu k prostředkům, jako jsou indexy AI Search nebo koncové body LLM, narazí na chyby autentizace, ověřte, že byl zaregistrován s potřebnými prostředky pro automatické předávání autentizace. Vizte automatické ověřování průchodem.

Pokud chcete zkontrolovat protokolované prostředky, spusťte v poznámkovém bloku následující příkaz:

%pip install -U mlflow[databricks]==2.20.2
%restart_python

import mlflow
mlflow.set_registry_uri("databricks-uc")

# Replace with the model name and version of your deployed agent
agent_registered_model_name = ...
agent_model_version = ...

model_uri = f"models:/{agent_registered_model_name}/{agent_model_version}"
agent_info = mlflow.models.Model.load(model_uri)
print(f"Resources logged for agent model {model_uri}:", agent_info.resources)

Pokud chcete znovu přidat chybějící nebo nesprávné prostředky, zapište agenta a znovu ho nasaďte.

Pokud pro prostředky používáte ruční ověřování, ověřte, že jsou proměnné prostředí správně nastavené. Ruční nastavení přebijí všechny konfigurace automatického ověřování. Viz ruční ověřování.

Ladění problémů s pamětí a úložištěm

U agentů používajících Lakebase pro úložiště paměti jsou běžné následující problémy:

Error Příčina Solution
relation 'store' does not exist Tabulky paměti nejsou inicializovány Spusťte await store.setup() místně před nasazením, abyste vytvořili požadované tabulky
Unable to resolve :re[LKB] instance Nesprávný název instance nebo nesprávná konfigurace Ověřte LAKEBASE_INSTANCE_NAME, že se používá value (nikoli valueFrom) v app.yaml a zda app.yaml odpovídá databricks.yml v
permission denied for table store Chybějící oprávnění Lakebase Přidejte database prostředek v databricks.yml s permission: 'CAN_CONNECT_AND_CREATE'
Paměť se neuchovává napříč konverzacemi Jiné user_id na žádost Ujistěte se, že pro každého uživatele předáváte konzistentní user_idcustom_inputs hodnoty.

Příklad konfigurace zdroje Lakebase:

resources:
  apps:
    my_agent:
      resources:
        - name: 'memory_database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

Před nasazením agenta s pamětí inicializujte tabulky místně:

import asyncio
from databricks_langchain import AsyncDatabricksStore

async def setup_memory():
    async with AsyncDatabricksStore(
        instance_name='your-lakebase-instance',
        embedding_endpoint='databricks-gte-large-en',
        embedding_dims=1024,
    ) as store:
        await store.setup()

asyncio.run(setup_memory())
  • Last updated on