Originals/ViGent2

Fork 0

Files

Kevin Wong 9af50a9066 更新

2026-02-03 17:15:35 +08:00

4.8 KiB

Raw Blame History

ViGent2 后端开发指南

本文档为后端开发人员提供架构概览、接口规范以及开发流程指南。

🏗️ 架构概览

后端采用 FastAPI 框架，基于 Python 3.10+ 构建，主要负责业务逻辑处理、AI 任务调度以及与各微服务组件的交互。

目录结构

backend/
├── app/
│   ├── api/              # API 路由定义 (endpoints)
│   ├── core/             # 核心配置 (config.py, security.py)
│   ├── models/           # Pydantic 数据模型 (schemas)
│   ├── services/         # 业务逻辑服务层
│   │   ├── auth_service.py       # 用户认证服务
│   │   ├── glm_service.py        # GLM-4 大模型服务
│   │   ├── lipsync_service.py    # LatentSync 唇形同步
│   │   ├── publish_service.py    # 社交媒体发布
│   │   └── voice_clone_service.py# Qwen3-TTS 声音克隆
│   └── tests/            # 单元测试与集成测试
├── scripts/              # 运维脚本 (watchdog.py, init_db.py)
├── assets/               # 资源库 (fonts, bgm, styles)
└── requirements.txt      # 依赖清单

🔌 API 接口规范

后端服务默认运行在 8006 端口。

文档地址: http://localhost:8006/docs (Swagger UI)
认证方式: Bearer Token (JWT)

核心模块

认证 (Auth)
- POST /api/auth/login: 用户登录 (手机号)
- POST /api/auth/register: 用户注册
- GET /api/auth/me: 获取当前用户信息
视频生成 (Videos)
- POST /api/videos/generate: 提交生成任务
- GET /api/videos/tasks/{task_id}: 查询任务状态
- GET /api/videos/generated: 获取历史视频列表
- DELETE /api/videos/generated/{video_id}: 删除历史视频

修正 (16:20)：任务查询与历史列表接口已更新为 /api/videos/tasks/{task_id} 与 /api/videos/generated。

素材管理 (Materials)
- POST /api/materials/upload: 上传素材 (Direct Upload to Supabase)
- GET /api/materials: 获取素材列表
社交发布 (Publish)
- POST /api/publish: 发布视频到 B站/抖音/小红书
资源库 (Assets)
- GET /api/assets/subtitle-styles: 字幕样式列表
- GET /api/assets/title-styles: 标题样式列表
- GET /api/assets/bgm: 背景音乐列表

🎛️ 视频生成扩展参数

POST /api/videos/generate 支持以下可选字段：

subtitle_style_id: 字幕样式 ID
title_style_id: 标题样式 ID
subtitle_font_size: 字幕字号（覆盖样式默认值）
title_font_size: 标题字号（覆盖样式默认值）
bgm_id: 背景音乐 ID
bgm_volume: 背景音乐音量（0-1，默认 0.2）

📦 资源库与静态资源

本地资源目录：backend/assets/{fonts,bgm,styles}
静态访问路径：/assets（用于前端样式预览与背景音乐试听）

🎵 背景音乐混音策略

混音发生在 唇形对齐之后，避免影响字幕/口型时间轴。
使用 FFmpeg amix，禁用归一化以保持配音音量稳定。

🛠️ 开发环境搭建

1. 虚拟环境

cd backend
python -m venv venv
source venv/bin/activate  # Linux/macOS
# .\venv\Scripts\activate # Windows

2. 依赖安装

pip install -r requirements.txt

3. 环境变量配置

复制 .env.example 到 .env 并配置必要的 Key：

# Supabase
SUPABASE_URL=http://localhost:8008
SUPABASE_KEY=your_service_role_key

# GLM API (用于 AI 标题生成)
GLM_API_KEY=your_glm_api_key

# LatentSync 配置
LATENTSYNC_GPU_ID=1

4. 启动服务

开发模式 (热重载):

uvicorn app.main:app --host 0.0.0.0 --port 8006 --reload

🧩 服务集成指南

集成新模型

如果需要集成新的 AI 模型 (例如新的 TTS 引擎)：

在 app/services/ 下创建新的 Service 类 (如 NewTTSService)。
实现 generate 方法，可以使用 subprocess 调用，也可以是 HTTP 请求。
重要: 如果模型占用 GPU，请务必使用 asyncio.Lock 进行并发控制，防止 OOM。
在 app/api/ 中添加对应的路由调用。

添加定时任务

目前推荐使用 APScheduler 或 Crontab 来管理定时任务。社交媒体的定时发布功能目前依赖 playwright 的延迟执行，未来计划迁移到 Celery 队列。

🛡️ 错误处理

全项目统一使用 Loguru 进行日志记录。

from loguru import logger

try:
    # 业务逻辑
except Exception as e:
    logger.error(f"操作失败: {str(e)}")
    raise HTTPException(status_code=500, detail="服务器内部错误")

🧪 测试

运行测试套件：

pytest

4.8 KiB Raw Blame History Unescape Escape