Penerapan agen untuk aplikasi AI generatif

2025-06-05

Artikel ini menunjukkan cara menyebarkan agen AI Anda ke Mosaic AI Model Serving menggunakan fungsi deploy() dari Agent Framework Python API.

Menyebarkan agen pada Mosaic AI Model Serving memberikan manfaat berikut:

Penyajian Model mengelola penskalaan otomatis, pencatatan, pengendalian versi, dan pengendalian akses sehingga Anda dapat lebih fokus pada pengembangan agen yang berkualitas.
Pakar subjek dapat menggunakan Aplikasi Ulasan untuk berinteraksi dengan agen yang disebarkan dan memberikan umpan balik yang dapat Anda masukkan ke dalam pemantauan dan evaluasi Anda.
Anda dapat memantau agen dengan melakukan evaluasi pada lalu lintas langsung. Meskipun lalu lintas pengguna tidak akan menyertakan data sebenarnya, evaluator LLM (dan metrik kustom yang Anda buat) melakukan evaluasi tanpa pengawasan.

Persyaratan

MLflow 2.13.1 atau lebih tinggi untuk menyebarkan agen menggunakan deploy() API dari databricks.agents.
Daftarkan agen AI ke Unity Catalog. Lihat Daftarkan agen ke Unity Catalog.
Menyebarkan agen dari luar notebook Databricks memerlukan databricks-agents SDK versi 0.12.0 atau lebih tinggi.
Pembuat titik akhir (pengguna yang menyebarkan agen) harus memiliki CREATE VOLUME izin pada skema Katalog Unity yang dipilih untuk menyimpan tabel inferensi pada waktu penyebaran. Ini memastikan bahwa penilaian dan tabel pengelogan yang relevan dapat dibuat dalam skema. Lihat Mengaktifkan dan menonaktifkan tabel inferensi.

databricks-agents Pasang SDK.

%pip install databricks-agents
dbutils.library.restartPython()

Menerapkan agen menggunakan `deploy()`

Gunakan deploy() untuk memasang agen Anda ke titik akhir pemodelan.

from databricks import agents

deployment = agents.deploy(uc_model_name, uc_model_info.version)

# Retrieve the query endpoint URL for making API requests
deployment.query_endpoint

Fungsi deploy() melakukan tindakan berikut secara default:

`deploy()` perbuatan	Deskripsi
Membuat model CPU yang melayani titik akhir	Membuat agen Anda dapat diakses oleh aplikasi yang berinteraksi langsung dengan pengguna dengan menyajikannya melalui endpoint penyajian model.
Menyediakan kredensial prinsipal layanan sementara	Databricks secara otomatis menyediakan kredensial sementara dengan izin terbatas untuk mengakses sumber daya yang dikelola Databricks saat Anda mencatat model. Databricks memeriksa bahwa pemilik titik akhir memiliki izin yang diperlukan sebelum mengeluarkan kredensial untuk mencegah eskalasi hak istimewa dan akses yang tidak sah. Lihat Autentikasi untuk sumber daya yang bergantung. Jika agen Anda bergantung pada sumber daya yang dikelola non-Databricks, Anda dapat meneruskan variabel lingkungan dengan rahasia ke `deploy()`. Lihat Mengonfigurasi akses ke sumber daya dari titik akhir penyajian model.
Aktifkan Tinjau Aplikasi	Memungkinkan pemangku kepentingan berinteraksi dengan agen dan memberikan umpan balik. Lihat Gunakan aplikasi ulasan untuk ulasan manusia dari aplikasi gen AI (MLflow 2).
Mengaktifkan tabel inferensi	Pantau dan debug agen dengan mencatat input dan respons permintaan. Untuk agen `ChatAgent` dan `ChatModel`, tabel inferensi diaktifkan dengan AI Gateway. Untuk skema agen lain yang tidak digunakan lagi, tabel inferensi standar digunakan. Untuk log respons streaming, hanya bidang dan jejak yang kompatibel dengan `ChatAgent` dan `ChatCompletion` yang diagregasi.
Mencatat permintaan REST API dan Meninjau umpan balik Aplikasi	Mencatat permintaan API dan umpan balik ke tabel inferensi. Buat model umpan balik untuk menerima dan mencatat umpan balik dari Aplikasi Ulasan. Model ini dijalankan pada titik akhir pelayan model CPU yang sama dengan agen yang telah Anda sebarkan.
Aktifkan Pemantauan Lakehouse untuk Gen AI (beta)	Mengharuskan pendaftaran di Lakehouse Monitoring untuk Gen AI beta. Pemantauan dasar diaktifkan secara otomatis untuk pelacakan agen yang terpasang.
Mengaktifkan pelacakan dan pemantauan real time dengan MLflow 3 (beta)	Memerlukan pendaftaran dalam Lakehouse Monitoring untuk versi beta Gen AI dan penggunaan MLflow 3.0 atau versi yang lebih tinggi. Selain merekam jejak dari agen yang diaktifkan ke tabel inferensi untuk penyimpanan jangka panjang, Databricks merekam jejak dari agen yang Anda aktifkan ke eksperimen MLflow agar terlihat secara real-time. Ini mengurangi latensi pemantauan dan debug. Saat Anda membuat titik akhir baru melalui `agents.deploy()`, pemantauan dan pelacakan dikonfigurasi untuk membaca dan menulis dari eksperimen MLflow yang saat ini aktif. Konfigurasikan eksperimen untuk titik akhir tertentu dengan memanggil `mlflow.set_experiment()` sebelum memanggil `agents.deploy()` untuk membuat titik akhir. Jejak dari semua agen yang dilayani di titik akhir (termasuk agen yang ditambahkan ke titik akhir melalui panggilan selanjutnya ke `agents.deploy()`) ditulis dalam eksperimen ini. Pemantauan mengukur metrik kualitas pada trase dalam eksperimen ini. Secara default, hanya metrik pemantauan dasar yang dikonfigurasi. Untuk menambahkan hakim LLM dan lainnya, lihat Menyiapkan pemantauan.

Catatan

Penyebaran dapat memakan waktu hingga 15 menit untuk selesai. Payload JSON mentah membutuhkan waktu 10 - 30 menit untuk tiba, dan log yang diformat diproses dari payload mentah sekitar setiap jam.

Menyesuaikan penyebaran

Untuk menyesuaikan penyebaran, Anda dapat meneruskan argumen tambahan ke deploy(). Misalnya, Anda dapat mengaktifkan skala ke nol untuk titik akhir yang tidak aktif dengan meneruskan scale_to_zero_enabled=True. Ini mengurangi biaya tetapi meningkatkan waktu untuk melayani kueri awal.

Untuk parameter lainnya, lihat Databricks Agents Python API.

Mengambil kembali dan menghapus penyebaran agen

Mengakses atau mengelola penyebaran agen yang ada.

from databricks.agents import list_deployments, get_deployments, delete_deployment

# Print all current deployments
deployments = list_deployments()
print(deployments)

# Get the deployment for a specific agent model name and version
agent_model_name = ""  # Set to your Unity Catalog model name
agent_model_version = 1  # Set to your agent model version
deployment = get_deployments(model_name=agent_model_name, model_version=agent_model_version)

# Delete an agent deployment
delete_deployment(model_name=agent_model_name, model_version=agent_model_version)

Autentikasi untuk sumber daya bergantung

Agen AI sering kali perlu mengautentikasi ke sumber daya lain untuk menyelesaikan tugas. Misalnya, agen mungkin perlu mengakses indeks Pencarian Vektor untuk mengkueri data yang tidak terstruktur.

Agen Anda dapat menggunakan salah satu metode berikut untuk melakukan autentikasi pada sumber daya dependen saat Anda menyajikannya di belakang endpoint Model Serving.

Penyampaian autentikasi otomatis: Deklarasikan dependensi sumber daya Databricks untuk agen Anda selama pengelogan. Databricks dapat secara otomatis melakukan penyediaan, perputaran, dan pengelolaan kredensial berumur pendek ketika agen Anda diterapkan untuk mengakses sumber daya dengan aman. Databricks merekomendasikan penggunaan passthrough autentikasi otomatis jika memungkinkan.
Autentikasi atas nama pengguna: Memungkinkan penggunaan kredensial pengguna akhir agen untuk mengakses REST API dan sumber daya Databricks
Autentikasi manual: Tentukan secara manual kredensial jangka panjang saat menyebarkan agen. Gunakan autentikasi manual untuk sumber daya Databricks yang tidak mendukung passthrough autentikasi otomatis, atau untuk akses API eksternal.

Penerusan autentikasi otomatis

Model Serving mendukung penerusan autentikasi otomatis untuk jenis sumber daya Databricks yang paling umum digunakan oleh agen.

Untuk mengaktifkan passthrough autentikasi otomatis, Anda harus menentukan dependensi selama pengelogan agen.

Kemudian, ketika Anda menyediakan layanan kepada agen pada titik akhir, Databricks melakukan langkah-langkah berikut:

Verifikasi izin: Databricks memverifikasi bahwa pencipta endpoint dapat mengakses semua dependensi yang ditentukan selama pencatatan log agen.
Pembuatan dan pemberian prinsipal layanan: Prinsipal layanan dibuat untuk versi model agen dan secara otomatis diberikan akses baca ke sumber daya agen.

Catatan

Prinsipal layanan yang dihasilkan sistem tidak muncul dalam daftar API atau antarmuka pengguna (UI). Jika versi model agen dihapus dari endpoint, maka prinsipal layanan akan dihapus juga.
Penyediaan dan rotasi kredensial: Kredensial jangka pendek (token OAuth M2M) untuk perwakilan layanan diterapkan pada titik akhir, memungkinkan kode agen untuk mengakses sumber daya Databricks. Databricks juga memperbarui kredensial, memastikan bahwa agen Anda terus memiliki akses aman ke sumber daya terkait.

Perilaku autentikasi ini mirip dengan perilaku "Jalankan sebagai pemilik" untuk dasbor Databricks - sumber daya yang ada di bagian hilir seperti tabel Katalog Unity dapat diakses menggunakan kredensial perwakilan layanan dengan akses hak istimewa paling rendah ke sumber daya dependen.

Tabel berikut mencantumkan sumber daya Databricks yang mendukung penerusan autentikasi secara otomatis dan izin yang harus dimiliki oleh pembuat titik akhir saat mengkonfigurasi agen.

Catatan

Sumber daya Katalog Unity juga memerlukan USE SCHEMA pada skema induk dan USE CATALOG pada katalog induk.

Jenis Sumber Daya	Izin
Gudang SQL	Gunakan Endpoint
Titik akhir Layanan Model	Dapat Mengajukan Pertanyaan
Fungsi Katalog Unity	MELAKSANAKAN
Ruang jin	Dapat Berlari
Indeks Pencarian Vektor	Bisa Pakai
Tabel Unity Catalog	SELECT

Autentikasi atas nama pengguna

Autentikasi atas nama pengguna memungkinkan pengembang agen mengakses sumber daya Databricks sensitif menggunakan kredensial pengguna akhir agen. Untuk mengaktifkan akses atas nama pengguna ke sumber daya, ada dua langkah:

Dalam kode agen, pastikan sumber daya databricks diakses dengan klien yang mengaktifkan autentikasi atas nama pengguna. Lihat Menyebarkan agen menggunakan autentikasi atas nama pengguna untuk informasi selengkapnya.
Pada waktu pengelogan agen, tentukan cakupan REST API pengguna akhir (misalnya, vectorsearch.vector-search-endpoints) yang diperlukan oleh agen Anda. Ketika agen Anda kemudian disebarkan, agen dapat mengakses sumber daya Databricks atas nama pengguna akhir, tetapi hanya menggunakan cakupan yang ditentukan. Untuk informasi selengkapnya tentang cakupan API, lihat Autentikasi atas nama pengguna.

Autentikasi manual

Anda juga dapat memberikan kredensial secara manual menggunakan variabel lingkungan berbasis rahasia . Autentikasi manual dapat membantu dalam skenario berikut:

Sumber daya dependen tidak mendukung penyaluran otentikasi otomatis.
Agen mengakses sumber daya eksternal atau API.
Agen perlu menggunakan kredensial selain kredensial dari penggelar agen.

Misalnya, untuk menggunakan Databricks SDK di agen Anda untuk mengakses sumber daya dependen lainnya, Anda dapat mengatur variabel lingkungan yang dijelaskan dalam autentikasi terpadu klien Databricks.

Memantau agen terpasang

Setelah agen disebarkan ke Databricks Model Serving, Anda dapat menggunakan tabel inferensi Gateway AI untuk memantau agen yang disebarkan. Tabel inferensi berisi log terperinci permintaan, respons, jejak agen, dan umpan balik agen dari aplikasi ulasan. Informasi ini memungkinkan Anda men-debug masalah, memantau performa, dan membuat himpunan data emas untuk evaluasi offline.

Penting

Jika MLflow 3 diinstal di lingkungan pengembangan Anda saat Anda memanggil agents.deploy(), titik akhir Anda akan mencatat Jejak MLflow secara real time ke Eksperimen MLflow yang diaktifkan pada saat panggilan agents.deploy(). Anda dapat memanggil mlflow.set_experiment() untuk mengubah eksperimen aktif sebelum penyebaran.

Lihat dokumen MLflow untuk detail selengkapnya.

Lihat Debug & Amati Aplikasi Anda dengan Pelacakan.

Dapatkan aplikasi yang telah disebarkan

Berikut cara mendapatkan agen yang telah Anda kerahkan.

from databricks.agents import list_deployments, get_deployments

# Get the deployment for specific model_fqn and version
deployment = get_deployments(model_name=model_fqn, model_version=model_version.version)

deployments = list_deployments()
# Print all the current deployments
deployments

Lihat Databricks Agents Python API.

Berikan umpan balik pada agen yang digunakan (eksperimental)

Saat Anda menyebarkan agen dengan agents.deploy(), kerangka kerja agen juga membuat dan menyebarkan versi model "umpan balik" di titik akhir yang sama, yang dapat Anda tanyakan dan memberikan umpan balik pada aplikasi agen Anda. Entri umpan balik muncul sebagai baris permintaan dalam tabel inferensi yang terkait dengan endpoint layanan agen Anda.

Perhatikan bahwa perilaku ini bersifat eksperimental: Databricks dapat menyediakan API kelas satu untuk memberikan umpan balik pada agen yang disebarkan di masa mendatang, dan fungsionalitas di masa mendatang mungkin memerlukan migrasi ke API ini.

Batasan API ini meliputi:

API umpan balik tidak memiliki validasi input - api selalu berhasil merespons, bahkan jika lulus input yang tidak valid.
API umpan balik memerlukan memasukkan request_id yang dihasilkan oleh Databricks dari permintaan titik akhir agen untuk mana Anda ingin memberikan umpan balik. Untuk mendapatkan databricks_request_id, sertakan {"databricks_options": {"return_trace": True}} dalam permintaan asli Anda ke agen yang melayani endpoint. Respons titik akhir agen kemudian akan menyertakan databricks_request_id yang terkait dengan permintaan sehingga Anda dapat meneruskan ID permintaan tersebut kembali ke API umpan balik saat memberikan umpan balik tentang respons agen.
Umpan balik dikumpulkan menggunakan tabel inferensi. Lihat batasan tabel inferensi.

Contoh permintaan berikut memberikan umpan balik tentang titik akhir agen yang bernama "your-agent-endpoint-name", dan mengasumsikan bahwa variabel lingkungan DATABRICKS_TOKEN disetel ke token Databricks REST API.

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '
      {
          "dataframe_records": [
              {
                  "source": {
                      "id": "user@company.com",
                      "type": "human"
                  },
                  "request_id": "573d4a61-4adb-41bd-96db-0ec8cebc3744",
                  "text_assessments": [
                      {
                          "ratings": {
                              "answer_correct": {
                                  "value": "positive"
                              },
                              "accurate": {
                                  "value": "positive"
                              }
                          },
                          "free_text_comment": "The answer used the provided context to talk about Lakeflow Declarative Pipelines"
                      }
                  ],
                  "retrieval_assessments": [
                      {
                          "ratings": {
                              "groundedness": {
                                  "value": "positive"
                              }
                          }
                      }
                  ]
              }
          ]
      }' \
https://<workspace-host>.databricks.com/serving-endpoints/<your-agent-endpoint-name>/served-models/feedback/invocations

Anda dapat meneruskan pasangan kunci-nilai tambahan atau berbeda pada bidang text_assessments.ratings dan retrieval_assessments.ratings untuk memberikan berbagai jenis umpan balik. Dalam contoh, payload umpan balik menunjukkan bahwa respons agen terhadap permintaan dengan ID 573d4a61-4adb-41bd-96db-0ec8cebc3744 sudah benar, akurat, dan didasarkan pada konteks yang diambil oleh alat pencari.

Bagikan melalui