Mencatat dan mendaftarkan agen AI (Model Serving)

Penting

Untuk kasus penggunaan baru, Databricks merekomendasikan penyebaran agen di Databricks Apps untuk kontrol penuh atas kode agen, konfigurasi server, dan alur kerja penyebaran. Lihat Menulis agen AI dan menyebarkannya di Aplikasi Databricks. Untuk memigrasikan agen yang ada, lihat Memigrasikan agen dari Model Melayani ke Aplikasi Databricks.

Mencatat agen AI menggunakan Mosaic AI Agent Framework. Pengelogan agen adalah dasar dari proses pengembangan. Pengelogan menangkap "titik waktu" kode dan konfigurasi agen sehingga Anda dapat mengevaluasi kualitas konfigurasi.

Requirements

Buat sebuah agen AI sebelum mencatatnya.

Databricks merekomendasikan untuk menginstal versi terbaru databricks-sdk.

% pip install databricks-sdk

pengelogan berbasis kode

Databricks merekomendasikan penggunaan Model MLflow dari fungsionalitas Kode saat mencatat agen.

Dalam pendekatan ini, kode agen ditangkap sebagai file Python, dan lingkungan Python ditangkap sebagai daftar paket. Ketika agen disebarkan, lingkungan Python dipulihkan, dan kode agen dijalankan untuk memuat agen ke dalam memori sehingga dapat dipanggil ketika titik akhir dipanggil.

Anda dapat menggandeng pendekatan ini dengan penggunaan API validasi pra-penyebaran seperti mlflow.models.predict() untuk memastikan bahwa agen berjalan dengan andal saat disebarkan untuk melayani.

Untuk melihat contoh pengelogan berbasis kode, lihat Buku catatan contoh penulisan ResponsesAgent.

Tanda Tangan Model Infer selama pengelogan

Note

Databricks merekomendasikan penulisan agen menggunakan antarmuka ResponsesAgent. Jika menggunakan ResponsesAgent, Anda dapat melewati bagian ini; MLflow secara otomatis menyimpulkan tanda tangan yang valid untuk agen Anda.

Jika tidak menggunakan antarmuka ResponsesAgent, Anda harus menggunakan salah satu metode berikut untuk menentukan Tanda Tangan Model MLflow agen Anda pada waktu pengelogan:

Tentukan tanda tangan secara manual
Gunakan kemampuan inferensi Tanda Tangan Model MLflow untuk secara otomatis menghasilkan tanda tangan agen berdasarkan contoh input yang Anda berikan. Pendekatan ini lebih nyaman daripada menentukan tanda tangan secara manual.

Tanda tangan model MLflow memvalidasi input dan output untuk memastikan agen berinteraksi dengan benar dengan alat hilir seperti AI Playground dan aplikasi ulasan. Ini juga memandu aplikasi lain tentang cara menggunakan agen secara efektif.

Contoh LangChain dan PyFunc di bawah ini menggunakan inferensi Model Signature.

Jika Anda lebih suka secara eksplisit menentukan Tanda Tangan Model sendiri pada waktu pengelogan, lihat dokumen MLflow - Cara mencatat model dengan tanda tangan.

Logging berbasis kode dengan LangChain

Instruksi dan sampel kode berikut menunjukkan kepada Anda cara mencatat agen dengan LangChain.

Buat buku catatan atau file Python dengan kode Anda. Untuk contoh ini, buku catatan atau file diberi nama agent.py. Buku catatan atau file harus berisi agen LangChain, yang disebut di sini sebagai lc_agent.
Sertakan mlflow.models.set_model(lc_agent) dalam buku catatan atau file.
Buat buku catatan baru untuk berfungsi sebagai buku catatan driver (dipanggil driver.py dalam contoh ini).
Di buku catatan driver, gunakan kode berikut untuk menjalankan agent.py dan mencatat hasilnya ke model MLflow:
```
mlflow.langchain.log_model(lc_model="/path/to/agent.py", resources=list_of_databricks_resources)
```
Parameter resources mendeklarasikan sumber daya yang dikelola Databricks yang diperlukan untuk melayani agen, seperti indeks pencarian vektor atau titik akhir penyajian yang melayani model fondasi. Untuk informasi selengkapnya, lihat Menerapkan passthrough autentikasi otomatis.
Terapkan model. Lihat Menyebarkan agen pada aplikasi AI generatif (Penyajian Model).
Saat lingkungan penyajian dimuat, agent.py dijalankan.
Ketika permintaan layanan masuk, lc_agent.invoke(...) dipanggil.


import mlflow

code_path = "/Workspace/Users/first.last/agent.py"
config_path = "/Workspace/Users/first.last/config.yml"

# Input example used by MLflow to infer Model Signature
input_example = {
  "messages": [
    {
      "role": "user",
      "content": "What is Retrieval-augmented Generation?",
    }
  ]
}

# example using langchain
with mlflow.start_run():
  logged_agent_info = mlflow.langchain.log_model(
    lc_model=code_path,
    model_config=config_path, # If you specify this parameter, this configuration is used by agent code. The development_config is overwritten.
    artifact_path="agent", # This string is used as the path inside the MLflow model where artifacts are stored
    input_example=input_example, # Must be a valid input to the agent
    example_no_conversion=True, # Required
  )

print(f"MLflow Run: {logged_agent_info.run_id}")
print(f"Model URI: {logged_agent_info.model_uri}")

# To verify that the model has been logged correctly, load the agent and call `invoke`:
model = mlflow.langchain.load_model(logged_agent_info.model_uri)
model.invoke(example)

pengelogan berbasis kode dengan PyFunc

Instruksi dan sampel kode berikut menunjukkan kepada Anda cara mencatat agen dengan PyFunc.

Buat buku catatan atau file Python dengan kode Anda. Untuk contoh ini, buku catatan atau file diberi nama agent.py. Buku catatan atau file harus berisi kelas PyFunc, bernama PyFuncClass.
Sertakan mlflow.models.set_model(PyFuncClass) dalam buku catatan atau file.
Buat buku catatan baru untuk berfungsi sebagai buku catatan driver (dipanggil driver.py dalam contoh ini).
Di buku catatan driver, gunakan kode berikut untuk menjalankan agent.py dan menggunakan log_model() untuk mencatat hasil ke model MLflow:
```
mlflow.pyfunc.log_model(python_model="/path/to/agent.py", resources=list_of_databricks_resources)
```
Parameter resources mendeklarasikan sumber daya yang dikelola Databricks yang diperlukan untuk melayani agen, seperti indeks pencarian vektor atau titik akhir penyajian yang melayani model fondasi. Untuk informasi selengkapnya, lihat Menerapkan passthrough autentikasi otomatis.
Terapkan model. Lihat Menyebarkan agen pada aplikasi AI generatif (Penyajian Model).
Saat lingkungan penyajian dimuat, agent.py dijalankan.
Ketika permintaan layanan masuk, PyFuncClass.predict(...) dipanggil.

import mlflow
from mlflow.models.resources import (
    DatabricksServingEndpoint,
    DatabricksVectorSearchIndex,
)

code_path = "/Workspace/Users/first.last/agent.py"
config_path = "/Workspace/Users/first.last/config.yml"

# Input example used by MLflow to infer Model Signature
input_example = {
  "messages": [
    {
      "role": "user",
      "content": "What is Retrieval-augmented Generation?",
    }
  ]
}

with mlflow.start_run():
  logged_agent_info = mlflow.pyfunc.log_model(
    python_model=agent_notebook_path,
    artifact_path="agent",
    input_example=input_example,
    resources=resources_path,
    example_no_conversion=True,
    resources=[
      DatabricksServingEndpoint(endpoint_name="databricks-meta-llama-3-3-70b-instruct"),
      DatabricksVectorSearchIndex(index_name="prod.agents.databricks_docs_index"),
    ]
  )

print(f"MLflow Run: {logged_agent_info.run_id}")
print(f"Model URI: {logged_agent_info.model_uri}")

# To verify that the model has been logged correctly, load the agent and call `invoke`:
model = mlflow.pyfunc.load_model(logged_agent_info.model_uri)
model.invoke(example)

Autentikasi untuk sumber daya Databricks

Agen AI sering kali perlu mengautentikasi ke sumber daya lain untuk menyelesaikan tugas. Misalnya, agen yang disebarkan mungkin perlu mengakses indeks Pencarian Vektor untuk mengkueri data yang tidak terstruktur, atau mengakses Prompt Registry untuk memuat permintaan dinamis.

Penerusan autentikasi otomatis dan autentikasi 'on-behalf-of' memerlukan konfigurasi selama pencatatan agen.

Daftarkan agen ke Katalog Unity

Sebelum menyebarkan agen, Anda harus mendaftarkan agen ke Unity Catalog. Pendaftaran agen mengemasnya sebagai sebuah model di dalam Unity Catalog. Akibatnya, Anda dapat menggunakan izin Katalog Unity untuk otorisasi sumber daya di agen.

import mlflow

mlflow.set_registry_uri("databricks-uc")

catalog_name = "test_catalog"
schema_name = "schema"
model_name = "agent_name"

model_name = catalog_name + "." + schema_name + "." + model_name
uc_model_info = mlflow.register_model(model_uri=logged_agent_info.model_uri, name=model_name)

Lihat mlflow.register_model().

Langkah selanjutnya

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-02-14