dsh-llm-vision-bridge

dsh plugin --profile web add dsh-llm-vision-bridge

dsh-llm-vision-bridge

[English](README.md) | 中文


让纯文本模型（DeepSeek）也能"看"图片：在 dsh web GUI 的聊天输入框直接粘贴图片，插件自动把图片路由到视觉辅助模型（复用你已配置的 pi-ai / llama.cpp 上的 Qwen3-VL），得到文字描述后交给 DeepSeek 继续生成回复——体验与原生多模态模型一致。

功能特性

• 原生 LLM provider——注册 deepseek-vision 到 DSH 的 LlmAdapter 接缝。图片准入、请求路由、会话压缩全部由 harness 原生机制驱动，无需改动 UI、无需拦截前端。
• 无图零开销——不含图片的请求原样透传给回退 provider（默认 deepseek-official）。
• 视觉辅助回复——每张图片由视觉模型解析（附带用户文本一起送入提示词），替换为 [图片 N 描述] 文本块后再发给 DeepSeek。
• LRU 描述缓存——同一张图 + 同一问题不重复解析；历史回放与会话压缩不会反复调用视觉模型。
• 503/429 自动重试——适配台式机单 GPU 互斥调度（其他工具占用显存时视觉网关返回 503）。
• 可配置失败策略——placeholder（插入失败说明继续对话）或 error（整轮报错）。

工作原理

聊天输入栏原生支持图片附件：图片以 {type:"image", attachment} 内容块进入模型请求。但 DeepSeek chat-completions 适配器对 image 块显式报 UNSUPPORTED_CONTENT，纯文本模型无法直接处理。

本插件的桥接 provider（deepseek-vision）对外声明 inputModalities: ["text", "image"]，从而通过 host 的图片准入校验（否则消息进 agent 前就会被 MODEL_DOES_NOT_SUPPORT_IMAGES 拒绝）。在它的 stream() 中：

1. 无图 → yield* ctx.llm.stream({ ...options, provider: fallbackProvider })，纯透传、零开销；

2. 有图 → 对每个 image 块，通过一次嵌套的 ctx.llm.stream() 调用配置的视觉 provider（如 pi-ai 的 llama 路由，图片字节由附件服务自动读取），把 image 块替换为 [图片 N 描述]\n<描述> 文本块后，将改写后的消息转发给回退 provider。

会话压缩（compaction）复用最近一次请求的 provider，因此含图历史也会自动走桥接。可选的 autoRoute（默认关）会把 deepseek-official 的 agent 请求额外改写为本 provider，但无法绕过 host 的图片准入校验，仅作兜底——要真正发图，请把主模型配置为 deepseek-vision。

安装

# 从 GitHub 安装（纯 JS 无需构建，也无需 allowBuilds）
dsh plugin --profile web add github:Einskyle/dsh-llm-vision-bridge

# 或从 npm registry 安装
dsh plugin --profile web add dsh-llm-vision-bridge

# 重启 web 服务生效
pnpm dsh web

无 pnpm 环境的手动安装（等效）：

1. 将本包目录复制到 %USERPROFILE%\.dsh\profiles\web\node_modules\dsh-llm-vision-bridge\

2. 编辑 %USERPROFILE%\.dsh\profiles\web\package.json：

• dependencies 增加 "dsh-llm-vision-bridge": "file:<绝对路径>"
• dsh.profile.bundles 数组增加 "dsh-llm-vision-bridge"

3. 重启 web 服务

快速开始

1. 重启后打开 设置 → 模型：出现新 provider 「DeepSeek（视觉桥接）」（模型 deepseek-v4-flash / deepseek-v4-pro）。

2. 把主模型配置为桥接 provider——agent-default-model.provider: deepseek-vision。这是必须的：host 的图片准入校验读的是会话选中模型的 inputModalities，只有桥接模型声明了 image。

3. 在聊天输入框直接 粘贴/上传图片（PNG/JPEG/WebP/GIF），可附图注文字，发送即可。图片先经视觉模型解析（约 10–40 秒，含冷加载与思考），随后 DeepSeek 基于描述回复。

4. 想用纯文本时可随时把主模型切回 deepseek-official（此时发图会被准入拒绝，属预期行为）。

配置（设置 → 模型 → llm-vision-bridge）

字段 · 默认 · 说明

enabled · true · 总开关；关闭后桥接 provider 退化为纯透传

autoRoute · false · 额外把 deepseek-official 的 agent 请求改写为本 provider（无法绕过图片准入，仅兜底）

fallbackProvider · deepseek-official · 真正生成回复的纯文本 provider

visionProvider · llama · 视觉 provider 路由（pi-ai）

visionModel · /models/qwen3-vl-4b-thinking/Qwen3-VL-4B-Thinking-Q4_K_M.gguf · 视觉模型 id

visionPrompt · （内置中文提示词） · 视觉解析系统提示词

visionMaxTokens · 2048 · 视觉解析输出上限（建议 ≥1024，思考过程会占 token）

visionRetries · 3 · 可重试错误（503/429/超时）的最大重试次数

visionRetryDelayMs · 30000 · 重试间隔

onVisionFailure · placeholder · 解析最终失败时：placeholder=插入失败说明继续对话；error=整轮报错

视觉模型选择

视觉调用走 pi-ai 适配器（ctx.llm.stream 指向 visionProvider/visionModel），因此任意 OpenAI 兼容的视觉端点都可以用——本地 llama.cpp 网关只是默认配置，不是硬性要求。

类型 · 示例 · 需要 key · 说明

本地 llama.cpp 网关（当前默认） · Qwen3-VL-4B via http://<desktop-ip>:18081/v1 · 否 · 免费、隐私、仅局域网；图片字节不出你的网络

云 OpenAI 兼容 API · qwen-vl-max（百炼）、glm-4v-plus（智谱）、gpt-4o（OpenAI）、OpenRouter/硅基流动等 · 是 · 模型更强；图片会发送到云端

示例——在 settings.yaml（或 设置 → 模型 → llm-pi-ai）新增百炼路由并让桥接指向它：

llm-pi-ai:
  providers:
    dashscope:
      displayName: DashScope
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen-vl-max
          name: Qwen-VL-Max
          input: [ text, image ]

llm-vision-bridge:
  visionProvider: dashscope
  visionModel: qwen-vl-max

设置改动即时生效，无需重启。约束：端点必须 OpenAI 兼容且支持图片输入；视觉 provider 不能是桥接 provider 自身（deepseek-vision，防递归）；云路由需要存储凭据（apiKeyEnv → 设置 → 模型），否则 pi-ai 报 MISSING_CREDENTIAL。

依赖与前置

• 视觉模型走 pi-ai 适配器，需在 设置 → 模型 → llm-pi-ai 配置好视觉 provider（如 llama 路由：baseURL 指向台式机 llama.cpp http://<desktop-ip>:18081/v1，模型声明 input: [text, image]）。
• 若视觉 provider 配置了 apiKeyEnv 但凭据未设置，pi-ai 会报 MISSING_CREDENTIAL：在设置页存一个任意占位值（本地 llama.cpp 不校验 key），或删除该 apiKeyEnv。
• 台式机单 GPU 互斥调度：其他工具占用显存时视觉网关返回 503，插件按 visionRetries 自动等待重试。

故障排查

现象 · 处理

设置里看不到「DeepSeek（视觉桥接）」 · 插件未加载成功，检查 web 服务启动日志；确认 bundle 已加入 profile

发图报 attachment-error / MODEL_DOES_NOT_SUPPORT_IMAGES · 会话选中模型不是桥接模型：把 agent-default-model.provider 配为 deepseek-vision，或在该会话手动选择「DeepSeek（视觉桥接）」

发图报 VISION_UNAVAILABLE · 视觉模型不可达：检查 llama provider 的 baseURL、台式机是否开机、LLAMA_API_KEY 是否缺失

发图后仍报 UNSUPPORTED_CONTENT · 请求没走桥接 provider：确认主模型是 deepseek-vision（不是 deepseek-official）

视觉解析慢 · Qwen3-VL 冷加载 10–40s 属正常；若频繁 503，等台式机其他 GPU 任务结束

许可

MIT