AI_A4000/video_worker/README.md

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 内执行：

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

cd video_worker
bash scripts/install_wsl_env.sh
cp .env.example .env  # 若脚本未自动生成

Windows PowerShell

cd video_worker
.\scripts\install_windows_env.ps1

5. 启动命令

WSL / Linux

cd video_worker
bash scripts/run_server.sh

Windows

cd video_worker
.\scripts\run_server.ps1

或：

scripts\run_server.bat

6. 调用示例

创建任务：

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
  }'

轮询状态：

curl http://127.0.0.1:8000/tasks/<task_id>
curl http://127.0.0.1:8000/tasks/<task_id>/result

烟雾测试：

cd video_worker
. .venv/bin/activate  # Windows: .\.venv\Scripts\Activate.ps1
python scripts/smoke_test.py

7. 目录说明

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 迁移：

• 启动服务时自动执行迁移
• 也可手动执行：

python scripts/migrate_db.py

迁移记录存储在 schema_migrations 表，便于后续版本升级与跨环境迁移。