1. Wprowadzenie
Duże modele językowe (LLM) zmieniają sposób tworzenia inteligentnych aplikacji. Przygotowanie tych zaawansowanych modeli do użytku w rzeczywistym świecie może być jednak trudne. Potrzebują dużej mocy obliczeniowej, zwłaszcza kart graficznych (GPU), i inteligentnych sposobów obsługi wielu żądań naraz. Chcesz też ograniczyć koszty i zapewnić płynne działanie aplikacji bez opóźnień.
Z tego laboratorium dowiesz się, jak sobie z nimi poradzić. Użyjemy 2 kluczowych narzędzi:
- vLLM to bardzo szybki silnik dla LLM. Dzięki temu modele działają znacznie wydajniej, obsługując więcej żądań naraz i zmniejszając zużycie pamięci.
- Google Cloud Run: to bezserwerowa platforma Google. Jest to świetne rozwiązanie do wdrażania aplikacji, ponieważ automatycznie skaluje zasoby – od zera do tysięcy użytkowników i z powrotem. Co najważniejsze, Cloud Run obsługuje teraz procesory graficzne, które są niezbędne do hostowania LLM.
vLLM i Cloud Run to wydajny, elastyczny i ekonomiczny sposób udostępniania dużych modeli językowych. Z tego przewodnika dowiesz się, jak wdrożyć otwarty model, aby był dostępny jako standardowy interfejs API sieciowy.
Czego się nauczysz:
- Jak wybrać odpowiedni rozmiar i wersję modelu do wyświetlania.
- Jak skonfigurować vLLM do obsługi punktów końcowych interfejsu API zgodnych z OpenAI.
- Jak konteneryzować serwer vLLM za pomocą Dockera.
- Jak przesłać obraz kontenera do Google Artifact Registry.
- Jak wdrożyć kontener w Cloud Run z akceleracją GPU.
- Jak przetestować wdrożony model.
Co będzie Ci potrzebne:
- przeglądarka, np. Chrome, do uzyskiwania dostępu do konsoli Google Cloud;
- stabilne połączenie z internetem,
- Projekt Google Cloud z włączonymi płatnościami
- Token dostępu Hugging Face (jeśli go jeszcze nie masz, możesz go utworzyć tutaj).
- Podstawowa znajomość języka Python, Dockera i interfejsu wiersza poleceń
- ciekawość i chęć do nauki,
2. Zanim zaczniesz
Konfigurowanie projektu Google Cloud
Te ćwiczenia wymagają projektu Google Cloud z aktywnym kontem rozliczeniowym.
- W przypadku sesji prowadzonych przez instruktora: jeśli jesteś w klasie, instruktor przekaże Ci niezbędne informacje o projekcie i rozliczeniach. Aby dokończyć konfigurację, postępuj zgodnie z instrukcjami instruktora.
- Dla osób uczących się samodzielnie: jeśli uczysz się samodzielnie, musisz skonfigurować nowy projekt i aktywować próbne konto rozliczeniowe. Aby rozpocząć, wykonaj czynności opisane poniżej.
- Otwórz okno incognito, naciskając Ctrl + Shift + N lub Cmd + Shift + N.
- Otwórz ten portal do realizacji w oknie incognito.
- Zaloguj się i utwórz próbne konto rozliczeniowe za pomocą osobistego konta Gmail.
- Aby dokończyć konfigurację, postępuj zgodnie z instrukcjami z tej prezentacji.
Konfigurowanie Cloud Shell
Teraz skonfigurujmy Cloud Shell, czyli wygodny interfejs wiersza poleceń dostępny bezpośrednio w konsoli Google Cloud.
Uruchom Cloud Shell
W prawym górnym rogu konsoli Google Cloud zobaczysz ikonę przypominającą terminal (>_). Kliknij ją, aby aktywować Cloud Shell.
Przyznaj dostęp
Jeśli pojawi się pytanie o autoryzację Cloud Shell, kliknij Autoryzuj, aby przyznać jej uprawnienia niezbędne do interakcji z Twoim projektem Google Cloud.
Weryfikacja identyfikatora projektu
Spójrz na tekst Project ID w terminalu. Będzie napisany na żółto, jak pokazano na obrazie poniżej. Upewnij się, że jest to ten sam identyfikator, który został zarejestrowany podczas tworzenia projektu.
Jeśli znak Project ID jest prawidłowo wyświetlany w terminalu, przejdź do kroku Włącz niezbędne interfejsy API.
Prawidłowy identyfikator projektu (w razie potrzeby)
Jeśli symbol Project ID jest nieprawidłowy lub w ogóle się nie wyświetla, użyj tego polecenia, aby to naprawić. Przed uruchomieniem polecenia zastąp tekst your-project-id prawidłowym Project ID.
gcloud config set project your-project-id
Włączanie niezbędnych interfejsów API
Aby korzystać z usług Google Cloud, takich jak Cloud Run, musisz najpierw aktywować odpowiednie interfejsy API w swoim projekcie. Aby włączyć usługi niezbędne do tego modułu, uruchom w Cloud Shell te polecenia:
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com
3. Wybór odpowiedniego modelu
Wiele modeli open source znajdziesz w witrynach takich jak Hugging Face Hub i Kaggle. Jeśli chcesz używać jednego z tych modeli w usłudze takiej jak Google Cloud Run, musisz wybrać model, który pasuje do Twoich zasobów (np. GPU NVIDIA L4).
Pamiętaj, że oprócz rozmiaru należy wziąć pod uwagę, co model może faktycznie zrobić. Modele nie są takie same; każdy ma swoje zalety i wady. Na przykład niektóre modele mogą obsługiwać różne typy danych wejściowych (np. obrazy i tekst – tzw. możliwości wielomodalne), a inne mogą zapamiętywać i przetwarzać więcej informacji naraz (co oznacza, że mają większe okna kontekstu). Większe modele często mają bardziej zaawansowane funkcje, takie jak wywoływanie funkcji i myślenie.
Ważne jest też sprawdzenie, czy wybrany model jest obsługiwany przez narzędzie do obsługi (w tym przypadku vLLM). Wszystkie modele obsługiwane przez vLLM znajdziesz tutaj.
Przyjrzyjmy się teraz Gemmie 3, najnowszej rodzinie otwartych dużych modeli językowych (LLM) od Google. Gemma 3 jest dostępna w 4 wersjach różniących się złożonością, która jest mierzona w parametrach: 1 miliard, 4 miliardy, 12 miliardów i aż 27 miliardów.
W przypadku każdego z tych rozmiarów znajdziesz 2 główne typy:
- Wersja podstawowa (wstępnie wytrenowana): to model podstawowy, który został wytrenowany na podstawie ogromnej ilości danych.
- Wersja dostosowana do instrukcji: ta wersja została dodatkowo ulepszona, aby lepiej rozumieć i wykonywać konkretne instrukcje lub polecenia.
Większe modele (4 miliardy, 12 miliardów i 27 miliardów parametrów) są wielomodalne, co oznacza, że mogą rozumieć i przetwarzać zarówno obrazy, jak i tekst. Najmniejsza wersja z 1 miliardem parametrów jest jednak przeznaczona wyłącznie do przetwarzania tekstu.
W tym ćwiczeniu użyjemy miliarda wariantów modelu Gemma 3: gemma-3-1b-it. Korzystanie z mniejszego modelu pomaga też nauczyć się pracy z ograniczonymi zasobami, co jest ważne, aby obniżyć koszty i zapewnić płynne działanie aplikacji w chmurze.
4. Zmienne środowiskowe i obiekty tajne
Tworzenie pliku środowiska
Zanim przejdziemy dalej, warto zebrać w jednym miejscu wszystkie konfiguracje, których będziesz używać podczas tych ćwiczeń z programowania. Aby rozpocząć, otwórz terminal i wykonaj te czynności:
- Utwórz nowy folder dla tego projektu.
- Przejdź do nowo utworzonego folderu.
- Utwórz w tym folderze pusty plik .env (będzie on później zawierać zmienne środowiskowe).
Oto polecenie, które umożliwia wykonanie tych czynności:
mkdir vllm-gemma3
cd vllm-gemma3
touch .env
Następnie skopiuj zmienne wymienione poniżej i wklej je do utworzonego właśnie pliku.env. Pamiętaj, aby zastąpić wartości zastępcze (your_project_id i your_region) informacjami o swoim projekcie. Na przykład (PROJECT_ID=unique-ai-project i REGION=us-central1)
PROJECT_ID=your_project_id
REGION=your_region
MODEL_PROVIDER=google
MODEL_VARIANT=gemma-3-1b-it
MODEL_NAME=${MODEL_PROVIDER}/${MODEL_VARIANT}
AR_REPO_NAME=vllm-gemma3-repo
SERVICE_NAME=${MODEL_VARIANT}-service
IMAGE_NAME=${REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/${SERVICE_NAME}
SERVICE_ACC_NAME=${SERVICE_NAME}-sa
SERVICE_ACC_EMAIL=${SERVICE_ACC_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
Po zmodyfikowaniu i zapisaniu pliku.env wpisz to polecenie, aby załadować zmienne środowiskowe do sesji terminala:
source .env
Możesz sprawdzić, czy zmienne zostały wczytane, wyświetlając jedną z nich. Na przykład:
echo $SERVICE_NAME
Jeśli otrzymasz taką samą wartość, jaką przypisano w pliku.env, zmienne zostały wczytane prawidłowo.
Przechowywanie obiektu tajnego w usłudze Secret Manager
W przypadku danych wrażliwych, w tym kodów dostępu, danych logowania i haseł, zalecamy korzystanie z menedżera obiektów tajnych.
Przed użyciem modeli Gemma 3 musisz najpierw potwierdzić warunki korzystania z usługi, ponieważ są one ograniczone. Otwórz kartę modelu Gamma3 w Hugging Face Hub i zaakceptuj warunki korzystania z usługi.
Gdy uzyskasz token dostępu Hugging Face, przejdź na stronę Secret Manager i utwórz obiekt tajny, wykonując te instrukcje.
- Otwórz konsolę Google Cloud
- Wybierz projekt z menu w lewym górnym rogu.
- Na pasku wyszukiwania wpisz Secret Manager i kliknij tę opcję, gdy się pojawi.
Gdy otworzysz stronę Secret Manager:
- Kliknij przycisk +Utwórz obiekt tajny.
- Podaj te informacje:
- Nazwa: HF_TOKEN
- Wartość obiektu tajnego: <your_hf_access_token>
- Gdy skończysz, kliknij przycisk Utwórz obiekt tajny.
Token dostępu Hugging Face powinien być teraz dostępny jako obiekt tajny w Google Cloud Secret Manager.
Możesz przetestować dostęp do obiektu tajnego, wykonując w terminalu to polecenie, które pobierze go z usługi Secret Manager:
gcloud secrets versions access latest --secret=HF_TOKEN
W oknie terminala powinien pojawić się pobrany token dostępu.
5. Tworzenie konta usługi
Aby zwiększyć bezpieczeństwo i skutecznie zarządzać dostępem w środowisku produkcyjnym, usługi powinny działać na dedykowanych kontach usługi, które są ściśle ograniczone do uprawnień niezbędnych do wykonywania określonych zadań.
Uruchom to polecenie, aby utworzyć konto usługi
gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'
To polecenie przyznaje niezbędne uprawnienia.
gcloud secrets add-iam-policy-binding HF_TOKEN \
--member="serviceAccount:${SERVICE_ACC_EMAIL}" \
--role="roles/secretmanager.secretAccessor"
6. Tworzenie obrazu w Artifact Registry
Ten krok obejmuje utworzenie obrazu Dockera, który zawiera wagi modelu i wstępnie zainstalowany vLLM.
1. Tworzenie repozytorium Dockera w Artifact Registry
Utwórzmy repozytorium Dockera w Artifact Registry, do którego będziesz przesyłać utworzone obrazy. Uruchom w terminalu to polecenie:
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. Przechowywanie modelu
Zgodnie z dokumentacją dotyczącą sprawdzonych metod korzystania z GPU możesz przechowywać modele ML w obrazach kontenerów lub zoptymalizować ich ładowanie z Cloud Storage. Oczywiście każde podejście ma swoje zalety i wady. Więcej informacji znajdziesz w dokumentacji. Dla uproszczenia model będzie przechowywany w obrazie kontenera.
3. Tworzenie pliku Dockera
Utwórz plik o nazwie Dockerfile i skopiuj do niego poniższą treść:
FROM vllm/vllm-openai:v0.9.0
ARG MODEL_NAME
ARG HF_TOKEN
ENV HF_HOME=/model-cache
ENV MODEL_NAME=${MODEL_NAME}
# Use the HF_TOKEN argument to log in and download the model
RUN huggingface-cli login --token ${HF_TOKEN} && \
huggingface-cli download ${MODEL_NAME}
ENV HF_HUB_OFFLINE=1
EXPOSE 8080
ENTRYPOINT python3 -m vllm.entrypoints.openai.api_server \
--port ${PORT:-8080} \
--model ${MODEL_NAME} \
--gpu-memory-utilization 0.90 \
${MAX_MODEL_LEN:+--max-model-len "$MAX_MODEL_LEN"}
4. Tworzenie pliku cloudbuild.yaml
Następnie w tym samym katalogu utwórz plik o nazwie cloudbuild.yaml. Ten plik określa czynności, które ma wykonać Cloud Build. Skopiuj i wklej do pliku cloudbuild.yaml tę treść:
steps:
- name: 'gcr.io/cloud-builders/docker'
entrypoint: 'bash'
args:
- '-c'
- |
docker build \
--build-arg MODEL_NAME=${_MODEL_NAME} \
--build-arg HF_TOKEN=$$HF_TOKEN_SECRET \
-t ${_IMAGE_NAME} .
secretEnv: ['HF_TOKEN_SECRET']
images:
- '${_IMAGE_NAME}'
availableSecrets:
secretManager:
- versionName: projects/${PROJECT_ID}/secrets/HF_TOKEN/versions/latest
env: 'HF_TOKEN_SECRET'
5. Przesyłanie kompilacji do Cloud Build
Skopiuj i wklej ten kod, a potem uruchom go w terminalu:
gcloud builds submit . \
--config=cloudbuild.yaml \
--region=${REGION} \
--substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}
To polecenie przesyła kod (Dockerfile i cloudbuild.yaml), przekazuje zmienne powłoki jako podstawienia (_MODEL_NAME i _IMAGE_NAME) oraz rozpoczyna kompilację.
Cloud Build wykona teraz kroki zdefiniowane w pliku cloudbuild.yaml. Logi możesz śledzić w terminalu lub klikając link do szczegółów kompilacji w konsoli Cloud. Po zakończeniu obraz kontenera będzie dostępny w repozytorium Artifact Registry i gotowy do wdrożenia.
7. Testowanie usługi
Aby utworzyć serwer proxy, który umożliwi Ci dostęp do usługi działającej na hoście lokalnym, uruchom w terminalu to polecenie:
gcloud run services proxy ${SERVICE_NAME} --region ${REGION}
W nowym oknie terminala uruchom to polecenie curl, aby przetestować połączenie.
curl -X POST http://localhost:8080/v1/completions \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-1b-it",
"prompt": "Cloud Run is a ",
"max_tokens": 128,
"temperature": 0.90
}'
Jeśli zobaczysz dane wyjściowe podobne do tych poniżej:
{"id":"cmpl-e96d05d2893d42939c1780d44233defa","object":"text_completion","created":1746870778,"model":"google/gemma-3-1b-it","choices":[{"index":0,"text":"100% managed Kubernetes service. It's a great option for many use cases.\n\nHere's a breakdown of key features and considerations:\n\n* **Managed Kubernetes:** This means Google handles the underlying infrastructure, including scaling, patching, and maintenance. You don't need to worry about managing Kubernetes clusters.\n* **Serverless:** You only pay for the compute time your application actually uses. No charges when your code isn't running.\n* **Scalability:** Cloud Run automatically scales your application based on demand. You can easily scale up or down to handle fluctuating traffic.\n*","logprobs":null,"finish_reason":"length","stop_reason":null,"prompt_logprobs":null}],"usage":{"prompt_tokens":6,"total_tokens":134,"completion_tokens":128,"prompt_tokens_details":null}}
8. Podsumowanie
Gratulacje! To ćwiczenie zostało ukończone. Dowiedziałeś(-aś) się, jak:
- Wybierz odpowiedni rozmiar modelu na potrzeby docelowego wdrożenia.
- Skonfiguruj vLLM do obsługi interfejsu API zgodnego z OpenAI.
- Bezpiecznie umieść serwer vLLM i wagi modelu w kontenerze za pomocą Dockera.
- przesłać obraz kontenera do Google Artifact Registry,
- wdrożyć w Cloud Run usługę akcelerowaną przez GPU,
- Testowanie uwierzytelnionego wdrożonego modelu.
Możesz też wdrożyć inne ciekawe modele, takie jak Llama, Mistral czy Qwen, aby kontynuować naukę.
9. Czyszczenie
Aby uniknąć przyszłych opłat, usuń utworzone zasoby. Aby wyczyścić projekt, uruchom te polecenia:
1. Usuń usługę Cloud Run:
gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet
2. Usuń repozytorium Artifact Registry:
gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet
3. Usuń konto usługi:
gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet
4. Usuń obiekt tajny z usługi Secret Manager:
gcloud secrets delete HF_TOKEN --quiet