# 数字人脚本 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 转发模式):
  ```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。