以自訂模型服務提供大型語言模型服務

Important

這項功能位於測試版 (Beta) 中。工作區管理員可以從 「預覽 」頁面控制對此功能的存取。請參閱管理 Azure Databricks 預覽。

本頁將展示如何利用 vLLM 引擎在 Model Serving 上部署自訂大型語言模型（LLM）。使用此工作流程來提供微調模型、PEFT 變體、多模態模型及其他基礎模型，這些模型在基礎模型 API （FMAPI）中無法提供。本頁末尾的起始筆記本包含所有可執行的程式碼，用於以下步驟。

何時使用自訂 LLM 服務

Azure Databricks 建議在有以下使用情境之一時使用自訂 LLM 服務：

完全微調過的模型，並自訂權重，並且是在 Azure Databricks 上訓練的。
Hugging Face 上 FMAPI 未提供的模型。
FMAPI 不支援的自訂 PEFT 配方。
FMAPI 目錄外的專用型號，如 MedGemma。
多模態（視覺語言）模型，例如 Qwen/Qwen2.5-VL-3B-Instruct。
嵌入 FMAPI 中沒有的模型，例如 nomic-ai/nomic-embed-text-v2-moe。
任何能裝在 1xH100（80 GB GPU 記憶體）上的型號。

Requirements

自訂大型語言模型服務目前為 Beta 版。 Workspace 管理員可以從預覽頁面啟用或關閉此功能。請參閱管理 Azure Databricks 預覽。
無伺服器 GPU 運算。小型機型建議使用 A10 GPU，大型機型則使用 H100。
MLflow 3.12 或以上，且 databricks-sdk>=0.102.0。入門筆記本的腳位 mlflow==3.12.0 和相容的 SDK 版本。如果你自己建環境，就要配合這些版本。較早版本的 SDK 在註冊期間上傳模型成品時，可能會逾時。請參閱註冊期間成品上傳逾時。

步驟一：建立你的環境

在配備 A10 GPU 的無伺服器 GPU 運算環境上建立筆記本。安裝 vLLM 及其相依性。入門筆記本固定使用已通過測試的 vLLM 版本。

你也可以透過無伺服器環境指定相依，而不是用 %pip install。

Important

將工作目錄設為本地硬碟（例如，使用 tempfile.mkdtemp()）。 /Workspace檔案系統不支援模型權重等大型檔案。

步驟二：下載你的模型

使用 snapshot_download 從 Hugging Face 下載模型權重。入門 Notebook 以 Qwen/Qwen3-4B 為例，但你可以替換為任何符合你所選 GPU 記憶體容量限制的模型，包括以下幾種：

多模態模型，例如用於視覺語言使用案例的 Qwen/Qwen2.5-VL-3B-Instruct。
較大的型號可安裝在1xH100上，例如 openai/gpt-oss-120b。

根據你機型的記憶體和效能需求選擇顯示卡。

GPU	GPU 記憶體	`workload_type`
T4	16 GB	`GPU_SMALL`
A100	80 GB	`GPU_LARGE`

步驟 3：在本地使用 vLLM 測試模型

在部署前，先在你的無伺服器 GPU 筆記本上直接測試模型，透過啟動本地 vLLM 伺服器。本地測試讓你能驗證模型、實驗 vLLM 參數，並在建立服務端點前排除問題。

重點資訊：

無伺服器 GPU 運算僅允許 3000–3999 埠用於本地測試。在該範圍內選擇一個連接埠；起始筆記本使用 3080。
vLLM 伺服器在 /invocations 提供與 OpenAI 相容的 API。
你可以測試一般和串流請求。
為模型調整參數，例如 --dtype、--max-model-len 和 --gpu-memory-utilization。
加入 --enforce-eager 可加快啟動速度，但代價是部分推論效能。
對於較大的機型，可以使用 H100 無伺服器 GPU 版本進行本地測試。

當你對設定感到滿意後，先停止本地伺服器再繼續。

步驟四：用自訂入口記錄模型

此步驟將您的本地設置與模型服務連接，並具備以下配置需求：

必須 task 是 "llm/v1/chat" （聊天模型，包括多模態）或 "llm/v1/embeddings" （嵌入模型）。請參閱支援任務。
入口必須在 8080 埠開啟，也就是 Model Serving 預期的埠口。
入口指令必須鏡像你在步驟 3 測試過的裝置，且埠口是 8080，而非本地埠口。
入口點是從 MLflow 模型產物資料夾啟動，因此模型路徑是相對於該資料夾的。

對於聊天模式：

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"
    ),
}

若為嵌入模型，請將 task 設為 "llm/v1/embeddings"，並以嵌入模式啟動伺服器。以這裡使用的 vLLM 版本來說（ --runner pooling 舊版 vLLM 使用 --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"
    ),
}

用 log 這個模型 mlflow.pyfunc.log_model ，然後傳遞 metadata 你定義的字典作為 metadata 參數。 python_model基底類別ChatModel會將記錄的模型類型化為聊天模型。

服務是 predict 執行你的入口點，而非模型的方法，因此 predict 永遠不會被呼叫，且可能回傳空結果。指向 artifacts 存放你下載的權重資料夾，釘選 mlflow ， extra_pip_requirements 與你的筆記本相符：

import mlflow
from mlflow.pyfunc.model import ChatModel, ChatCompletionResponse

# ChatModel types this as a chat model; serving runs the entrypoint, so predict is never called.
class LLMModel(ChatModel):
    def predict(self, context, messages, params):
        return ChatCompletionResponse.from_dict({"choices": []})

model_info = mlflow.pyfunc.log_model(
    name="qwen",
    python_model=LLMModel(),
    artifacts={"model_dir": "qwen3"},
    metadata=metadata,
    extra_pip_requirements=["mlflow==3.12.0"],
)
model_info.model_uri

Important

從你在步驟 1 中設定的無伺服器 GPU 筆記本執行這步驟。從非 GPU 執行時進行日誌會封裝 CPU 相依性，導致 GPU 服務端點無法啟動。

支援任務

`task`	車型類型	查詢介面
`llm/v1/chat`	聊天模型，包括多模態（視覺語言）	`chat.completions`
`llm/v1/embeddings`	內嵌模型	`embeddings`

你宣告的 task 必須與你的進入點實際提供的內容相符：該進入點必須在連接埠 8080 上提供該任務的 OpenAI 相容 API。上述範例使用 vLLM，但任何符合此合約的伺服器都能正常運作。其他任務類型，如 llm/v1/completions，則不支援。

步驟 5：將模型註冊到 Unity 目錄

使用 mlflow.register_model 將模型註冊至 Unity Catalog。自訂 LLM 服務建立在 express 部署之上，因此註冊使用 env_pack="databricks_model_serving" 參數，需要 mlflow>=3.12 和 databricks-sdk>=0.102.0。

例如，在你的筆記本上新增以下內容：


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

步驟 6：建立服務端點

從使用者介面或使用 Azure Databricks SDK 程式化建立端點。關鍵決策包括計算類型、工作負載大小，以及可縮放至零的行為。

根據你的型號和雲端，選擇 workload_type：

`workload_type`	GPU	註釋
`GPU_SMALL`	1 台 T4（16 GB）	最小的選項。
`GPU_LARGE`	1 台 A100（80 GB）	建議用於大型 LLM 工作負載。

workload_size （Small， Medium，或 Large）控制端點後方配置的複本數量。將 Small 用於開發及低流量工作負載。

以下範例展示了典型的配置：

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

規模至零與容量規劃

Beta 版的自訂 LLM 服務會在您的端點後端配置固定數量的副本。目前尚未支援在超過 0 個複本之間進行自動調整，因此你必須根據尖峰流量來設定 workload_type 和 workload_size 的大小。端點會將超出已佈建複本容量的請求排入佇列。

設定 scale_to_zero_enabled=True 讓端點在閒置時縮放到零複本。冷啟動速度較慢——載入模型權重和啟動 vLLM 通常需要一到數分鐘。

對於延遲敏感或對正式環境至關重要的工作負載，請預先設定 scale_to_zero_enabled=False，並依尖峰流量規劃 workload_size 的容量。

Warning

擴展能力並不保證。 每當 Azure Databricks 需要為您的端點取得新的 GPU——無論是在建立時、workload_size增加時，或端點從零狀態喚醒時——如果雲端供應商在您所在的區域沒有 GPU 容量，該請求可能會停止回應。這適用於所有 GPU 類型。 Databricks 透過暖池和預留機制來緩解這個問題，讓 GPU 容量保持可用且隨時可用。

步驟 7：查詢你的端點

端點準備好後，會自動從端點頁面的 AI 遊樂場中顯示。你也可以用 Databricks SDK、OpenAI SDK 或 curl 來程式化查詢。

聊天模式（llm/v1/chat）：

Databricks SDK

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

OpenAI 開發套件

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

嵌入模型（llm/v1/embeddings）：

OpenAI 開發套件

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

有些嵌入模型期望每個輸入有任務專屬的前綴（例如， nomic-embed-text-v2-moe 使用 search_query: 和 search_document:）。檢查你型號的卡是否有輸入慣例。

監控你的端點

自訂 LLM 服務使用與標準自訂模型服務端點相同的可觀察性基礎設施，但加入一些 vLLM 專屬的附加功能，詳見後續章節。

即時記錄

Serving UI 中端點頁面的日誌分頁會即時顯示來自 vLLM 處理程序的 stdout 和 stderr。你也可以透過日誌 API 開啟這個輸出。

持久化日誌與指標

啟用遙測時，日誌與指標都會持續保存到 Unity 目錄 Delta 資料表，以長期保存、SQL 查詢及合規。請參閱「將自訂模型服務資料存於 Unity 目錄」以獲取完整設定說明、需求及資料表結構。

就客製化 LLM 服務而言：

日誌：stdout以及stderr來自 vLLM 程序的日誌會自動被擷取。不需要應用程式端的日誌程式碼。
Metrics：Azure Databricks 會自動抓取 vLLM 伺服器的 Prometheus /metrics 端點，並將指標與日誌一併保存。預設情況下，你會獲得每請求延遲、吞吐量、令牌數量、隊列深度和 KV 快取利用率。

查詢遙測資料

在 Beta 階段，沒有 UI 來視覺化日誌或指標。直接在 Unity 目錄中使用 SQL 或筆記本查詢持久化的資料。請參閱 Persist custom model 提供資料至 Unity 目錄中所記錄的度量與日誌架構。

以下筆記本說明如何解析並視覺化持久化的 vLLM 指標：

自訂 LLM 服務指標筆記本

拿筆記本

範例筆記本

在無伺服器 GPU 筆記本中開發並測試模型，然後將相同的配置記錄並部署為服務端點。以下筆記本包含本指南中完整的可執行流程。

自訂 LLM 服務入門筆記本

拿筆記本

Limitations

以下限制適用於測試版期間。

複製品間沒有自動縮放。支援從零到零的縮放。
僅支援聊天（llm/v1/chat包括多模態）和嵌入llm/v1/embeddings任務。請參閱支援任務。
沒有路線優化。
沒有用來視覺化日誌或指標的介面。直接在 Unity 目錄中查詢遙測。

請聯繫您的 Azure Databricks 帳戶團隊，尋求回饋或問題。

註冊期間成品上傳逾時

當你用 env_pack註冊模型時，Azure Databricks 會上傳打包後的模型權重和環境作為工件（model_version.tar和model_environment.tar）。使用早於 databricks-sdk 的 0.102.0 版本時，上傳大型 LLM 成品可能會在超過五分鐘後逾時，並導致註冊失敗，錯誤如下：

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')"
}

要解決這個問題，請升級至 databricks-sdk>=0.102.0 並重新註冊該模型：

%pip install databricks-sdk>=0.102.0

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-14

以自訂模型服務提供大型語言模型服務

何時使用自訂 LLM 服務

Requirements

步驟一：建立你的環境

步驟二：下載你的模型

步驟 3：在本地使用 vLLM 測試模型

步驟四：用自訂入口記錄模型

支援任務

步驟 5：將模型註冊到 Unity 目錄

步驟 6：建立服務端點

規模至零與容量規劃

步驟 7：查詢你的端點

Databricks SDK

OpenAI 開發套件

curl

OpenAI 開發套件

curl

監控你的端點

即時記錄

持久化日誌與指標

查詢遙測資料

自訂 LLM 服務指標筆記本

範例筆記本

自訂 LLM 服務入門筆記本

Limitations

註冊期間成品上傳逾時

意見反應

其他資源