Udostępniaj niestandardowe modele LLM za pomocą funkcji Custom Model Serving

Ta strona pokazuje, jak serwować własny LLM na punkcie końcowym GPU Model Serving. Każdy model uruchomiony przez vLLM staje się produkcyjnym punktem końcowym z interfejsem API kompatybilnym z OpenAI. Tak to działa:

• Uruchamiasz serwer inferencyjny, taki jak vLLM, i wybierasz jego wersję oraz ustawienia.
• Testujesz serwer w notatniku AI Runtime . Zła flaga lub błąd braku pamięci pojawia się w ciągu kilku sekund, a nie po wdrożeniu.
• Wdrażasz to samo polecenie i środowisko, które zbudowałeś i wiesz, że działa, na punkt końcowy obsługujący produkcję.

Szybki start

Zaimportuj poniższy notatnik do swojego workspace i kliknij Run all w AI Runtime z kartą A10. W około 15 minut masz punkt końcowy Qwen3.5-4B, który odpowiada na żądania czatu zgodne z OpenAI.

Obsługuj Qwen3.5-4B za pomocą vLLM

Pobierz laptopa

Kiedy używać niestandardowej usługi LLM

Używaj niestandardowego udostępniania modeli LLM w następujących przypadkach:

• Dopracowałeś LLM w AI Runtime i chcesz go wdrożyć. Zobacz poniższą sekcję, na przykład.
• Chcesz serwować otwarty model, którego Foundation Model API (FMAPI) nie obsługuje, jak nowy LLM, model mowy na tekst czy model osadzania.
• Chcesz zmienić runtime lub architekturę LLM i potrzebujesz kontroli nad runtime oraz środowiskiem.

Nie używaj niestandardowego udostępniania modeli LLM w następujących przypadkach:

• FMAPI udostępnia model, którego potrzebujesz, bez zmian. FMAPI jest prostsze w użyciu i bardzo zoptymalizowane.
• Model nie mieści się na jednej kartie graficznej z około 80 GB pamięci. Na przykład Qwen3.8-27B i gpt-oss-120b pasują, ale Kimi K3 i GLM 5.3 nie.
• Potrzebujesz przepustowości na poziomie frontier lub ceny za token bez tuningu. Wydajność dorównuje open source vLLM na tym samym GPU.

Requirements

Udostępnianie niestandardowych modeli LLM spełnia następujące wymagania:

• Twój obszar roboczy musi zawierać AI Runtime.
• Musisz zarejestrować model z notatnika AI Runtime. Model zarejestrowany z poziomu środowiska CPU pakuje zależności CPU, a punkt końcowy GPU nie daje się uruchomić.
• Musisz mieć uprawnienia do tworzenia modeli w schemacie Unity Catalog.
• Musisz zarejestrować model w env_pack="databricks_model_serving". Niestandardowe serwowanie LLM opiera się na wdrożeniach Express, które pakują środowisko notebooka wraz z modelem.
• Musisz używać MLflow 3.12 lub nowszej oraz databricks-sdk 0.102.0 lub nowszej. Środowisko AI v6 obejmuje oba te elementy.

Notatniki dla początkujących

Każdy notebook przenosi jeden model z Hugging Face do odpytywanego punktu końcowego, jak w quickstart. Uruchom jeden bez zmian albo zacznij od jednego, aby wdrożyć własny model.

AI v6 i Standard v6 to środowiska AI Runtime. AI v6 zawiera preinstalowane i gotowe do użycia pakiety vLLM, PyTorch, Transformers oraz inne popularne pakiety uczenia maszynowego. Zobacz listę pakietów AI v6. Standardowy notebook v6 sam instaluje vLLM, więc wybierasz jego wersję. Używaj notesu Standard v6, gdy Twój model potrzebuje nowszego vLLM lub transformerów niż AI v6, jak w Muse Glimmer.

Udostępnij własny model

Aby obsłużyć inny model, wybierz notatnik startowy z tym samym zadaniem i GPU, którego potrzebuje twój model. Zmień MODEL_REPO_ID i flagi w vllm_command, a potem uruchom notatnik. Każdy notatnik wykonuje następujące kroki:

1. Pobierz wagi modelu z Hugging Face lub pobierz je z punktu kontrolnego treningowego.
2. Uruchom vLLM w notatniku i zapytaj go.
3. Zaloguj model z poleceniem vLLM jako punktem wejścia i zarejestruj go w Unity Catalog jako wdrożenie express.
4. Utwórz endpoint, który uruchamia to samo polecenie.
5. Wykonaj zapytanie do endpointu za pomocą klienta OpenAI, Databricks SDK lub SQL ai_query.

W poniższym przykładzie model metadata przechowuje zadanie i punkt wejścia:

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

# The endpoint runs the entrypoint and never calls predict, but MLflow needs a model class to log.
class Placeholder(ChatModel):
    def predict(self, context, messages, params):
        return ChatCompletionResponse.from_dict({"choices": []})

model_info = mlflow.pyfunc.log_model(
    name="my-model",
    python_model=Placeholder(),
    artifacts={"model_dir": "my-model"},  # the weights folder, which --model names
    metadata={
        "task": "llm/v1/chat",
        "entrypoint": (
            "python -u -m vllm.entrypoints.openai.api_server "
            "--model my-model --served-model-name my-model "
            "--host 0.0.0.0 --port 8080 --max-model-len 16384"
        ),
    },
)
mlflow.register_model(model_info.model_uri, "<catalog>.<schema>.my_model", env_pack="databricks_model_serving")

Udostępnij dopracowany model

Dopracuj model w AI Runtime i serwuj go z tego samego notatnika. Dla przykładu zobacz Supervised fine-tuning (Full) i serwowanie Qwen3.5-0.8B. W tym samouczku dostraja się model Qwen3.5-0.8B na pojedynczym H100, porównuje odpowiedzi przed i po treningu oraz udostępnia dostrojony model.

Adaptery LoRA Serve

Jeden punkt końcowy może obsłużyć kilka adapterów LoRA na jednym modelu bazowym: vLLM ładuje model bazowy raz i stosuje adapter wskazany w każdym żądaniu. Przykład, który obsługuje dwa adaptery placeholder, można znaleźć w notatniku startowym adaptery Qwen3.5-4B i LoRA.

Aby obsługiwać adaptery LoRA, wykonaj następujące czynności:

1. Zapisz każdy adapter w osobnym folderze, na przykład z save_pretrained biblioteki Hugging Face Parameter-Efficient Fine-Tuning (PEFT).

2. Zaloguj folder adapters obok wag modelu bazowego i dodaj flagi LoRA vLLM do punktu wejścia. --max-loras Ustala, ile adapterów może działać w jednej partii. Ustaw --max-lora-rank na rangę co najmniej tak wysoką jak ranga największego adaptera. vLLM akceptuje tylko 1, 8, 16, 32, 64, 128, 256, 320 i 512, więc zaokrąglij w górę.

   model_info = mlflow.pyfunc.log_model(
       name="my-model",
       python_model=Placeholder(),
       artifacts={"model_dir": "my-model", "adapters": "adapters"},  # the base weights, and one folder per adapter
       metadata={
           "task": "llm/v1/chat",
           "entrypoint": (
               "python -u -m vllm.entrypoints.openai.api_server "
               "--model my-model --served-model-name my-model "
               "--enable-lora --lora-modules finance=adapters/finance support=adapters/support "
               "--max-loras 2 --max-lora-rank 8 "
               "--host 0.0.0.0 --port 8080"
           ),
       },
   )
   

3. Utwórz endpoint i wyszukaj adapter po nazwie.

Adaptery mają następujące ograniczenia:

• Wybór adaptera działa tylko na punktach końcowych czatu (llm/v1/chat).
• Punkt końcowy musi obsługiwać jeden model, kierując do niego 100% ruchu. Punkty końcowe, które dzielą ruch między modele lub wersje, nie mogą wybrać adaptera.
• Adaptery są ładowane, gdy punkt końcowy się uruchamia. Aby je zmienić, zarejestruj nową wersję modelu i zaktualizuj punkt końcowy.

Obsługiwane zadania

task w metadanych modelu określa, które API obsługuje punkt końcowy. Twój serwer musi udostępnić API kompatybilne z OpenAI do tego zadania. Inne zadania, takie jak llm/v1/completions, nie są obsługiwane. Poniższa tabela przedstawia obsługiwane zadania.

Wybierz kartę graficzną

Azure Databricks zaleca tworzenie na tym samym GPU, na którym wdrażasz model, więc ustawienia, które testujesz, są tymi, które wdrażasz. Poniższa tabela wymienia układy GPU do obsługi niestandardowych modeli LLM.

Typowe problemy

Następujące problemy są najczęstsze, gdy zmieniasz notebook:

• Pobieranie kończy się niepowodzeniem w /Workspace, które nie akceptuje plików o rozmiarze wielu GB. Pobierz wagi na lokalny dysk, tak jak robią to notatniki startowe.
• Lokalny serwer się nie uruchamia. Notebooki AI Runtime pozwalają tylko na porty 3000–3999, więc testuj na jednym z nich. Tylko entrypoint korzysta z portu 8080 i poza tym musi być zgodny z przetestowanym poleceniem.
• Endpoint nie może znaleźć wag. Punkt wejścia działa w folderze artefaktów modelu, więc --model musi wskazywać folder wag, który zarejestrowałeś.
• Model embeddingów nie zwraca embeddingów. Uruchom vLLM za pomocą --runner pooling.
• Rejestracja kończy się niepowodzeniem z TimeoutError('Timed out after 0:05:00') podczas przesyłania model_version.tar lub model_environment.tar. Zaktualizuj do databricks-sdk wersji 0.102.0 lub wyższej i ponownie zarejestruj model.

Tworzenie punktu końcowego

Utwórz endpoint z interfejsu Serving UI lub za pomocą Databricks SDK, tak jak robią to notatniki startowe. workload_type wybiera GPU, a workload_size (Small, Medium, lub Large) ustala liczbę replik.

ServedEntityInput(
    entity_name="<catalog>.<schema>.<model>",
    entity_version="<version>",
    workload_type=ServingModelWorkloadType.GPU_MEDIUM,
    workload_size="Small",
    scale_to_zero_enabled=False,
)

Skalowanie do zera i wydajność

Obecnie niestandardowe endpointy LLM nie skalują się dynamicznie, więc dobierz rozmiar workload_size do szczytowego ruchu.

W przypadku skalowania do zera wszystkie repliki bezczynnego punktu końcowego są zatrzymywane. Kolejne żądanie czeka od jednej do kilku minut, podczas gdy vLLM ponownie ładuje model i wszystkie repliki się uruchamiają. Azure Databricks zaleca wyłączenie scale-to-zero dla ruchu produkcyjnego.

Wykonywanie zapytań względem punktu końcowego

W AI Playground pojawia się gotowy punkt końcowy czatu. Poniższe przykłady zapytują punkt końcowy za pomocą SDK Databricks, klienta OpenAI oraz REST.

Databricks SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ChatMessage, ChatMessageRole

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

Klient OpenAI

from openai import 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"}])
client.embeddings.create(model="<endpoint-name>", input=["The quick brown fox jumps over the lazy dog."])
with open("speech.flac", "rb") as audio:
    client.audio.transcriptions.create(model="<endpoint-name>", file=audio)

REST: czat

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

REST: embeddingi

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

Niektóre modele osadzania oczekują prefiksu na każdym wejściu, takiego jak search_query: lub search_document:. Sprawdź kartę modelu.

Zapytanie do adaptera LoRA

Aby wybrać adapter LoRA, wyślij żądanie czatu OpenAI do https://<workspace-url>/serving-endpoints/chat/completions. Ustaw nagłówek Databricks-Model-Serving-Endpoint na nazwę swojego punktu końcowego, a adapter nazwij w model. Nieznana nazwa zwraca błąd. Adres URL punktu końcowego /invocations, pakiet SDK Databricks query i ai_query ignorują nazwę adaptera i używają modelu bazowego.

Klient OpenAI

from openai import OpenAI

client = OpenAI(
    api_key=DATABRICKS_TOKEN,
    base_url=f"{DATABRICKS_HOST}/serving-endpoints",
    default_headers={"Databricks-Model-Serving-Endpoint": "<endpoint-name>"},
)
client.chat.completions.create(model="finance", messages=[{"role": "user", "content": "What is EBITDA?"}])

REST

curl -X POST \
  -u "token:$DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Databricks-Model-Serving-Endpoint: <endpoint-name>" \
  -d '{"model":"finance","messages":[{"role":"user","content":"What is EBITDA?"}]}' \
  https://<workspace-url>/serving-endpoints/chat/completions

Monitoruj swój punkt końcowy

Zakładka Logi punktu końcowego pokazuje na żywo stdout i stderr Twojego serwera. API logów zwraca ten sam wynik.

Azure Databricks przekazuje metryki serwera vLLM i wyświetla je na karcie Metrics punktu końcowego:

• Opóźnienia: czas do pierwszego tokena, czas na token wyjściowy, opóźnienie żądań oraz czas kolejki.
• Obciążenie: żądania działające i oczekujące.
• Pamięć podręczna KV: użycie i wskaźnik trafień.
• Przepustowość: tokeny promptu i generowania na sekundę.

API eksportu metryk zwraca te same metryki w formacie Prometheus, więc możesz je pobierać do Prometheus lub Datadog.

Przy włączonej telemetrii, Azure Databricks zapisuje także logi serwera oraz metryki vLLM Prometheus w tabelach katalogu Unity, dzięki czemu można je zapytać przez dłuższy czas. Zobacz Utrwalanie danych obsługi niestandardowych modeli w katalogu Unity.

Pricing

Płacisz za każdą godzinę instancji GPU, tak samo jak za inne usługi udostępniania niestandardowych modeli GPU. Zobacz ceny Model Serving.

Ograniczenia i dostępność regionów

Rejestrujesz niestandardowy model LLM z AI Runtime, więc obsługa niestandardowych modeli LLM jest dostępna w tych samych regionach co bezserwerowe obliczenia GPU. To są regiony USA na AWS i Azure. GCP nie jest obsługiwany.

Następujące funkcje nie są obsługiwane:

• Obsługa międzyregionalna.
• Logowanie modeli poza AI Runtime, na przykład z Databricks Runtime lub bezserwerowego CPU.
• Routing uwzględniający pamięć podręczną KV.
• Optymalizacja tras.