docs: refresh current project status
This commit is contained in:
@@ -1,146 +1,97 @@
|
||||
# SKG TK 二创验证 — 当前状态（2026-05-13）
|
||||
# SKG TK 二创验证 — 当前状态（2026-05-18）
|
||||
|
||||
## 一句话
|
||||
SKG AI 素材生产管线第二条思路：TK 链接/上传 → 拆轨 → 抽关键帧（5 张+手动加）→ Vision 识别 → 改写文案 → 生图 → 生视频 → 合成。**MVP 通到生图，剩余 3 个节点占位**。
|
||||
当前产品方向已收窄为“信息流广告快速复刻”：TK 链接 / 上传视频后，先下载源视频，再并行跑音频文案路和视频视觉路；产品素材独立成池，自动识别视角并补缺角度；分镜工作台按逐句时间轴写新口播、人物/产品需求和首尾帧规划。当前暂停直接提交视频模型，先逐条生成并审核首帧 / 尾帧。
|
||||
|
||||
## 路径 / 端口
|
||||
- 路径：`~/Projects/business/20260512-20260512-skg-tk-二创验证/`
|
||||
- web dev：`cd web && pnpm dev`（端口 **4290**）
|
||||
- api dev：`cd api && source .venv/bin/activate && uvicorn main:app --port 4291 --reload`
|
||||
- 测试 job：`?job=c6767f3a166b`（chrisorb 71s 竖屏 TK）
|
||||
- 当前工作树：`/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` 跑下载、抽帧、音频和生图等长任务。
|
||||
|
||||
## SKG 网关能力（实测 · 关键！）
|
||||
`base_url: https://ai.skg.com/ezlink/v1`
|
||||
key 写在 `api/.env` 的 `LLM_API_KEY`
|
||||
## 当前模型分工
|
||||
`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`。
|
||||
|
||||
| 端点 / 字段 | 状态 | 用途 |
|
||||
| 任务 | 当前模型 / 通道 | 备注 |
|
||||
|---|---|---|
|
||||
| `/v1/chat/completions` text-only | ✅ 通 | translate / rewrite |
|
||||
| `/v1/chat/completions` + image_url | ✅ **通**（之前误判为不通，是 dog.jpg 那张图损坏） | vision 识别图片（gemini-2.5-flash 推荐） |
|
||||
| `/v1/chat/completions` + input_audio | ❌ 不通 | ASR 不能走这条 |
|
||||
| `/v1/audio/transcriptions` (whisper) | ❌ 404 | 整个 audio 端点都没暴露 |
|
||||
| `/v1/audio/speech` (tts) | ❌ 404 | |
|
||||
| `/v1/images/generations` (text→image) | ✅ 通 | 生图（gemini-3-pro-image-preview = nano-banana-pro） |
|
||||
| `/v1/images/generations` + image 参数 | ✅ **通**（image-to-image） | 实测能传 reference image，关键的发现 |
|
||||
| `/v1/images/edits` | ❌ 404 | |
|
||||
| `/v1/videos/*` (sora-2) | ❌ 404 | 视频生成需要 IT 开通或外部 key |
|
||||
| `/v1/files` | ❌ 403 "必须指定渠道" | |
|
||||
| 远端 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` | MiniMax 仍保留兼容，但不是默认语音通道。 |
|
||||
| 视频 | `VIDEO_MODEL=seedance` | 当前主流程暂停直接提交；生产通道默认 `ai.skg.com/doubao`，Seedance 真实 ID 由 `VIDEO_MODEL_SEEDANCE` 配置。 |
|
||||
|
||||
**网关后端 = one-hub 多渠道代理**。当前 key 分组叫「纯OpenAI+AWSClaude+Gemini官方」，缺 audio 渠道（`gpt-4o-audio-preview` 503 "无可用渠道"）和 video 渠道。
|
||||
|
||||
## 模型选型（已写入 api/.env）
|
||||
```
|
||||
ASR_MODEL=whisper-1 # ⚠️ 端点 404，ASR 还没真跑通
|
||||
TRANSLATE_MODEL=gemini-2.5-flash # ✅ text 已通
|
||||
REWRITE_MODEL=gemini-2.5-pro # 占位
|
||||
VISION_MODEL=gemini-2.5-flash # ✅ 识别已通
|
||||
IMAGE_MODEL=gemini-3-pro-image-preview # ✅ nano-banana-pro，i2i 已通
|
||||
```
|
||||
|
||||
## Pipeline 状态（8 节点合并版）
|
||||
原 10 节点已合并：input + download + split 合一；translate 合到 transcript；videogen 和 compose 占位。
|
||||
|
||||
| 步 | 节点 | 状态 | 备注 |
|
||||
## 当前主流程
|
||||
| 步 | 模块 | 状态 | 备注 |
|
||||
|---|---|---|---|
|
||||
| 1 | **输入·Input**（合并下载+拆分） | ✅ | yt-dlp 真下 + ffmpeg 拆 wav |
|
||||
| 2 | **关键帧·Keyframes** | ✅ | D 启发式：候选 30 张 → pHash 去重 + Laplacian variance 评分 + 时序分桶 → 5 张；手动加帧 OK |
|
||||
| 3 | **转录·ASR** | ❌ 阻塞 | SKG 网关 audio 不通；待 IT 开 audio 渠道 / 外部 key |
|
||||
| 4 | **翻译·Translate** | ❌ 阻塞 | 依赖 ASR |
|
||||
| 5 | **改写·Rewrite** | ⏳ 占位 | 等用户给产品信息模板 |
|
||||
| 6 | **生图·Image Gen** | ✅ **刚做完** | nano-banana-pro i2i + 正负 prompt |
|
||||
| 7 | **生视频·Video Gen** | ⏳ 占位 | sora-2 端点不通 |
|
||||
| 8 | **合成·Compose** | ⏳ 占位 | 本地 ffmpeg + 字幕 + TTS |
|
||||
|
||||
## UI 架构（重要）
|
||||
- **左侧 sidebar**（108px 极窄）：8 个 stage tile 竖排 + DAG 路径分叉表达
|
||||
- **主区 ReactFlow**：8 节点 DAG（input → keyframe/asr → ... → compose）
|
||||
- **点 sidebar tile**：从左滑出 drawer panel（粉/紫/橙 Kanban 风格）
|
||||
- **关键帧 lightbox**：**embedded 嵌入到 keyframe drawer**（不全屏）—— `<FrameLightbox embedded ... />`，drawer 宽度有 expandedFrame 时 760，无时 400
|
||||
- **Input 节点上方**：多视频缩略图浮条 + 「+」加新视频
|
||||
- **关键帧节点上方**：5+ 张缩略图按视频原比例（aspect-ratio: width/height）
|
||||
- **缩略图 hover**：弹大图静态（关键帧是垫图素材，不放视频）
|
||||
- **缩略图点击**：打开 keyframe drawer 内的 lightbox（左大图 + 右识别面板）
|
||||
|
||||
## 数据模型（关键 typescript / pydantic）
|
||||
```typescript
|
||||
KeyFrame {
|
||||
index: number // 稳定 ID（不连续！frames 数组按 timestamp 排序）
|
||||
timestamp: number
|
||||
url: string
|
||||
description?: {
|
||||
scene, objects: [{name, position, color, extract_prompt}],
|
||||
style, suggested_prompt
|
||||
}
|
||||
generated_images?: [{ id, prompt, model, mode, url, selected, created_at }]
|
||||
}
|
||||
|
||||
Job { frames: KeyFrame[] ... }
|
||||
```
|
||||
|
||||
**前端取帧必须用 `frames.find(x => x.index === activeIndex)` 不能用数组下标**（之前的 bug）。
|
||||
| 1 | 输入 / 下载 | 已通 | TK 链接或上传视频创建 job，下载完成后进入分析队列。 |
|
||||
| 2 | 音频文案路 | 已通 | 拆 `audio.wav`，ASR、翻译、讲话人 / 节奏 / 背景音分析；结果默认折叠展示。 |
|
||||
| 3 | 视频视觉路 | 已通 | 自动或手动抽参考帧，当前工作区按 9:16 原视频播放秒数补帧。 |
|
||||
| 4 | 相似主体资产 | 已通 | 用关键帧和可选内置角色生成同一主体的 10 张白底视图。 |
|
||||
| 5 | 产品资产池 | 已通 | 上传 / 内置产品图统一入池，自动识别视角、结构点、用途、风险，缺角度可补图。 |
|
||||
| 6 | 分镜工作台 | 已通 | 按逐句时间轴编辑新口播、镜头类型、人物 / 产品开关、首帧 / 尾帧规划。 |
|
||||
| 7 | 首尾帧闸门 | 已通 | 每条分镜先用相似主体视图和产品素材生成首帧 / 尾帧，审核后保存。 |
|
||||
| 8 | 视频候选 | 暂停直提 | 历史候选保留展示；当前不再一键打 Seedance，等首尾帧审核后再开放单条提交。 |
|
||||
|
||||
## 关键文件
|
||||
- `web/app/page.tsx` — 多 job state 管理（jobs[] + activeJobId），8 节点 LAYOUT
|
||||
- `web/components/dashboard.tsx` — sidebar + drawer + 9 个 Kanban section（input/keyframe/asr/translate/rewrite/imagegen/videogen/compose），含 `ImageGenCard` 子组件
|
||||
- `web/components/lightbox.tsx` — `FrameLightbox` 支持 `embedded` prop
|
||||
- `web/components/video-lightbox.tsx` — Input 节点点视频缩略图弹的播放器
|
||||
- `web/components/nodes/index.tsx` — ReactFlow 8 节点定义
|
||||
- `web/lib/api.ts` — API client
|
||||
- `api/main.py` — FastAPI 所有端点，KeyFrame/GeneratedImage 模型
|
||||
- `api/main.py` — FastAPI 后端、模型路由、任务状态、ASR/翻译/音频分析、生图、产品识别、首尾帧和视频接口。
|
||||
- `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 端点
|
||||
## 主要 API
|
||||
```
|
||||
POST /jobs 创建 job（链接）
|
||||
POST /jobs/upload 上传视频
|
||||
GET /jobs/{id} job 状态
|
||||
POST /jobs/{id}/analyze?frames=5 拆轨+抽帧+ASR 自动一气呵成
|
||||
POST /jobs/{id}/frames?t=<sec> 手动按时间戳加帧
|
||||
POST /jobs/{id}/frames/{idx}/describe ✅ Vision 识别（3 次重试 + reasoning_content 兜底）
|
||||
POST /jobs/{id}/frames/{idx}/generate ✅ 生图（i2i / text-only, 含 negative_prompt）
|
||||
GET /jobs/{id}/frames/{idx}/gen/{gen_id}.jpg 生成图二进制
|
||||
POST /jobs/{id}/frames/{idx}/gen/{gen_id}/select 选用某 gen 给下游
|
||||
GET /jobs/{id}/video.mp4 原视频
|
||||
GET /jobs/{id}/frames/{idx}.jpg 关键帧 jpg
|
||||
GET /health
|
||||
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. **关键帧 index 不连续**：手动加帧后 frames 数组按 timestamp 排序，index 是稳定 ID。lightbox 必须用 `frames.find(x => x.index === activeIndex)`，**不要**用 `frames[activeIndex]`。
|
||||
2. **SKG 网关 vision 之前测试结果错误**：用 `dog.jpg` 那张 wikipedia 200px 缩略图损坏 / metadata 异常，导致一直以为 image input 不通。用标准 PNG / 真实 jpeg 测就通了。
|
||||
3. **Gemini 2.5 Flash 默认带 thinking**，`content` 字段经常为空（token 都给了 reasoning），要从 `reasoning_content` 正则挖 JSON 兜底。
|
||||
4. **缩略图 aspect-ratio**：必须用 `aspectRatio: ${job.width}/${job.height}` 自适应，不要强制 `aspect-video` 16:9（竖屏视频会被裁切）。
|
||||
5. **ReactFlow `type="input"` / `"output"` 是 reserved**：自带白底默认样式，要 CSS 覆盖 `.react-flow .react-flow__node-input { background: transparent !important; ... }`。
|
||||
6. **ReactFlow 12 colorMode 独立于 next-themes**：必须 `<ReactFlow colorMode={resolvedTheme}>` 联动，否则节点白底。
|
||||
7. **FastAPI BackgroundTasks 用法**：`bg.add_task(func, arg)` 不能传 coroutine。
|
||||
8. **ffmpeg 8 mjpeg encoder 拒绝 yuv420p**：抽帧必须加 `-pix_fmt yuvj420p`，且 `-vsync` 改 `-fps_mode`。
|
||||
9. **抽帧速度**：场景切换检测（`select='gt(scene,0.4)'`）超慢（71s 视频要 30s+），换均匀采样 fast seek（5 张 < 3 秒）。
|
||||
## 当前约束 / 不要踩
|
||||
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. 当前主流程不直接批量提交视频；先走“分镜规划 → 首尾帧 → 人工审核”。
|
||||
6. 产品素材池默认是“同一产品”，不做不同产品身份判断；视角识别必须按佩戴者左 / 右、上 / 下、内 / 外侧描述。
|
||||
7. 后端长任务不要用 `--reload`。
|
||||
8. 关键帧 `index` 是稳定 ID，不等于数组下标；前端取帧用 `frames.find(x => x.index === idx)`。
|
||||
|
||||
## 待办（按优先级）
|
||||
1. **ASR 阻塞**：找 SKG IT 开 audio 渠道，或给一个外部 ASR key（Deepgram / 讯飞 / OpenAI 直连）
|
||||
2. **生图测试反馈**：刚做完，等用户在浏览器试 → 调 negative prompt / 模型选型
|
||||
3. **区域化修图（inpainting）**：用户讨论了，方案 A 纯 prompt / B 矩形框 / C 画笔 mask / D SAM；暂时搁置
|
||||
4. **改写 Rewrite**：等用户给产品信息卡模板
|
||||
5. **视频生成**：sora-2 走 SKG 端点不通；考虑外部 key (Runway/Kling/Veo3)
|
||||
6. **合成 Compose**：全本地 ffmpeg + 字幕 + TTS
|
||||
|
||||
## 操作流（开发会话）
|
||||
```bash
|
||||
# 1. 启动后端（如未跑）
|
||||
cd ~/Projects/business/20260512-20260512-skg-tk-二创验证/api
|
||||
source .venv/bin/activate
|
||||
uvicorn main:app --port 4291 --reload
|
||||
|
||||
# 2. 启动前端（如未跑）
|
||||
cd ../web
|
||||
pnpm dev
|
||||
|
||||
# 3. 浏览器
|
||||
open http://localhost:4290/?job=c6767f3a166b
|
||||
```
|
||||
|
||||
## 用户偏好提醒（feedback memory）
|
||||
- feedback_image-gen-model：生图统一用 nano-banana-pro ✅
|
||||
- feedback_keep-scope-small：小需求小做
|
||||
- feedback_flow-dont-stop：连续执行到交付，真分叉才问
|
||||
- feedback_demand-before-infra：基建前先反问谁/痛点/频率
|
||||
- feedback_no-guessing-ports：操作前先核实
|
||||
## 最近变更
|
||||
- 2026-05-18：`VISION_MODEL`、`REWRITE_MODEL`、`AUDIO_REWRITE_MODEL` 切到 GPT 默认模型 `gpt-4o`，并加旧 Gemini 环境变量归一化保护。
|
||||
- 2026-05-18：当前主路径暂停直接提交视频，改为逐条首尾帧闸门。
|
||||
- 2026-05-18：媒体素材交互统一收口到 `MediaAssetTile`。
|
||||
- 2026-05-18：产品图视角识别和产品缺角度补图收敛到 `gpt-image-2`。
|
||||
|
||||
Reference in New Issue
Block a user