AI_A4000/read.md

你是一个资深 Python / AI Infra / 推理服务工程师。你的任务不是讨论方案，而是直接在本地完成一个可运行的项目。

任务目标

在 WSL2 + Ubuntu + NVIDIA RTX A4000 16GB 环境下，开发一个 本地单机视频生成 Worker 服务，只做一件事：

接收一次视频生成请求 → 根据模式选择模型 → 在 A4000 上执行推理 → 输出视频文件 → 返回任务状态与结果路径。

这个 Worker 是一个边缘执行节点，不是完整平台。

---

必须遵守的边界

只做这些

• 提供本地 HTTP API

• 接收 text-to-video 请求

• 使用本地模型推理

• 单任务串行执行

• 输出固定目录结构

• 支持两种模式：

  • preview → LTX-Video
  • refine → HunyuanVideo-1.5

不要做这些

• 不做脚本生成
• 不做分镜拆解
• 不做 prompt 自动生成
• 不做剪辑
• 不做 ComfyUI 集成
• 不做多机调度
• 不做前端页面
• 不做复杂鉴权
• 不做 image-to-video
• 不做 video extend
• 不做数据库集群
• 不做消息队列中间件

---

最终交付物

你必须直接生成一个完整可运行项目，至少包含：

1. 项目源码目录
2. requirements.txt
3. .env.example
4. README.md
5. scripts/install_wsl_env.sh
6. scripts/run_server.sh
7. scripts/smoke_test.py
8. FastAPI 服务源码
9. SQLite 任务存储
10. 单 worker 串行队列
11. 模型路由器
12. LTX backend
13. Hunyuan backend
14. 统一输出目录
15. 基础日志
16. 错误处理
17. 健康检查接口

---

技术要求

基础技术栈

• Python 3.10+
• FastAPI
• Uvicorn
• Pydantic
• SQLite
• asyncio
• ffmpeg
• torch
• diffusers / transformers / accelerate / safetensors（按需要引入）
• WSL2 下通过 CUDA 调用 A4000

代码要求

• 代码必须结构清晰
• 所有核心模块必须可直接运行
• 不要只写伪代码
• 必须包含真实可执行代码骨架
• 重要处要有注释
• 要考虑异常处理
• 要考虑模型懒加载
• 要考虑单卡显存限制
• 所有路径都要可配置
• 配置统一放到 settings.py 和 .env

---

系统架构

实现下面这个最小架构：

Client
  -> FastAPI
  -> TaskManager
  -> ModelRouter
  -> GPUWorker
  -> Backend(LTX/Hunyuan)
  -> OutputWriter
  -> outputs/{task_id}/video.mp4

---

模型路由规则

固定规则：

• quality_mode = "preview" → LTX-Video
• quality_mode = "refine" → HunyuanVideo-1.5

请把模型路由实现成独立模块，后续方便替换。

---

任务状态

只保留这些状态：

• PENDING
• RUNNING
• SUCCEEDED
• FAILED

不要额外扩展复杂状态机。

---

API 设计

你必须实现以下接口。

1）创建任务

POST /generate

请求体：

{
  "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
}

要求：

• 自动生成 task_id
• 写入 SQLite
• 入队
• 返回 task_id 和状态

---

2）查询任务状态

GET /tasks/{task_id}

返回：

• task_id
• status
• backend
• model_name
• progress
• created_at
• updated_at

---

3）查询任务结果

GET /tasks/{task_id}/result

成功时返回：

• task_id
• status
• video_path
• first_frame_path
• metadata_path
• log_path

失败时返回：

• task_id
• status
• error

---

4）健康检查

GET /health

返回：

• 服务状态
• CUDA 是否可用
• GPU 名称
• 两个模型是否已加载

---

输入参数约束

第一版严格限制：

• 只支持 text-to-video
• duration_sec 允许 1~5
• width 最大 832
• height 最大 480
• fps 最大 24
• quality_mode 只允许 preview 或 refine

你需要在 Pydantic schema 中严格校验。

---

输出目录规范

每个任务固定输出到：

outputs/{task_id}/
  ├─ video.mp4
  ├─ first_frame.jpg
  ├─ metadata.json
  └─ run.log

其中：

metadata.json

至少包含：

• task_id
• backend
• model_name
• prompt
• negative_prompt
• seed
• width
• height
• fps
• steps
• duration_sec
• status
• created_at
• started_at
• finished_at
• video_path

---

目录结构要求

按下面结构生成项目：

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
│  ├─ run_server.sh
│  └─ smoke_test.py
├─ requirements.txt
├─ .env.example
└─ README.md

---

模块职责

schemas.py

定义：

• GenerateRequest
• TaskStatusResponse
• TaskResultResponse
• HealthResponse

---

task_store.py

使用 SQLite 存储任务信息，至少包含：

• task_id
• status
• backend
• model_name
• request_json
• output_dir
• error_message
• created_at
• updated_at

---

task_manager.py

负责：

• 创建任务
• 写入数据库
• 入队
• 更新状态
• 查询状态与结果

---

gpu_worker.py

负责：

• 后台单线程取任务
• 标记任务为 RUNNING
• 调用路由器选择 backend
• 执行生成
• 写入结果
• 成功标记 SUCCEEDED
• 失败标记 FAILED

要求：

• 必须是单任务串行
• 不允许多任务并发占用 GPU

---

model_router.py

根据 quality_mode 返回 ltx_backend 或 hunyuan_backend

---

backends/base.py

定义统一接口：

• load()
• is_loaded()
• generate(task)

---

backends/ltx_backend.py

要求：

• 实现懒加载
• 作为默认 preview 模型
• 重点保证代码结构正确
• 若本地真实模型推理接入较复杂，可先封装清晰的推理入口与参数映射，但不要省略真实调用预留位
• 输出必须符合统一目录规范

---

backends/hunyuan_backend.py

要求：

• 实现懒加载
• 作为 refine 模型
• 保留 cpu offload、vae tiling 等内存优化入口
• 输出必须符合统一目录规范

---

utils/ffmpeg_utils.py

必须实现：

• 如果 backend 输出帧序列，则合成为 video.mp4
• 从 video.mp4 抽取 first_frame.jpg

---

运行原则

1）模型懒加载

• 服务启动时不要强制加载所有模型
• 第一次调用对应 backend 时再加载
• 加载后常驻

2）单任务串行

• A4000 16GB 只允许一个视频任务同时运行
• 必须实现内存队列 + 单 worker

3）先支持 preview，再支持 refine

• 但代码结构里两个 backend 都要存在
• 如果某个 backend 先以占位实现，也必须说明后续替换点

---

配置要求

在 .env.example 中提供以下配置项：

APP_HOST=0.0.0.0
APP_PORT=8000
OUTPUT_DIR=./outputs
RUNTIME_DIR=./runtime
SQLITE_PATH=./runtime/tasks.db

LTX_MODEL_DIR=./models/ltx
HUNYUAN_MODEL_DIR=./models/hunyuan

DEFAULT_WIDTH=832
DEFAULT_HEIGHT=480
DEFAULT_FPS=16
DEFAULT_DURATION=5
DEFAULT_STEPS_PREVIEW=8
DEFAULT_STEPS_REFINE=12

---

README 必须包含

1. 项目说明
2. 环境准备
3. WSL + CUDA 检查方法
4. 安装命令
5. 启动命令
6. 调用示例
7. 目录说明
8. API 说明
9. 常见问题
10. 已知限制

---

安装脚本要求

scripts/install_wsl_env.sh

需要完成：

• 创建 Python venv
• 升级 pip
• 安装 requirements
• 安装 ffmpeg
• 创建输出目录
• 创建 runtime 目录
• 给出后续启动提示

---

启动脚本要求

scripts/run_server.sh

需要完成：

• 激活 venv
• 检查 .env
• 启动 uvicorn

---

烟雾测试要求

scripts/smoke_test.py

需要完成：

• 调用 /health
• 创建一个 preview 任务
• 轮询任务状态
• 打印结果路径

---

开发顺序

严格按这个顺序实现：

Phase 1

• 建目录
• 写 settings.py
• 写 schemas.py
• 写 task_store.py
• 写 task_manager.py
• 写基础 API
• 写 SQLite 初始化
• 写单 worker 队列

Phase 2

• 写 model_router.py
• 写 backends/base.py
• 写 ltx_backend.py
• 打通 preview 路由
• 输出 video.mp4 / metadata.json / run.log

Phase 3

• 写 hunyuan_backend.py
• 打通 refine 路由
• 增加 /health
• 增加 ffmpeg 抽帧

Phase 4

• 完善 README
• 完善脚本
• 完善错误处理
• 完善 smoke test

---

验收标准

你完成后，必须满足以下条件：

1. 项目可直接启动
2. GET /health 可用
3. POST /generate 可创建任务
4. 任务会进入 PENDING -> RUNNING -> SUCCEEDED/FAILED
5. preview 模式能真正走 LTX backend
6. refine 模式能真正走 Hunyuan backend
7. 输出目录结构正确
8. metadata.json 完整
9. 失败时有明确错误信息
10. 代码结构足够清晰，后续方便替换真实模型实现

---

输出要求

你现在直接开始产出代码与文件内容，不要继续解释方案，不要重复需求，不要空谈架构。

请按下面顺序输出：

1. 项目目录树
2. 每个文件的完整内容
3. 最后给出运行步骤

要求所有内容都尽可能完整，可复制使用。