Kimi K3 vLLM: Fehler reproduzierbar eingrenzen

Die Fehlermeldung wechselt nach jeder Änderung an Treiber, Container oder Inferenzparametern? Für eine belastbare Kimi K3 vLLM-Fehlerreproduktion sollten Sie diese Änderungen sofort stoppen, den ursprünglichen Zustand einfrieren und ausschließlich in der Reihenfolge „Kompatibilität, Minimalstart, Einzelanfrage, Einzelfunktion“ weiterarbeiten.

Zeitplan für diese Woche: Am ersten Tag sichern Sie Host, Container, Startbefehl und Anfrage. Danach prüfen Sie CUDA 13 sowie den NVIDIA-Treiber gegen die offizielle Kimi-K3-Basis. Erst wenn der Dienst stabil startet, kommen prefix caching, längerer Kontext, Parallelität und Mehrknotenbetrieb einzeln zurück. Bleibt der Fehler auf der offiziellen Basis unklar oder nur sporadisch, wechseln Sie für die Gegenprobe auf eine isolierte Testumgebung.

Für wen dieser Ablauf gedacht ist: Für Infrastruktur-Ingenieure, Agent-Plattformteams und Clusterverantwortliche, die Kimi K3 bereits selbst hosten und nach mehreren Änderungen keine stabile Fehlerklasse mehr sehen. Besonders relevant ist der Ablauf, wenn OOM-, CUDA-, Cache- oder Kommunikationsfehler als Folge derselben Änderungskette gemeldet werden.

Zuletzt aktualisiert am 09.08.2026; Angaben zu Image, CUDA-Build, Treibergrenze und Cache-Verhalten wurden gegen die offizielle Kimi-K3-Recipe vom 06.08.2026 sowie die vLLM-Dokumentation geprüft.

Warum wechselnde Fehler den ursprünglichen Befund entwerten

Wenn zunächst ein CUDA-Fehler erscheint, danach ein Speicherfehler und nach einer weiteren Änderung ein NCCL-Abbruch, bedeutet das nicht automatisch, dass drei unabhängige Defekte vorliegen. Häufig wurde die Ausführungsumgebung so stark verändert, dass der erste Fehler nicht mehr reproduzierbar ist.

Drei typische Diagnoseverluste treten dabei gleichzeitig auf:

1. Der Fehlerort verschiebt sich. Ein inkompatibler Treiber kann die Geräteinitialisierung verhindern. Wird anschließend die Parallelität reduziert, erreicht der Prozess vielleicht erstmals die Gewichtsinitialisierung und meldet dort einen OOM. Der OOM ist dann möglicherweise real, aber nicht zwingend der ursprüngliche Grund für den Fehlschlag.

2. Die Vergleichsbasis verschwindet. Ein neues Container-Image kann andere vLLM-, PyTorch-, Triton- oder NCCL-Abhängigkeiten enthalten. Ein Vergleich der installierten Python-Pakete reicht nicht aus, weil der tatsächlich geladene Treiber vom Host kommt und nicht aus dem Container.

3. Die Beweiskette wird unbrauchbar. Ohne exakten Startbefehl, vollständigen ersten Stacktrace und identische Anfrage kann ein Plattformteam nicht feststellen, ob eine Änderung die Ursache beseitigt oder den Prozess lediglich in eine spätere Phase verschoben hat.

Das Ziel der Minimalreproduktion lautet deshalb nicht „möglichst schnell einen laufenden Dienst erzeugen“. Das Ziel ist ein stabiler, wiederholbarer erster Fehlerpunkt. Erst danach lohnt eine gezielte Reparatur.

Bewertungsmatrix für die nächste Maßnahme

Erste Stunde: Fehleraufnahme einfrieren und einen Vergleichspunkt schaffen

Bevor Sie den Container neu bauen oder den Treiber aktualisieren, erstellen Sie eine unveränderliche Kopie des Fehlers. Speichern Sie nicht nur die letzte rote Zeile. Für eine verwertbare Kimi K3 vLLM-Fehlerreproduktion brauchen Sie den zeitlichen Verlauf vom Prozessstart bis zum ersten Abbruch.

Sichern Sie mindestens:

• vollständige Ausgabe von nvidia-smi;
• GPU- und Prozesssichtbarkeit innerhalb des Containers;
• Container-Image mit vollständigem Tag oder Digest;
• vLLM-Version und Python-Abhängigkeiten;
• vollständigen docker run- oder Compose-Aufruf;
• alle gesetzten Umgebungsvariablen;
• Tensor- und Expert-Parallel-Konfiguration;
• ersten vollständigen Ausnahme-Stacktrace;
• eine unveränderte Anfrage oder ein festes Testskript;
• Uhrzeit, Hostname und Reihenfolge aller vorherigen Änderungen.

Der Unterschied zwischen „erstem Fehler“ und „letzter Fehlerzeile“ ist entscheidend. Der letzte Eintrag kann lediglich der Prozessabbruch eines früheren CUDA-, NCCL- oder Speicherfehlers sein.

Für die Aufzeichnung genügt zunächst ein separates Verzeichnis:

mkdir -p repro-2026-08-09
nvidia-smi -q > repro-2026-08-09/host-gpu.txt
docker inspect <container> > repro-2026-08-09/container.json
docker logs <container> > repro-2026-08-09/container.log

Ersetzen Sie <container> durch die tatsächliche Container-ID oder den Namen. Der Befehl ist absichtlich einfach: In dieser Phase geht es nicht um Optimierung, sondern darum, den Ausgangszustand zu erhalten.

Welche Variablen sollten Sie bei wechselnden Startfehlern zuerst festhalten? Hostname, GPU-Zuordnung, Treiberversion, Container-Digest, vLLM-Version, Startargumente, Umgebungsvariablen, Modellpfad und dieselbe Anfrage. Erst wenn diese Werte unverändert dokumentiert sind, ist ein Vergleich zwischen zwei Versuchen sinnvoll.

Zweite Stunde: Kompatibilitätsbasis gegen die offizielle Recipe prüfen

Die aktuelle offizielle Kimi-K3-Recipe beschreibt eine enge Startbasis: Das bereitgestellte Docker-Image ist als CUDA-13-Build cu130 ausgewiesen, ein cu129-Tag wird dort nicht angeboten, und für NVIDIA-Hosts wird ein Treiber der r580-Generation oder höher verlangt. Außerdem nennt die Recipe mindestens acht GB300-GPUs für das beschriebene NVIDIA-Profil. Diese Angaben sind zeitabhängig und sollten vor jedem neuen Versuch erneut geprüft werden.

Prüfen Sie die Umgebung an zwei Stellen. Auf dem Host zeigt nvidia-smi, welcher Treiber tatsächlich geladen ist. Im Container zeigen nvidia-smi, Python und vLLM, welche Geräte und Laufzeitbibliotheken der Prozess wirklich verwenden kann.

nvidia-smi
docker run --rm --gpus all vllm/vllm-openai:kimi-k3 nvidia-smi
docker run --rm --gpus all vllm/vllm-openai:kimi-k3 \
  python -c "import vllm, torch; print(vllm.__version__); print(torch.version.cuda); print(torch.cuda.device_count())"

Die drei Ausgaben beantworten unterschiedliche Fragen. Der erste Befehl prüft den Host. Der zweite prüft die GPU-Sichtbarkeit im Container. Der dritte prüft, welche CUDA-Version und welche vLLM-Laufzeit der Python-Prozess meldet. Eine erfolgreiche Paketinstallation ersetzt keine dieser Prüfungen.

Wie erkennen Sie nach einem Treiberwechsel eine Vermischung alter Versionen? Vergleichen Sie die laufende Ausgabe von nvidia-smi mit dem erwarteten Hostzustand, starten Sie einen neuen Container aus dem festgelegten Image und speichern Sie dessen Laufzeitmeldung. Wenn alte Prozesse, persistente Worker oder ein nicht neu gestarteter Host beteiligt sind, darf der Versuch nicht als sauberer Vorher-nachher-Vergleich gelten.

Prüfen Sie zusätzlich, ob der Container tatsächlich dieselben GPU-Geräte sieht wie der Host. Eine fehlerhafte CUDA_VISIBLE_DEVICES-Zuordnung, ein begrenztes Container-Runtime-Profil oder ein bereits belegtes Gerät kann die Fehlerklasse verändern, ohne dass sich die installierten Pakete geändert haben.

Dritter Schritt: den Minimalstart auf den ersten Abbruch reduzieren

Entfernen Sie nun alles, was nicht erforderlich ist, um das Modell zu initialisieren. Dazu gehören Agent-Wrapper, Tool-Schemas, externe Router, Lasttestskripte, Streaming-Anpassungen, speculative decoding, zusätzliche Cache-Connectoren und nicht zwingend benötigte Performance-Flags.

Der offizielle Kimi-K3-Startpfad verwendet unter anderem Tensor Parallelism, --trust-remote-code, das schnelle Safetensors-Ladeformat sowie Kimi-K3-Parser und --enable-prefix-caching. Für die Ursachenisolierung sollten Sie jedoch nicht alle Produktionsoptionen gleichzeitig aktivieren. Die vollständige Recipe ist ein funktionaler Ausgangspunkt; die Minimalreproduktion benötigt daraus zunächst nur die zwingenden Komponenten. (vLLM-Blog zur Kimi-K3-Unterstützung)

Ein sinnvoller Ablauf besteht aus fünf Phasen:

1. Containerinitialisierung: Startet der Prozess überhaupt mit dem festgelegten Image?
2. Geräteerkennung: Werden alle erwarteten GPUs im Container sichtbar?
3. Gewichtsladen: Beginnt und beendet sich das Laden der Modellgewichte?
4. Engine-Initialisierung: Werden CUDA-Kernel, Cache-Verwaltung und Parallelgruppen aufgebaut?
5. Schnittstellenbereitschaft: Meldet der OpenAI-kompatible Endpunkt seine Bereitschaft?

Notieren Sie pro Versuch nur den ersten fehlgeschlagenen Abschnitt. Wenn die Initialisierung bei CUDA oder beim Treiber scheitert, ist jede anschließende Diskussion über max-model-len, OOM oder Cache-Treffer verfrüht.

Für zusätzliche Belege können Sie die von vLLM dokumentierten Diagnosevariablen zeitweise setzen:

export VLLM_LOGGING_LEVEL=DEBUG
export VLLM_LOG_STATS_INTERVAL=1
export CUDA_LAUNCH_BLOCKING=1
export NCCL_DEBUG=INFO

VLLM_TRACE_FUNCTION=1 sollte nur eingesetzt werden, wenn die normale Debug-Ausgabe nicht ausreicht, weil die Dokumentation vor erheblicher Verlangsamung warnt. Nach dem Test müssen Sie Diagnosevariablen wieder entfernen. Die vLLM-Anleitung zur Fehlersuche weist darauf hin, dass dauerhaft gesetzte Optionen spätere Versuche verfälschen können.

Ist ein Kimi K3 OOM bereits die Ursache? Nur dann, wenn der Prozess die Geräte- und Engine-Initialisierung reproduzierbar durchläuft, beim Gewichts- oder Cache-Aufbau tatsächlich Speicher anfordert und derselbe Speicherauslastungspunkt erneut fehlschlägt. Ein OOM direkt nach einem CUDA- oder Treiberfehler kann dagegen ein Folgefehler sein. Deshalb wird zuerst die zeitliche Position im Log bewertet, nicht nur die Fehlermeldung selbst.

Vierter Schritt: eine einzige Anfrage als Laufzeit-Baseline

Sobald der Dienst ohne Geschäftslogik startet, testen Sie genau eine feste Anfrage. Verwenden Sie dasselbe Nachrichtenformat, dieselbe Eingabelänge, dieselbe maximale Ausgabelänge und dieselbe Zugriffsmethode.

Ein Basistest kann so aussehen:

curl -sS http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "moonshotai/Kimi-K3",
    "messages": [
      {"role": "user", "content": "Geben Sie genau einen kurzen Satz aus."}
    ],
    "max_tokens": 32,
    "temperature": 0
  }'

Die Anfrage soll nicht die reale Agent-Last abbilden. Sie soll lediglich beantworten, ob ein einzelner Aufruf nach erfolgreicher Initialisierung stabil verarbeitet wird. Speichern Sie HTTP-Status, Antwortkörper, Prozesslog und GPU-Speicherzustand.

Erst wenn diese Anfrage wiederholt funktioniert, erhöhen Sie genau eine Dimension:

• längere Eingabe;
• höheres max_tokens;
• Bild- oder Multimodalinhalt;
• Tool-Schema;
• parallele Anfragen;
• längerer Kontext;
• mehrere Knoten.

Die vLLM-Dokumentation erklärt, dass Online-Serving nicht vollständig deterministisch ist, weil die Scheduling-Reihenfolge von gleichzeitig eintreffenden Anfragen abhängt. Selbst bei gleichem Seed ist deshalb ein identischer Textausgang kein ausreichender Beweis für eine identische Laufzeit. Reproduzierbarkeit setzt insbesondere dieselbe Hardware und dieselbe vLLM-Version voraus. (vLLM-Dokumentation zur Reproduzierbarkeit)

Woran erkennen Sie den Unterschied zwischen Start- und Laufzeitfehler? Ein Startfehler tritt vor der Bereitschaft des Endpunkts auf und lässt sich ohne API-Anfrage beobachten. Ein Laufzeitfehler erscheint erst nach einer Anfrage oder nach einer Laständerung. Diese Trennung gehört in jedes Übergabedokument, weil beide Fehlerklassen unterschiedliche Zuständigkeiten und Testschritte haben.

Fünfter Schritt: prefix caching erst nach dem stabilen Einzeltest zuschalten

prefix caching gehört in den Testplan, aber nicht an den Anfang jeder Fehlersuche. Für Kimi K3 muss die Funktion explizit geprüft werden, weil die offizielle Startanleitung --enable-prefix-caching verwendet und die Kimi-K3-Architektur hybride Zustände aus regulärem KV-Cache und rekurrentem KDA-Zustand verwaltet. (vLLM-Recipe für Kimi K3)

Soll prefix caching in den Minimalstart aufgenommen werden? Ja, wenn die konkrete Frage lautet, ob die Cache-Funktion selbst funktioniert. Nein, wenn der Dienst bereits vor der Engine-Initialisierung scheitert. In diesem Fall würde der Parameter nur die Fehlersuche mit einer weiteren Variable belasten.

Die richtige Reihenfolge lautet:

1. Dienst ohne optionale Cache- und Lasttestlogik starten.
2. Eine feste Einzelanfrage erfolgreich ausführen.
3. Dieselbe Anfrage oder denselben gemeinsamen Präfix erneut senden.
4. Cache-bezogene Logs und Statistiken aktivieren.
5. Ausschließlich --enable-prefix-caching hinzufügen.
6. Vorher-nachher-Logs vergleichen.
7. Bei geändertem Fehlerbild auf die letzte stabile Stufe zurückgehen.

Der vLLM-Beitrag beschreibt für Kimi K3 eine hybride Cache-Verwaltung, bei der KDA-Zustände nicht an jeder beliebigen Tokenposition vollständig gespeichert werden. Praktisch bedeutet das: Ein fehlender Treffer ist nicht automatisch ein Defekt. Für die Diagnose müssen Präfix, Anfragefolge, Cache-Konfiguration und beobachtete Statistik zusammenpassen.

Sechster Schritt: Kontext, Parallelität und Kommunikation einzeln wiederherstellen

Nach dem Cache-Test kommen die teuren Produktionsvariablen zurück. Beginnen Sie mit der Kontextlänge, danach mit der Anfrageparallelität und erst anschließend mit Mehrknoten- oder Kommunikationsoptionen. Jede Stufe braucht einen eigenen Startdatensatz.

Wenn ein Fehler nach dem Hinzufügen längerer Eingaben entsteht, prüfen Sie zunächst Speicherbedarf und Cache-Auslastung. Wenn er erst bei parallelen Anfragen erscheint, sind Scheduling und Speicherreserve relevant. Wenn er nur bei mehreren Knoten auftritt, müssen Sie zusätzlich Topologie, NCCL, RDMA und die IP-Erkennung untersuchen.

Die offizielle Recipe nennt für die Kommunikation unterschiedliche All-to-All-Backends für RDMA und NVLink und weist auf zusätzliche Einstellungen für bestimmte Mehrknoten- sowie MNNVL-Umgebungen hin. Diese Optionen sollten nicht in einem einzigen Schritt wiederhergestellt werden.

Für jede Änderung führen Sie folgende kurze Notiz:

Wenn sich der Fehlertyp ändert, ist das kein Anlass, sofort den neuen Fehler zu reparieren. Kehren Sie zur letzten stabilen Stufe zurück und wiederholen Sie ausschließlich die letzte Änderung. Genau dadurch entsteht die Kausalität, die in einer bereits mehrfach veränderten Umgebung fehlt.

Die ausführbare Reproduktions-Checkliste

• [ ] Hostname, GPU-Zuordnung und laufende Treiberversion gespeichert
• [ ] Exakter Container-Tag oder Image-Digest dokumentiert
• [ ] CUDA-Laufzeit im Container ausgelesen
• [ ] vLLM-Version und PyTorch-CUDA-Version gespeichert
• [ ] Vollständiger Startbefehl ohne gekürzte Umgebungsvariablen gesichert
• [ ] Erster vollständiger Stacktrace statt nur der letzten Logzeile archiviert
• [ ] Ein fester Einzelanfragetest erstellt
• [ ] Geräteerkennung, Gewichtsstart, Engine-Initialisierung und Endpunkt getrennt bewertet
• [ ] prefix caching erst nach dem stabilen Einzeltest aktiviert
• [ ] Kontext, Parallelität und Mehrknotenbetrieb einzeln ergänzt
• [ ] Nach jeder Änderung ein Rückfall auf die letzte stabile Stufe möglich
• [ ] Diagnosevariablen nach dem Versuch wieder entfernt
• [ ] Bei gemeinsam genutzten GPUs ein exklusiver Testlauf eingeplant
• [ ] Ergebnis als Übergabepaket mit Umgebung, Befehl, Anfrage und Logs vorbereitet

Reparatur, Upgrade oder isolierte Testumgebung

Eine Reparatur im bestehenden Cluster ist sinnvoll, wenn derselbe Fehler auf derselben Basis wiederholt auftritt und die Änderung eindeutig zugeordnet werden kann. Ein Upgrade ist sinnvoll, wenn die offizielle Kimi-K3-Recipe oder die vLLM-Dokumentation eine neue kompatible Version ausdrücklich nennt. Beides sollte erst nach der Sicherung der ursprünglichen Fehlersituation erfolgen.

Wann sollten Sie trotz aller Protokolle in eine Testumgebung wechseln? Wenn der ursprüngliche Cluster keine Version einfrieren kann, andere Aufgaben GPU-Speicher oder Netzwerkzustände verändern, ein Treiberwechsel nicht vollständig zurückrollbar ist oder derselbe Fehler nur sporadisch erscheint. In diesem Fall bringt weiteres Ändern am Produktionsknoten keinen belastbaren Erkenntnisgewinn.

Die vLLM-Dokumentation empfiehlt für reproduzierbare Ergebnisse dieselbe Hardware und dieselbe vLLM-Version; für Online-Serving bleiben Scheduling-Effekte bestehen. Eine isolierte Umgebung ist daher keine Komfortmaßnahme, sondern eine Möglichkeit, die Zahl unbekannter Variablen zu reduzieren.

Bereiten Sie für die Gegenprobe ein Übergabepaket vor:

• Umgebungsfingerabdruck;
• Container-Tag oder Digest;
• minimale Startzeile;
• feste Einzelanfrage;
• erster Fehlerstack;
• Ergebnis jeder einzelnen Änderung;
• klare Definition von „bestanden“ und „fehlgeschlagen“.

Für die organisatorische Entscheidung können Sie die JexMac-Übersicht für Mac-Rechenumgebungen als alternative Testumgebung prüfen. Für kurzfristige Versuche ist außerdem die Übersicht der Mietoptionen relevant; entscheidend sind dabei nicht nur Mietkosten, sondern Exklusivität, Rücksetzbarkeit und die Möglichkeit, eine unveränderte Testbasis zu erhalten.

Aktuelle Clusterlösung gegen isolierte Mac-Testumgebung

Ein gemeinsam genutzter GPU-Cluster bleibt für dauerhaft hohe Modelllasten, spezielle GPU-Topologien und physische Hochgeschwindigkeitsverbindungen die passendere Lösung. Für eine driftende Kimi-K3-Fehleranalyse hat er jedoch drei reale Nachteile: Treiberänderungen betreffen möglicherweise andere Aufgaben, freie Speicherstände sind nicht garantiert, und ein Rücksetzen auf den ursprünglichen Container- und Hostzustand kann organisatorisch schwierig sein.

Eine isolierte Mac-Umgebung ersetzt keine CUDA-13-GPU-Plattform und ist daher nicht die richtige Wahl, wenn der konkrete Fehler nur auf NVIDIA-, NCCL- oder RDMA-Ebene untersucht werden soll. Sie kann aber als sauber getrennte Test- und Dokumentationsumgebung sinnvoll sein, wenn die aktuelle Umgebung durch andere Workloads, fehlende Rollback-Möglichkeiten oder wechselnde Berechtigungen unbrauchbar geworden ist. Für den eigentlichen CUDA-Kompatibilitätstest muss die gebuchte Umgebung die erforderliche technische Plattform bereitstellen; andernfalls dient sie nur der Vorbereitung von Skripten, API-Verträgen und reproduzierbaren Anfragesätzen.

Unsere Empfehlung lautet deshalb: Nicht wegen eines einzelnen roten Logs umziehen, sondern dann, wenn die bestehende Umgebung keine stabile Baseline mehr zulässt. Übernehmen Sie den minimalen Startbefehl, die feste Anfrage und den Umgebungsfingerabdruck in eine exklusiv kontrollierbare Umgebung, führen Sie genau eine Gegenprobe durch und entscheiden Sie erst danach über Treiber- oder Clusterumbau. Wenn kurzfristig eine getrennte Testressource benötigt wird, können Sie die JexMac-Hilfe zur Vorbereitung und Nutzung heranziehen.