Soup CLI
CLI для дообучения языковых моделей из одного YAML: LoRA, QLoRA, DPO и GRPO, потоковая загрузка слоев для 8B на видеокарте в 4 ГБ, выгрузка в GGUF
- 9 577 ★ репозитория
- Последний коммит
- Apache-2.0
Широкий доступ
Почему такой уровень
- Запускает обучение, ставит пакеты и скачивает веса с Hugging Face; при выгрузке в GGUF может вызвать pip, если не указан `--no-install-deps`
- `soup push` и `--push-as` отправляют модели и контрольные точки в ваш аккаунт Hugging Face по токену
- Запуск `--cloud modal` или `--cloud lambda` только готовит план, а с `--cloud-submit` отправляет платное задание в облако
Установка
В терминале, через SkillFoxx CLI
npx skillfoxx add cli/soupОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемШирокий доступИнструмент может менять данные, выполнять команды или работать с секретами.
- Запускает обучение, ставит пакеты и скачивает веса с Hugging Face; при выгрузке в GGUF может вызвать pip, если не указан `--no-install-deps`
- `soup push` и `--push-as` отправляют модели и контрольные точки в ваш аккаунт Hugging Face по токену
- Запуск `--cloud modal` или `--cloud lambda` только готовит план, а с `--cloud-submit` отправляет платное задание в облако
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Soup — командная утилита `soup` для дообучения языковых моделей: вы описываете задачу в одном файле `soup.yaml`, а она сама подбирает размер батча, находит видеокарту и включает квантование. Поддерживаются обучение на примерах (SFT), методы на парах ответов DPO, KTO, ORPO, SimPO и IPO, а также GRPO и PPO. Базой служит любая модель с Hugging Face, которая загружается через `AutoModelForCausalLM`; для Llama 3.x и 4, Qwen 2.5 и 3, Gemma 3, Mistral, DeepSeek и Phi-4 есть готовые рецепты, их список выводит `soup recipes list`. Типичный путь короткий. `soup init --template chat` создает конфиг, `soup train --config soup.yaml` запускает обучение, `soup chat --model ./output` открывает диалог с результатом, `soup merge --adapter ./output` вливает адаптер LoRA в базовую модель, а `soup export --model ./output --format gguf --quant q4_k_m` готовит файл для Ollama и llama.cpp. Остальные команды покрывают пакетный вывод, `soup serve` с OpenAI-совместимым сервером, оценку качества и проверку данных; `soup ui` открывает локальную панель в браузере. Отдельная возможность для тех, кто делает агентов, называется Agent Forge. Команда `soup agent synth --spec api.yaml` разбирает описание OpenAPI, манифест MCP-сервера или схему GraphQL и собирает набор примеров вызова инструментов для обучения без ручной разметки. Другая отличительная функция, потоковая загрузка слоев, подает замороженную базу на видеокарту по одному слою, и Llama-3.1-8B с NF4 по замерам автора укладывается в 3,32 ГБ пика на ноутбучной RTX 3050 с 4 ГБ.
Для кого. Для разработчиков и исследователей, которые дообучают открытые модели на своей видеокарте и хотят обойтись одним конфигом вместо сборки обучающего стека вручную.
Подходит, если
- Нужно дообучить модель 7–8B методом QLoRA на домашней видеокарте с 8 ГБ памяти или на ноутбуке и не писать обучающий скрипт самому
- Есть набор примеров в формате Alpaca, ShareGPT, ChatML или пар для DPO, и его надо превратить в адаптер одной командой
- Готовую модель требуется выгрузить в GGUF и сразу развернуть в Ollama командой `soup export --deploy ollama`
- Нужно проверить данные и обучение до траты GPU-часов: `soup doctor`, `soup data inspect` и `soup advise` дают предварительную оценку
- Агенту для вызова инструментов нужен собственный набор обучающих примеров, собранный из OpenAPI-описания или манифеста MCP-сервера
Не подходит, если
- У вас Python 3.13 или новее: пакет объявляет поддержку только 3.10–3.12, потому что на более новых версиях сборки PyTorch не проверялись
- Нужно просто запустить готовую модель без обучения: для этого подойдет Ollama, а Soup нужен, когда модель дообучают
- Видеокарты нет совсем: все задачи идут и на процессоре, но автор называет такой режим экспериментальным и очень медленным
- Ваш конфиг содержит опции вроде `quantization_aware: true` или `use_longlora`: с версии 0.76.0 такие настройки, которые раньше принимались и не применялись, обрываются при загрузке
Пример запроса к агенту
Установи soup-cli с набором train, создай конфиг из шаблона chat для Llama-3.1-8B-Instruct на моем train.jsonl и запусти дообучение методом QLoRAОграничения
Версия 0.76.0 помечена в метаданных пакета как альфа. Легкая установка `soup-cli` без PyTorch умеет только создавать конфиги и проверять данные, а для обучения нужен дополнительный набор `soup-cli[train]`.
Потоковая загрузка слоев включается параметром `stream_layers: true` и сам автор называет ее бета-функцией. Цифры 119,6 токена в секунду и пик 3,32 ГБ получены до исправления корректности в версии 0.73.0, а повторный замер другого участника дал 208,6 токена в секунду при пике 2,40 ГБ на другой частоте; автор предупреждает, что эти строки не сопоставимы.
С версии 0.75 неизвестные ключи конфига приводят к ошибке загрузки, а не молча отбрасываются. Форматы AWQ и GPTQ для выгрузки объявлены устаревшими и исчезнут в версии 0.77: оба проекта-источника заархивированы.
Статистику запуска Soup отправляет только после явного включения `SOUP_TELEMETRY=1`.
Как отключить. Удалите утилиту командой `pipx uninstall soup-cli` или `pip uninstall soup-cli`. Результаты обучения лежат в каталоге из поля `output` вашего конфига, а служебные файлы в `~/.soup/`; их удаляют вручную.
Частые вопросы
Как дообучить модель на видеокарте с 4 ГБ памяти?
В конфиге включают `stream_layers: true`. Тогда замороженная база хранится в оперативной памяти или на NVMe и подается на видеокарту по одному слою декодера. Автор замерил Llama-3.1-8B-Instruct с NF4 на RTX 3050 Laptop 4 ГБ: пик памяти 3,32 ГБ. Функция бета, а проверить утверждение можно в ноутбуке `notebooks/proof-4gb.ipynb` на бесплатном Colab T4.
Какие версии Python поддерживает soup-cli?
Только 3.10, 3.11 и 3.12: в `pyproject.toml` стоит ограничение `<3.13`. На более новых версиях менеджер пакетов ставил непроверенные сборки PyTorch, которые падали в нативном расширении раньше, чем стартовал сам Soup.
Чем отличается легкая установка от soup-cli[train]?
Обычный `pip install soup-cli` не тянет PyTorch и дает команды `soup init`, `soup data` и проверки. Набор `[train]` добавляет torch, transformers, peft, trl, datasets, bitsandbytes и accelerate. Для веб-панели нужен `[ui]`, а набор `[all]` ставит обучение, сервер, панель и данные сразу.
Как выгрузить обученную модель в Ollama?
Команда `soup export --model ./output --format gguf --quant q4_k_m` готовит GGUF, а `soup export --model ./output --deploy ollama` выгружает и сразу разворачивает файл в Ollama. Отдельно есть `soup deploy ollama --model m.gguf --name x`, `--list` показывает развернутые Soup модели, а `--remove` удаляет их.
Что такое Agent Forge и зачем он нужен?
Это команды `soup agent synth`, `soup agent train` и `soup agent eval`. Они читают OpenAPI 3.x, манифест MCP-сервера или интроспекцию GraphQL и собирают обучающие примеры вида запрос пользователя и вызов инструмента. Ссылки `$ref` в OpenAPI остаются неразрешенными, чтобы не читать файлы по внешним путям.
Почему мой старый конфиг перестал загружаться после обновления?
С версии 0.75 неизвестные ключи вызывают ошибку, а в 0.76.0 так же обрываются опции, которые принимались, но ничем не читались. Перед запуском выполните `soup doctor --config soup.yaml`: сообщение называет поле и то, на что его заменить.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
CLI-инструментыСкилл и Python-пакет для подбора гиперпараметров: агент читает код, предлагает следующий набор значений, а результат измеряет ваш запуск
Официальный скилл NVIDIA для Claude Code и Codex: по описанию набора данных агент собирает конфигурацию, проверяет, показывает превью и создает синтетику
Официальные скиллы Hugging Face: работа с Hub через CLI hf, датасеты, обучение моделей, Spaces, оценка и деплой
Графовая база с ветвями как в git: сервер отдает ее агентам по MCP на /mcp, а встроенный скилл учит агента схемам, запросам и политикам
Локальный RAG в контейнерах с MCP-сервером: агент ищет по вашим документам, данные остаются на своей машине
Скилл математического моделирования
Math Modeling Skill
Воркфлоу из трех этапов для задач математического моделирования: разбор и выбор модели, расчеты на Python или MATLAB, сборка статьи в Word или LaTeX
Коротко о README
Описание проекта начинается с обещания дообучать модели одной командой без настройки инфраструктуры и показывает потоковую загрузку слоев с замерами на ноутбучных видеокартах. Дальше идут перечень новинок версии 0.76.0 с изменениями, ломающими совместимость, установка через pipx, uv и pip, шаблоны конфигов, полный пример `soup.yaml`, список частых команд, таблица размера модели по объему видеопамяти и запуск в Docker. В репозитории лежат подробные справки по обучению, данным, оценке, выгрузке и политике приватности, примеры конфигов, каталог замеров с воспроизводимыми скриптами и тесты; описание переведено на турецкий, арабский, японский и китайский.