launcher/specs/tech-architecture/flare-engine-driver.md

FLARE как движок рецепта (engine = "flare", deploy = "native")

Цель: запускать FLARE-пакеты из наших рецептов тем же путём, что dgpp: рецепт описывает что подать, кластер — где, а лаунчер делает preflight, провижининг, запуск, ожидание готовности, follow и stop. Никаких ручных flare orbit … в истории смен.

Блок рецепта

engine = "flare"
deploy = "native"
model = "deepseek-ai/DeepSeek-V4.1-Flash-1017"   # для отчёта/медалей
docker_image = "flare-inference"                  # не используется (нет докера)

[flare]
package   = "local-inference-lab/DeepSeek-V4.1-Flash-1017-FLARE"  # HF-репо пакета
revision  = "gb10"                # ветка/ревизия пакета (gb10 = под 4 Spark)
name      = "deepseek1017"        # имя группы в orbit (--name)
http_port = 8000                  # API на контроллере, /health + /v1/models
serve_flags = [                   # verbatim в `flare orbit run`
  "--max-concurrency", "16",
  "--mtp-draft-tokens", "5", "--mtp-adaptive-verification",
  "--embedding-table-storage", "disk",
  "--embedding-table-resident-scales",
  "--embedding-table-cache-size", "1GiB",
]
# необязательное: пин агентского пакета + ключ издателя проверяются в config,
# не в рецепте (репозиторий рецептов публичный)

Конфиг (приватный, на аддоне/Mac'е):

[flare]
accept_key        = "3748701d…"        # --dangerously-approve-key (пакет подписан)
accept_publisher  = "local-development"
binary            = "flare"            # если не в PATH
orbit_cluster     = "sparks"           # имя `[cluster.<...>]` в orbit.toml

Что делает драйвер (src/engine/drivers.rs, как у dgpp)

1. Preflight (все ноды запуска): flare --version, сервис агента (systemctl --user is-active flare-agent), flare orbit status --cluster <orbit_cluster> — все ноды кластера на месте и в нужном порядке рангов. Не выполнено → отказ до любого запуска (класс ошибок «publisher not approved»/«peer not paired» нам уже знаком по bring-up).
2. Провижининг пакета (только контроллер = rank 0): flare download <package> --revision <revision> (идемпотентно — кэш переиспользуется), путь сохраняется в <dir>/.sm121-flare-package; повторный serve с тем же package@revision пропускает проверку подписи и лицензии (штамп .sm121-flare-rev, аналог dgpp .sm121-dgpp-rev).
3. Запуск: flare orbit run "<node>:<package_path>" --cluster <orbit_cluster> --name <name> --host 0.0.0.0 --port <http_port> --detach --dangerously-approve-key <ключ> --dangerously-accept-publisher … <serve_flags> на rank 0 (агенты сами раздают рангам их срезы). Лог — через flare orbit attach <name> пишется в <dir>/log/.
4. Готовность: поллинг GET http://<rank0>:<http_port>/health, затем /v1/models (30 мин, --no-wait пропускает) — как у остальных движков.
5. Follow: HTTP-проба раз в 30 с; 2 промаха → падение (как в docker-пути).
6. Stop: flare orbit stop <name> --cluster <orbit_cluster>, затем проверка, что /health недоступен; ledger закрывается только после успешной остановки (как у docker stop).
7. Логи: sm121 logs → flare orbit attach (tail) на контроллере.

Открытые вопросы

• Ключ издателя: хранить в config ([flare].accept_key), в репозиторий рецептов не пускать; validate ругается, если ключ попал в рецепт.
• --max-concurrency 16 упаковочный: у нас исторически 4 seqs на vLLM — для FLARE это его собственный prepared capacity, не наш KV-бюджет.
• Порт: у FLARE API фиксирован (8000 в их примере, но задаётся), это освобождение от правила «порт 30000» — как у gr8/dgpp (takes_host_port() == false).
• A/B с текущими лейнами: мерить теми же бенчами (sm121 bench), сравнение с прод-SGLang (47.8–50.7 c1 / 64.2–68.3 c2, pp 2.8–3.1k) и нашим прошлым FLARE-bring-up (19.2 / 29.6, pp 1430–1700).
• Обновления FLARE: перед экспериментом — scripts/flare-upstream-watch.sh (пин flare-upstream.pin), git pull + пересборка обеих сторон.