Buckets:
| # AI Toolkit Manager | |
| Self-contained install/update manager for this checkout of AI Toolkit. Runs | |
| with any Python >= 3.8 and **no dependencies**, so it works before the | |
| training environment exists. | |
| ```bash | |
| python3 -m manager install # first-time setup: venv + torch + requirements | |
| python3 -m manager check # is an update available / are deps out of sync? | |
| python3 -m manager update # git pull, then sync deps + run migrations | |
| python3 -m manager launch # start the web UI (http://localhost:8675) | |
| python3 -m manager doctor # diagnose problems | |
| ``` | |
| ## Design | |
| - **The install logic lives in the repo it installs.** Every commit knows how | |
| to install itself; external frontends (the desktop launcher, `install.sh`, | |
| `install.ps1`) just shell out to this CLI and stay dumb. Machine-readable | |
| output via `check --json` / `detect --json`. | |
| - **Hardware → spec mapping** is in [spec.py](spec.py). One universal torch | |
| pin (2.13.0 / torchvision 0.28.0 / torchaudio 2.11.0) on every platform: | |
| cu130 wheels when the driver supports CUDA 13 (cu126 fallback for older | |
| drivers, refused outright on Blackwell GPUs which need cu130), same stack + | |
| Python 3.11 + `dgx_requirements.txt` on DGX/Grace, PyPI wheels on Mac, | |
| rocm7.1 (experimental) for AMD, `--cpu` to force a CPU install. **Torch | |
| pins there must be updated together with the README install instructions, | |
| run_mac.zsh, and dgx_instructions.md.** | |
| - **Accelerators everywhere wheels exist**, via per-spec `extra_packages` | |
| (installed after requirements with `--upgrade` so they override pins) and | |
| `optional_packages` (installed one-by-one, warn-only on failure): | |
| `torchcodec==0.15.0` on all platforms; flash-attn 2.8.3 prebuilt wheels | |
| (mjun0812) on Linux x86_64/aarch64 + Windows; NATTEN 0.21.7 wheels | |
| (whl.natten.org) on Linux both arches; triton bundled with torch on Linux | |
| and `triton-windows` 3.7.x on Windows. No flash-attn/NATTEN/triton on Mac, | |
| no NATTEN on Windows (no wheels exist). | |
| - **The torch stack is pinned against the resolver.** torch is an unpinned | |
| transitive dep of timm/peft/accelerate/torchvision, so anything in | |
| `requirements*.txt` that conflicts with what the pinned torch needs makes the | |
| resolver silently backtrack to an older torch rather than fail — and prebuilt | |
| accelerator wheels then reinstall a plain PyPI torch over the GPU one, | |
| leaving torchvision/torchaudio's C++ extensions linked against a libtorch | |
| that is gone. Every install pass after torch therefore carries a generated | |
| constraints file (`torch==X+cu130`, ...) plus per-package `--find-links` to | |
| the pytorch index, and `_verify_torch` re-checks (and repairs) the trio | |
| before the optional accelerators are import-tested and again at the end. | |
| Requirements files must never pin a torch dependency below what torch needs | |
| (torch 2.13 wants `setuptools>=77.0.3`). | |
| - **`ui/package-lock.json` is never modified by installing.** A plain | |
| `npm install` re-derives the lockfile for whichever machine runs it — on | |
| Windows it strips the `libc` fields off the Linux-only optional binaries | |
| (`@next/swc-linux-*`, rollup, lightningcss), on Linux it adds them back — so | |
| with the install baked into `npm run build_and_start` every user got a dirty | |
| tree on every launch, which then blocks `manager update` (a dirty tree aborts | |
| the pull). `nodejs.ensure_ui_deps` owns the install instead: `npm install | |
| --no-save`, gated on a hash of `ui/package.json` + `ui/package-lock.json` | |
| (stored in the venv state), with the lockfile bytes snapshotted and restored | |
| either way. `manager launch` therefore runs `npm run db_build_start`, not | |
| `build_and_start`; the latter still exists for the manual | |
| `cd ui && npm run build_and_start` flow in the README and calls the same | |
| non-writing install via `npm run install_deps`. | |
| - **Nothing global is ever installed.** FFmpeg (shared builds — the libs | |
| torchcodec dlopens) goes to `.ffmpeg/` ([ffmpeg.py](ffmpeg.py)), Node | |
| (when the system lacks >= 20) to `.node/` ([nodejs.py](nodejs.py)), the uv | |
| binary (when absent) to `.uv/` ([uvbin.py](uvbin.py)) with uv-managed | |
| Pythons kept in `.uv/python/` via `UV_PYTHON_INSTALL_DIR`, and on Windows | |
| without git, portable MinGit to `.mingit/` ([gitwin.py](gitwin.py)) — all | |
| inside the repo and gitignored. The first clone on a git-less Windows | |
| box is handled by the bootstrap layer (install.ps1 / desktop launcher), | |
| which downloads MinGit itself and moves it into the checkout afterwards. `manager launch` puts them on PATH (and | |
| LD_LIBRARY_PATH on Linux) for the whole UI/training process tree, and a | |
| generated `sitecustomize.py` in the venv exposes ffmpeg to any direct use | |
| of the venv python (plus `os.add_dll_directory` on Windows). | |
| - **Hostile-environment hardening** (learned from the community Windows | |
| installer): every python/pip subprocess runs with PYTHONPATH/PYTHONHOME/ | |
| CONDA/PYENV/PIP_* scrubbed from the env; git runs with | |
| `GIT_LFS_SKIP_SMUDGE=1`; git-pinned requirements (diffusers) are | |
| force-reinstalled when requirements change since pip skips unchanged | |
| version numbers; `launch` polls the UI port and opens the browser when | |
| ready (`--no-browser` to disable, auto-skipped on headless boxes). | |
| - **uv is used when present** (fast installs, auto-downloads the right | |
| Python); plain `venv` + `pip` otherwise. The venv is created at `.venv/` | |
| (an existing `venv/` is also respected, matching `ui/cron/pythonPath.ts`). | |
| - **State** (requirements hash, applied migrations) lives inside the venv | |
| (`aitk_manager_state.json`) — deleting the venv resets everything. | |
| - **Update flow**: `update` pulls fast-forward only, then **re-execs** | |
| `python -m manager sync` so the freshly pulled manager code — not the stale | |
| in-memory copy — performs its own dependency sync and migrations. | |
| **Local work is never overwritten**: a dirty tree aborts the update by | |
| default (untracked files don't count), `--auto` (used by the run_* scripts) | |
| warns and skips the pull instead so launching still works, and there is no | |
| reset/clean anywhere — even `--force` relies on git itself refusing to | |
| clobber modified files. | |
| - **Migrations** ([migrations.py](migrations.py)): one-time post-update steps, | |
| each applied at most once per environment. | |
Xet Storage Details
- Size:
- 6.27 kB
- Xet hash:
- aaf9e094b2c9639f66abb1cd913ac8bab35c06bb037d67d05c64327fb46a68b0
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.