BoosAPI/docs/superpowers/specs/2026-06-18-digital-human-llm-model-select-design.md

数字人脚本 LLM 模型可选 设计

日期:2026-06-18 分支:feat/comfy-cloud-adapter 状态:已通过 brainstorming,待用户复审

背景

数字人脚本生成的 LLM 模型现在写死在 Pixelle config(llm.model = gpt-5.5),用户无法在 数字人页面选用别的模型。本功能加一个「脚本模型(可选)」下拉,让用户自选生成脚本的 LLM。 生图模型已可通过现有「图片工作流」下拉选择,不在本范围。

已确认决策

1. 只做脚本 LLM 模型可选;生图模型已由「图片工作流」下拉覆盖,不动。
2. 下拉只列文本/对话模型(过滤掉生图/视频模型,避免选错导致生成失败)。
3. 默认空 = 用 Pixelle config 的默认模型(deepseek-v4-flash),向后兼容。实现时把 Pixelle config.yaml 的 llm.model 设为 deepseek-v4-flash。
4. 三层改动(前端选择器 + 后端转发 + Pixelle 传 model)。

集成点(调查结论)

• Pixelle llm_service.py:llm(prompt=, model=...) 已支持按调用传 model 覆盖 (优先级:参数 > config)。
• Pixelle asset_based.py 脚本生成调用 self.core.llm(prompt=, response_type=VideoScript, ...) 当前未传 model → 需补 model=context.request.get("llm_model")。
• BoosAPI digital_human.rs pixelle_request_body 转发字段(媒体/tts 工作流等), 未转发 llm_model → 需补。
• 前端模型列表:api.getModelsMarketplace()(/api/models/marketplace)已有,可作下拉数据源。
• /v1/models 需鉴权(401 直取不行),故用 marketplace 接口。

三层改动设计

层1 前端 src/web/pages/DigitalHuman.tsx

• 加 state llmModel(默认空)+ draft 持久化。
• 加载时调 api.getModelsMarketplace() 取模型,过滤掉生图/视频模型(名称含 image/video/dall/flux/sd/wan/seedance/kling/banana 等,或按 marketplace 项的类型字段), 得文本模型列表 state llmModels。
• 加「脚本模型(可选)」<select>:空选项「默认(deepseek-v4-flash)」+ 文本模型选项。
• 提交 payload 加 llm_model: llmModel || undefined。

层2 后端 src/routes/digital_human.rs

• pixelle_request_body 加(照搬 tts_workflow 转发模式):

  if let Some(value) = optional_string(body, &["llmModel", "llm_model"]) {
      request_body["llm_model"] = json!(value);
  }
  

层3 Pixelle pixelle_video/pipelines/asset_based.py

• 脚本生成调用前取 llm_model = context.request.get("llm_model"),非空则传入: self.core.llm(prompt=prompt, response_type=VideoScript, temperature=0.8, max_tokens=4000, model=llm_model)。 (llm() 已接受 model 参数;None 时走 config 默认。)
• 容器内改 + 备份到 /opt/Pixelle-Video/patches/。

验证

• 前端 npm run typecheck:web 干净。
• 后端 cargo build -j 2 通过。
• Pixelle 语法校验 + 重启 healthy。
• 端到端:数字人任务选非默认脚本模型,Pixelle 日志出现 LLM call: model=<所选模型>。

非目标

• 不改生图模型选择(已由图片工作流下拉覆盖)。
• 不做参考图上传(功能 B,留后续)。
• 不动 comfy-cloud 适配器、LTX2.3 工作流。

提交约定

分支 feat/comfy-cloud-adapter。前端、后端分别提交;Pixelle 容器内改 + 备份(非本仓库)。中文 commit。