Skip to content

Commit b68d70a

Browse files
vavovavo
committed
docs/ section update
1 parent 37b13d8 commit b68d70a

31 files changed

Lines changed: 3977 additions & 993 deletions

‎docs/components/copilot-sidecar.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Ucopilot Usidecar
2+
3+
Status: Draft stub.
4+
5+
This page is intentionally a placeholder so navigation and cross-links stay intact.
6+
7+
## Scope
8+
9+
TODO: Add full content.
10+
11+
## Related
12+
13+
- [Section Index](README.md)
14+
- [Documentation Home](../README.md)
15+
16+
---
17+
18+
_Last updated: 2026-02-11_

‎docs/components/diffusion-pipe.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Diffusion Pipe
2+
3+
Diffusion Pipe in LoRA Pilot is an experimental DeepSpeed-based training path with TensorBoard baked in. It is exposed as the `diffpipe` supervisor service and as the `Dpipe` training tab in ControlPilot.
4+
5+
## 🎯 Overview
6+
7+
Current implementation provides:
8+
- TensorBoard service on port `4444` (default)
9+
- Optional `deepspeed train.py` launch when a config is provided
10+
- ControlPilot API/UI for start/stop/logs and config generation
11+
- Single-run process guard in the API (one active training process at a time)
12+
13+
## 🚀 Access
14+
15+
- **ControlPilot Dpipe tab**: `http://localhost:7878` -> `Dpipe`
16+
- **TensorBoard URL**: `http://localhost:4444`
17+
- **Supervisor service name**: `diffpipe`
18+
- **Startup script**: `/opt/pilot/diffusion-pipe.sh`
19+
20+
## ⚙️ Runtime Modes
21+
22+
The supervisor service behaves differently based on `DIFFPIPE_CONFIG`:
23+
24+
| Mode | Condition | Behavior |
25+
|---|---|---|
26+
| TensorBoard-only | `DIFFPIPE_CONFIG` is empty | Starts TensorBoard on `DIFFPIPE_PORT` |
27+
| Train + TensorBoard | `DIFFPIPE_CONFIG` is set | Runs `deepspeed --num_gpus=<N> train.py --deepspeed --config <file>` and optionally starts TensorBoard |
28+
29+
Notes:
30+
- `DIFFPIPE_TENSORBOARD=1` starts TensorBoard sidecar during training mode.
31+
- `NCCL_P2P_DISABLE=1` and `NCCL_IB_DISABLE=1` are exported by default.
32+
33+
## 📁 Paths and Artifacts
34+
35+
| Path | Purpose |
36+
|---|---|
37+
| `/opt/pilot/repos/diffusion-pipe` | Default training repo used by runtime script |
38+
| `/workspace/apps/diffusion-pipe` | Workspace override location (used by API if `train.py` exists there) |
39+
| `/workspace/logs/diffusion-pipe` | Default TensorBoard logdir (`DIFFPIPE_LOGDIR`) |
40+
| `/workspace/configs/dataset_config.toml` | Generated dataset config (ControlPilot API flow) |
41+
| `/workspace/configs/training_config.toml` | Generated training config (ControlPilot API flow) |
42+
43+
## 🔧 Environment Variables
44+
45+
| Variable | Purpose | Default |
46+
|---|---|---|
47+
| `DIFFPIPE_PORT` | TensorBoard port | `4444` |
48+
| `DIFFPIPE_CONFIG` | Training config path for service script | empty |
49+
| `DIFFPIPE_LOGDIR` | TensorBoard log directory | `/workspace/logs/diffusion-pipe` |
50+
| `DIFFPIPE_NUM_GPUS` | Passed to `deepspeed --num_gpus` | `1` |
51+
| `DIFFPIPE_EXTRA_ARGS` | Extra CLI args appended to train command | empty |
52+
| `DIFFPIPE_TENSORBOARD` | Start TensorBoard sidecar in train mode | `1` |
53+
| `NCCL_P2P_DISABLE` | NCCL setting | `1` |
54+
| `NCCL_IB_DISABLE` | NCCL setting | `1` |
55+
56+
## 🖥️ ControlPilot Dpipe API
57+
58+
`apps/Portal/dpipe_api.py` exposes:
59+
60+
| Endpoint | Method | Purpose |
61+
|---|---|---|
62+
| `/dpipe/train/validate` | `POST` | Validate required model paths exist |
63+
| `/dpipe/train/start` | `POST` | Generate configs and launch training |
64+
| `/dpipe/train/stop` | `POST` | Stop active training process |
65+
| `/dpipe/train/logs` | `GET` | Return in-memory log tail for active/recent run |
66+
67+
`/dpipe/train/start` currently builds a `hunyuan-video` style config and requires:
68+
- `transformer_path`
69+
- `vae_path`
70+
- `llm_path`
71+
- `clip_path`
72+
73+
## 🧰 Operational Commands
74+
75+
```bash
76+
# Service status
77+
docker exec lora-pilot supervisorctl status diffpipe
78+
79+
# Follow service logs (TensorBoard/service bootstrap)
80+
docker exec lora-pilot tail -n 200 /workspace/logs/diffpipe.out.log
81+
docker exec lora-pilot tail -n 200 /workspace/logs/diffpipe.err.log
82+
83+
# Hit training logs from API
84+
curl -s "http://localhost:7878/dpipe/train/logs?limit=200"
85+
```
86+
87+
## 🛠️ Troubleshooting
88+
89+
### Port `4444` opens but no training runs
90+
- Expected when `DIFFPIPE_CONFIG` is unset: service is TensorBoard-only.
91+
- Start training from ControlPilot `Dpipe` tab or set `DIFFPIPE_CONFIG`.
92+
93+
### Start fails with missing model files
94+
- Use `POST /dpipe/train/validate` (ControlPilot does this automatically).
95+
- Verify each configured model path exists under `/workspace/models`.
96+
97+
### Start fails with "A training process is already running."
98+
- Stop current run first:
99+
```bash
100+
curl -s -X POST http://localhost:7878/dpipe/train/stop
101+
```
102+
103+
### TensorBoard starts but shows empty runs
104+
- Confirm `DIFFPIPE_LOGDIR` points to the directory where your training writes events.
105+
- If training is launched via API, verify output/config/log paths in the Dpipe form.
106+
107+
## Related
108+
109+
- [ControlPilot](../user-guide/control-pilot.md)
110+
- [Training Workflows](../user-guide/training-workflows.md)
111+
- [Environment Variables](../configuration/environment-variables.md)
112+
- [Section Index](README.md)
113+
- [Documentation Home](../README.md)
114+
115+
---
116+
117+
_Last updated: 2026-02-11_

‎docs/components/invokeai.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# InvokeAI
2+
3+
InvokeAI is the second inference engine bundled in LoRA Pilot. It runs as a supervised service and is wired to the shared workspace model tree so it can reuse the same assets as ComfyUI and training tools.
4+
5+
## 🎯 Overview
6+
7+
LoRA Pilot’s InvokeAI integration provides:
8+
- Web UI served on port `9090` (default)
9+
- Shared model directory (`/workspace/models`)
10+
- Shared output directory (`/workspace/outputs/invoke`)
11+
- Supervisor management (`invoke` service)
12+
- Update support through ControlPilot service updates (pip-based)
13+
14+
## 🚀 Access
15+
16+
- **Services tab** in ControlPilot: open `Invoke AI`
17+
- **Direct URL**: `http://localhost:9090`
18+
- **Supervisor service name**: `invoke`
19+
- **Startup script**: `/opt/pilot/invoke.sh`
20+
21+
## 📁 Runtime Layout
22+
23+
| Path | Purpose |
24+
|---|---|
25+
| `/workspace/apps/invoke` | InvokeAI root (`INVOKEAI_ROOT`) |
26+
| `/workspace/models` | Shared model storage used across LoRA Pilot |
27+
| `/workspace/outputs/invoke` | InvokeAI image outputs |
28+
| `/workspace/logs/invoke.out.log` | InvokeAI stdout log |
29+
| `/workspace/logs/invoke.err.log` | InvokeAI stderr log |
30+
31+
Startup behavior in `scripts/invoke.sh`:
32+
- Activates `/opt/venvs/invoke`
33+
- Tries `invokeai-config --root <root> set ModelsDir <shared_models>`
34+
- Tries `invokeai-config --root <root> set OutputDir <shared_output>`
35+
- Falls back to symlinks (`<root>/models` and `<root>/outputs`)
36+
- Launches `invokeai-web --root <root>`
37+
38+
## ⚙️ Environment Variables
39+
40+
| Variable | Purpose | Default |
41+
|---|---|---|
42+
| `INVOKE_PORT` | Service port | `9090` |
43+
| `INVOKEAI_HOST` | Bind host for Invoke runtime | `0.0.0.0` |
44+
| `INVOKEAI_PORT` | Runtime port passed to Invoke | value of `INVOKE_PORT` |
45+
| `WORKSPACE_ROOT` | Root for app/models/outputs paths | `/workspace` |
46+
47+
## 🧰 Typical Workflow
48+
49+
1. Download/install models in ControlPilot (`Models` tab) so files land in `/workspace/models`.
50+
2. Open InvokeAI from `Services`.
51+
3. Generate images.
52+
4. Review outputs from:
53+
- Invoke itself (`/workspace/outputs/invoke`)
54+
- MediaPilot (`/mediapilot/`), which scans Invoke outputs by default.
55+
56+
## 🔄 Service Operations
57+
58+
```bash
59+
# Status
60+
docker exec lora-pilot supervisorctl status invoke
61+
62+
# Restart
63+
docker exec lora-pilot supervisorctl restart invoke
64+
65+
# Logs
66+
docker exec lora-pilot tail -n 200 /workspace/logs/invoke.out.log
67+
docker exec lora-pilot tail -n 200 /workspace/logs/invoke.err.log
68+
```
69+
70+
## 🛠️ Troubleshooting
71+
72+
### InvokeAI UI does not open
73+
- Verify service is running:
74+
```bash
75+
docker exec lora-pilot supervisorctl status invoke
76+
```
77+
- Check port mapping in `docker-compose.yml` (`${INVOKE_PORT}:${INVOKE_PORT}`).
78+
79+
### Models do not show up in InvokeAI
80+
- Confirm shared path exists:
81+
```bash
82+
ls -la /workspace/models
83+
ls -la /workspace/apps/invoke/models
84+
```
85+
- `apps/invoke/models` should resolve to `/workspace/models` (config or symlink).
86+
87+
### Generated images are missing in MediaPilot
88+
- Verify MediaPilot env points to Invoke outputs:
89+
```bash
90+
grep MEDIAPILOT_INVOKEAI_DIR /workspace/apps/MediaPilot/.env
91+
```
92+
- Expected default: `/workspace/outputs/invoke`.
93+
94+
### Startup errors after version updates
95+
- Recheck logs:
96+
```bash
97+
docker exec lora-pilot tail -n 300 /workspace/logs/invoke.err.log
98+
```
99+
- If needed, restart service and retest.
100+
101+
## Related
102+
103+
- [Inference Guide](../user-guide/inference.md)
104+
- [ComfyUI](comfyui.md)
105+
- [MediaPilot](mediapilot.md)
106+
- [Environment Variables](../configuration/environment-variables.md)
107+
- [Section Index](README.md)
108+
- [Documentation Home](../README.md)
109+
110+
---
111+
112+
_Last updated: 2026-02-11_

‎docs/components/mediapilot.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# MediaPilot
2+
3+
MediaPilot is the built-in gallery and curation layer for generated images in LoRA Pilot. It is embedded into ControlPilot and optimized for large output directories.
4+
5+
## 🎯 Overview
6+
7+
MediaPilot gives you:
8+
- Fast gallery browsing with generated WebP thumbnails
9+
- Search over extracted metadata (prompt, LoRA, sampler, scheduler, steps, CFG)
10+
- Image curation tools: like, tag/move, delete
11+
- Bulk actions: ZIP download and ComfyUI upscale queue
12+
- Optional password gate for shared environments
13+
14+
## 🚀 Access
15+
16+
- **ControlPilot tab**: `MediaPilot`
17+
- **Direct route**: `http://localhost:7878/mediapilot/`
18+
- **Status check**: `GET /api/mediapilot/status`
19+
20+
In LoRA Pilot, MediaPilot is mounted inside ControlPilot (same host/port), not exposed as a separate default port.
21+
22+
## 📂 Data Sources and Paths
23+
24+
Default LoRA Pilot bootstrap values:
25+
- `MEDIAPILOT_OUTPUT_DIR=/workspace/outputs/comfy`
26+
- `MEDIAPILOT_INVOKEAI_DIR=/workspace/outputs/invoke`
27+
- `MEDIAPILOT_THUMBS_DIR=/workspace/cache/mediapilot/thumbs`
28+
- `MEDIAPILOT_DB_FILE=/workspace/config/mediapilot/data.db`
29+
- `MEDIAPILOT_COMFY_API_URL=http://127.0.0.1:5555`
30+
31+
Config file location:
32+
- `/workspace/apps/MediaPilot/.env`
33+
34+
## ⚙️ Environment Variables
35+
36+
Key variables:
37+
38+
| Variable | Purpose | Default |
39+
|---|---|---|
40+
| `MEDIAPILOT_OUTPUT_DIR` | Main image root (Comfy outputs) | `./data/output` |
41+
| `MEDIAPILOT_INVOKEAI_DIR` | InvokeAI image root | `./data/invokeai` |
42+
| `MEDIAPILOT_THUMBS_DIR` | Thumbnail cache root | `./data/thumbs` |
43+
| `MEDIAPILOT_DB_FILE` | SQLite likes/tags DB file | `./data/data.db` |
44+
| `MEDIAPILOT_MAX_BULK_DOWNLOAD_FILES` | Bulk ZIP file count cap | `500` |
45+
| `MEDIAPILOT_MAX_BULK_UPSCALE_FILES` | Bulk upscale file count cap | `50` |
46+
| `MEDIAPILOT_COMFY_API_URL` | ComfyUI API base URL | `http://127.0.0.1:5555` |
47+
| `MEDIAPILOT_UPSCALE_WORKFLOW_FILE` | Workflow template JSON for upscaling | `./comfy_upscale_workflow.json` |
48+
| `MEDIAPILOT_ACCESS_PASSWORD` | Enables auth when non-empty | empty |
49+
| `MEDIAPILOT_ALLOW_ORIGINS` | CORS origins (comma-separated) | `*` |
50+
51+
## 🔍 Search and Filtering
52+
53+
Search supports free text and field filters:
54+
55+
```text
56+
portrait cinematic
57+
lora:my_style
58+
sampler:uni_pc
59+
scheduler:sgm_uniform
60+
steps:24
61+
steps>=20
62+
cfg:4.5
63+
cfg<7
64+
```
65+
66+
Metadata is extracted from image metadata and ComfyUI prompt JSON where available.
67+
68+
## 🧰 Common Workflows
69+
70+
### 1. Curate Comfy/Invoke outputs
71+
1. Open `MediaPilot` in ControlPilot.
72+
2. Choose folder (`Untagged`, `InvokeAI`, or custom folders).
73+
3. Use search to isolate candidates.
74+
4. Like, tag/move, or delete in bulk.
75+
76+
### 2. Download selected images as ZIP
77+
1. Select images in gallery.
78+
2. Use bulk download action.
79+
3. MediaPilot generates a temporary archive and streams it.
80+
81+
### 3. Send selected images to ComfyUI upscale queue
82+
1. Configure `MEDIAPILOT_UPSCALE_WORKFLOW_FILE`.
83+
2. Use placeholder `__INPUT_IMAGE__` for input image and `__OUTPUT_PREFIX__` for output prefix.
84+
3. Select images and run bulk upscale.
85+
86+
## 🔌 API Reference (Core)
87+
88+
| Endpoint | Method | Description |
89+
|---|---|---|
90+
| `/healthz` | `GET` | Health check |
91+
| `/auth/status` | `GET` | Auth enabled/authenticated state |
92+
| `/auth/login` | `POST` | Login when password auth enabled |
93+
| `/folders` | `GET` | List folders |
94+
| `/folders` | `POST` | Create folder |
95+
| `/images` | `GET` | Paginated image list |
96+
| `/like/{filename}` | `POST` | Like image |
97+
| `/unlike/{filename}` | `POST` | Unlike image |
98+
| `/tag` | `POST` | Move image between folders |
99+
| `/image/{filename}` | `DELETE` | Delete image from root |
100+
| `/image/{folder}/{filename}` | `DELETE` | Delete image from folder |
101+
| `/download/bulk` | `POST` | Download selected files as ZIP |
102+
| `/upscale/bulk` | `POST` | Queue selected files to ComfyUI |
103+
104+
## 🧪 Thumbnail Pre-generation
105+
106+
For large libraries, you can prebuild thumbnails:
107+
108+
```bash
109+
cd /workspace/apps/MediaPilot
110+
/opt/venvs/core/bin/python pregenerate_thumbs.py
111+
```
112+
113+
## 🛠️ Troubleshooting
114+
115+
### MediaPilot section is blank in ControlPilot
116+
- Check status API:
117+
```bash
118+
curl -s http://localhost:7878/api/mediapilot/status
119+
```
120+
- If `available=false`, confirm app files exist at `/workspace/apps/MediaPilot` (or bundled `/opt/pilot/apps/MediaPilot`).
121+
122+
### Gallery loads but images are missing
123+
- Verify `MEDIAPILOT_OUTPUT_DIR` and `MEDIAPILOT_INVOKEAI_DIR` in `/workspace/apps/MediaPilot/.env`.
124+
- Confirm files exist and are readable.
125+
126+
### Upscale action fails
127+
- Confirm `MEDIAPILOT_COMFY_API_URL` points to active ComfyUI.
128+
- Validate workflow JSON at `MEDIAPILOT_UPSCALE_WORKFLOW_FILE`.
129+
- Ensure workflow has either placeholders or a `LoadImage` node.
130+
131+
### Auth issues after enabling password
132+
- Set `MEDIAPILOT_ACCESS_PASSWORD` in `.env`.
133+
- If running behind HTTPS, set `MEDIAPILOT_AUTH_COOKIE_SECURE=true`.
134+
135+
## Related
136+
137+
- [ControlPilot](../user-guide/control-pilot.md)
138+
- [ComfyUI](comfyui.md)
139+
- [Model Management](../user-guide/model-management.md)
140+
- [Section Index](README.md)
141+
- [Documentation Home](../README.md)
142+
143+
---
144+
145+
_Last updated: 2026-02-11_

0 commit comments

Comments
 (0)