105 lines
7.9 KiB
Markdown
105 lines
7.9 KiB
Markdown
# SKG TK 二创验证 — 当前状态（2026-05-18）
|
||
|
||
## 一句话
|
||
当前产品方向已收窄为“信息流广告快速复刻”：TK 链接 / 上传视频后，先下载源视频，再并行跑音频文案路和视频视觉路；视频视觉路自动抽 6 张人物定向随机参考帧；产品素材独立成池，自动识别视角并补缺角度；分镜工作台按逐句时间轴写新口播、人物/产品需求和首尾帧规划。当前暂停直接提交视频模型，先逐条生成并审核首帧 / 尾帧。
|
||
|
||
## 路径 / 端口
|
||
- 当前工作树：`/Users/kangwan/Projects/business/20260512-20260512-skg-tk-二创验证-backend/`
|
||
- 主项目路径：`/Users/kangwan/Projects/business/20260512-20260512-skg-tk-二创验证/`
|
||
- 后台启动：`./scripts/start-dev-background.sh`（前端 4290，后端 4291，launchd 托管）
|
||
- 后台停止：`./scripts/stop-dev-background.sh`
|
||
- web dev：`cd web && npm run dev`
|
||
- api dev：`cd api && uvicorn main:app --host 127.0.0.1 --port 4291`
|
||
- 注意：后端不要带 `--reload` 跑下载、抽帧、音频和生图等长任务。
|
||
|
||
## 当前模型分工
|
||
`LLM_BASE_URL` 默认走 `https://ai.skg.com/ezlink/v1`，图片同样默认走 `IMAGE_BASE_URL=https://ai.skg.com/ezlink/v1`，语音默认走 `https://ai.skg.com/azure`，生产视频默认走 `https://ai.skg.com/doubao`。
|
||
|
||
| 任务 | 当前模型 / 通道 | 备注 |
|
||
|---|---|---|
|
||
| 远端 ASR | `ASR_MODEL=whisper-1` | 失败后进本机 ASR，再进多模态兜底。 |
|
||
| 本机 ASR | `LOCAL_ASR_MODEL=mlx-community/whisper-tiny` | 默认二级兜底，优先产出真实逐句时间轴。 |
|
||
| ASR 兜底 / 音频分析 | `ASR_FALLBACK_MODEL=gemini-2.5-flash` | 多模态音频兜底；后端会拒绝假字幕、重复文本和覆盖率过低结果。 |
|
||
| 字幕翻译 | `TRANSLATE_MODEL=gemini-2.5-flash` | 保留 Gemini。 |
|
||
| 画面理解 | `VISION_MODEL=gpt-4o` | 关键帧 Vision 已切 GPT；旧环境若写 `gemini-*` 会自动归一化到 `GPT_TEXT_MODEL`。 |
|
||
| 通用改写 / 分镜描述 | `REWRITE_MODEL=gpt-4o` | 已切 GPT；旧 Gemini 覆盖值会自动归一化。 |
|
||
| 新口播改写 | `AUDIO_REWRITE_MODEL=gpt-4o` | 默认跟随 `REWRITE_MODEL`；旧 Gemini 覆盖值会自动归一化。 |
|
||
| 产品视角识别 | `PRODUCT_VIEW_MODEL=gpt-image-2` | 产品图批量识别视角、左右 / 上下 / 内外侧、用途和风险。 |
|
||
| 所有生图 / 修图 | `gpt-image-2` | 服务端硬锁，无图片模型 fallback；覆盖关键帧生图、水印清理、元素提取、主体资产包、产品补角度、首尾帧。 |
|
||
| 配音 | `VOICE_PROVIDER=azure_openai` + `AZURE_TTS_MODEL=gpt-4o-mini-tts` | 语音固定 Azure OpenAI TTS；MiniMax 不再作为 fallback。后端会按 `AZURE_TTS_PATHS` 依次尝试路径，便于区分路径错误和整条语音服务不可用。 |
|
||
| 视频 | `VIDEO_MODEL=seedance` | 当前主流程暂停直接提交；生产通道默认 `ai.skg.com/doubao`，Seedance 真实 ID 由 `VIDEO_MODEL_SEEDANCE` 配置。 |
|
||
|
||
## 当前主流程
|
||
| 步 | 模块 | 状态 | 备注 |
|
||
|---|---|---|---|
|
||
| 1 | 输入 / 下载 | 已通 | TK 链接或上传视频创建 job，下载完成后进入分析队列。 |
|
||
| 2 | 音频文案路 | 已通 | 拆 `audio.wav`，ASR、翻译、讲话人 / 节奏 / 背景音分析；结果默认折叠展示。 |
|
||
| 3 | 视频视觉路 | 已通 | 自动抽 6 张人物定向随机参考帧；当前工作区按 9:16 原视频播放秒数手动补帧。 |
|
||
| 4 | 相似主体资产 | 已通 | 用关键帧和可选内置角色生成同一主体的 10 张白底视图。 |
|
||
| 5 | 产品资产池 | 已通 | 上传 / 内置产品图统一入池，自动识别视角、结构点、用途、风险，缺角度可补图。 |
|
||
| 6 | 分镜工作台 | 已通 | 按逐句时间轴编辑新口播、镜头类型、人物 / 产品开关、首帧 / 尾帧规划。 |
|
||
| 7 | 首尾帧闸门 | 已通 | 每条分镜先用相似主体视图和产品素材生成首帧 / 尾帧，审核后保存。 |
|
||
| 8 | 视频候选 | 暂停直提 | 历史候选保留展示；当前不再一键打 Seedance，等首尾帧审核后再开放单条提交。 |
|
||
|
||
## 关键文件
|
||
- `api/main.py` — FastAPI 后端、模型路由、任务状态、ASR/翻译/音频分析、生图、产品识别、首尾帧和视频接口。
|
||
- `api/database.py` — 后端数据库层；当前用 SQLite 保存 document / job / media asset 元数据，媒体文件仍在 `jobs/<jobId>/`。
|
||
- `api/.env.example` — 本地模型和网关模板；已包含 `GPT_TEXT_MODEL=gpt-4o`。
|
||
- `deploy/.env.production.example` — 生产环境模板；视频默认 SKG Doubao / Seedance 网关。
|
||
- `RULES.md` — 启动、部署事实、模型环境变量和项目规则。
|
||
- `docs/source-analysis.html` — 源码解析页；任何影响产品理解、接口、模型分工或操作路径的改动都要同步这里。
|
||
- `web/components/ad-recreation-board.tsx` — 当前信息流复刻主工作台。
|
||
- `web/components/media-asset-tile.tsx` — 统一媒体素材缩略图、hover 放大、删除和状态遮罩组件。
|
||
- `web/lib/api.ts` — 前端 API client 和运行模型标注类型。
|
||
|
||
## 主要 API
|
||
```
|
||
GET /health
|
||
GET /documents
|
||
POST /jobs
|
||
POST /jobs/upload
|
||
GET /jobs
|
||
GET /jobs/{id}
|
||
DELETE /jobs/{id}
|
||
POST /jobs/{id}/analyze
|
||
POST /jobs/{id}/transcribe
|
||
POST /jobs/{id}/frames?t=<sec>
|
||
DELETE /jobs/{id}/frames/{idx}
|
||
POST /jobs/{id}/frames/{idx}/describe
|
||
POST /jobs/{id}/frames/{idx}/cleanup
|
||
POST /jobs/{id}/frames/{idx}/cleanup/apply
|
||
POST /jobs/{id}/frames/{idx}/generate
|
||
POST /jobs/{id}/frames/{idx}/scene-asset
|
||
POST /jobs/{id}/frames/{idx}/elements
|
||
POST /jobs/{id}/frames/{idx}/elements/{element_id}/cutout
|
||
POST /jobs/{id}/frames/{idx}/elements/{element_id}/subject-assets
|
||
POST /jobs/{id}/assets
|
||
PUT /jobs/{id}/product-refs
|
||
POST /jobs/{id}/assets/product-views/analyze
|
||
POST /jobs/{id}/assets/product-angle
|
||
POST /jobs/{id}/script/rewrite
|
||
PUT /jobs/{id}/frames/{idx}/storyboard
|
||
POST /jobs/{id}/frames/{idx}/storyboard/video
|
||
```
|
||
|
||
## 当前约束 / 不要踩
|
||
1. 图片 / 视频 / 抽帧 / 产品图 / 生成图 / 首尾帧 / 视频候选缩略图默认复用 `web/components/media-asset-tile.tsx`。
|
||
2. 所有生图入口服务端只允许 `gpt-image-2`，不要重新加 Gemini 图片模型或其他 fallback。
|
||
3. 画面理解和文案改写默认归 GPT：`VISION_MODEL`、`REWRITE_MODEL`、`AUDIO_REWRITE_MODEL` 会拦截旧 `gemini-*` 覆盖值。
|
||
4. Gemini 仍保留在 ASR fallback / 音频分析 / 翻译链路，不要误删。
|
||
5. 语音只走 Azure OpenAI TTS；不要新增或依赖 MiniMax 配音配置。
|
||
6. 当前主流程不直接批量提交视频；先走“分镜规划 → 首尾帧 → 人工审核”。
|
||
7. 产品素材池默认是“同一产品”，不做不同产品身份判断；视角识别必须按佩戴者左 / 右、上 / 下、内 / 外侧描述。
|
||
8. 自动抽帧默认是 `frames=6` + `target=random_subject` + `quality=accurate` + `mode=replace`；如果需要特定动作或表情，用“当前点抽帧”手动补。
|
||
9. 文档是顶层业务归类：每个 TK 链接或上传视频默认一个 `document`，`job` 归属到 `document_id`；DB 存元数据和文件索引，视频 / 图片 / 音频文件不进 DB。
|
||
10. 后端长任务不要用 `--reload`。
|
||
11. 关键帧 `index` 是稳定 ID，不等于数组下标；前端取帧用 `frames.find(x => x.index === idx)`。
|
||
|
||
## 最近变更
|
||
- 2026-05-18：新增后端数据库层，SQLite 默认落在 `APP_DB_URL` / `DATABASE_URL` 或 `JOBS_DIR/app.db`；`/documents` 返回文档归类列表，`/health.database` 返回 DB 状态。
|
||
- 2026-05-18：`VISION_MODEL`、`REWRITE_MODEL`、`AUDIO_REWRITE_MODEL` 切到 GPT 默认模型 `gpt-4o`，并加旧 Gemini 环境变量归一化保护。
|
||
- 2026-05-18：语音通道固定 Azure OpenAI TTS，移除 MiniMax fallback，并按 `AZURE_TTS_PATHS` 尝试语音路径。
|
||
- 2026-05-18：当前主路径暂停直接提交视频，改为逐条首尾帧闸门。
|
||
- 2026-05-18：媒体素材交互统一收口到 `MediaAssetTile`。
|
||
- 2026-05-18：产品图视角识别和产品缺角度补图收敛到 `gpt-image-2`。
|