Тихий апдейт, громкий баг
Обновили llama-server до свежей версии 2.2 в конце марта 2026 – и ваши скрипты загрузки моделей рассыпались в пыль? Вы не одиноки. Разработчики сервера решили "улучшить" управление кэшем HuggingFace, добавив автоматическую миграцию старых .gguf файлов в новую структуру директорий. Без спроса. Без флага отката в первом релизе.
Симптомы просты: скрипты, которые раньше находили модели по путям вроде ~/.cache/huggingface/hub/models--TheBloke--Llama-3.2-1B-Instruct-GGUF/snapshots/, теперь возвращают пустоту. Модели физически на диске есть, но llama-server их не видит. Потому что переместил.
Что конкретно сломалось и зачем это вообще нужно?
До версии 2.2 llama-server использовал стандартный кэш HuggingFace Hub. Все модели лежали в предсказуемых путях, с которыми работали кастомные скрипты загрузки, мониторинга и ротации. Новая "фича" переносит файлы в собственную директорию ~/.cache/llama-server/models/, сортируя их по алгоримту, который понятен только автору коммита.
huggingface-hub. Реальность: сломанные пайплайны у тысяч пользователей, которые управляют десятками моделей через свои скрипты.Особенно больно пришлось тем, кто использует llama-swap для быстрой смены моделей или кастомные решения на базе llama.cpp RPC-server. Внезапное изменение путей ломает всю логику.
Экстренный патч: отключаем миграцию сейчас же
Разработчики выпустили хотфикс 2.2.1, добавив переменную окружения для отключения миграции. Но она спрятана так, что не попала в основную документацию. Вот что нужно сделать, чтобы вернуть старые пути и оживить скрипты:
1Остановите все запущенные инстансы llama-server
Сначала убейте все процессы. Миграция запускается при старте сервера, поэтому работающие инстансы продолжат портить данные.
2Экспортируйте переменную LLAMA_SERVER_NO_HF_CACHE_MIGRATION
Перед запуском сервера установите эту переменную в 1. В bash или в вашем systemd service файле:
Для однократного запуска:
LLAMA_SERVER_NO_HF_CACHE_MIGRATION=1 llama-server start --your-flags
Для постоянного отключения в shell профиле (.bashrc, .zshrc):
export LLAMA_SERVER_NO_HF_CACHE_MIGRATION=1
3Верните модели на старые места (опционально)
Если миграция уже произошла, файлы нужно переместить вручную. Новый путь обычно выглядит так: ~/.cache/llama-server/models/<хэш>/<имя_файла.gguf>. Старый путь: ~/.cache/huggingface/hub/.... Просто скопируйте .gguf файлы обратно в старую структуру. Сам сервер после отключения миграции будет снова использовать старый кэш.
Важно: если вы используете обновленный Hugging Face Hub v1.0+, его структура кэша также изменилась. Убедитесь, что ваши скрипты ориентируются на актуальные пути от библиотеки huggingface-hub, а не на устаревшие шаблоны.
А что сломалось еще? Проверяем соседние технологии
Breaking changes в экосистеме llama.cpp идут волнами. Пока чините миграцию кэша, проверьте другие узкие места:
- Новая версия llama.cpp может падать на специфичных наборах инструкций CPU.
- Обновили LlamaIndex? Проверьте, не отправляет ли он ваши промпты в OpenAI по тихому фолбэку.
- Тихие баги в пайплайнах – от повреждения контекста до утечек памяти.
Особенно обидно, когда подобные изменения ломают продакшен-скрипты, которые работали годами. (Кто-нибудь вообще тестирует эти апдейты на backward compatibility?)
Долгосрочное решение: заблокируйте версии и контролируйте кэш
Чтобы не гадать после каждого обновления, зафиксируйте версию llama-server в вашем проекте. Используйте пин в requirements.txt или Dockerfile. Например:
llama-server==2.1.4 # Последняя стабильная до миграции
Или переходите на управление моделями через симлинки. Храните .gguf файлы в отдельной, контролируемой вами директории (например, /opt/models/), а в кэш HuggingFace помещайте только симлинки. Тогда любая миграция сломается об эти ссылки, но сами файлы останутся на месте.
Предупреждение: если вы используете Prompt Caching в llama.cpp, изменения в путях моделей могут также сбросить кэши промптов. Будьте готовы к временному падению производительности после отката миграции.
Главный урок 2026 года: инфраструктурные инструменты для AI стали слишком хрупкими. Одно неосторожное обновление – и вы тратите день на отладку скриптов, которые просто хотят загрузить модель. Может, пора задуматься о более простых и стабильных решениях, даже если они менее модные?
А пока – экспортируйте ту переменную, пока разработчики не придумают следующее "улучшение", которое сломает что-то еще. Как говорится, если работает, не обновляй. Особенно если в changelog есть слова "cache migration" и "automated".
