Samouczek KTransformers: uruchom GLM-5.3-Flash lokalnie

KTransformers to otwartoźródłowe środowisko inference, które pozwala CPU i GPU aktywnie wykonywać różnych ekspertów podczas wnioskowania, dzięki czemu uruchomisz modele Mixture-of-Experts (MoE) znacznie większe niż pamięć twojej karty graficznej. Frameworki takie jak vLLM także potrafią przenosić wagi do pamięci CPU, ale KTransformers jest zbudowany specjalnie z myślą o rzadkiej strukturze modeli MoE.

W tym samouczku użyjemy KTransformers i SGLang, aby uruchomić GLM-5.3-Flash, model z 320 mld parametrów, którego wagi nie mieszczą się w 192 GB VRAM. Będziemy monitorować użycie pamięci CPU i GPU, poeksperymentujemy z rozmieszczeniem ekspertów, przetestujemy zgodne z OpenAI API i połączymy model z Pi jako lokalnym agentem do kodowania.

Główna idea jest prosta: zamiast traktować pamięć CPU jako bufor na przepełnienie, KTransformers używa zarówno mocy obliczeniowej CPU, jak i GPU podczas wnioskowania.

W skrócie

• KTransformers uruchamia duże modele MoE na VRAM GPU i RAM systemu, przy czym CPU oblicza ekspertów trzymanych w RAM.
• Natywne wagi FP8 GLM-5.3-Flash zajmują około 306 GiB, więc oficjalny poradnik zaleca co najmniej 350 GB dostępnej pamięci systemowej.
• Uruchomiliśmy pełny model na 2× RTX PRO 6000 (łącznie 192 GB VRAM) z oknem kontekstu 32K, osiągając około 11 tokenów na sekundę.
• Serwer udostępnia API zgodne z OpenAI, więc agenci kodujący tacy jak Pi mogą używać modelu bezpośrednio.

Czym jest KTransformers?

KTransformers to otwartoźródłowe środowisko inference do uruchamiania bardzo dużych modeli językowych, wykorzystujące połączenie VRAM GPU i RAM CPU. Zwykle serwowanie dużego modelu wymaga załadowania większości jego wag do pamięci GPU, co szybko staje się kosztowne przy rozmiarze takim jak GLM-5.3-Flash.

KTransformers podchodzi do tego inaczej: trzyma wielu ekspertów MoE w pamięci systemowej i rezerwuje pamięć GPU dla części wnioskowania, które najbardziej korzystają z akceleracji GPU.

To dobrze działa dla modeli MoE, ponieważ nie każdy ekspert jest używany dla każdego tokena. GLM-5.3-Flash ma na przykład 288 ekspertów trasowanych, ale jego router wybiera tylko 8 z nich (plus 1 współdzielonego eksperta) dla każdego tokena. Dlatego KTransformers może rozdzielać obliczenia ekspertów między CPU i GPU:

Jak KT-Kernel i SGLang współpracują

Obecny stos KTransformers integruje KT-Kernel z SGLang do heterogenicznego wnioskowania CPU-GPU. Każdy komponent odpowiada za inny obszar:

• SGLang zapewnia runtime serwujący: żądania API, batchowanie, kolejkowanie żądań, zarządzanie pamięcią podręczną KV oraz równoległość GPU.
• KT-Kernel zastępuje standardową ścieżkę wykonania MoE wariantem świadomym CPU-GPU. Wybrani eksperci działają na GPU, pozostali zostają w pamięci CPU i są liczeni na CPU.

KTransformers wspiera też zmianę rozmieszczenia ekspertów w zależności od wzorców obciążenia, jak opisano w samouczku planowania ekspertów.

Innymi słowy, KTransformers traktuje pamięć CPU i GPU jako wspólny system wnioskowania, zamiast wymagać, by cały model mieścił się w VRAM. To właśnie pozwala uruchamiać bardzo duże modele MoE na sprzęcie z dużo mniejszą pamięcią GPU, niż normalnie byłaby potrzebna.

Czym jest GLM-5.3-Flash?

GLM-5.3-Flash to model MoE Z.ai o otwartych wagach, natywnie multimodalny, wydany na licencji MIT w sierpniu 2026. Mimo nazwy „Flash” jest to duży model: 320 mld parametrów łącznie, z około 18 mld aktywnych na token.

To są najważniejsze specyfikacje dla lokalnego inference:

• Eksperci: 288 ekspertów trasowanych z trasowaniem top-8, plus 1 ekspert współdzielony
• Wagi: około 306 GiB dla oficjalnego checkpointu FP8 (zai-org/GLM-5.3-Flash)
• Okno kontekstu: do 1M tokenów
• Wejścia: tekst, obrazy i wideo, ze wsparciem dla rozumowania i wywoływania narzędzi

KTransformers czyta oficjalne wagi FP8 bezpośrednio, więc nie ma potrzeby konwersji ani dodatkowej kwantyzacji. Benchmarki i pełny przegląd modelu znajdziesz w naszym poradniku GLM-5.3-Flash.

Wymagania sprzętowe GLM-5.3-Flash

W przypadku GLM-5.3-Flash pytanie o sprzęt dotyczy głównie pamięci systemowej. Oficjalny samouczek KTransformers dla GLM-5.3-Flash zaleca zarezerwowanie co najmniej 350 GB dostępnej pamięci.

Zalecana konfiguracja: 2× RTX PRO 6000

W tym samouczku używamy instancji RunPod z mniej więcej:

GPU:         2× RTX PRO 6000
VRAM:        96 GB each
Total VRAM:  192 GB

System RAM:  350 GB+
Storage:     500 GB+
Python:      3.11

Oficjalny checkpoint FP8 GLM-5.3-Flash ma około 306 GiB (około 329 GB), podczas gdy nasze dwie karty graficzne zapewniają łącznie 192 GB VRAM. Pełny model nie może więc po prostu zostać załadowany do pamięci GPU.

Zamiast tego KTransformers trzyma dużą część wag ekspertów MoE w RAM systemu i przenosi najbardziej użyteczne obliczenia na GPU. Rekomendacja 350 GB zostawia dość miejsca na wagi modelu plus narzut uruchomieniowy.

Więcej pamięci GPU nie eliminuje potrzeby RAM w tym układzie. Pamięć CPU to celowy element heterogenicznego projektu inference KTransformers: wagi ekspertów pozostają w RAM, a GPU obsługuje te części modelu, które najbardziej korzystają z akceleracji.

Obecna implementacja GLM-5.3-Flash ma też konkretne wymagania dla CPU i GPU:

• GPU: architektury NVIDIA SM89 lub SM120, obejmujące serie RTX 40, RTX 50 oraz karty stacji roboczych Blackwell, takie jak RTX PRO 6000.
• CPU: wsparcie AVX-512, na którym opiera się jądro ekspertów FP8 na CPU.

Czy uruchomisz GLM-5.3-Flash na pojedynczym GPU?

Tak, pod warunkiem że masz wystarczająco dużo RAM i wspierany CPU. Oficjalny samouczek zawiera konfigurację z jednym GPU, ustawiając --kt-num-gpu-experts 0, dzięki czemu eksperci MoE są liczeni po stronie CPU.

Tutaj używamy dwóch RTX PRO 6000, ale to nie jest sztywny wymóg minimalny. Druga karta daje więcej VRAM i zapas podczas eksperymentów z dość nową implementacją KTransformers, zamiast stroić konfigurację pod najmniejszy sprzęt, który „jakoś” uruchomi model.

Krok 1: Zainstaluj KTransformers z SGLang

Utwórz czyste środowisko Python 3.11 i zainstaluj KTransformers ze wsparciem SGLang:

python3.11 -m venv /workspace/kt
source /workspace/kt/bin/activate

pip install --upgrade pip
pip install "ktransformers[sglang]"

Sprawdź, czy KTransformers, KT-Kernel, SGLang i CUDA są poprawnie wykryte:

kt version

Powinieneś zobaczyć wyjście podobne do:

KTransformers CLI v0.7.0.post4

Python      3.11.13
Platform    Linux 6.8.0-136-generic
CUDA        13.0

Packages:
kt-kernel   0.7.0.post4
sglang-kt   0.7.0.post4

To potwierdza, że runtime KTransformers i jego backend SGLang są zainstalowane i gotowe do użycia.

Krok 2: Pobierz GLM-5.3-Flash z Hugging Face

Przed uruchomieniem serwera pobierz oficjalny checkpoint GLM-5.3-Flash z Hugging Face:

hf download zai-org/GLM-5.3-Flash \
  --local-dir /workspace/GLM-5.3-Flash

Checkpoint ma około 306 GiB, więc pobieranie może potrwać w zależności od twojego łącza.

Następnie wskaż KTransformers lokalną ścieżkę do modelu:

export MODEL_PATH=/workspace/GLM-5.3-Flash

Krok 3: Uruchom serwer GLM-5.3-Flash z SGLang

Uruchom teraz GLM-5.3-Flash z dwukierunkowym równolegleniem tensorów, używając obu kart RTX PRO 6000. Model wspiera do 1M tokenów kontekstu, a oficjalne przykłady używają zweryfikowanej konfiguracji 501 025 tokenów. My zaczynamy od okna 32K, żeby podczas testów utrzymać przewidywalne zużycie pamięci.

CUDA_VISIBLE_DEVICES=0,1 \
python -m sglang.launch_server \
  --model-path "$MODEL_PATH" \
  --kt-weight-path "$MODEL_PATH" \
  --served-model-name GLM-5.3-flash \
  --host 0.0.0.0 \
  --port 30000 \
  --tp-size 2 \
  --context-length 32768 \
  --max-total-tokens 32768 \
  --mem-fraction-static 0.85 \
  --chunked-prefill-size 2048 \
  --kt-method FP8 \
  --kt-cpuinfer 64 \
  --kt-threadpool-count 2 \
  --kt-num-gpu-experts 14 \
  --kt-gpu-prefill-token-threshold 2048 \
  --kt-expert-placement-strategy uniform \
  --cuda-graph-bs 1 2 4 \
  --enable-p2p-check \
  --tool-call-parser glm47 \
  --reasoning-parser glm45

Ta konfiguracja udostępnia model przez serwer SGLang zgodny z OpenAI na porcie 30000. Dwie karty GPU są użyte z --tp-size 2, a KTransformers utrzymuje część pracy MoE na CPU i umieszcza wybranych ekspertów na GPU.

Ustawienia są celowo zachowawcze na pierwszy start: kontekst 32K, 85% statycznego użycia pamięci GPU, 14 ekspertów GPU i 64 wątki inference na CPU. Gdy serwer będzie stabilny, możesz eksperymentować z większym oknem, większą liczbą ekspertów GPU lub innymi ustawieniami pamięci, by poprawić przepustowość.

Wyjaśnienie kluczowych flag uruchomieniowych KTransformers

Większość powyższych flag to standardowe opcje SGLang. Te sterują tym, jak KTransformers dzieli pracę między CPU i GPU:

Krok 4: Przetestuj offloading CPU-GPU i rozmieszczenie ekspertów

Skoro serwer działa, możemy sprawdzić, jak KTransformers używa VRAM GPU i RAM systemu, a następnie zmieniać liczbę ekspertów rezydujących na GPU, by zobaczyć, jak zmienia się użycie zasobów i wydajność.

Na RunPod free -h może być mylące, bo kontener może widzieć całkowity RAM hosta zamiast faktycznie dostępnej pamięci dla poda. Lepiej monitorować osobno pamięć GPU i pamięć kontenera.

Monitoruj użycie VRAM GPU

Otwórz nowy terminal i monitoruj użycie GPU:

watch -n 1 nvidia-smi

Przy naszej konfiguracji w pełni załadowany model zużywa około 48 GB na GPU, zostawiając spory zapas VRAM. To sugeruje, że można umieścić więcej ekspertów na GPU albo przetestować konfigurację z pojedynczym GPU, jeśli RAM systemu wystarczy.

Monitoruj RAM kontenera na RunPod

Dla pamięci kontenera odczytaj bezpośrednio liczniki pamięci cgroup:

watch -n 1 'echo -n "Used: "; awk "{printf \"%.1f GiB\n\", \$1/1024/1024/1024}" /sys/fs/cgroup/memory.current; echo -n "Limit: "; awk "{printf \"%.1f GiB\n\", \$1/1024/1024/1024}" /sys/fs/cgroup/memory.max'

Powinieneś zobaczyć, że duża część dostępnego RAM jest zajęta przez wagi modelu i ekspertów liczących po stronie CPU. To oczekiwane: KTransformers celowo trzyma wielu ekspertów MoE w RAM zamiast wymagać, by wszyscy mieścili się w VRAM.

Strojenie --kt-num-gpu-experts

Następnie uruchom ponownie serwer z różnymi wartościami --kt-num-gpu-experts. Na przykład porównaj:

0
10
20

--kt-num-gpu-experts steruje liczbą ekspertów na warstwę MoE umieszczanych na GPU. Przy 0 obliczenia ekspertów pozostają po stronie CPU; zwiększanie tej wartości przenosi więcej ekspertów do pamięci GPU.

Dla każdej konfiguracji porównaj użycie VRAM GPU, użycie RAM kontenera, tokeny na sekundę i czas do pierwszego tokena. Generalnie, więcej ekspertów na GPU zużywa więcej VRAM, ale ogranicza wykonywanie ekspertów na CPU, co może poprawić wydajność inference, jeśli VRAM wystarczy.

Jedno zastrzeżenie z oficjalnego samouczka: gdy dla GLM-5.3-Flash włączone jest Layerwise Prefill, obecna implementacja normalizuje liczbę rezydujących ekspertów GPU do zera. Jeśli użycie VRAM ledwie się zmienia między uruchomieniami, to prawdopodobna przyczyna.

Ten eksperyment pokazuje kluczową zaletę KTransformers: RAM CPU i VRAM GPU stają się strojeniowalnymi elementami jednego systemu wnioskowania, więc możesz wymieniać rozmieszczenie pamięci na prędkość, zamiast wymagać, by cały model MoE mieścił się na GPU.

Krok 5: Przetestuj API zgodne z OpenAI

Gdy serwer działa, możemy potwierdzić, że model jest dostępny, i wysłać realne żądanie przez zgodne z OpenAI API SGLang.

Najpierw sprawdź, czy model jest zarejestrowany:

curl http://localhost:30000/v1/models

Następnie wyślij testowy prompt:

curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "GLM-5.3-flash",
    "messages": [
      {
        "role": "user",
        "content": "Create a FastAPI application with a health endpoint."
      }
    ],
    "max_tokens": 500
  }'

Jeśli konfiguracja działa poprawnie, serwer zwróci standardową odpowiedź chat completion zawierającą wygenerowany kod i statystyki użycia.

Krok 6: Użyj GLM-5.3-Flash jako lokalnego agenta kodującego z Pi

Pi to lekki agent kodujący, który może używać dowolnego modelu zgodnego z OpenAI jako backendu, co pozwala GLM-5.3-Flash pracować bezpośrednio nad zadaniami programistycznymi, a nie tylko odpowiadać na prompty.

Zainstaluj Pi

Zainstaluj Pi skryptem instalacyjnym:

curl -fsSL https://pi.dev/install.sh | sh

Następnie dodaj Pi do zmiennej PATH:

echo 'export PATH="/root/.local/share/pi-node/current/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Skieruj Pi na serwer KTransformers

Utwórz konfigurację modelu, która wskaże Pi lokalny serwer KTransformers:

mkdir -p ~/.pi/agent && cat > ~/.pi/agent/models.json <<'EOF'
{
  "providers": {
    "ktransformers": {
      "baseUrl": "http://localhost:30000/v1",
      "api": "openai-completions",
      "apiKey": "local",
      "models": [
        {
          "id": "GLM-5.3-flash",
          "name": "GLM-5.3-Flash",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 32768,
          "maxTokens": 8192,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}
EOF

Uruchom Pi:

pi

Następnie otwórz selektor modelu:

/model

Uruchom zadanie kodowania z GLM-5.3-Flash

Wybierz GLM-5.3-Flash i spróbuj realnego zadania programistycznego:

Build a FastAPI service with /health and /users endpoints.
Add pytest tests and run them.

Po kilku sekundach Pi powinien zacząć tworzyć pliki, pisać API, uruchamiać testy i poprawiać problemy w trakcie pracy nad zadaniem.

Możesz też obserwować pierwszy terminal, w którym działa serwer SGLang. W naszym teście szybkość generacji wynosiła około 11 tokenów na sekundę. To rozsądny wynik dla modelu tej wielkości działającego z znacznym offloadingiem na CPU, a konfigurację można dalej stroić, przenosząc więcej ekspertów na GPU.

W ciągu kilku minut model utworzył endpointy, napisał i wykonał testy, zrobił smoke test i przygotował krótkie podsumowanie wyjaśniające, jak uruchomić projekt.

Co ciekawe, kompletny model działa lokalnie, mimo że jego wagi są znacznie większe niż dostępny VRAM GPU. Pi obsługuje pętlę agenta kodującego, a SGLang i KTransformers odpowiadają za właściwe wnioskowanie modelu.

KTransformers vs vLLM vs llama.cpp

KTransformers to nie jedyny sposób na uruchomienie modelu większego niż twój VRAM. vLLM i llama.cpp także wspierają offloading na CPU, ale dzielą pracę inaczej:

W tym układzie SGLang i KTransformers nie konkurują. SGLang obsługuje serwowanie, a KTransformers realizuje heterogeniczne wykonanie MoE na CPU i GPU.

Na koniec

Najbardziej spodobało mi się to, że KTransformers robi coś nieco innego niż zwykły stos inference. Zamiast myśleć tylko w kategoriach warstw modelu, umieszcza pojedynczych ekspertów na GPU, a innych trzyma w RAM systemu, i CPU rzeczywiście bierze udział w obliczeniach ekspertów. CPU nie jest tylko „magazynem na przelewające się dane”.

W tym samouczku uruchomiliśmy pełny model GLM-5.3-Flash lokalnie na dwóch RTX PRO 6000, mimo że jego wagi są dużo większe niż dostępny VRAM.

To nie najszybsza konfiguracja. U mnie było około 11 tokenów na sekundę i nadal jest sporo miejsca na strojenie liczby i rozmieszczenia ekspertów GPU. Możesz też poeksperymentować z jednym GPU, jeśli masz dość RAM; ja użyłem dwóch, żeby dać konfiguracji większy zapas.

Dla mnie to główny wniosek z tego przewodnika: KTransformers nie jest wyjątkowy dlatego, że „wynalazł” offloading na CPU. Jest wyjątkowy, bo sprawia, że RAM CPU, moc obliczeniowa CPU i GPU współpracują ze sobą wokół rzadkiej struktury modeli MoE.