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

数字人页加脚本模型下拉(只列文本模型,默认 gpt-5.5),三层: 前端选择器(getModelsMarketplace过滤)+ 后端转发 llm_model + Pixelle 脚本步传 model。生图模型已由图片工作流下拉覆盖,不在范围。 Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-18 04:50:05 +08:00
parent 054343f489
commit 230eef96ed
1 changed files with 70 additions and 0 deletions
@@ -0,0 +1,70 @@
+# 数字人脚本 LLM 模型可选 设计
+
+日期:2026-06-18
+分支:`feat/comfy-cloud-adapter`
+状态:已通过 brainstorming,待用户复审
+
+## 背景
+
+数字人脚本生成的 LLM 模型现在写死在 Pixelle config(`llm.model = gpt-5.5`),用户无法在
+数字人页面选用别的模型。本功能加一个「脚本模型(可选)」下拉,让用户自选生成脚本的 LLM。
+生图模型已可通过现有「图片工作流」下拉选择,不在本范围。
+
+## 已确认决策
+
+1. 只做脚本 LLM 模型可选;生图模型已由「图片工作流」下拉覆盖,不动。
+2. 下拉只列文本/对话模型(过滤掉生图/视频模型,避免选错导致生成失败)。
+3. 默认空 = 用 Pixelle config 的默认模型(gpt-5.5),向后兼容。
+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>`:空选项「默认(gpt-5.5)」+ 文本模型选项。
+- 提交 payload 加 `llm_model: llmModel || undefined`。
+
+### 层2 后端 `src/routes/digital_human.rs`
+- `pixelle_request_body` 加(照搬 tts_workflow 转发模式):
+  ```rust
+  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。