diff --git a/docs/todo/后端管线全景图.html b/docs/todo/后端管线全景图.html new file mode 100644 index 0000000..8c2fd4f --- /dev/null +++ b/docs/todo/后端管线全景图.html @@ -0,0 +1,307 @@ + + + + + +AirShelf 后端生成管线 · 全景结构图 + + + +
+

AirShelf 后端生成管线 · 全景结构图

+
// 商品 → 脚本 → 基础资产 → 故事板 → 视频 → 导出  ·  2026-06-19 实测代码录制
+

看清楚每一步:触发(哪个端点)→ 读了哪些数据 → 提示词怎么拼 → 哪步是 AI / 哪步是纯代码 → 参考图怎么引 → 落到哪。 + 橙色=真在调 AI 模型,灰色=纯程序在跑,绿色=数据落点。

+ +
+
AI 调用 —— LLM / 图像 / 视频模型真在生效
+
纯代码 —— 规范化 / 校验 / 拼提示词 / 调度 / 落库
+
数据落点 —— DB 表 / project.metadata
+
+ + +
+
1
脚本 Agent
+
POST /script-agent-stream/ · SSE 流式
模式 auto / theme / revise(可精准改1镜)
+
+
+ 选文本模型→ + load_ecommerce_skill 拼系统提示词→ + 拼商品+卖点上下文→ + 预扣额度→ + ① 1 次 text LLM 流式调用→ + 抽JSON+规范化兜底→ + 落库 +
+
+
+
AI 节点 ① · 唯一一次 AI 调用
+
+
能力  text(纯文本,无图无视频)
+
底座  火山直连 VolcanoArk · 或中转站 OpenAICompatible(看模型 provider)
+
模型  请求指定 或 最早创建的 active 文本模型
+
系统提示词  SKILL.md + 5 篇 references + 运行时输出协议
+
+
+
+
AI 一次性产出(同一次调用里)
+
entities[] 角色/场景/商品,每个带: + id · type · name · visual_prompt(给图模型的生图词) · ref_index +segments[] 每 15 秒一镜: + index · role(钩子/痛点/卖点/CTA) · narration(口播) + · visual(画面) · product_exposure · entity_refs(本镜引用哪些实体)
+
+
+
关键澄清:角色/场景/商品 = AI 生成脚本时「一次性吐出」的,不是后面用程序/正则单独提取。 + skill 里把 entities 写进同一份输出契约,要求 AI 为每个实体自动写一份 visual_prompt(小白不用打字)。后端只做规范化兜底,不再二次调 AI。
+
+
纯代码步骤(无 AI)
+
+ normalize_draft 抽 JSON+对抗字段名漂移 · + _merge_single_segment 精准改1镜只换该镜 · + _map_entities_to_project_metadata 把 entities 拆进 metadata · + 计费 reserve→charge +
+
+
+
数据落点
+
+ ScriptVersion content=完整JSON · metadata={entities 全量}   + ScriptSegment(每镜) narration · visual_prompt · role · entity_refs · dialogue   + project.metadata cast · cast_prompts{名:visual_prompt} · scenes · scene_prompts · script_entities(全量) +
+
+
+
+ +
↓
+
project.metadata.cast_prompts / scene_prompts / script_entities  ——传给下游——→
+ + +
+
2
基础资产(人物 / 场景 / 商品图)
+
POST /generate-base-asset/ · 202秒回
真出图在后台 worker
+
+
+ 前端读 metadata.cast_prompts[名]→ + 当 prompt + label=实体名 POST→ + 按 kind 拼最终 prompt→ + ② 图像模型出 1 张图→ + 落 Asset + 归组 + 自动采用→ + ③ 人物再出三视图 +
+
+
+
提示词拼装(按 kind 三选一)
+
# 商品(有主图)→ image_edit 锁包装 +参考图1是「商品名」真实主图,严格参照包装/配色/Logo +生成三视图:正面/侧面/背面,纯白底,16:9 + {前端prompt} + +# 人物 → 文生图,固定模板包裹 +电商真人模特,氛围正面全身照,{visual_prompt}, +自然妆容,柔和影棚光,单人,纯色背景 + +# 场景 → 原样透传 +{visual_prompt}(不加模板)
+
+
+
AI 节点 ②③
+
+
底座  默认图像模型 = tokenssr:gpt-image-2(中转站 OpenAICompatible)
+
商品  image_edit images=[商品主图] · 锁一致性
+
人物/场景  image_generation 纯文生图
+
三视图  image_edit 据立绘/主图 → 1 张 16:9 横图(4 视角并排)
+
+
label = 实体名:生成时 group.metadata.label = 前端传的实体 tag。下游故事板就靠它把参考图对回实体。
+
+
+
+
数据落点 + 推进
+
BaseAssetGroup kind · metadata.label=实体名 · candidate_assets · adopted_asset  ·  + 三种 kind(人+场景+商品)都有采用资产 → 推进到故事板阶段
+
+
+
+ +
↓
+
segment.entity_refs + 已采用 BaseAssetGroup(按 label)  ——→ 选参考图
+ + +
+
3
故事板(分镜图)
+
POST /generate-storyboard + /poll-storyboard
HTTP秒回 + 后台线程出图(非 celery)· 最多 4 并发
+
+
+ 取本镜 15s 脚本(visual/narration/露出)→ + _storyboard_reference_images 选参考图→ + 拼 @图N + 导演指令 + 分镜脚本→ + ④ image_edit 多图合成→ + 落 StoryboardFrame +
+
+
+
提示词拼装(refs 版 · 实际走这个)
+
【设定】@图1是小美(角色),@图2是耳机(商品), + @图3是地铁(场景)。 +根据以下脚本生成导演故事板,用于指导 seedance 视频生成。 +{项目级 cast/scene/色调摘要} +【分镜脚本】(本段约 15 秒) + 画面:{segment.visual_prompt} + 口播:{segment.narration} + 商品露出:{segment.product_exposure} +请严格保持各参考图同一张脸/同一商品外观配色; +9:16 竖屏,一镜一图。
+
+
+
参考图怎么选 · _storyboard_reference_images
+
+
来源  本镜 entity_refs → script_entities 查实体 → 找已采用的 BaseAssetGroup
+
匹配  先精确(kind + label==实体名)→ 匹不到放宽到"同类任一组"
+
商品兜底  无商品组 → 直接用商品真实主图(已修)
+
上限/顺序  最多 4 张 · 角色→商品→场景(与 @图N 对齐)
+
+
+
AI 节点 ④
+
image_edit tokenssr:gpt-image-2(中转站)· multipart 上传 N 张参考图合成 · 1024×1536
+
+
+
+
无参考图时降级走纯文生图 build_storyboard_frame_prompt(没有 @图N、没有"锁脸锁商品"那句)→ 一致性会丢。所以参考图配齐很关键。
+
+
+ +
↓
+
同一套参考图引擎 + 末位多追加 1 张「故事板帧」 ——→
+ + +
+
4
视频(Seedance 片段)
+
POST /submit-video-segment + /poll-video-segment
同步提交 + celery 轮询(+前端兜底)· 5–10 分钟/段
+
+
+ 取同一镜脚本→ + _video_reference_images(=故事板那套+追加故事板帧)→ + 拼 @图N + @故事板图 + 脚本 + 规格→ + ⑤ Seedance 出视频(带音)→ + 落 VideoSegmentVersion +
+
+
+
提示词拼装 · build_video_segment_prompt
+
【设定】@图1是小美(角色),@图2是地铁(场景), + @图3是耳机(商品)。 +【分镜】根据@图4分镜图生成「商品名」短视频。 +【脚本】{画面/口播/露出} + {用户额外提示} +15s · 9:16 竖屏电商带货,镜头稳定,商品露出清晰, +节奏有转化感。
+
+
+
AI 节点 ⑤
+
+
底座  火山直连 VolcanoArk(create_video_task)
+
能力  video / Seedance · 9:16 · 720p
+
参考图  角色→场景→商品 + 末位故事板帧,作 reference_image 传入
+
音频  generate_audio=True(直接出音效+人物声,不是哑片)
+
降级  带参考图被拒 → 退纯文生视频(文本含旁白/画面)
+
+
+
+
+
+ + +
AI 调用总清单(整条管线一共在哪几处真调了模型)
+ + + + + + + + +
#阶段能力底座 / 模型输入纯代码 or AI
①脚本text(LLM 流式)火山/中转站 · 文本模型skill 系统词 + 商品上下文AI 脚本+实体一次产出
②基础资产·商品image_edit中转站 gpt-image-2商品主图 + 模板词AI
②基础资产·人物/场景image_generation中转站 gpt-image-2实体 visual_promptAI
③基础资产·三视图image_edit中转站 gpt-image-2立绘/主图AI
④故事板分镜图image_edit 多图合成中转站 gpt-image-2N 张参考图 + 分镜脚本AI
⑤视频片段video(Seedance)火山直连 VolcanoArk参考图+故事板帧+脚本AI
+

其余全是纯代码:选模型、拼提示词、选参考图、规范化兜底、归组、落库、轮询调度、计费预扣结算。 + 「提取角色/场景」不是单独的程序步骤——它跟脚本一起由 AI ① 产出;后面所有图/视频用的"角色/场景/商品提示词"都源自 ① 那次,中途纯代码搬运、不再二次问 AI。

+ + +
你 demo 撞到的断点 · 落在链路哪一步
+
+
① 商品参考图丢失  阶段3/4 选参考图
+
商品天生有真实主图,但旧逻辑非要"商品基础资产组"才认,没生成就丢掉商品参考。实测某项目每镜要 3 张只给 2 张。
+
✓ 已修:无商品组时直接用商品主图兜底(实测 2/3 → 3/3)
+
+
+
② 实体没全生成基础资产  阶段2
+
脚本 ① 提取了角色+场景+商品,但第二步常只生成一部分(漏场景/漏第二角色)→ 没生成的实体在阶段3/4 自然没参考图。实测某项目每镜要 4 张只给 1 张。
+
待修:第二步明确标出"还差哪几个实体没基础资产"(前端 UX 提示)
+
+
+
③ 资产标签 ≠ 脚本实体名  阶段2→3 接线
+
阶段3 按 label==实体名 精确匹配参考图。若生成的资产被标成别的名(如脚本"通勤女主"、资产"通勤打工人"),精确匹配失败、退到"同类随便挑一个",多角色就挑错人。
+
待定:从实体卡生成时强制 label=实体名 + 清理"·三视图"这类占位组的误匹配
+
+ +
+ +