Kimi K3 vLLM-Fehler 2026: Erst Umgebung, dann Cache

Gemessene Einstiegshürde: Die offizielle vLLM-Recipe verlangt für das Kimi-K3-Image einen Host-Treiber ab R580; das Image wird ausschließlich als CUDA-13-Build angeboten. (offizielle Kimi-K3-Recipe)

Symptom → schnellste Lösung

• Container startet nicht: Erst Image, CUDA-Build und nvidia-smi prüfen. Nicht sofort vLLM-Parameter ändern.
• OOM oder Cache-Miss: Zuerst den Fehlerzeitpunkt und die vollständige Konfiguration sichern. Danach Speicherbelegung, Eingabepräfix und Retention-Verhalten trennen.

Wenn Sie einen Kimi K3 vLLM-Fehler untersuchen, gehen Sie in dieser Reihenfolge vor: Image und Host-Treiber → Abhängigkeiten → GPU-Speicher → Prefix Caching → Multi-Node-Kommunikation. Das offizielle Image verwendet CUDA 13, benötigt laut Recipe einen NVIDIA-Treiber der R580-Serie oder neuer und aktiviert Prefix Caching nicht automatisch.

Für wen ist diese Anleitung gedacht?

Sie richtet sich an Inferenzplattform-Ingenieure, die einen Fehler anhand der ersten aussagekräftigen Logzeile klassifizieren müssen.
Sie ist ebenso für AI-Agent-Teams relevant, die lange gemeinsame Prompts und Prefix Caching zuverlässig testen wollen.
Infrastrukturverantwortliche erhalten eine Entscheidungsgrundlage für Treiber-Upgrade, Eigenbau oder eine temporär bereitgestellte, bereits geprüfte Umgebung.

Letzte Aktualisierung: 11.08.2026. Die Angaben wurden anhand der offiziellen Kimi-K3-Recipe vom 06.08.2026, des vLLM-Beitrags vom 27.07.2026 und der NVIDIA-CUDA-13-Dokumentation geprüft. (vLLM-Beitrag zu Kimi K3)

Die erste Logzeile trennt Infrastrukturfehler von Anwendungsfehlern

Viele Fehlersuchen beginnen mit der letzten Zeile des Stacktraces. Das ist bei Kimi K3 häufig der falsche Ansatz. Der letzte Fehler kann nur ein Folgefehler sein. Wenn der Container bereits wegen einer inkompatiblen CUDA-Laufzeit nicht korrekt initialisiert wurde, sind Meldungen zu Speicher, Kernel oder Kommunikation oft nicht die eigentliche Ursache.

Sichern Sie deshalb vor jeder Änderung diese fünf Elemente:

1. Den vollständigen docker run- oder Orchestrierungsbefehl.
2. Das exakte Container-Tag.
3. Die installierte vLLM-Version beziehungsweise den Build-Stand.
4. Die vollständige Ausgabe von nvidia-smi.
5. Die erste Ausnahme mit mindestens 30 bis 50 Zeilen Kontext.

Ein sinnvoller erster Datensatz sieht beispielsweise so aus:

docker image inspect vllm/vllm-openai:kimi-k3
nvidia-smi
docker logs --timestamps <container> > kimi-k3-start.log

Prüfen Sie zusätzlich die GPU-Sichtbarkeit innerhalb des Containers:

docker run --rm --gpus all vllm/vllm-openai:kimi-k3 nvidia-smi

Die offizielle Recipe nennt als Mindestbasis vllm/vllm-openai:kimi-k3, vLLM 0.27.0 oder neuer sowie eine Hardwarekonfiguration mit mindestens acht GB300-GPUs für den NVIDIA-Pfad. Für produktiven Multi-Node-Betrieb wird eine Verteilung über mehrere Knoten vorgesehen. Diese Angaben sind eine offizielle Startgrenze, keine allgemeine Kapazitätsgarantie für jede Last.

• Image wird nicht gefunden oder startet sofort ab: Container-Tag, Registry-Zugriff und GPU-Passthrough prüfen. Danach das offizielle Kimi-K3-Image mit identischem Tag verwenden.
• CUDA-Initialisierung, Treiber- oder ABI-Fehler: Host-Treiber, CUDA-Build im Image und lokale Toolkit-Installation trennen. Danach den Host-Treiber aktualisieren oder den offiziellen Eigenbaupfad prüfen.
• Modul, Modellarchitektur oder Operator fehlt: vLLM-Version, Wheel-Index und Pre-Release-Abhängigkeiten prüfen. Eine generische vLLM-Umgebung nicht als gleichwertig behandeln.
• OOM vor dem ersten Request: Hardwaretopologie, Gewichtsformat, Parallelisierung und freie GPU-Kapazität prüfen.
• OOM erst unter Last: Kontext, Batch, Parallelität sowie Cache- und Scheduler-Parameter untersuchen.
• Prefix Cache bleibt ohne Treffer: Flag, identischen Promptanfang, Retention und Metriken prüfen.
• NCCL- oder RDMA-Fehler: Backend, Netzpfad, mlx5, Kernelmodule und Treiber kontrollieren.

Achtung: Ändern Sie nicht gleichzeitig Image, Treiber, Parallelisierungsgröße und Kontextlänge. Nach vier Änderungen wissen Sie nicht mehr, welche davon den Fehler beseitigt oder nur verdeckt hat.

Die richtige Reparaturrichtung lässt sich mit einer Entscheidungsprüfung festlegen

Bevor Sie einen Host neu installieren oder zusätzliche GPU-Kapazität buchen, arbeiten Sie diese Liste in der angegebenen Reihenfolge ab:

• [ ] Das offizielle Image ist bestätigt: Container-Name, Tag und Digest stimmen mit der Kimi-K3-Recipe überein.
• [ ] Der Host-Treiber ist kompatibel: nvidia-smi zeigt auf jedem beteiligten Host einen Treiber der R580-Serie oder neuer.
• [ ] Die CUDA-Ebenen sind getrennt geprüft: Container-Runtime, Host-Treiber und lokales Toolkit werden nicht als dieselbe Komponente behandelt.
• [ ] Die GPU-Topologie passt: Alle erwarteten GPUs sind sichtbar und die gewählte Parallelisierung entspricht der Hardwareverteilung.
• [ ] Der Fehlerzeitpunkt ist bekannt: Der OOM tritt entweder beim Start oder erst während einer Anfrage auf.
• [ ] Prefix Caching ist tatsächlich aktiviert: Der laufende Prozess enthält --enable-prefix-caching; die Eingaben werden tokenidentisch wiederholt.
• [ ] Der Kommunikationspfad ist festgelegt: RDMA und NVLink werden nicht mit überlappenden Backend-Parametern betrieben.
• [ ] Die Änderung ist reproduzierbar: Image-Digest, Startparameter, Treiber, Logs und Testeingaben sind archiviert.

Die Entscheidung ergibt sich daraus:

• Wenn einer der ersten beiden Punkte nicht erfüllt ist: Zuerst Host oder Image korrigieren. Parameteränderungen an Kontext und Batch sind an dieser Stelle nicht zielführend.
• Wenn Image und Treiber stimmen, aber Imports oder Operatoren fehlen: Abhängigkeiten und vLLM-Build zurücksetzen. Keine zufälligen Wheels aus einem anderen CUDA-Index mischen.
• Wenn der Start gelingt und der OOM erst unter Last erscheint: Kontextlänge, Parallelität und Cache-Nutzung einzeln testen.
• Wenn nur wiederholte Präfixe keinen Treffer zeigen: Cache-Flag, Präfixidentität und Retention prüfen, bevor Sie die Speicherkonfiguration verändern.
• Wenn nur Multi-Node-Starts scheitern: Backend, RDMA-Geräte, Kernelmodule und NCCL-Umgebung isoliert testen. Eine funktionierende Einzelknoteninstanz beweist keine funktionierende Clusterkommunikation.

Diese Reihenfolge verhindert, dass Sie einen Infrastrukturfehler mit einem Modellparameter kaschieren. Sie ist besonders wichtig, wenn mehrere Teams denselben Cluster verwenden und ein Rollback später exakt nachvollziehbar sein muss.

CUDA 13, Host-Treiber und Toolkit sind drei verschiedene Ebenen

Der häufigste Kimi K3 vLLM-Fehler vor dem eigentlichen Modellstart ist ein Ebenenproblem. Sie sehen im Container eine CUDA-Version und schließen daraus, dass der Host automatisch kompatibel sein müsse. Das ist nicht korrekt.

Unterscheiden Sie:

• NVIDIA-Kerneltreiber auf dem Host: Er stellt die Verbindung zwischen Betriebssystem und GPU her.
• CUDA-Runtime im Container: Sie enthält Bibliotheken, gegen die vLLM und seine Operatoren gebaut wurden.
• Lokales CUDA Toolkit: Es wird vor allem für Kompilierung und Eigenbau benötigt. Es ersetzt den Host-Treiber nicht.

Das offizielle Kimi-K3-Image ist derzeit ein CUDA-13-Build. Die Recipe weist ausdrücklich darauf hin, dass es kein cu129-Tag gibt und die K3-fähigen Wheels nicht im cu129-Nightly-Index liegen. Ein Host mit CUDA 12.9 und R575 kann deshalb nicht einfach durch das Installieren weiterer Pakete im Container „repariert“ werden.

NVIDIA bestätigt in den CUDA-13-Release-Notes, dass CUDA 13.x mit Treibern der R580-Serie oder neuer kompatibel ist. Die NVIDIA-Kompatibilitätsdokumentation nennt für CUDA 13.x ebenfalls mindestens Treiber 580.

Führen Sie auf jedem betroffenen Host aus:

nvidia-smi --query-gpu=name,driver_version,memory.total,memory.free \
  --format=csv

Für die Treiberprüfung zählt die Driver Version, nicht die in nvidia-smi angezeigte „CUDA Version“. Letztere beschreibt, welche CUDA-Version der Treiber maximal unterstützt. Sie ist kein Beweis dafür, dass Ihr Container, vLLM und alle vorkompilierten Operatoren zueinander passen.

Es gibt hier nur zwei belastbare Wege:

1. Host-Treiber aktualisieren: Verwenden Sie einen offiziell unterstützten R580+-Treiber und starten Sie danach einen isolierten CUDA-Test im Kimi-K3-Container.
2. Kompatible Umgebung selbst bauen: Nutzen Sie nur den von der Recipe beschriebenen Kimi-K3-Branch und die dort vorgesehene CUDA-/PyTorch-Kombination.

Vermeiden Sie Mischinstallationen aus einem CUDA-12.9-Wheel, einem CUDA-13-Container und manuell kopierten Bibliotheken. Das kann den Import zunächst ermöglichen, aber später bei Kernelstart, Speicherregistrierung oder NCCL abbrechen.

Generische Images und alte Wheels erzeugen eigene Fehlerklassen

Ein allgemeines vLLM-Image ist nicht automatisch ein Kimi-K3-Image. Kimi K3 verwendet eine hybride Architektur mit Kimi Delta Attention, speziellen MoE-Pfaden, einem eigenen Chat-Template und einer Cache-Verwaltung, die rekurrente Zustände und klassische KV-Blöcke gemeinsam behandelt. vLLM beschreibt diese Anpassungen als spezielle Integrationsarbeit für das Modell.

Typische Symptome einer nicht passenden Umgebung sind:

• Die Modellarchitektur wird nicht erkannt.
• Ein Modul aus dem Kimi-K3-Frontend kann nicht importiert werden.
• Ein CUDA- oder FlashInfer-Operator fehlt.
• Das Container-Tag existiert nicht.
• Das Modell lädt teilweise und bricht erst beim ersten Prefill ab.
• Ein Tool-Call wird nicht korrekt geparst, obwohl die Textausgabe funktioniert.

Prüfen Sie zuerst, ob Sie wirklich das vorgesehene Image verwenden:

docker images --digests vllm/vllm-openai
docker inspect <container> | grep -E 'Image|Env'

Suchen Sie im Log nach:

grep -Ei 'version|cuda|flashinfer|architecture|operator|import|traceback' kimi-k3-start.log

Der offizielle vLLM-Beitrag zu Kimi K3 weist darauf hin, dass die aktuelle Unterstützung wegen komplexer Abhängigkeiten auf Docker-Images setzt und mehrere Vorab-Abhängigkeiten einbezieht. Ein altes Nightly-Wheel oder ein Index für CUDA 12.9 ist daher kein getesteter Ersatz, nur weil der Paketname ähnlich aussieht.

Die korrekte Reparatur lautet in dieser Fehlerklasse nicht „noch ein Paket installieren“. Besser ist:

1. Container stoppen.
2. Image-Digest und vLLM-Version dokumentieren.
3. Offizielles Image erneut beziehen.
4. Den Start mit minimalen, offiziell genannten Optionen reproduzieren.
5. Erst danach zusätzliche Tool-Calling-, Speculative-Decoding- oder Cache-Optionen aktivieren.

Für die laufende Umgebung sollten Sie eine unveränderliche Startdefinition verwenden. Hinterlegen Sie Image-Tag, Digest, Umgebungsvariablen und Startargumente in Ihrer Betriebsdokumentation, damit ein identischer Test später erneut ausgeführt werden kann.

Prefix Caching braucht einen kontrollierten Wiederholungstest

Bei Kimi K3 ist Prefix Caching ein besonders leicht missverstandener Bereich. Der vLLM-Blog zeigt --enable-prefix-caching im Startbeispiel. Die offizielle Recipe beschreibt gleichzeitig die zugrunde liegenden Retention-Mechanismen für KDA-Zustände. Daraus folgt: Das Feature ist unterstützt, aber Sie dürfen einen Cache-Treffer nicht nur anhand der ersten Antwortzeit beurteilen.

Prüfen Sie zunächst den tatsächlich laufenden Prozess:

ps aux | grep '[v]llm serve'
docker inspect <container> | grep -i prefix

Danach führen Sie drei Requests mit kontrollierten Eingaben aus:

1. Ein neuer, einmaliger Prompt.
2. Derselbe Prompt mit identischem Systemteil und identischem Präfix.
3. Derselbe Präfix mit einer bewusst veränderten frühen Textstelle.

Die drei Fälle müssen getrennt protokolliert werden. Achten Sie auf:

• Cache-Hit- oder Reuse-Metriken.
• Prefill-Zeit.
• Anzahl wiederverwendeter Tokens.
• Veränderung des Systemprompts.
• Unterschiedliche Tool-Definitionen.
• Unterschiedliche Nachrichtenreihenfolge.
• Änderungen an Bildern oder multimodalen Eingaben.

Es gibt drei verschiedene Ursachen für „kein Treffer“:

• Funktion nicht aktiviert: Das Startargument fehlt oder wurde vom Wrapper nicht weitergereicht.
• Präfix nicht identisch: Schon eine frühe Änderung am Systemprompt, an Tool-Schemas oder an der Nachrichtenstruktur verhindert den erwarteten Treffer.
• Retention-Effekt: Der KDA-Zustand wird nicht an jeder Tokenposition dauerhaft gespeichert. vLLM nutzt dafür unter anderem Prompt-Ende, Intervalle und selektive Aufbewahrung.

Der Blog beschreibt eine konfigurierbare Intervall-Retention und weist darauf hin, dass VLLM_PREFIX_CACHE_RETENTION_INTERVAL=0 periodische Checkpoints deaktiviert und nur Prompt-Endzustände behält. Eine solche Einstellung kann für mehrstufige Gespräche sinnvoll sein, aber bei einem Test mit einem wiederverwendeten Präfix außerhalb einer Prompt-Grenze ein anderes Ergebnis liefern.

Erfahrung aus der Fehleranalyse: Ein einzelner langsamer zweiter Request reicht nicht als Beweis. Prüfen Sie mindestens identische Eingaben, Cache-Metrik und Retention-Einstellung gemeinsam.

Start-OOM und Inferenz-OOM benötigen unterschiedliche Maßnahmen

Ein OOM beim Start bedeutet nicht dasselbe wie ein OOM nach mehreren erfolgreichen Requests. Die zeitliche Position der Meldung ist hier der wichtigste Filter.

OOM vor dem ersten Request

Prüfen Sie in dieser Reihenfolge:

1. Sind alle erwarteten GPUs sichtbar?
2. Haben alle GPUs vergleichbare freie Speicherkapazität?
3. Entspricht die GPU-Topologie der gewählten Tensor-, Expert- oder Pipeline-Parallelisierung?
4. Wird das vorgesehene Gewichtsformat geladen?
5. Läuft bereits ein anderer Prozess auf einer GPU?
6. Wird der Fehler beim Laden, beim Graph-Aufbau oder beim ersten CUDA-Kernel ausgelöst?

Nutzen Sie:

nvidia-smi --query-compute-apps=pid,process_name,used_memory \
  --format=csv
nvidia-smi topo -m

Die offizielle Recipe nennt mindestens acht GB300-GPUs für das NVIDIA-Kimi-K3-Profil und verweist für realen Produktionsverkehr auf Multi-Node-Betrieb. Der vLLM-Blog nennt zusätzlich unterschiedliche Mindestanforderungen für andere Hardwaregenerationen. Diese Werte dürfen nicht durch Erfahrungen mit kleineren Modellen oder einzelnen Kimi-Modellen ersetzt werden.

OOM während der Anfrageverarbeitung

Wenn der Dienst zunächst startet, untersuchen Sie:

• max-model-len
• maximale Anzahl paralleler Requests
• Batch- und Scheduler-Einstellungen
• Länge des Prefill-Abschnitts
• Cache-Nutzung
• gleichzeitige Bild- oder Tool-Call-Eingaben
• Prefill-/Decode-Aufteilung

Reduzieren Sie nicht sofort alles. Erstellen Sie zuerst eine Baseline mit einem Request und kurzer Eingabe. Erhöhen Sie danach jeweils nur einen Parameter. So erkennen Sie, ob der Speicherfehler durch Kontext, Parallelität oder Cache-Wachstum ausgelöst wird.

Der offizielle Blog beschreibt für Kimi K3 ein Kontextfenster von bis zu 1.000.000 Tokens und erklärt, dass die hybride Cache-Verwaltung sowohl paged KV-Blöcke als auch rekurrente KDA-Zustände hält. Das ist ein Architekturhinweis, keine Zusage, dass jede Hardwarekonfiguration diese Kontextlänge unter jeder Last bereitstellen kann.

Ein sinnvoller Wiederholungstest lautet:

1 Request, kurzer Kontext
1 Request, langer Kontext
2 parallele Requests, kurzer Kontext
2 parallele Requests, langer Kontext
wiederholtes Präfix mit aktiviertem Cache

Notieren Sie für jeden Durchlauf den Startzeitpunkt, die GPU-Speichernutzung, die vLLM-Parameter und die genaue Eingabelänge. Ohne diese vier Angaben ist „Kimi K3 OOM“ keine ausreichend präzise Fehlerklasse.

NCCL, RDMA und NVLink dürfen nicht vermischt werden

Multi-Node-Fehler sehen oft wie Speicherfehler aus, weil der Engine-Start während der Kommunikationsinitialisierung abbricht. Besonders wichtig ist die Wahl des all-to-all-Backends:

• Für RDMA nennt die offizielle Recipe deepep_v2.
• Für NVLink nennt sie flashinfer_nvlink_one_sided.
• DeepGEMM MegaMoE wird für bestimmte Cross-Node-NVLink-Szenarien empfohlen, ist laut Recipe aber nicht mit Cross-Node-RDMA kompatibel.

Prüfen Sie zuerst auf jedem Knoten:

nvidia-smi
ibv_devinfo
ip -br link
lsmod | grep -E 'nvidia_peermem|mlx5'

Wenn RDMA verwendet wird, prüfen Sie außerdem die von der Recipe genannte Einstellung:

echo "$UCX_TLS"

Für RDMA soll UCX_TLS="rc,cuda_copy" gesetzt werden, damit die KV-Cache-Übertragung den vorgesehenen Pfad verwendet. Bei NVLink setzen Sie nicht einfach dieselben RDMA-Variablen zusätzlich. Die Netzwerktopologie muss zur Konfiguration passen.

Ein dokumentiertes Sonderbild ist:

NCCL error: unhandled system error
mlx5dv_reg_dmabuf_mr: errno 524

Die offizielle Kimi-K3-Recipe ordnet diesen Fall einer fehlenden mlx5-dmabuf-Unterstützung in Kernel oder Treiber zu. Als Rückfall nennt sie NCCL_DMABUF_ENABLE=0, wodurch nvidia_peermem verwendet wird. Das ist nur dann zulässig, wenn nvidia_peermem auf den beteiligten Knoten geladen ist.

Prüfen Sie die Einstellung gezielt:

echo "$NCCL_DMABUF_ENABLE"
modprobe nvidia_peermem
lsmod | grep nvidia_peermem

Ändern Sie diese Variable nicht als allgemeine NCCL-Reparatur. Der Rückfall bezieht sich auf ein bestimmtes mlx5-Registrierungsproblem. Bei einem falsch gewählten Backend, fehlendem RDMA-Gerät oder einer abweichenden GPU-Topologie löst er die Ursache nicht.

Der reproduzierbare Abnahmelauf schließt die Fehlerkette

Nach einer Änderung gilt der Dienst erst dann als repariert, wenn fünf Prüfungen nacheinander bestehen:

1. Dienststart: Alle Ranks initialisieren ohne CUDA-, Import- oder NCCL-Fehler.
2. Basisanfrage: Eine kurze Textanfrage liefert eine vollständige Antwort.
3. Langer gemeinsamer Präfix: Zwei kontrolliert identische Anfragen zeigen den erwarteten Cache-Reuse.
4. Parallellast: Mehrere Requests laufen ohne OOM oder Rank-Abbruch.
5. Multi-Node-Stabilität: Wiederholte Anfragen bestehen mit dem gewählten RDMA- oder NVLink-Backend.

Speichern Sie dabei den Container-Digest, den Host-Treiber, die vLLM-Version, die Umgebungsvariablen und die Testeingaben. Für den späteren Betrieb können Sie die Abnahmehilfe für GPU-Treiber und CUDA-Umgebungen als feste Vorlage verwenden. Wenn Ihr Team regelmäßig lange Agent-Prompts testet, sollte zusätzlich ein eigener Testfall für Prefix-Reuse in Ihrer Betriebsumgebung hinterlegt werden.

FAQ für die wichtigsten Kimi-K3-Fehlerbilder

Die offiziellen Angaben können sich ändern, wenn vLLM die Kimi-K3-Unterstützung in eine neue stabile Version übernimmt. Prüfen Sie daher vor jedem produktiven Rollout erneut Recipe, Image-Tag, Mindestversion, CUDA-Anforderung und Cache-Standard.

Wenn Ihre bestehende Umgebung auf R575 oder CUDA 12.9 festhängt, entstehen meist drei reale Nachteile: Sie können das offizielle CUDA-13-Image nicht unverändert einsetzen, müssen einen Eigenbaupfad dauerhaft pflegen und verlieren bei Multi-Node-Fehlern Zeit durch unklare Zuständigkeiten zwischen Host, Container und Netzwerk. Für kurzfristige Tests ist es deshalb oft sinnvoller, eine bereits geprüfte Umgebung von MacHTML zu mieten, statt auf inkompatiblen Knoten weiter zu experimentieren. Das ist vor allem dann sinnvoll, wenn Sie nur für einen Projektzeitraum Kimi K3, Prefix Caching oder Multi-Node-Kommunikation abnehmen möchten. Für dauerhaft hohe Auslastung oder spezielle physische Schnittstellen bleibt der Kauf eigener Hardware die bessere Entscheidung. Eine passende Umgebung können Sie über die MacHTML-Konsole prüfen und für Ihren Abnahmelauf einplanen.

FAQ

Weiterführende Links: Kimi K3 vLLM-Startfehler systematisch nach Treiber-, CUDA- und Umgebungsproblemen eingrenzen Kimi K3 lokal bereitstellen: Hardware, Speicherbedarf und verteilte Inferenz planen