Daniel/AI_A4000
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
AI_A4000/read.md
Daniel 8d0b729f2f feat: 新增代码
2026-04-07 00:37:39 +08:00

9.4 KiB
Raw Permalink Blame History

你是一个资深 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. 最后给出运行步骤

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

Reference in New Issue View Git Blame Copy Permalink