Kimi K3 vLLM: запуск не удался — драйвер или среда?

По официальному рецепту vLLM для Kimi K3 текущий образ поставляется только в варианте CUDA 13, а хост с драйвером r575 требует обновления до серии r580 или самостоятельной сборки под cu129. Поэтому при подтверждённой связке «cu130 + r575» не перебирайте параметры запуска: если есть окно обслуживания — обновляйте драйвер с планом отката; если общий кластер менять нельзя — сразу переносите проверку в изолированную совместимую среду.

Кому это руководство пригодится

Вы уже пытаетесь запустить Kimi K3 vLLM на существующих GPU-узлах и получили ошибку инициализации, CUDA или NCCL. Вы отвечаете за общий кластер и должны оценить цену изменения драйвера. Либо вам нужно быстро вернуть Agent-команду к интеграционным тестам, не ожидая изменения всей платформы.

Последнее обновление: 5 августа 2026 года. Данные сверены с официальным рецептом vLLM для Kimi K3, публикацией vLLM от 27 июля 2026 года и документацией по совместимости CUDA.

Сбой начался — сначала сохраните состояние, а не меняйте команду

Типичный случай выглядит так: контейнер загружен, модель найдена, но процесс завершается ещё до нормального старта сервера. В журнале могут одновременно встречаться сообщения про CUDA, загрузчик ядра, NCCL, невозможность инициализировать устройство или отсутствие подходящего бинарного пакета.

В этот момент опасно сразу добавлять новые флаги. Вы потеряете исходное доказательство и не поймёте, какая переменная действительно повлияла на результат.

Сохраните четыре группы данных:

• точный тег контейнера;
• источник установки vLLM и версию пакета;
• вывод nvidia-smi, включая версию драйвера и список устройств;
• полный журнал запуска от первой строки контейнера до завершения процесса.

Минимальный набор команд для фиксации выглядит так:

date -u
nvidia-smi
docker image inspect vllm/vllm-openai:kimi-k3
docker info
env | sort

Если используется оркестратор, сохраните описание пода или задачи, переменные окружения, образ контейнера и последние логи с предыдущим запуском. Команды управления драйвером и контейнерным рантаймом зависят от вашей платформы, поэтому перед изменением узла сверяйтесь с документацией конкретного дистрибутива и кластера.

Главная развилка простая:

• ошибка появляется до загрузки модели и указывает на несовместимость CUDA или драйвера — это проблема среды;
• CUDA инициализируется, модель начинает загружаться, но процесс завершается после выделения памяти — это отдельная цепочка проверки вместимости, параметров модели или распределения памяти;
• сервер запускается, но ломается на запросе инструмента, мультимодальном вводе или межузловом обмене — это не повод автоматически откатывать драйвер.

Официальный рецепт разделяет образ Kimi K3, требования к драйверу и альтернативу самостоятельной сборки. Не смешивайте эти уровни с ошибкой OOM: несовместимый бинарный стек может остановиться раньше, чем приложение вообще дойдёт до осмысленной проверки доступной памяти.

Первая проверка: cu130 и r575 — жёсткое ограничение или нет

Проверьте не только строку «CUDA Version» в nvidia-smi. Она показывает поддерживаемую драйвером версию CUDA, но не доказывает, что конкретный контейнер и его библиотеки совместимы с узлом.

Для текущей связки Kimi K3 важны три факта:

• официальный образ vllm/vllm-openai:kimi-k3 собран только под CUDA 13;
• в официальном рецепте нет готового тега cu129 для этого образа;
• для CUDA 13 документация указывает минимальную серию драйвера r580, тогда как r575 относится к ветке CUDA 12.x.

Сопоставление версий CUDA и драйвера проверяйте по официальной документации NVIDIA о совместимости CUDA, а точные требования CUDA 13 — по примечаниям к выпуску CUDA Toolkit 13.0. В таблице NVIDIA для CUDA 13.x указан минимальный драйвер версии 580 или новее. (Документация NVIDIA по совместимости)

Проверьте версии по отдельности:

nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv
docker run --rm --gpus all vllm/vllm-openai:kimi-k3 \
  bash -lc 'python - << "PY"
import torch
print("torch:", torch.__version__)
print("cuda:", torch.version.cuda)
print("available:", torch.cuda.is_available())
PY'

Если контейнер не доходит до выполнения Python-кода или сообщает о неподходящем драйвере, сначала исправляйте совместимость. Не тратьте время на --max-model-len, размеры батча и параметры кеша: эти параметры не превращают CUDA 13 в CUDA 12.9.

При этом не всякая ошибка запуска означает, что нужно менять драйвер. Если текущий узел уже использует r580 или новее, а CUDA инициализируется, проверьте:

• правильность имени модели;
• доступ к весам и авторизацию;
• доступное число GPU;
• настройки tensor parallel;
• сетевой обмен между узлами;
• ошибки загрузки конкретного ядра или расширения.

Обновление драйвера оправдано только тогда, когда журнал и конфигурация подтверждают версионную несовместимость.

Решение на сегодня: обновить драйвер, собрать cu129 или уйти в изоляцию

Вместо списка случайных исправлений сравните три маршрута по условиям входа и выхода.

Вариант A — обновление драйвера до совместимой серии

Выбирайте этот путь, если:

• кластером управляет ваша команда;
• есть согласованное окно обслуживания;
• можно выделить отдельный узел для проверки;
• после изменения вы готовы прогнать регрессию существующих рабочих нагрузок;
• есть проверенный способ вернуть прежний драйвер или переустановить узел.

Преимущества:

• используется официальный образ Kimi K3;
• меньше локальных патчей и самодельных колёс;
• проще повторить окружение на других узлах;
• ниже риск, что временная сборка станет незаметной производственной зависимостью.

Недостатки:

• меняется базовый слой для всех контейнеров на узле;
• нужно проверить старые CUDA 12.x-нагрузки, коммуникационные библиотеки и контейнерный рантайм;
• откат может потребовать перезагрузки, переноса задач или пересоздания узла.

Проверьте также руководство NVIDIA по веткам драйверов для дата-центров. В нём отдельно описываются ветки R575 и R580, их поддерживаемые поколения CUDA и жизненный цикл. Это полезно для планирования не только разового запуска, но и последующего обслуживания кластера.

Это лучший основной маршрут для управляемого производственного кластера, но только после проверки на изолированном узле.

Вариант B — самостоятельная сборка ветки Kimi K3 под cu129

Официальный рецепт допускает самостоятельную сборку vLLM из ветки K3 против окружения cu129, если команда способна поддерживать такой стек.

Подход оправдан, когда:

• обновить драйвер сейчас невозможно;
• есть специалисты, которые фиксируют версии исходников и зависимостей;
• сборка нужна как контролируемый переходный слой;
• вы готовы хранить Dockerfile, lock-файлы, журналы сборки и результаты тестов.

Преимущества:

• рабочие узлы остаются на r575;
• можно продолжить эксперименты без изменения общего драйвера;
• зависимости фиксируются внутри контейнера.

Недостатки:

• это уже не готовый официальный образ;
• совместимость FlashInfer, PyTorch, CUDA и vLLM становится вашей зоной ответственности;
• следующий сбой может быть связан не с моделью, а с расхождением вашей сборки и upstream-ветки;
• исправление придётся повторять при обновлении модели или vLLM.

Установите для такой сборки чёткий срок выхода. Если команда не может воспроизвести контейнер с нуля и объяснить каждую зависимость, не превращайте cu129-сборку в долгосрочную производственную основу.

Вариант C — изолированная совместимая среда

Выбирайте её, если общий GPU-кластер нельзя менять в тот же день, а Agent-команде нужно продолжить проверку.

Подход подходит для:

• функциональной проверки Kimi K3;
• сравнения поведения инструментов;
• подготовки интеграционных тестов;
• временной оценки prefix caching;
• проверки межузлового взаимодействия до утверждения изменения в общем кластере.

Преимущества:

• рабочая среда r575 не затрагивается;
• проще ограничить эксперимент одним набором версий;
• можно сохранить исходный кластер как точку сравнения;
• решение быстро отменяется без массового отката.

Недостатки:

• появится второй контур эксплуатации;
• результаты нельзя автоматически переносить на общий кластер;
• нужно отдельно проверить сеть, хранилище, мониторинг и доступы;
• временная среда может стать постоянной по инерции.

Если вы не можете изменить общий кластер, не называйте изолированный ресурс «костылём». Для восстановления в тот же день это контролируемая стратегия, если вы заранее определили срок пересмотра и критерии возврата.

Чек-лист выбора маршрута

Отметьте пункты до начала изменений:

• [ ] В журнале подтверждена именно несовместимость CUDA 13 и драйвера r575, а не ошибка модели или авторизации.
• [ ] Для обновления драйвера согласовано окно обслуживания.
• [ ] Есть отдельный узел, на котором можно выполнить первый тест.
• [ ] Сохранены образ, версия vLLM, вывод nvidia-smi и полные журналы.
• [ ] Зафиксирован способ отката драйвера или пересоздания узла.
• [ ] После изменения вы сможете проверить хотя бы одну прежнюю рабочую нагрузку.
• [ ] Если общий кластер нельзя менять, подготовлена изолированная совместимая среда.
• [ ] Если выбрана сборка cu129, назначен владелец зависимостей и срок отказа от временного решения.
• [ ] Для prefix caching подготовлены повторяемые запросы с одинаковым префиксом.
• [ ] Для Agent-сценариев определены тесты инструментов, структурированного вывода и корректности цикла.

Решение принимается так:

• если отмечены первые пять пунктов и кластером можно управлять — начинайте с обновления драйвера;
• если общий кластер нельзя затрагивать, но нужна проверка сегодня — выбирайте изоляцию;
• если обновление невозможно, а команда умеет сопровождать собственную сборку — используйте cu129 только как переходный маршрут;
• если не сохранены исходные доказательства — сначала остановите изменения и вернитесь к фиксации состояния.

Перед изменением узла: зафиксируйте границы отката

До обновления драйвера соберите базовую запись состояния:

hostname
uname -a
nvidia-smi
docker version
docker info
lsmod | grep -E 'nvidia|nv_peer_mem|nvidia_peermem'

Дополнительно сохраните:

• список активных контейнеров;
• привязку задач к GPU;
• версии NCCL и коммуникационных библиотек внутри образов;
• настройки RDMA, если используется межузловой обмен;
• текущие проверки доступности GPU;
• журналы последнего успешного запуска других моделей.

Не пытайтесь обновлять весь кластер сразу. Последовательность должна быть такой:

1. Выведите один узел из планировщика.
2. Сохраните его текущий образ или автоматизированную процедуру восстановления.
3. Обновите драйвер согласно документации вашей платформы.
4. Перезагрузите узел, если это требуется.
5. Проверьте nvidia-smi, контейнерный рантайм и доступность GPU.
6. Запустите минимальный Kimi K3 smoke test.
7. Повторите один существующий рабочий тест.
8. Только после этого расширяйте изменение на следующую группу узлов.

Если на этапе проверки ломается прежняя рабочая нагрузка, остановите расширение. Не исправляйте одновременно драйвер, контейнер, сетевой стек и параметры vLLM: иначе у вас не останется причинной связи.

Для общего кластера действует правило выхода: если невозможно гарантировать окно, откат и изолированный тест, прекращайте изменения на месте и переносите Kimi K3 в отдельную совместимую среду.

После запуска: prefix caching проверяйте отдельно от драйвера

Запущенный процесс ещё не означает, что миграция завершена. В официальной команде vLLM для Kimi K3 параметр --enable-prefix-caching передаётся явно. В рецепте также указано, что для межузлового обмена могут потребоваться отдельные настройки all-to-all backend, а для RDMA — переменная UCX_TLS.

Описание механизма и параметра enable_prefix_caching приведено в официальной документации vLLM по Automatic Prefix Caching. Документация vLLM уточняет, что повторное использование происходит только при совпадающем префиксе, а не для любых запросов к одной и той же модели.

Минимальная команда запуска включает такие параметры:

vllm serve moonshotai/Kimi-K3 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --load-format fastsafetensors \
  --enable-prefix-caching \
  --enable-auto-tool-choice \
  --tool-call-parser kimi_k3 \
  --reasoning-parser kimi_k3

Сверяйте параметры с актуальным рецептом запуска Kimi K3, а не копируйте старую команду из внутреннего чата.

Для проверки кеша используйте два одинаковых запроса:

• одинаковый системный промпт;
• одинаковое описание инструментов;
• одинаковое начало пользовательского контекста;
• различающийся короткий вопрос в конце.

Затем повторите запрос после очистки или перезапуска и сравните доступные признаки:

• сообщения о cache hit или miss;
• время prefill;
• число обработанных входных токенов;
• загрузку GPU во время повторного запроса;
• поведение при изменении одного токена в начале префикса.

Если кеш не даёт выигрыша, возможны три причины:

• флаг не передан в фактический процесс;
• повторные запросы не имеют общего префикса;
• нужное состояние не удерживается выбранной политикой.

В публикации vLLM о Kimi K3 описаны отдельные стратегии удержания состояния KDA, включая интервальные контрольные точки и сохранение концов промптов. Поэтому «сервер запущен» и «каждый повторный запрос попадает в кеш» — разные критерии.

Проверяйте их раздельно. Иначе вы ошибочно припишете отсутствие ускорения драйверу, хотя причина находится в форме запросов или политике хранения.

Первая нагрузка: отделите нехватку памяти от проблем связи

После smoke test увеличивайте нагрузку по ступеням:

• загрузка модели без пользовательского трафика;
• короткий текстовый запрос;
• целевой для вашей команды контекст;
• два последовательных запроса с общим префиксом;
• несколько параллельных запросов;
• мультимодальный или инструментальный сценарий;
• межузловой тест, если он входит в архитектуру.

На каждой ступени сохраняйте журнал, параметры запуска и состояние GPU. Если появляется OOM, фиксируйте момент: загрузка весов, prefill, декодирование или рост параллельности. Это разные причины и разные действия.

Если появляется NCCL error, проверяйте топологию, RDMA, peer memory, сетевой backend и переменные окружения. В официальном рецепте Kimi K3 отдельно описаны настройки all-to-all, RDMA и случай ошибки mlx5dv_reg_dmabuf_mr с возможным переходом через NCCL_DMABUF_ENABLE=0, но такой параметр применяйте только после подтверждения соответствующего сообщения в журнале.

Рецепт Kimi K3 указывает минимальную конфигурацию из восьми GPU GB300 для NVIDIA-сценария. Это ориентир конкретного рецепта, а не универсальное обещание производительности для любого GPU-кластера. Не подменяйте его общественными оценками объёма памяти и не делайте вывод о пригодности узла только по числу GPU.

После первичной проверки закрепите результаты в рабочей консоли MacHTML, если ваша команда использует её для контроля временной среды. Инструкции по доступу, подключению и восстановлению храните отдельно от команд запуска — это сокращает время повторного развёртывания при неудачном тесте.

Стабильное наблюдение: оставлять новую среду или возвращаться

Через несколько циклов нагрузки примите решение не по ощущению, а по четырём признакам:

• повторяется ли исходная ошибка;
• сохраняется ли ожидаемое поведение prefix caching;
• корректно ли работают Agent-инструменты и структурированный вывод;
• сколько ручных действий требует обслуживание среды.

Результат оформите одной из трёх записей.

Оставить обновлённый кластер. Подходит, если драйвер прошёл проверку на новых и прежних рабочих нагрузках, а откат документирован.

Продолжить изолированную эксплуатацию. Подходит, если общий кластер нельзя менять или временная среда нужна для независимой разработки. Укажите владельца, срок пересмотра и условия переноса.

Вернуться к исходной схеме. Подходит, если новая версия драйвера ломает критические нагрузки, а изолированный контур не подтверждает нужную функциональность. Зафиксируйте, какая именно проверка не пройдена.

Перед передачей среды команде разработки сверяйтесь с инструкциями MacHTML по подключению и эксплуатации. В решении должны быть указаны образ, версия vLLM, драйверная ветка, команда запуска, результаты smoke test, тест prefix caching и процедура возврата.

Если общий кластер нельзя менять, а проверку Kimi K3 и Agent нужно продолжить сейчас, изолированная среда обычно безопаснее бесконечных попыток «дожать» r575. Самостоятельная cu129-сборка может помочь как переходный вариант, но требует постоянного владельца зависимостей. Для короткого эксперимента разумнее рассмотреть аренду MacHTML как отдельный контур: сначала восстановить проверку и собрать доказательства, затем решить, оправдана ли миграция драйвера и окружения в долгосрочной инфраструктуре. Условия аренды MacHTML проверяйте перед запуском, поскольку доступные варианты и параметры среды могут меняться.

FAQ

Читайте также: Локальное развёртывание Kimi K3: какое оборудование потребуется Как выбрать основной и резервный API для Kimi K3