dsh-vision-bridge

DSH-vision-bridge

给任意 OpenAI 兼容的文本模型（如 DeepSeek）加视觉能力的本地桥。

A local OpenAI-compatible proxy that gives any OpenAI-compatible text model (e.g. DeepSeek) the ability to see images — by routing images to a vision model and text to a text model.

原理

你的客户端（DSH / 任意 OpenAI 兼容前端 / MCP 客户端）
        │  POST /v1/chat/completions（可能带 image_url）
        ▼
┌──────────────────────────────┐
│        dsh-vision-bridge     │
│  1. 图片 → 视觉模型 → 文字描述 │
│  2. 图片替换为文字描述         │
│  3. 转发给文本模型（流式回传） │
└──────────────────────────────┘
        │
        ▼
  视觉模型（Kimi / OpenAI / Qwen / GLM …）
  文本模型（DeepSeek / 任意 OpenAI 兼容）

一句话：大脑还是你的文本模型，眼睛用视觉模型。文本模型本身无需支持图片。

特性

• 零运行时依赖（sharp 为可选，用于图片压缩）
• 任意 OpenAI 兼容的视觉后端 + 任意 OpenAI 兼容的文本后端，可自由组合
• 流式回传（SSE 透传），支持 tool calls
• 图片描述缓存（同一张图只调用一次视觉模型）
• 视觉接口 429 / 限流 / 并发自动退避重试
• 兼容性修复内置：developer→system 角色归一化、max_completion_tokens→max_tokens 归一化
• 提供三种入口：桥服务（OpenAI 兼容 HTTP）、MCP 服务器、命令行

快速开始

1. 安装

npm install -g dsh-vision-bridge
# 或临时用：npx dsh-vision-bridge

2. 配置

复制示例配置并填写：

cp config.example.env .env

（或者直接设环境变量。）核心三项：

# 视觉后端（看图）
VISION_BASE_URL=https://api.moonshot.cn/v1
VISION_MODEL=kimi-k3
VISION_API_KEY=sk-你的视觉key

# 文本后端（大脑）
UPSTREAM_BASE_URL=https://api.deepseek.com
UPSTREAM_MODEL=deepseek-v4-pro
UPSTREAM_API_KEY=sk-你的文本key

3. 启动

dsh-vision-bridge

默认监听 http://127.0.0.1:10101。然后把你的客户端 base_url 指向它、模型选它对外暴露的模型名即可。

配置项

变量	默认值	说明
VISION_BASE_URL	https://api.moonshot.cn/v1	视觉模型接口地址
VISION_MODEL	kimi-k3	视觉模型名
VISION_API_KEY	（必填）	视觉模型 API Key
VISION_PROMPT	详细中文描述	看图提示词
VISION_TIMEOUT_MS	60000	看图请求超时（毫秒）
VISION_IMAGE_MAX_DIMENSION	0（关闭）	图片压缩最大边长，见下
UPSTREAM_BASE_URL	https://api.deepseek.com	文本模型接口地址
UPSTREAM_MODEL	deepseek-v4-pro	文本模型名
UPSTREAM_API_KEY	（必填）	文本模型 API Key
BRIDGE_HOST	127.0.0.1	桥监听地址
BRIDGE_PORT	10101	桥监听端口
BRIDGE_MODEL_ID	deepseek-v4-pro-vision	对外暴露的模型名
MODEL_MAP	空	多模型映射（JSON），见下

图片压缩（可选项，默认关闭）

视觉模型按图片分辨率动态计费——图越大、消耗 token 越多、越贵。启用压缩可把图片先缩到指定最大边长，大幅降低输入 token 成本。

• 为什么通常不损失精度：绝大多数视觉模型内部本来就会把大图缩到固定分辨率再推理；对于文字/OCR/界面截图，缩到 10241536px 基本不影响识别结果，却能省 4~10 倍 token。
• 如何开启：设置 VISION_IMAGE_MAX_DIMENSION=1024（最大边长像素），并安装可选依赖 sharp：

npm install sharp

• 未安装 sharp 或该值为 0 时，图片原样发送（最高精度）。

多模型映射

想让一个桥同时暴露 Pro / Flash 两个模型（转发到不同上游模型），用 MODEL_MAP（JSON）：

MODEL_MAP='{"deepseek-v4-pro-vision":"deepseek-v4-pro","deepseek-v4-flash-vision":"deepseek-v4-flash"}'

接入指南

• DeepSeek Harness：见 docs/dsh-setup.md（注册成模型，拖图即用）
• MCP 客户端（Claude / Codex / Cursor / DSH 等）：见 docs/mcp-setup.md

常见问题

Q：为什么报 429 / concurrency？ 视觉模型账号限流（常见于免费额度：并发 1、RPM 很低）。桥已内置退避重试 + 图片缓存；仍频繁出现请给视觉账号充值提额，或换额度更高的视觉服务商。

Q：为什么报 unknown variant 'developer'？ 某些客户端把系统提示词发成 developer 角色，而上游只认 system。桥已自动归一化，无需处理。

Q：能不能用 OpenAI / Qwen / GLM 做视觉？ 可以。任意 OpenAI 兼容视觉接口，改 VISION_BASE_URL / VISION_MODEL / VISION_API_KEY 即可。

License

MIT