Menjajaki kesalahan pada agen AI yang sudah diterapkan

Halaman ini membahas cara men-debug masalah umum dengan agen AI yang disebarkan di Azure Databricks.

Pergi ke:

Sebagian besar bagian debugging di halaman ini berlaku untuk agen yang di-deploy ke Aplikasi Databricks. Namun, Anda juga dapat menemukan informasi penelusuran kesalahan untuk agen yang disebarkan di Model Serving (warisan) menggunakan pemilih tab.

Agen author menggunakan praktik terbaik

Gunakan praktik terbaik berikut saat mengembangkan agen.

  • Aktifkan pelacakan MLflow: Ikuti praktik terbaik dalam Menulis agen AI dan sebarkan di Aplikasi Databricks. Agar lebih mudah mem-debug agen Anda, aktifkan autologging pelacakan MLflow.
  • Alat dokumen dengan jelas: Deskripsi alat dan parameter yang jelas memastikan agen Anda memahami alat Anda dan menggunakannya dengan tepat. Lihat Tingkatkan panggilan alat dengan dokumentasi yang jelas.
  • Tambahkan batas waktu habis dan token ke panggilan LLM: Tambahkan batas waktu habis dan token ke panggilan LLM dalam kode Anda untuk menghindari keterlambatan yang disebabkan oleh langkah-langkah yang berjalan lama.
    • Jika agen Anda menggunakan klien OpenAI untuk mengkueri titik akhir penyajian AZURE Databricks LLM, atur batas waktu kustom pada panggilan titik akhir penyajian sesuai kebutuhan.
  • Validasi konfigurasi sebelum penyebaran: Jalankan databricks bundle validate sebelum Anda menyebarkan untuk menangkap masalah konfigurasi YAML lebih awal. Ini membantu mengidentifikasi referensi sumber daya yang tidak cocok, izin yang tidak valid, dan kesalahan sintaksis.
  • Uji secara lokal terlebih dahulu: Gunakan pengembangan lokal untuk menangkap masalah sebelum Anda menyebarkan. Mulai server agen Anda secara lokal, uji dengan permintaan sampel, dan verifikasi bahwa jejak MLflow muncul dengan benar sebelum Anda menyebarkan ke Aplikasi Databricks.

Men-debug masalah pengembangan lokal

Uji agen Anda secara lokal untuk mengidentifikasi masalah sebelum penyebaran.

Sebelum Anda menjalankan agen secara lokal, verifikasi bahwa lingkungan Anda dikonfigurasi dengan benar:

  1. Periksa versi Databricks CLI: Jalankan databricks -v untuk memverifikasi bahwa Anda memiliki versi 0.283.0 atau yang lebih baru.

  2. Verifikasi profil CLI: Jalankan databricks auth profiles untuk melihat profil autentikasi yang dikonfigurasi.

  3. Memvalidasi konfigurasi lingkungan: Periksa apakah file Anda .env berisi variabel yang diperlukan, terutama MLFLOW_TRACKING_URI, yang harus menggunakan format databricks://PROFILE_NAME untuk menyertakan profil CLI Anda.

Kesalahan pengembangan lokal umum

Kesalahan Penyebab Solusi
The provided MLFLOW_EXPERIMENT_ID does not exist Format atau eksperimen URI pelacakan yang salah dihapus Verifikasi bahwa MLFLOW_TRACKING_URI menggunakan databricks://PROFILE_NAME format dengan nama profil CLI Anda
Module not found Dependensi tidak terinstal Jalankan uv sync untuk menginstal dependensi
Port already in use Proses lain menggunakan port Gunakan --port bendera untuk menentukan port yang berbeda (misalnya, uv run start-app --port 8001)
Kesalahan autentikasi saat berjalan secara lokal Lingkungan tidak dikonfigurasi Jalankan skrip mulai cepat atau konfigurasikan .env file secara manual dengan profil CLI Anda

Menguji agen di lingkungan lokal

Untuk menguji agen Anda sebelum pendistribusian:

  1. Mulai server agen secara lokal:

    uv run start-app

  2. Di terminal lain, kirim permintaan pengujian:

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

  3. Lihat jejak MLflow di antarmuka pengguna Azure Databricks untuk memverifikasi bahwa agen Anda mencatat jejak dengan benar.

Masalah konfigurasi debug

Kesalahan konfigurasi dalam databricks.yml dan app.yaml merupakan sumber umum kegagalan penyebaran.

Memvalidasi konfigurasi Bundel Otomatisasi Deklaratif

Validasi konfigurasi Bundel Otomatisasi Deklaratif sebelum menyebarkan aplikasi:

databricks bundle validate

Perintah ini memeriksa konfigurasi Anda untuk:

  • Kesalahan sintaks YAML
  • Bidang yang diperlukan tidak ada
  • Referensi sumber daya tidak valid
  • Masalah konfigurasi izin

Ketidakcocokan konfigurasi umum

Titik konfigurasi Peraturan Cara debugging
valueFrom referensi dalam app.yaml Harus sama persis dengan sumber daya name di databricks.yml Cari string yang tepat di kedua file untuk memverifikasi kecocokan
Nama aplikasi Harus dimulai dengan awalan agent- (misalnya, agent-data-analyst) Periksa bidang di name bawah resources.apps di databricks.yml
ID Ruang Genie Harus berupa string heksa 32 karakter dari URL Genie Ekstrak dari jalur URL: https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Referensi fungsi Katalog Unity Harus menggunakan format catalog.schema.function_name Memverifikasi fungsi yang ada menggunakan databricks unity-catalog functions list
Referensi instans Lakebase Harus menggunakan value (bukan valueFrom) dalam app.yaml file Nama instans adalah string literal, bukan referensi sumber daya

Masalah penyebaran debug

Agen yang diimplementasikan ke aplikasi

Kesalahan: Aplikasi sudah ada

Kesalahan aplikasi sudah ada

Jika Anda melihat Error: failed to create app - An app with the same name already exists, Anda memiliki dua opsi:

Opsi 1: Ikat ke aplikasi yang ada (disarankan)

# 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>

Opsi 2: Hapus dan buat ulang

databricks apps delete <app-name>
databricks bundle deploy
databricks bundle run <bundle-name>
Aplikasi tidak diperbarui setelah penyebaran

Aplikasi tidak memperbarui setelah penyebaran

databricks bundle deploy hanya mengunggah file ke ruang kerja. Anda juga harus menjalankan databricks bundle run <bundle-name> untuk menghidupkan ulang aplikasi dengan kode baru.

Selalu sebarkan menggunakan kedua perintah:

databricks bundle deploy && databricks bundle run <bundle-name>
Lihat status dan catatan penyebaran

Lihat status serta log penyebaran

Untuk memeriksa status penyebaran aplikasi Anda:

databricks apps get <app-name>

Untuk melihat log aplikasi secara real time:

databricks apps logs <app-name> --follow

Agen pada Model Melayani (warisan)

Jika Anda menyebarkan agen menggunakan agents.deploy() ke titik akhir Model Serving, tinjau Panduan Debugging untuk Model Serving untuk masalah khusus penyebaran.

Untuk melakukan debug masalah runtime seperti permintaan yang lambat atau mengalami kegagalan, lihat Melakukan debug kesalahan runtime.

Debug kesalahan runtime

Agen yang diimplementasikan ke aplikasi

Gunakan log aplikasi dan minta pengujian untuk mengidentifikasi masalah dengan agen yang Anda sebarkan.

Menganalisis log aplikasi

Lihat log real-time dari aplikasi yang Anda sebarkan:

databricks apps logs <app-name> --follow

Cari:

  • Stack trace menunjukkan kesalahan kode
  • Pesan penolakan izin untuk sumber daya
  • Kesalahan koneksi ke layanan eksternal
  • Pesan batas waktu

Kesalahan runtime umum

Error Sebab Solution
Pengalihan 302 saat melakukan query pada aplikasi Menggunakan Token Akses Pribadi alih-alih OAuth Mendapatkan token OAuth dengan databricks auth token
Agen tidak menggunakan alat yang tersedia Perangkat yang tidak dikembalikan oleh klien MCP Pastikan URL server MCP sudah benar dan sumber daya memiliki izin yang tepat di databricks.yml
Respons streaming terputus di tengah-tengah tanggapan Waktu koneksi habis CHAT_PROXY_TIMEOUT_SECONDS Meningkatkan variabel lingkungan diapp.yaml
Agen yang mengembalikan "Memori tidak tersedia" Komponen user_id hilang dalam permintaan Kirim custom_inputs.user_id dalam permintaan payload
Respons kosong atau kesalahan meskipun status 200 Kesalahan terjadi dalam respons yang dialirkan Periksa konten streaming aktual dan log aplikasi, bukan hanya kode status HTTP

Agen pada Model Melayani (warisan)

Gunakan tabel inferensi dan jejak MLflow untuk mengidentifikasi masalah dengan agen yang disebarkan ke titik akhir Model Serving.

Mengidentifikasi permintaan bermasalah

Jika Anda mengaktifkan pencatatan otomatis pelacakan MLflow saat menulis agen Anda, jejak secara otomatis masuk ke tabel inferensi. Gunakan jejak ini untuk mengidentifikasi komponen agen yang lambat atau gagal.

  1. Di ruang kerja Anda, buka tab Melayani dan pilih nama penyebaran Anda.
  2. Di bagian Tabel inferensi , temukan nama tabel inferensi yang sepenuhnya memenuhi syarat. Contohnya, my-catalog.my-schema.my-table.
  3. Jalankan yang berikut ini di buku catatan Databricks: 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
  4. Periksa kolom Respons untuk informasi pelacakan terperinci.
  5. Filter pada request_time, databricks_request_id atau status_code untuk mempersempit hasil. 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
WHERE status_code != 200

Menganalisis akar masalah penyebab

Setelah mengidentifikasi permintaan yang gagal atau lambat, gunakan API mlflow.models.validate_serving_input untuk memanggil agen Anda terhadap permintaan input yang gagal. Lihat jejak yang dihasilkan dan lakukan analisis akar penyebab pada respons yang gagal.

Untuk mempercepat proses pengembangan, perbarui kode agen Anda secara langsung, lalu lakukan iterasi dengan memanggil agen Anda pada contoh input yang gagal.

Debug kesalahan autentikasi

Agen yang diimplementasikan ke aplikasi

Autentikasi token OAuth diperlukan

Autentikasi token OAuth diperlukan

Anda harus menggunakan token OAuth Databricks untuk mengkueri agen yang disebarkan ke Aplikasi. Menggunakan Token Akses Pribadi (PAT) menghasilkan kesalahan pengalihan 302.

Untuk mendapatkan token OAuth:

databricks auth token

Gunakan token dalam permintaan ke aplikasi yang Anda sebarkan:

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"}]}'
Kesalahan izin sumber daya

Kesalahan izin sumber daya

Ketika agen Anda tidak dapat mengakses sumber daya ruang kerja, verifikasi bahwa sumber daya dikonfigurasi dengan benar di databricks.yml. Setiap jenis sumber daya memerlukan izin tertentu:

Error Sebab Solution
Izin ditolak pada Genie Space Sumber daya hilang genie_space Tambahkan genie_space sumber daya dengan permission: 'CAN_RUN'
Indeks pencarian vektor tidak dapat diakses Sumber daya hilang untuk indeks uc_securable uc_securable Menambahkan sumber daya dengan securable_type: 'TABLE' dan permission: 'SELECT'
Eksekusi fungsi Katalog Unity ditolak Sumber daya yang hilang uc_securable untuk fungsi uc_securable Menambahkan sumber daya dengan securable_type: 'FUNCTION' dan permission: 'EXECUTE'
Akses titik akhir penyajian ditolak Sumber daya hilang serving_endpoint Tambahkan serving_endpoint sumber daya dengan permission: 'CAN_QUERY'
Akses gudang SQL ditolak Sumber daya hilang sql_warehouse Tambahkan sql_warehouse sumber daya dengan permission: 'CAN_USE'

Contoh konfigurasi sumber daya di 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'
Izin server MCP kustom

Izin kustom server MCP

Jika agen Anda terhubung ke server MCP kustom yang berjalan sebagai aplikasi Databricks, Anda harus memberikan izin secara manual karena aplikasi belum didukung sebagai dependensi sumber daya di 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\"}]}"

Agen pada Model Melayani (warisan)

Jika agen yang Anda sebarkan mengalami kesalahan autentikasi saat mengakses sumber daya seperti indeks pencarian vektor atau endpoint LLM, verifikasi bahwa agen tersebut terautentikasi dengan sumber daya yang diperlukan untuk penerusan autentikasi otomatis. Lihat penerusan autentikasi otomatis.

Untuk memeriksa sumber daya yang dicatat, jalankan yang berikut ini di buku catatan:

%pip install -U mlflow[databricks]
%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)

Untuk menambahkan kembali sumber daya yang hilang atau salah, masuk ke sistem sebagai agen dan terapkan lagi.

Jika Anda menggunakan autentikasi manual untuk sumber daya, verifikasi bahwa variabel lingkungan diatur dengan benar. Pengaturan manual mengambil alih konfigurasi autentikasi otomatis apa pun. Lihat Autentikasi manual.

Men-debug masalah memori dan penyimpanan

Untuk agen yang menggunakan Lakebase untuk penyimpanan memori, masalah berikut umum terjadi:

Error Sebab Solution
relation 'store' does not exist Tabel memori tidak diinisialisasi Jalankan await store.setup() secara lokal sebelum menyebarkan untuk membuat tabel yang diperlukan
Unable to resolve :re[LKB] instance Nama instans yang salah atau konfigurasi yang salah Verifikasi LAKEBASE_INSTANCE_NAME menggunakan value (bukan valueFrom) di app.yaml dan cocok dengan instance_name di databricks.yml.
permission denied for table store Izin untuk Lakebase hilang Tambahkan sumber daya database di databricks.yml dengan permission: 'CAN_CONNECT_AND_CREATE'
Memori tidak bertahan di seluruh percakapan Berbeda user_id berdasarkan permintaan Pastikan Anda meneruskan user_id yang konsisten dalam custom_inputs untuk setiap pengguna

Contoh konfigurasi sumber daya Lakebase:

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

Sebelum menyebarkan agen dengan memori, inisialisasi tabel secara lokal:

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