feat: 新增代码
This commit is contained in:
Daniel
194
video_worker/README.md
Normal file
194
video_worker/README.md
Normal file
@@ -0,0 +1,194 @@
|
||||
# Local Video Worker
|
||||
|
||||
一个本地单机视频生成 Worker，提供最小化 HTTP API：接收任务、按模式路由模型、单任务串行执行、输出统一结果目录。
|
||||
|
||||
## 1. 项目说明
|
||||
|
||||
- 目标：边缘执行节点，不是完整平台。
|
||||
- 路由规则：
|
||||
- `preview` -> `LTX-Video`
|
||||
- `refine` -> `HunyuanVideo-1.5`
|
||||
- 状态机：`PENDING` / `RUNNING` / `SUCCEEDED` / `FAILED`
|
||||
- 当前后端是可执行骨架：
|
||||
- 已实现懒加载、参数透传、输出规范、日志与错误处理
|
||||
- 真实模型推理请替换 `app/backends/ltx_backend.py` 与 `app/backends/hunyuan_backend.py` 中 `TODO` 位置
|
||||
|
||||
## 2. 环境准备
|
||||
|
||||
- Python 3.10+
|
||||
- ffmpeg
|
||||
- NVIDIA GPU + CUDA（可选，健康检查会显示可用性）
|
||||
|
||||
## 3. WSL + CUDA 检查方法
|
||||
|
||||
在 WSL Ubuntu 内执行：
|
||||
|
||||
```bash
|
||||
nvidia-smi
|
||||
python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'no gpu')"
|
||||
```
|
||||
|
||||
## 4. 安装命令
|
||||
|
||||
### WSL / Linux
|
||||
|
||||
```bash
|
||||
cd video_worker
|
||||
bash scripts/install_wsl_env.sh
|
||||
cp .env.example .env # 若脚本未自动生成
|
||||
```
|
||||
|
||||
### Windows PowerShell
|
||||
|
||||
```powershell
|
||||
cd video_worker
|
||||
.\scripts\install_windows_env.ps1
|
||||
```
|
||||
|
||||
## 5. 启动命令
|
||||
|
||||
### WSL / Linux
|
||||
|
||||
```bash
|
||||
cd video_worker
|
||||
bash scripts/run_server.sh
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
cd video_worker
|
||||
.\scripts\run_server.ps1
|
||||
```
|
||||
|
||||
或：
|
||||
|
||||
```bat
|
||||
scripts\run_server.bat
|
||||
```
|
||||
|
||||
## 6. 调用示例
|
||||
|
||||
创建任务：
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:8000/generate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "a lonely man walking in a rainy neon street, cinematic, handheld camera",
|
||||
"negative_prompt": "blurry, deformed face, extra limbs, flicker",
|
||||
"quality_mode": "preview",
|
||||
"duration_sec": 5,
|
||||
"width": 832,
|
||||
"height": 480,
|
||||
"fps": 16,
|
||||
"steps": 8,
|
||||
"seed": 123456
|
||||
}'
|
||||
```
|
||||
|
||||
轮询状态：
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/tasks/<task_id>
|
||||
curl http://127.0.0.1:8000/tasks/<task_id>/result
|
||||
```
|
||||
|
||||
烟雾测试：
|
||||
|
||||
```bash
|
||||
cd video_worker
|
||||
. .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
|
||||
python scripts/smoke_test.py
|
||||
```
|
||||
|
||||
## 7. 目录说明
|
||||
|
||||
```text
|
||||
video_worker/
|
||||
├─ app/
|
||||
│ ├─ main.py
|
||||
│ ├─ api.py
|
||||
│ ├─ schemas.py
|
||||
│ ├─ settings.py
|
||||
│ ├─ task_manager.py
|
||||
│ ├─ model_router.py
|
||||
│ ├─ gpu_worker.py
|
||||
│ ├─ task_store.py
|
||||
│ ├─ backends/
|
||||
│ │ ├─ base.py
|
||||
│ │ ├─ ltx_backend.py
|
||||
│ │ └─ hunyuan_backend.py
|
||||
│ └─ utils/
|
||||
│ ├─ files.py
|
||||
│ ├─ ffmpeg_utils.py
|
||||
│ ├─ image_utils.py
|
||||
│ └─ logger.py
|
||||
├─ models/
|
||||
│ ├─ ltx/
|
||||
│ └─ hunyuan/
|
||||
├─ outputs/
|
||||
├─ runtime/
|
||||
│ ├─ tasks.db
|
||||
│ └─ logs/
|
||||
├─ scripts/
|
||||
│ ├─ install_wsl_env.sh
|
||||
│ ├─ install_windows_env.ps1
|
||||
│ ├─ run_server.sh
|
||||
│ ├─ run_server.ps1
|
||||
│ ├─ run_server.bat
|
||||
│ ├─ migrate_db.py
|
||||
│ └─ smoke_test.py
|
||||
├─ requirements.txt
|
||||
├─ .env.example
|
||||
└─ README.md
|
||||
```
|
||||
|
||||
## 8. API 说明
|
||||
|
||||
- `POST /generate`
|
||||
- 创建任务并入队
|
||||
- `GET /tasks/{task_id}`
|
||||
- 查询任务状态
|
||||
- `GET /tasks/{task_id}/result`
|
||||
- 查询结果路径或错误
|
||||
- `GET /health`
|
||||
- 服务状态、CUDA、GPU 名称、模型加载状态
|
||||
|
||||
参数限制：
|
||||
|
||||
- `duration_sec`: 1~5
|
||||
- `width`: <= 832
|
||||
- `height`: <= 480
|
||||
- `fps`: <= 24
|
||||
- `quality_mode`: `preview` 或 `refine`
|
||||
|
||||
## 9. 常见问题
|
||||
|
||||
- `ffmpeg not found`
|
||||
- WSL: `sudo apt-get install -y ffmpeg`
|
||||
- Windows: 安装 ffmpeg 并加入 PATH
|
||||
- `torch.cuda.is_available() == False`
|
||||
- 检查驱动、CUDA、WSL GPU 直通是否正常
|
||||
- 任务失败
|
||||
- 查看 `outputs/{task_id}/run.log`
|
||||
- 查看 `/tasks/{task_id}/result` 返回的 `error`
|
||||
|
||||
## 10. 已知限制
|
||||
|
||||
- 当前后端默认输出演示视频（可执行骨架），未内置完整真实模型权重加载
|
||||
- 单进程单 worker 串行执行，不支持多卡并行
|
||||
- SQLite 用于单机场景
|
||||
|
||||
## 迁移支持（数据库）
|
||||
|
||||
项目内置 schema version 迁移：
|
||||
|
||||
- 启动服务时自动执行迁移
|
||||
- 也可手动执行：
|
||||
|
||||
```bash
|
||||
python scripts/migrate_db.py
|
||||
```
|
||||
|
||||
迁移记录存储在 `schema_migrations` 表，便于后续版本升级与跨环境迁移。
|
||||
Reference in New Issue
Block a user