Melayani LLM kustom dengan Layanan Model Kustom

Important

Fitur ini ada di Beta. Admin ruang kerja dapat mengontrol akses ke fitur ini dari halaman Pratinjau . Lihat Kelola Pratinjau Azure Databricks.

Halaman ini menunjukkan kepada Anda cara menyebarkan model bahasa besar kustom (LLM) pada Model Melayani menggunakan mesin vLLM . Gunakan alur kerja ini untuk melayani model yang disempurnakan, varian PEFT, model multimodal, dan model fondasi lainnya yang tidak tersedia di FOUNDATION Model API (FMAPI). Buku catatan pemula di akhir halaman ini berisi semua kode yang dapat dijalankan untuk langkah-langkah berikut.

Kapan menggunakan penyajian LLM kustom

Azure Databricks merekomendasikan penyajian LLM kustom saat Anda memiliki salah satu kasus penggunaan berikut:

  • Model yang sepenuhnya disempurnakan dengan bobot kustom yang Anda latih di Azure Databricks.
  • Model dari Hugging Face yang tidak tersedia di FMAPI.
  • Resep PEFT kustom yang tidak didukung FMAPI.
  • Model khusus di luar katalog FMAPI, seperti MedGemma.
  • Model multimodal (bahasa visi) seperti Qwen/Qwen2.5-VL-3B-Instruct.
  • Menyematkan model yang tidak tersedia di FMAPI, seperti nomic-ai/nomic-embed-text-v2-moe.
  • Model apa pun yang sesuai dengan memori GPU 1xH100 (80 GB).

Requirements

  • Penyajian LLM kustom masih dalam tahap Beta. Admin ruang kerja dapat mengaktifkan atau menonaktifkan fitur ini dari halaman Pratinjau . Lihat Kelola Pratinjau Azure Databricks.

  • Komputasi GPU tanpa server. GPU A10 adalah lingkungan pengembangan yang direkomendasikan untuk model yang lebih kecil, H100 untuk model yang lebih besar.

  • MLflow 3.12 atau lebih tinggi dan databricks-sdk>=0.102.0. Notebook starter menyematkan mlflow==3.12.0 dan versi SDK yang kompatibel. Jika Anda membangun lingkungan Anda sendiri, cocokkan versi ini. Versi SDK sebelumnya dapat kehabisan waktu saat mengunggah artefak model selama pendaftaran. Lihat Waktu unggahan artefak habis selama pendaftaran.

Langkah 1: Siapkan lingkungan Anda

Buat buku catatan di komputasi GPU tanpa server dengan GPU A10. Pasang vLLM dan dependensinya. Notebook pemula menyematkan versi vLLM yang diuji.

Anda juga dapat menentukan dependensi melalui lingkungan tanpa server alih-alih menggunakan %pip install.

Important

Atur direktori kerja Anda ke hard drive lokal (misalnya, menggunakan tempfile.mkdtemp()). /Workspace sistem file tidak mendukung berkas besar seperti bobot model.

Langkah 2: Unduh model Anda

Unduh bobot model dari Hugging Face dengan snapshot_download. Buku catatan pemula menggunakan Qwen/Qwen3-4B sebagai contoh, tetapi Anda dapat mengganti model apa pun yang sesuai dengan anggaran memori GPU yang Anda pilih, termasuk yang berikut ini:

  • Model multimodal seperti Qwen/Qwen2.5-VL-3B-Instruct untuk kasus penggunaan bahasa visi.
  • Model yang lebih besar yang sesuai dengan 1xH100, seperti openai/gpt-oss-120b.

Pilih GPU berdasarkan kebutuhan memori dan performa model Anda.

GPU (Unit Pemrosesan Grafis) Memori GPU workload_type
T4 16 GB GPU_SMALL
A100 80 GB GPU_LARGE

Langkah 3: Uji model secara lokal dengan vLLM

Sebelum Anda menyebarkan, uji model langsung di notebook GPU tanpa server Anda dengan meluncurkan server vLLM lokal. Pengujian lokal memungkinkan Anda memverifikasi model, bereksperimen dengan parameter vLLM, dan memecahkan masalah sebelum Anda membuat titik akhir penyajian.

Hal-hal penting yang perlu diketahui:

  • Komputasi GPU tanpa server hanya memungkinkan port 3000–3999 untuk pengujian lokal. Pilih port dalam rentang tersebut; notebook awal menggunakan 3080.
  • Server vLLM mengekspos API yang kompatibel dengan OpenAI di /invocations.
  • Anda dapat menguji permintaan reguler dan streaming.
  • Sesuaikan parameter seperti --dtype, --max-model-len, dan --gpu-memory-utilization untuk model Anda.
  • Tambahkan --enforce-eager untuk waktu mulai yang lebih cepat, dengan mengorbankan sebagian performa inferensi.
  • Untuk model yang lebih besar, gunakan varian GPU tanpa server H100 untuk pengujian lokal.

Ketika Anda puas dengan konfigurasi, hentikan server lokal sebelum Melanjutkan.

Langkah 4: Catat model dengan titik masuk kustom

Langkah ini menghubungkan penyiapan lokal Anda ke Model Serving dan memiliki persyaratan konfigurasi berikut:

  • task harus berupa "llm/v1/chat" (model chat, termasuk multimodal) atau "llm/v1/embeddings" (model embedding). Lihat Tugas yang didukung.
  • Entry point harus dibuka di port 8080, yaitu port yang diharapkan oleh Model Serving.
  • Perintah titik masuk harus mencerminkan apa yang Anda uji di Langkah 3, dengan port 8080 alih-alih port lokal Anda.
  • Titik masuk diluncurkan dari folder artefak model MLflow, sehingga jalur model relatif terhadap folder tersebut.

Untuk model chat:

metadata = {
    "task": "llm/v1/chat",
    "entrypoint": (
        "python -u -m vllm.entrypoints.openai.api_server "
        "--model qwen3 --served-model-name qwen "
        "--host 0.0.0.0 --port 8080 "
        "--dtype float16 --max-model-len 16384 "
        "--gpu-memory-utilization 0.85"
    ),
}

Untuk model penyematan, atur task ke "llm/v1/embeddings" dan mulai server Anda dalam mode penyematan. Dengan versi vLLM yang digunakan di sini, yaitu --runner pooling (versi vLLM yang lebih lama menggunakan --task embed):

metadata = {
    "task": "llm/v1/embeddings",
    "entrypoint": (
        "python -u -m vllm.entrypoints.openai.api_server "
        "--model nomic-embed --served-model-name nomic-embed "
        "--runner pooling "
        "--host 0.0.0.0 --port 8080 "
        "--gpu-memory-utilization 0.85"
    ),
}

Tugas yang didukung

task Jenis model Area kueri
llm/v1/chat Model percakapan, termasuk multimodal (visi-bahasa) chat.completions
llm/v1/embeddings Menyematkan model embeddings

Yang task Anda nyatakan harus cocok dengan apa yang sebenarnya dilayani oleh titik masuk Anda: titik masuk harus mengekspos API yang kompatibel dengan OpenAI untuk tugas tersebut pada port 8080. Contoh di atas menggunakan vLLM, tetapi server apa pun yang memenuhi kontrak ini berfungsi. Jenis tugas lain, seperti llm/v1/completions, tidak didukung.

Langkah 5: Daftarkan model ke Unity Catalog

Daftarkan model ke Unity Catalog menggunakan mlflow.register_model. Penyajian LLM kustom dibangun pada penyebaran ekspresenv_pack="databricks_model_serving", sehingga pendaftaran menggunakan parameter dan memerlukan mlflow>=3.12 dan databricks-sdk>=0.102.0.

Misalnya, tambahkan yang berikut ini ke buku catatan Anda:


model_version = mlflow.register_model(model_info.model_uri, UC_MODEL_NAME, env_pack="databricks_model_serving")

Langkah 6: Membuat titik akhir penyajian

Buat titik akhir dari UI atau secara terprogram dengan SDK Azure Databricks. Keputusan utama adalah jenis komputasi, ukuran beban kerja, dan perilaku skala-ke-nol.

Pilih workload_type berdasarkan model dan cloud Anda:

workload_type GPU (Unit Pemrosesan Grafis) Notes
GPU_SMALL 1x T4 (16 GB) Opsi terkecil.
GPU_LARGE 1x A100 (80 GB) Direkomendasikan untuk beban kerja LLM besar.

workload_size (Small, Medium, atau Large) mengontrol jumlah replika yang disediakan di belakang titik akhir. Gunakan Small untuk pengembangan dan beban kerja lalu lintas rendah.

Contoh berikut menunjukkan konfigurasi umum:

ServedEntityInput(
    entity_name="main.<catalog>.<model_name>",
    entity_version="<version>",
    workload_type=ServingModelWorkloadType.GPU_MEDIUM,
    workload_size="Small",
    scale_to_zero_enabled=True,
)

Perencanaan skala-ke-nol dan kapasitas

Penyajian LLM kustom dalam versi Beta menyediakan sejumlah replika tetap untuk endpoint Anda. Penskalaan otomatis antara lebih dari nol replika belum didukung, jadi Anda harus mengukur workload_type dan workload_size untuk lalu lintas puncak Anda. Endpoint mengantrikan permintaan yang melebihi kapasitas replika yang diprovisikan.

Atur scale_to_zero_enabled=True agar endpoint dapat menurunkan skala ke nol replika saat tidak aktif. Start dingin itu lambat — memuat bobot model dan memulai vLLM biasanya memakan waktu satu hingga beberapa menit.

Untuk beban kerja yang sensitif terhadap latensi atau penting bagi produksi, atur scale_to_zero_enabled=False dan tentukan ukuran workload_size untuk trafik puncak Anda sejak awal.

Warning

Kapasitas peningkatan skala tidak dijamin. Setiap kali Azure Databricks perlu memperoleh GPU baru untuk endpoint Anda—saat pembuatan, saat workload_size ditingkatkan, atau saat endpoint aktif kembali dari nol—permintaan mungkin berhenti merespons jika penyedia cloud tidak memiliki kapasitas GPU di wilayah Anda. Ini berlaku untuk semua jenis GPU. Databricks mengatasi hal ini dengan warm pool dan prareservasi, yang menjaga kapasitas GPU tetap tersedia dan siap.

Langkah 7: Mengkueri titik akhir Anda

Setelah titik akhir siap, titik akhir muncul secara otomatis di AI Playground dari halaman titik akhir. Anda juga dapat mengkuerinya secara terprogram menggunakan Databricks SDK, OpenAI SDK, atau curl.

Model obrolan (llm/v1/chat):

Databricks SDK

w.serving_endpoints.query(
    name="<endpoint-name>",
    messages=[ChatMessage(role=ChatMessageRole.USER, content="Hello")],
)

OpenAI SDK

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=f"{DATABRICKS_HOST}/serving-endpoints",
)
client.chat.completions.create(
    model="<endpoint-name>",
    messages=[{"role": "user", "content": "Hello"}],
)

curl

curl -X POST \
  -u "token:$DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}]}' \
  https://<workspace-url>/serving-endpoints/<endpoint-name>/invocations

Menyematkan model (llm/v1/embeddings):

OpenAI SDK

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=f"{DATABRICKS_HOST}/serving-endpoints",
)
client.embeddings.create(
    model="<endpoint-name>",
    input=["The quick brown fox jumps over the lazy dog."],
)

curl

curl -X POST \
  -u "token:$DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":["The quick brown fox jumps over the lazy dog."]}' \
  https://<workspace-url>/serving-endpoints/<endpoint-name>/invocations

Beberapa model penyematan mengharapkan awalan khusus tugas pada setiap input (misalnya, nomic-embed-text-v2-moe menggunakan search_query: dan search_document:). Periksa kartu model Anda untuk mengetahui konvensi inputnya.

Pantau endpoint Anda

Penyajian LLM kustom menggunakan infrastruktur observabilitas yang sama dengan endpoint penyajian model kustom standar, tetapi dengan beberapa fitur tambahan khusus vLLM yang dijelaskan di bagian berikut.

Log Langsung

Tab Logs pada halaman endpoint di UI Serving menampilkan stdout dan stderr dari proses vLLM Anda secara waktu nyata. Anda juga dapat membuka output ini melalui API log.

Log dan metrik persisten

Saat telemetri diaktifkan, baik log maupun metrik disimpan dalam tabel Delta Unity Catalog untuk penyimpanan jangka panjang, kueri SQL, dan kepatuhan. Lihat Menyimpan data penyajian model kustom di Unity Catalog untuk petunjuk penyiapan lengkap, persyaratan, dan skema tabel.

Untuk penyajian LLM kustom khusus:

  • Log: stdout dan stderr dari proses vLLM diambil secara otomatis. Tidak diperlukan kode pengelogan sisi aplikasi.
  • Metrics: Azure Databricks secara otomatis mengambil metrik dari endpoint Prometheus server vLLM /metrics dan menyimpan metrik tersebut secara persisten bersamaan dengan log. Secara default, Anda mendapatkan latensi per permintaan, throughput, jumlah token, kedalaman antrean, dan pemanfaatan KV-cache.

Kueri data telemetri

Selama Beta, tidak ada UI untuk memvisualisasikan log atau metrik. Kueri data yang dipertahankan langsung di Unity Catalog menggunakan SQL atau buku catatan. Lihat metrik dan skema log yang didokumenkan dalam Mempertahankan model kustom yang melayani data ke Unity Catalog.

Buku catatan berikut ini memperlihatkan cara mengurai dan memvisualisasikan metrik vLLM yang bertahan:

Notebook metrik penyediaan LLM kustom

Dapatkan buku catatan

Contoh buku catatan

Kembangkan dan uji model di notebook GPU tanpa server , lalu catat dan sebarkan konfigurasi yang sama dengan titik akhir penyajian. Buku catatan berikut berisi alur lengkap yang dapat dijalankan dari panduan ini.

Notebook pemula penyajian LLM kustom

Dapatkan buku catatan

Keterbatasan

Batasan berikut berlaku selama Beta.

  • Tidak ada penskalaan otomatis antar replika. Skala-ke-nol didukung.
  • Yang didukung hanya tugas percakapan (llm/v1/chat, termasuk multimodal) dan embedding (llm/v1/embeddings). Lihat Tugas yang didukung.
  • Tidak ada pengoptimalan rute.
  • Tidak ada UI untuk memvisualisasikan log atau metrik. Kueri telemetri langsung di Unity Catalog.

Hubungi tim akun Azure Databricks Anda untuk mendapatkan umpan balik atau pertanyaan.

Waktu unggahan artefak habis selama pendaftaran

Saat Anda mendaftarkan model dengan env_pack, Azure Databricks mengunggah bobot dan lingkungan model kemasan sebagai artefak (model_version.tar dan model_environment.tar). Pada versi databricks-sdk yang lebih lama daripada 0.102.0, pengunggahan artefak LLM berukuran besar dapat mengalami time-out setelah lima menit dan menyebabkan registrasi gagal dengan pesan kesalahan seperti berikut:

MlflowException: The following failures occurred while uploading one or more artifacts to
/Models/<catalog>/<schema>/<model>/<version>: {
  '.../model_environment.tar': "TimeoutError('Timed out after 0:05:00')",
  '.../model_version.tar': "TimeoutError('Timed out after 0:05:00')"
}

Untuk memperbaikinya, tingkatkan ke databricks-sdk>=0.102.0 dan daftarkan ulang model:

%pip install databricks-sdk>=0.102.0
  • Last updated on