基于 SoulX-FlashHead 的说话头部视频生成服务。上传一张人像图片和一段音频，自动裁剪头肩区域并生成 512×512 的说话头部视频。
节点运行状态一览：在线状态、队列深度、当前任务。
上传参考图片和音频文件，一键提交合成任务。
按状态筛选任务，查看历史记录，支持刷新、预览和下载。
任务完成后在线预览生成的说话头部视频。
- 双模式推理 — lite（单卡蒸馏模型）/ pro（预训练模型，支持单卡或双卡序列并行）
- 自动人脸裁剪 — 基于 MediaPipe 的 CPU 人脸检测，自动定位并裁剪头肩正方形区域；也支持前端手动指定裁剪区域
- 背景移除 — 集成 RVM (Robust Video Matting) 模型，支持将视频背景替换为自定义颜色（默认绿幕），便于后期抠像合成
- 贴回原图 — 支持将生成的 512×512 头部视频贴回原图尺寸，其他区域保持静止
- 异步任务队列 — Redis 队列 + 单线程池串行调度，提交即返回 task_id，轮询获取进度
- 管理面板 — 内置 Vue 3 单页面，暗色主题，可视化管理任务与文件
- 网关对接 — 支持向 Once Edge 网关自动注册节点 + 心跳保活
- API Key 认证 — 所有业务接口通过
X-API-KeyHeader 鉴权 - 自动清理 — 过期上传文件定时清理，可配置保留时长
once_flash_head_api/
├── config/ # 配置层
│ ├── config.yml # 唯一配置文件（.gitignore 已忽略）
│ ├── schema.py # Pydantic 配置模型 (AppConfig)
│ └── loader.py # get_config() 单例加载器
├── state/ # 状态层（数据库 / 队列 / 调度）
│ ├── db_engine.py # SQLAlchemy 引擎 (PostgreSQL, 自动建表)
│ ├── db_models.py # ORM 模型: Task, UploadedFile
│ ├── db_operations.py # 数据库 CRUD
│ ├── redis_client.py # Redis 客户端（任务队列 + 进度）
│ └── scheduler.py # 单线程池任务调度器
├── schema/ # 数据模型
│ ├── enums.py # TaskStatus 枚举
│ └── request_entities.py # 请求体定义 (SynthesizeRequest 等)
├── service/ # 服务层
│ ├── app.py # FastAPI 应用 + 生命周期管理
│ ├── dependencies.py # API Key 认证依赖
│ └── routes/ # 路由
│ ├── task_api.py # 任务：合成 / 查询 / 下载
│ ├── file_api.py # 文件：上传
│ └── system_api.py # 系统：健康检查、调度器状态
├── cores/ # 核心适配
│ ├── pipeline_adapter.py # FlashHead 推理适配器（初始化 / 预处理 / 推理 / 编码）
│ ├── rvm_processor.py # RVM 背景移除处理器
│ └── rvm/ # RVM 模型架构
│ ├── model.py # MattingNetwork 主模型
│ ├── decoder.py # 解码器
│ ├── mobilenetv3.py # MobileNetV3 backbone
│ ├── resnet.py # ResNet50 backbone
│ └── ... # 其他模块
├── utils/ # 工具
│ ├── result.py # 统一响应格式 R
│ └── file_manager.py # 文件上传管理
├── flash_head/ # 核心算法（SoulX-FlashHead 源码，不修改）
│ ├── inference.py # 推理入口
│ ├── audio_analysis/ # wav2vec2 音频特征提取
│ ├── ltx_video/ # LTX-Video VAE & Transformer
│ ├── wan/ # WAN VAE 模块
│ ├── src/ # FlashHead 模型 + 分布式推理
│ ├── utils/ # 人脸裁剪、工具函数
│ └── configs/ # 推理参数 (infer_params.yaml)
├── checkpoint/ # 模型权重（需自行下载，已 gitignore）
│ ├── SoulX-FlashHead-1_3B/ # FlashHead 1.3B 模型
│ ├── wav2vec2-base-960h/ # wav2vec2 音频编码器
│ └── rvm_resnet50.pth # RVM 背景移除模型（可选）
├── libs/ # 外部工具（已 gitignore，需自行下载）
│ └── ffmpeg(.exe) # FFmpeg 可执行文件
├── images/ # README 截图
├── templates/
│ └── index.html # Vue 3 管理面板（暗色主题单页应用）
├── base.py # 路径常量
├── start_api.py # 启动入口
├── requirements.txt # Python 依赖
└── cache/ # 运行时缓存（自动创建，已 gitignore）
├── uploads/ # 上传文件暂存
└── out/ # 输出视频
| 依赖 | 版本 |
|---|---|
| Python | 3.10 |
| CUDA | 12.8+ |
| PyTorch | 2.7.1 |
| PostgreSQL | 12+ |
| Redis | 5+ |
| FFmpeg | 4.4+ |
GPU 显存需求：lite 模式约 8 GB，pro 模式约 18 GB（单卡 4090 24GB 可运行）。
项目依赖 FFmpeg 进行视频编码，需要自行下载并放置到 libs/ 目录下，然后在 config.yml 中配置 ffmpeg_path 为绝对路径。
- Windows：下载 ffmpeg-release-essentials.zip，解压后将
ffmpeg.exe放入libs/ - Linux：下载 ffmpeg-release-amd64-static.tar.xz，解压后将
ffmpeg二进制放入libs/
conda create -n flashhead python=3.10
conda activate flashhead# PyTorch (CUDA 12.8)
pip install torch==2.7.1 torchvision==0.22.1 --index-url https://download.pytorch.org/whl/cu128
# 项目依赖
pip install -r requirements.txt
# FlashAttention（需要 ninja 编译）
pip install ninja && pip install flash_attn==2.8.0.post2 --no-build-isolation将模型文件放置到 checkpoint/ 目录下：
checkpoint/
├── SoulX-FlashHead-1_3B/ # FlashHead 模型权重
├── wav2vec2-base-960h/ # wav2vec2 音频编码器
└── rvm_resnet50.pth # RVM 背景移除模型（可选，启用背景移除功能时需要）
RVM 模型下载：
如需使用背景移除功能，请下载 RVM 模型：
- 下载地址：rvm_resnet50.pth
- 放置位置：
checkpoint/rvm_resnet50.pth - 模型大小：约 103 MB
复制并编辑 config/config.yml，按实际环境修改以下字段：
database:
host: "your-pg-host"
password: "your-pg-password"
redis:
host: "your-redis-host"
password: "your-redis-password"
flashhead:
mode: lite # lite 或 pro
ckpt_dir: "/absolute/path/to/checkpoint/SoulX-FlashHead-1_3B"
wav2vec_dir: "/absolute/path/to/checkpoint/wav2vec2-base-960h"
# RVM 背景移除配置（可选）
rvm:
enabled: true # 是否启用背景移除功能
variant: resnet50 # 模型变体：resnet50 或 mobilenetv3
checkpoint: "/absolute/path/to/checkpoint/rvm_resnet50.pth"
device: cuda # 推理设备
bg_color: [0, 255, 0] # 默认背景颜色 BGR 格式（绿色）
downsample_ratio: 0.5 # 下采样比例
server:
port: 8100
api_key: "your-api-key"
ffmpeg_path: "/absolute/path/to/ffmpeg"
cache_dir: "/absolute/path/to/cache"
out_dir: "/absolute/path/to/cache/out"注意：所有路径必须使用绝对路径。
config.yml已被.gitignore忽略，不会提交到仓库。
python start_api.py服务启动后访问：
| 地址 | 说明 |
|---|---|
http://localhost:8100/ |
管理面板 |
http://localhost:8100/docs |
Swagger API 文档 |
http://localhost:8100/redoc |
ReDoc API 文档 |
所有业务接口需携带 Header：X-API-Key: <your-api-key>
POST /api/files/upload
Content-Type: multipart/form-data
支持格式：.png .jpg .jpeg .wav .mp3 .m4a响应示例：
{
"code": 200,
"message": "success",
"data": {
"file_id": "uuid",
"filename": "photo.png",
"file_size": 102400,
"file_type": "image"
}
}POST /api/tasks/synthesize
Content-Type: application/json
{
"image_file_id": "上传返回的 file_id",
"audio_file_id": "上传返回的 file_id",
"crop_region": [x1, y1, x2, y2],
"restore_to_original": false,
"bg_remove": false,
"bg_color": "#00FF00"
}参数说明：
image_file_id(必填)：上传图片返回的 file_idaudio_file_id(必填)：上传音频返回的 file_idcrop_region(可选)：裁剪区域 [x1, y1, x2, y2]，不传则自动人脸检测裁剪restore_to_original(可选)：是否将生成的头部视频贴回原图尺寸，默认 falsebg_remove(可选)：是否移除背景并替换为纯色，默认 falsebg_color(可选)：背景颜色（十六进制格式），默认#00FF00（绿色）
GET /api/tasks/{task_id}任务状态流转：pending → running → completed / failed
GET /api/tasks/{task_id}/download返回 MP4 视频文件流。
| 模式 | 模型 | 推理步数 | GPU 需求 | 说明 |
|---|---|---|---|---|
| lite | 蒸馏模型 (1.3B) | 4 steps | 单卡 (~8GB) | 速度快，适合实时场景 |
| pro | 预训练模型 (1.3B) | 4 steps | 单卡 (~18GB) 或 双卡 | 质量更高，单卡 4090 24GB 可运行；双卡自动 torchrun 序列并行 |
Teacher 模型尚未发布，当前 pro 模式使用已发布的预训练模型。
在 config.yml 中设置 flashhead.mode 切换模式。pro 双卡模式通过 flashhead.pro_device_ids 指定 GPU。
用户上传图片/音频
│
▼
POST /api/files/upload ──→ 返回 file_id
│
▼
POST /api/tasks/synthesize
│
├─ 有 crop_region ──→ 按指定区域裁剪
│
└─ 无 crop_region ──→ MediaPipe 人脸检测
│
▼
ratio=3.0 裁剪正方形
│
▼
resize_and_centercrop → 512×512
│
▼
FlashHead Pipeline 推理
│
▼
FFmpeg 编码 → .mp4
│
├─ restore_to_original=true ──→ 贴回原图
│
└─ bg_remove=true ──→ RVM 背景移除
│
▼
替换为自定义颜色背景
│
▼
GET /api/tasks/{task_id} ──→ 查询状态
GET /api/tasks/{task_id}/download ──→ 下载视频
- SoulX-FlashHead — 核心说话头部生成算法
本项目基于 Apache License 2.0 开源。