Schnellstart

Quelldateien

Diese Seite wurde aus den folgenden Quelldateien erstellt:

• README.md
• example.py
• pyproject.toml
• nanovllm/init.py
• bench.py
• nanovllm/llm.py
• nanovllm/config.py
• nanovllm/sampling_params.py
• nanovllm/models/qwen3.py
• nanovllm/utils/loader.py

Nano-vLLM ist eine leichtgewichtige Implementierung von vLLM, die von Grund auf neu entwickelt wurde. Das Projekt bietet vergleichbare Inferenzgeschwindigkeiten wie vLLM bei einer Codebasis von nur etwa 1.200 Zeilen Python-Code. Zu den Hauptmerkmalen gehören Prefix Caching, Tensor Parallelism, Torch Compilation und CUDA Graph Unterstützung (README.md:1-66).

Installation und Voraussetzungen

Die Installation von nano-vLLM erfolgt direkt über das GitHub-Repository mittels pip. Der offizielle Installationsbefehl lautet:

bash
1pip install git+https://github.com/GeeeekExplorer/nano-vllm.git

(README.md:19-23)

Systemanforderungen

Das Projekt benötigt Python 3.10 bis 3.12 (Python 3.13 wird aktuell nicht unterstützt). Die folgenden Abhängigkeiten werden automatisch installiert:

(pyproject.toml:13-20)

Wichtiger Hinweis: Die Installation von flash-attn erfordert eine CUDA-fähige GPU und kann während des Kompilierungsprozesses einige Zeit in Anspruch nehmen. Es wird empfohlen, die Installation in einer isolierten virtuellen Umgebung durchzuführen.

Modell-Download

Für die Verwendung von nano-vLLM müssen die Modellgewichte manuell heruntergeladen werden. Das Projekt verwendet standardmäßig das Qwen3-0.6B Modell. Der Download erfolgt über die Hugging Face CLI:

bash
1huggingface-cli download --resume-download Qwen/Qwen3-0.6B \
2  --local-dir ~/huggingface/Qwen3-0.6B/ \
3  --local-dir-use-symlinks False

(README.md:25-32)

Der Pfad ~/huggingface/Qwen3-0.6B/ entspricht der Standardkonfiguration im Beispielcode. Bei der Initialisierung des Tokenizers und der LLM-Instanz wird dieser Pfad verwendet:

python
1path = os.path.expanduser("~/huggingface/Qwen3-0.6B/")
2tokenizer = AutoTokenizer.from_pretrained(path)
3llm = LLM(path, enforce_eager=True, tensor_parallel_size=1)

(example.py:7-9)

Alternative Modellpfade

Der Modellpfad kann an jeden lokalen Verzeichnispfad angepasst werden, solange die Modellkonfiguration und die Gewichte im safetensors-Format vorliegen. Die Konfigurationsklasse validiert, dass der angegebene Pfad ein gültiges Verzeichnis ist (nanovllm/config.py:21).

Grundlegende Verwendung

Die API von nano-vLLM orientiert sich stark an der vLLM-Schnittstelle mit geringfügigen Unterschieden in der LLM.generate-Methode. Die wichtigsten Klassen werden direkt aus dem Hauptmodul exportiert:

python
1from nanovllm import LLM, SamplingParams

(nanovllm/init.py:1-2)

Minimales Beispiel

Das folgende Beispiel zeigt die kürzeste Möglichkeit, nano-vLLM zu verwenden:

python
1from nanovllm import LLM, SamplingParams
2
3llm = LLM("/YOUR/MODEL/PATH", enforce_eager=True, tensor_parallel_size=1)
4sampling_params = SamplingParams(temperature=0.6, max_tokens=256)
5prompts = ["Hello, Nano-vLLM."]
6outputs = llm.generate(prompts, sampling_params)
7outputs[0]["text"]

(README.md:34-44)

Die LLM-Klasse erbt von LLMEngine und stellt die Hauptschnittstelle für die Inferenz dar (nanovllm/llm.py:1-5).

Verwendung mit Chat-Templates

Für eine vollständige Konversation mit Chat-Templates kann der AutoTokenizer von transformers verwendet werden:

python
1from transformers import AutoTokenizer
2
3tokenizer = AutoTokenizer.from_pretrained(path)
4prompts = [
5    tokenizer.apply_chat_template(
6        [{"role": "user", "content": prompt}],
7        tokenize=False,
8        add_generation_prompt=True,
9    )
10    for prompt in prompts
11]

(example.py:16-23)

Sampling-Parameter

Die SamplingParams-Klasse steuert die Textgenerierung und bietet folgende Konfigurationsmöglichkeiten:

(nanovllm/sampling_params.py:1-11)

Temperatur-Einschränkungen

Ein wichtiger Unterschied zu vLLM ist, dass Greedy Sampling nicht erlaubt ist. Die Temperatur muss größer als 1e-10 sein:

python
1def __post_init__(self):
2    assert self.temperature > 1e-10, "greedy sampling is not permitted"

(nanovllm/sampling_params.py:10-11)

Beispielkonfiguration

Eine typische Konfiguration für die Textgenerierung sieht wie folgt aus:

python
1sampling_params = SamplingParams(temperature=0.6, max_tokens=256)

(example.py:11)

Für Benchmark-Zwecke kann der ignore_eos-Parameter verwendet werden, um die Generierung bis zum Erreichen von max_tokens zu erzwingen:

python
1sampling_params = SamplingParams(temperature=0.6, ignore_eos=True, max_tokens=randint(100, 1024))

(bench.py:18)

Engine-Konfiguration

Die Config-Klasse definiert die Engine-Parameter für die LLM-Initialisierung. Die wichtigsten Konfigurationsoptionen sind:

(nanovllm/config.py:6-18)

Tensor Parallelism

Für Multi-GPU-Setups kann der tensor_parallel_size-Parameter angepasst werden. Der Wert muss zwischen 1 und 8 liegen:

python
1assert 1 <= self.tensor_parallel_size <= 8

(nanovllm/config.py:23)

Eager Mode vs. CUDA Graphs

Der enforce_eager-Parameter steuert, ob CUDA Graphs verwendet werden:

• enforce_eager=True: Deaktiviert CUDA Graphs, nützlich für Debugging
• enforce_eager=False: Aktiviert CUDA Graphs für bessere Performance

python
1llm = LLM(path, enforce_eager=True, tensor_parallel_size=1)

(example.py:9)

Im Benchmark-Code wird enforce_eager=False für maximale Performance verwendet:

python
1llm = LLM(path, enforce_eager=False, max_model_len=4096)

(bench.py:15)

Automatische Modelllängen-Anpassung

Die Engine passt die max_model_len automatisch an die maximale Position des Modells an:

python
1self.max_model_len = min(self.max_model_len, self.hf_config.max_position_embeddings)

(nanovllm/config.py:25)

Ausführung und Verifikation

Beispiel ausführen

Das mitgelieferte Beispiel kann direkt ausgeführt werden:

bash
1python example.py

Voraussetzung ist, dass das Modell unter ~/huggingface/Qwen3-0.6B/ verfügbar ist.

Erwartete Ausgabe

Bei erfolgreicher Ausgabe werden der Prompt und die generierte Completion angezeigt:

python
1for prompt, output in zip(prompts, outputs):
2    print(f"Prompt: {prompt!r}")
3    print(f"Completion: {output['text']!r}")

(example.py:26-29)

Benchmark ausführen

Für Performance-Tests kann der Benchmark ausgeführt werden:

bash
1python bench.py

Die erwartete Ausgabe zeigt die Gesamtanzahl der Tokens, die Zeit und den Durchsatz:

Total: XXXXXtok, Time: XX.XXs, Throughput: XXXX.XXtok/s

(bench.py:28)

Häufige Probleme und Lösungen

Problem 1: Modellpfad nicht gefunden

Fehlermeldung: AssertionError bei der Pfadvalidierung

Ursache: Der angegebene Modellpfad existiert nicht oder ist kein Verzeichnis.

Lösung: Sicherstellen, dass der Pfad korrekt ist und die Modellgewichte heruntergeladen wurden:

python
1assert os.path.isdir(self.model)

(nanovllm/config.py:21)

Problem 2: Temperatur zu niedrig

Fehlermeldung: AssertionError: greedy sampling is not permitted

Ursache: Die Temperatur wurde auf 0 oder einen sehr kleinen Wert gesetzt.

Lösung: Eine Temperatur größer als 1e-10 verwenden:

python
1# Falsch
2sampling_params = SamplingParams(temperature=0)
3
4# Richtig
5sampling_params = SamplingParams(temperature=0.6)

(nanovllm/sampling_params.py:10-11)

Problem 3: Flash Attention nicht verfügbar

Fehlermeldung: Importfehler oder CUDA-Fehler während der Initialisierung

Ursache: flash-attn ist nicht korrekt installiert oder die GPU unterstützt es nicht.

Lösung:

1. CUDA-Installation überprüfen
2. Flash-Attention neu installieren: pip install flash-attn --no-build-isolation
3. Alternative: enforce_eager=True verwenden (kann die Performance beeinträchtigen)

Problem 4: KV-Cache Blockgröße ungültig

Fehlermeldung: AssertionError bei der Blockgrößen-Validierung

Ursache: Die kvcache_block_size ist nicht durch 256 teilbar.

Lösung: Die Blockgröße muss ein Vielfaches von 256 sein:

python
1assert self.kvcache_block_size % 256 == 0

(nanovllm/config.py:22)

Problem 5: Tensor Parallel Size außerhalb des gültigen Bereichs

Fehlermeldung: AssertionError bei der Tensor-Parallel-Validierung

Ursache: tensor_parallel_size ist kleiner als 1 oder größer als 8.

Lösung: Einen Wert zwischen 1 und 8 verwenden:

python
1assert 1 <= self.tensor_parallel_size <= 8

(nanovllm/config.py:23)

Nächste Schritte

Nach der erfolgreichen Einrichtung von nano-vLLM können folgende Aspekte weiter erkundet werden:

1. Performance-Optimierung: Anpassung der gpu_memory_utilization und max_num_batched_tokens für spezifische Hardware-Konfigurationen

2. Multi-GPU-Setup: Konfiguration von tensor_parallel_size für verteilte Inferenz über mehrere GPUs

3. Benchmark-Anpassung: Modifikation von bench.py für eigene Test-Szenarien mit unterschiedlichen Eingabelängen und Ausgabelängen (bench.py:10-12)

4. Modell-Unterstützung: Erweiterung der Modellunterstützung durch Analyse der nanovllm/models/-Struktur für weitere Architekturen

5. Integration: Einbindung in bestehende Anwendungen über die LLM.generate()-Schnittstelle mit benutzerdefinierten Sampling-Parametern