DeepSeek Harness 配置 deepseek-v4-flash-vision-exp 视觉模型

项目	内容
文档日期	2026-08-21
文档版本	v1.0
模型	`deepseek-v4-flash-vision-exp`（DeepSeek-V4-Flash-Vision-Exp，多模态视觉模型，2026-08-21 上线）
环境	本机 DSH Web 实例（http://127.0.0.1:3080，pid 514）
相关路径	配置：`~/.dsh/settings.yaml`；适配器：`~/.npm-cache-dsh/_npx/1e7f6d9597241db0/node_modules/@deepseek-ai/dsh-llm-deepseek/lib/index.js`（已备份 `.bak-vision`）
模型规格	上下文 1M tokens；支持思考模式与非思考模式；价格与 V4 Flash 相同；图片按尺寸换算 token（官方文档、价格页）

1. 背景：为什么需要两层改动

DSH 的 dsh-llm-deepseek 适配器：

模型目录（catalog）默认只有 deepseek-v4-flash / deepseek-v4-pro------新模型不会出现在 Web 模型选择器中；
序列化层显式拒绝图片内容 （UNSUPPORTED_CONTENT）------即使模型 ID 透传成功，图片也无法发送。

因此"支持视觉模型" = ① 注册模型目录 + ② 启用适配器图片序列化。

2. 第一步：注册模型目录（settings.yaml）

在 ~/.dsh/settings.yaml 增加 llm-deepseek 段：

yaml 复制代码

# dsh-llm-deepseek: 官方 DeepSeek 模型目录
# 注意：显式列出 models 会替换适配器默认目录，因此需同时包含 flash / pro / vision-exp
llm-deepseek:
  models:
    - id: deepseek-v4-flash
      name: DeepSeek-V4-Flash
    - id: deepseek-v4-pro
      name: DeepSeek-V4-Pro
    - id: deepseek-v4-flash-vision-exp
      name: DeepSeek-V4-Flash-Vision-Exp
      description: DeepSeek 多模态视觉模型（Exp），支持图像理解，上下文 1M
      contextWindow: 1000000
      maxTokens: 256000

机制说明：

dsh-llm-deepseek 的 settings 段会按字段覆盖插件配置，且 settings.yaml 热加载 （watch: true）------模型选择器无需重启即可看到新模型；
模型 ID 本身透传（未列入目录的 ID 也能用），目录仅影响选择器展示与上下文窗口/输出上限的解析；
目录条目支持字段：id / name / description / contextWindow / maxTokens。

3. 第二步：适配器启用图片序列化（代码补丁）

仅在升级包会被覆盖、需注意（见 §6）。补丁已应用并备份：index.js.bak-vision。

修改 dsh-llm-deepseek/lib/index.js，共 5 处：

#	位置	改动
1	`modelInfo`	`inputModalities` 按模型 ID 判断：含 `vision` → `["text","image"]`，否则 `["text"]`
2	`serializeMessages`	改为 async；系统/助手消息仍拒绝图片；用户消息含图片块时序列化为 OpenAI 风格 `content` 数组
3	`serializeUserParts`（新增）	图片块 → `{ type: "image_url", image_url: { url: "data:<mime>;base64,..." } }`（经 `attachments.readImage` 读取）
4	`serializeRequest` / `request`	异步化；`request` 中：模型非视觉但含图片 → 抛清晰错误 `UNSUPPORTED_CONTENT`；注入 `resolveAttachments`
5	插件 `apply`	`new DeepSeekAdapter({ ..., resolveAttachments: () => ctx.get("attachments") })`

关键代码片段：

js 复制代码

// 视觉能力判断
function isVisionCapableModel(model) {
  return model.includes("vision");
}

// 用户消息图片序列化（OpenAI 兼容格式）
async function serializeUserParts(blocks, attachments) {
  // ... text → { type: "text", text }
  // ... image → { type: "image_url", image_url: { url: `data:${mimeType};base64,${base64}` } }
}

// request() 中的能力校验
const hasImage = options.messages.some((m) => contentHasImage(m.content));
if (hasImage && !isVisionCapableModel(options.model)) {
  throw new LlmError(`DeepSeek model "${options.model}" does not support image input; use deepseek-v4-flash-vision-exp for vision`, "UNSUPPORTED_CONTENT");
}

依赖：图片经 ctx.attachments（durable attachment service）读取，dsh-attachment-local 已在 dsh-base 挂载，无需额外配置。

4. 验证方法（全部通过 ✅）

4.1 视觉端到端（真实 API）

bash 复制代码

node ~/009_dsh/scripts/dsh-vision-test.mjs

测试图：600×300（上蓝 #3B5998 / 下橙 #FF5722，白字 "DSH VISION"），PIL 生成
结果：模型正确回答 "蓝色和橙色，写着 DSH VISION"（in=251 / out=318 tokens）

4.2 负向测试（非视觉模型 + 图片）

deepseek-v4-flash + 图片 → 清晰报错 UNSUPPORTED_CONTENT（"does not support image input; use deepseek-v4-flash-vision-exp"）

4.3 文本回归

隔离 DSH_HOME headless 会话文本任务 → 正常

4.4 语法检查

node --check 通过

5. 重启 Web 实例（让运行中的 GUI 加载新适配器代码）

settings.yaml 已热加载（模型选择器可见 vision-exp），但运行中进程内存里仍是旧适配器代码，图片上传需重启生效。

bash 复制代码

# 1) 按端口找到并停止旧进程（注意：不要用 pkill -f "dsh web"，会误杀自身 shell）
PID=$(ss -tlnp 2>/dev/null | grep ':3080' | grep -oP 'pid=\K[0-9]+' | head -1)
[ -n "$PID" ] && kill "$PID"

# 2) 等待端口释放
sleep 1

# 3) 重新启动（脚本会设置 npm_config_cache、加载 ark.env 密钥）
cd /home/frank && ./dsh-start.sh

要点：

会话已持久化（~/.dsh/sessions/），重启不丢对话；浏览器自动重连或手动刷新页面即可
启动后访问 http://127.0.0.1:3080
验证：会话中点击模型选择器应看到 DeepSeek-V4-Flash-Vision-Exp；附加图片提问即可测试视觉能力

6. 注意事项

升级覆盖 ：适配器改动位于 npx 缓存包（~/.npm-cache-dsh/_npx/1e7f6d9597241db0/），未来 @deepseek-ai/dsh 升级会被覆盖。长期方案 ：向 deepseek-ai/deepseek-harness 上游提交此改动（TypeScript 源码 src/llm/deepseek/，而非编译产物）；
目录替换语义 ：显式 models 列表整体替换默认目录，务必保留 flash/pro；
费用：图片按尺寸换算 token 计费，价格与 V4 Flash 相同（官方说明）；
备份：适配器原文件备份为 index.js.bak-vision；恢复：cp index.js.bak-vision index.js。

7. 相关文档

文档	位置
本记录	`~/009_dsh/doc/memory/20260821-dsh-deepseek-v4-flash-vision-exp-support.md`
视觉测试脚本	`~/009_dsh/scripts/dsh-vision-test.mjs`