Цей проект розроблено для автоматизації розгортання оточення ComfyUI. Замість того, щоб вручну завантажувати гігабайти моделей та клонувати ноди, ти просто описуєш їх у TOML та запускаєш скрипт.

Завдяки архітектурі, яку ми заклали, ти можеш розділяти налаштування інфраструктури (API ключі, шляхи) та переліки моделей.

---

🛠 Підготовка

Тобі знадобляться:

1. Python 3.11+ (використовується вбудована бібліотека tomllib).
2. Зовнішні утиліти: huggingface-cli, curl, git та інші залежно від доданих API.
3. yq: Для збирання модульних конфігів у один фінальний файл.

---

📁 Структура конфігурації

Для зручності ми використовуємо розділення на Ядро та Модулі. У описі присутні правила лише для зарезервованих імен параметрів (вказано обов'язкові вони чи опціональні), решта параметрів довільна і призначається користувачем.

1. Ядро (config_main.toml)

Тут живуть твої глобальні налаштування та секрети.

• назви [api] блоків мають бути унікальними і обов'язково мають містити base_cli_cmd
• base_cli_cmd у своєму тексті підтримують вбудовування(підстановки) тексту по шаблону ${scope.param}, де scope: api|target, у яких можна отримати доступ до будь якого параметра поточного блоку, та sys scope де є лише 2 фіксованих параметри dest - шлях до тека призначення та parent - батьківська тека теки призначення

[core]
comfyui_path = "/path/to/ComfyUI" # Абсолютний шлях до кореня
max_workers = 5                  # Кількість паралельних потоків завантаження

[api.hf]
token = "%HF_TOKEN" # Плейсхолдер токена
base_cli_cmd = "hf download ${target.author}/${target.repo} ${target.filename} --local-dir ${sys.dest} --token ${api.token}"
api_driven_save_path = true

[api.civitai]
api_key = "%CIVITAI_API_KEY"
base_cli_cmd = "curl -L -H \"Authorization: Bearer ${api.api_key}\" https://civitai.com/api/download/models/${target.model_id} -o ${sys.dest}/${target.rename}"
api_driven_save_name = true

2. Модулі (наприклад, base_model/cfg-flux-dev.toml)

Тут описуються конкретні моделі. Шлях завантаження вираховується рекурсивно на основі ієрархії ключів.

• [[target.models.checkpoints]] автоматично збереже файл у comfyui/models/checkpoints/.
• [[custom_target]] вимагає обов'язкового параметра save_path.

[[target.models.checkpoints]]
name = "FLUX 1 dev"
provider = "hf"
author = "black-forest-labs"
repo = "FLUX.1-dev"
filename = "FLUX.1-dev.safetensors"

[[target.models.vae]]
name = "FLUX VAE"
provider = "hf"
author = "black-forest-labs"
repo = "FLUX.1-dev"
filename = "ae.safetensors"
rename = "flux_vae.safetensors"

---

🧬 Робочий процес з yq

Оскільки скрипт main.py приймає один цілісний файл, ми використовуємо yq для "мерджу" (злиття) ядра та потрібних тобі модулів.

Команда для підміни плейсхолдерів на реальні ключі:

yq eval-all '
  (.. | select(. == "%CIVITAI_API_KEY")) = strenv(CIVITAI_API_KEY) |
  (.. | select(. == "%HF_TOKEN")) = strenv(HF_TOKEN)' ./config_main.toml

Команда для збірки конфігу(Deep Merge):

yq eval-all '
  . as $item ireduce ({}; . * $item)
' config_main.toml cfg2.toml cfg3.toml cfg4.toml cfg5.toml > deploy.toml

Це дозволяє тримати окремі файли для SDXL, Pony, Flux або набору ControlNet-ів і комбінувати їх під конкретну задачу.

---

🚀 Запуск

Після того, як deploy.toml сформовано, запускай скрипт:

python main.py -f deploy.toml

Що відбудеться:

1. Discovery: Скрипт рекурсивно обійде TOML і зрозуміє, куди і що вантажити.
2. Checking: Якщо файл (або тека для git) вже існує, завантаження буде пропущено (SKIPPED).
3. Download: Завантаження піде асинхронно згідно з лімітом max_workers.
4. Rename: Якщо api_driven_save_name = false, скрипт сам перейменує файл. Якщо виникне конфлікт імен (файл вже існує), ти отримаєш WARNING, але нічого не буде видалено.
5. Summary: В кінці ти отримаєш детальну таблицю зі статусом кожної моделі.

---

📝 Правила написання тарget-ів

• name: Довільна назва для звіту.
• provider: Має збігатися з ключем у блоці [api].
• rename (опціонально): Як файл має називатися у тебе на диску. Ігнорується якщо в [api] вказано api_driven_save_name = true
• save_path (тільки для custom_target): Абсолютний шлях, якщо модель має лежати поза межами ComfyUI.

решта парамертрів залежать від структури base_cli_cmd у [api]. Так, наприклад, для Hugging Face CLI треба параметри author, repo, filename, а для Civit AI лише model_version_id.