Ошибки Kimi K3 в vLLM: среда важнее кэша

По официальному рецепту vLLM для Kimi K3 контейнер использует только CUDA 13, а хосту нужен драйвер NVIDIA r580 или новее. Поэтому при ошибках Kimi K3 в vLLM действуйте в таком порядке: официальный образ и драйвер → загрузка зависимостей → выделение памяти → prefix caching → межузловая связь. Не начинайте с уменьшения контекста после первого Out of memory: это может скрыть ошибку среды.

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

Эта статья для вас, если вы:

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

Карта первичной диагностики

Не копируйте только последнюю строку из лога. Для воспроизводимой проверки сохраните:

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

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

Официальный рецепт указывает vLLM 0.27.0+, образ vllm/vllm-openai:kimi-k3, минимум восемь GPU класса GB300 для NVIDIA-пути и отдельный ROCm-образ для AMD. Эти значения являются базовой границей конкретного рецепта, а не универсальной формулой для любого будущего релиза. Проверяйте страницу recipe перед каждым обновлением.

Среда CUDA 13 и драйвер r580+

Самая дорогая ошибка — считать CUDA внутри контейнера полной заменой драйвера хоста. Это разные уровни.

• Драйвер хоста предоставляет интерфейс для запуска CUDA-приложений и взаимодействует с GPU.
• CUDA runtime контейнера содержит библиотеки, с которыми собран образ.
• CUDA Toolkit на локальной машине нужен для разработки и сборки, но сам по себе не исправляет старый драйвер на сервере.

Сейчас официальный Kimi K3-образ собран только под CUDA 13. В recipe отдельно указано, что тега -cu129 нет, а K3-совместимые wheel не публикуются в nightly-индексе CUDA 12.9. Поэтому попытка заменить официальный образ на обычный vLLM с CUDA 12.9 не является равнозначным обходом.

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

nvidia-smi
docker run --rm --gpus all vllm/vllm-openai:kimi-k3 nvidia-smi
docker image inspect vllm/vllm-openai:kimi-k3 \
  --format '{{.RepoTags}} {{.Created}}'

Если nvidia-smi на хосте не показывает требуемый драйвер, обновите драйвер узла и перезапустите Docker runtime. Не пытайтесь лечить это установкой нового torch, FlashInfer или CUDA Toolkit внутрь уже запущенного контейнера. Такой подход меняет зависимости, но не исправляет интерфейс между драйвером и runtime.

Если обновление невозможно, используйте только второй путь, описанный официальным recipe: самостоятельную сборку vLLM из соответствующей ветки против совместимого стека. Зафиксируйте commit, базовый образ, версию PyTorch и результат теста на одном узле до масштабирования. Непроверенная смесь старого драйвера, нового runtime и случайного nightly создаёт среду, которую потом трудно воспроизвести.

Загрузка образа и зависимостей

Ошибки импорта и неизвестной архитектуры обычно возникают до распределения весов. В этом случае уменьшение --max-model-len не поможет.

Типичные признаки:

• ModuleNotFoundError;
• неизвестный тип модели или конфигурации;
• отсутствующий CUDA-оператор;
• ошибка загрузки FlashInfer;
• тег Docker не найден;
• падение на trust_remote_code или пользовательском chat template.

Официальная публикация vLLM прямо указывает, что из-за сложных зависимостей на текущем этапе пригодны Docker-образы, а интеграция опирается в том числе на предварительные зависимости. Это объясняет, почему «почти такой же» общий образ может пройти импорт, но завершиться на первом специализированном операторе.

Проверьте среду без запуска всего сервера:

docker pull vllm/vllm-openai:kimi-k3

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

Затем запустите минимальный процесс с официальным именем модели и сохраните полный стек:

docker run --rm --gpus all --ipc=host \
  vllm/vllm-openai:kimi-k3 \
  vllm serve moonshotai/Kimi-K3 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --load-format fastsafetensors

Если импорт падает, сначала исправьте образ и зависимости. Если процесс доходит до распределения GPU, переходите к диагностике памяти. Не переносите вывод из issue для другой модели на Kimi K3 без подтверждения тем же контейнером и той же конфигурацией.

Prefix caching и реальные попадания

Kimi K3 поддерживает prefix caching одновременно для обычного KV-кэша и рекуррентного состояния KDA. Но по состоянию на 11 августа 2026 года эта функция для модели отключена по умолчанию. Флаг нужно указывать явно:

vllm serve moonshotai/Kimi-K3 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --load-format fastsafetensors \
  --enable-prefix-caching

Проверяйте три разных сценария, не объединяя их в один диагноз.

Функция не включена. В командной строке нет --enable-prefix-caching, либо фактический процесс запускается не той командой, которая хранится в Helm-чарте или systemd unit. Исправьте источник конфигурации, а не только временный shell-скрипт.

Префикс отличается. Даже незначительное изменение system prompt, списка инструментов, порядка сообщений, пробелов или сериализации мультимодального содержимого разрушает совпадение. Для теста отправьте два запроса с байт-в-байт одинаковой общей частью и измените только последнее пользовательское сообщение.

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

Контролируемая проверка должна выглядеть так:

1. Запишите команду запуска и убедитесь, что флаг присутствует.
2. Отправьте первый запрос с фиксированным системным промптом.
3. Повторите его с тем же префиксом и другим хвостом.
4. Сопоставьте метрики кэша и журнал планировщика.
5. Проверьте несколько повторов, а не только задержку первого токена.

Снижение задержки само по себе не доказывает попадание. На результат влияют планирование, загрузка GPU, сетевой обмен и длина генерируемого ответа. Для AI Agent-системы полезнее отдельно фиксировать долю повторно используемых токенов, длину общего префикса и время prefill.

OOM при старте и во время вывода

У Kimi K3 есть два разных класса ошибок памяти.

Загрузка модели

Если процесс завершается до готовности API, проверьте:

• сколько GPU реально видит контейнер;
• одинаковы ли модели GPU на всех рангах;
• не занят ли один из адаптеров другим процессом;
• соответствует ли --tensor-parallel-size фактической топологии;
• не включён ли неподходящий режим expert parallelism;
• не отличается ли конфигурация одного узла от остальных.

Официальная публикация vLLM описывает Kimi K3 как модель на 2,8 триллиона параметров с 16 активными экспертами из 896 и контекстом до 1 миллиона токенов. Эти параметры объясняют, почему опыт с обычной небольшой моделью нельзя использовать для оценки запуска. Для NVIDIA-пути официальный материал на момент проверки указывает конфигурацию с восемью B300, а также поддерживаемый вариант с 16 B200. Источник — раздел запуска и FAQ vLLM.

Работа после запуска

Если сервер уже принял запрос, а затем получил OOM, анализируйте другой набор факторов:

• фактическую длину входа;
• --max-model-len;
• число одновременных последовательностей;
• размер батча;
• объём KV и KDA-состояния;
• offload и внешние коннекторы кэша;
• остаточную память после загрузки весов.

Снимите состояние до и после запроса:

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

Затем изменяйте только один параметр. Например, сначала ограничьте конкуренцию, после этого отдельно проверьте длину контекста. Если одновременно менять --max-model-len, --max-num-seqs и --gpu-memory-utilization, вы не узнаете, какой фактор устранил сбой.

Не используйте неподтверждённые оценки «на одну карту» для Kimi K3. Ёмкость зависит от формата весов, способа загрузки, параллелизма, кэша и конкретной аппаратной топологии. Для планирования берите данные из официального рецепта, журнала запуска или собственного теста с зафиксированной конфигурацией.

Важное ограничение: уменьшение контекста лечит только часть OOM во время обслуживания. Оно не исправляет несовместимый драйвер, ошибочный tensor parallelism или нехватку памяти на этапе загрузки весов.

NCCL, RDMA и топология узлов

В многоузловом запуске сначала определите, какой канал связи используется фактически. Нельзя без проверки переносить параметры RDMA в NVLink-конфигурацию и наоборот.

Официальный recipe рекомендует:

• flashinfer_nvlink_one_sided для NVLink;
• deepep_v2 для RDMA;
• UCX_TLS="rc,cuda_copy" при включённом RDMA, чтобы передача KV-кэша шла через RDMA;
• deep_gemm_mega_moe для DEP-сценариев, но не для cross-node RDMA.

Проверки на каждом узле:

nvidia-smi topo -m
ibv_devinfo
lsmod | grep -E 'nvidia_peermem|mlx5'
ip -br link
env | grep -E 'NCCL|UCX|VLLM'

Если в журнале есть:

NCCL error: unhandled system error
mlx5dv_reg_dmabuf_mr errno 524

recipe связывает такой случай с отсутствующей поддержкой регистрации dma-buf в ядре или драйвере. В качестве отката указан параметр:

export NCCL_DMABUF_ENABLE=0

Но он допустим только при загруженном nvidia_peermem на узлах. Это не универсальное «исправление NCCL». Документация NCCL по переменной NCCL_DMABUF_ENABLE описывает dma-buf как механизм регистрации буферов для GPU Direct RDMA, а руководство NCCL по диагностике рекомендует начинать с WARN-журнала, интерфейсов и низкоуровневой связности.

Для сбора деталей временно включите:

export NCCL_DEBUG=WARN
export NCCL_DEBUG_SUBSYS=INIT,NET

Не меняйте сразу пять переменных NCCL. Сначала проверьте, видят ли узлы друг друга, затем соответствие backend, затем RDMA-модули и только после этого тестируйте обходной параметр.

Повторный запуск и критерии восстановления

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

1. Старт сервиса. Все ранги завершают инициализацию, API отвечает на health-запрос.
2. Базовый запрос. Короткий текстовый запрос возвращает корректный ответ без предупреждений о модели или операторе.
3. Повторный префикс. Два запроса с одинаковой общей частью показывают ожидаемое поведение prefix caching.
4. Конкурентная нагрузка. Увеличивайте число запросов постепенно, фиксируя память и ошибки планировщика.
5. Межузловая стабильность. Повторите тест после перезапуска одного процесса и убедитесь, что NCCL, RDMA или NVLink не уходят в зависание.

Для командной эксплуатации добавьте в журнал артефакты: тег образа, digest контейнера, версию vLLM, вывод nvidia-smi, параметры запуска, переменные NCCL и результат каждого этапа. Так следующий инженер сможет отличить регрессию vLLM от изменения хоста.

Частые вопросы

Первичная проверка запуска

Если Kimi K3 не стартует через vLLM, первой проверяйте не память, а цепочку совместимости: официальный Docker-образ, версию драйвера, видимость GPU и фактическую команду. Затем сопоставьте первое исключение с recipe. Последняя строка часто является вторичным следствием, например неудачного импорта оператора или незапущенного распределённого ранга.

Причина требований CUDA 13 и r580+

Официальный контейнер Kimi K3 собран под CUDA 13, а хостовый NVIDIA-драйвер должен соответствовать уровню r580 или новее. Runtime CUDA находится в образе, но драйвер остаётся на сервере. Поэтому установка нового Toolkit внутри контейнера не заменяет обновление хоста. Если хост обновить нельзя, рассматривайте только документированный путь самостоятельной сборки совместимой ветки.

Отсутствие попаданий кэша

Проверьте флаг --enable-prefix-caching, затем идентичность префикса и политику хранения KDA-состояния. Разные системные инструкции, инструменты или сериализация сообщений создают разные префиксы. Кроме того, гибридный кэш может сохранить состояние только на выбранной границе. Поэтому сравнивайте метрики и структуру запросов, а не только время ответа.

Отличие OOM

OOM на старте указывает на загрузку весов, топологию и параллелизм. OOM после начала обработки чаще связан с контекстом, конкурентностью, батчем или кэшем. Снимайте memory.used до и после запроса и меняйте один параметр за раз. Нельзя выводить причину по одному тексту ошибки без привязки к моменту, когда процесс завершился.

Ошибка NCCL в многоузловой конфигурации

Сначала установите тип соединения и выберите соответствующий all-to-all backend. Для RDMA отдельно проверьте mlx5, nvidia_peermem, UCX и dma-buf. Для NVLink не переносите RDMA-переменные автоматически. Если появляется unhandled system error, найдите первую предупреждающую строку NCCL и проверьте топологию, интерфейс и shared memory до изменения настроек.

Если ваш текущий кластер постоянно упирается в старый драйвер, неодинаковую топологию GPU или долгую поставку совместимых узлов, проблема уже не только в команде запуска. Самостоятельная среда даёт полный контроль, но одновременно требует собственных тестов, обновления kernel-модулей, проверки RDMA и повторной валидации после каждого изменения. Для временного проекта или пилота иногда разумнее не тратить дни на несовместимый узел, а взять уже проверенную вычислительную среду в аренду у MacHTML; при этом для постоянной тяжёлой эксплуатации Kimi K3 и физических GPU-интерфейсов отдельный специализированный кластер остаётся более подходящим выбором.

Перед передачей окружения команде сохраните инструкции и материалы поддержки MacHTML, а состояние доступной среды можно контролировать через консоль MacHTML. Если вы сравниваете краткосрочный тест с постоянной инфраструктурой, отдельно оцените условия аренды MacHTML: это не заменяет GPU-кластер для продуктивного Kimi K3, но может быть удобнее для временной проверки клиентской части AI Agent-системы, API-интеграций и сценариев доработки.

FAQ