deepsee

让 DeepSeek 等纯文本模型读懂图片的本地视觉桥。

deepsee 会先用你选择的视觉模型把图片转换成与问题相关的文字，再交给原来的文本模型回答。它可以作为命令行工具、Web 聊天界面、MCP Server，或 OpenAI / Anthropic 兼容代理使用。

快速导航：开始使用 · 选择接入方式 · 常用场景 · 配置 · 常见问题 · 开发与贡献

为什么需要 deepsee？

纯文本模型不能直接理解图片。即使聊天客户端允许粘贴图片，上游接口仍可能拒绝请求，或模型只能看到一个无意义的图片占位符。

deepsee 在本机增加一层视觉转换：

flowchart LR
    A["图片 + 你的问题"] --> B["deepsee"]
    B --> C["视觉模型：图片 → 针对问题的文字"]
    C --> D["原来的文本模型"]
    D --> E["最终回答"]

它不会把文本模型变成原生多模态模型，而是在请求到达文本模型之前，补上它缺少的视觉信息。

你可以用它做什么？

• 在 Claude Code、Codex、Cursor、Cline、Cherry Studio、ChatBox 等客户端中处理截图和图片。

• 从终端识图、提取文字，或比较 2–4 张图片。

• 在本地 Web 界面中粘贴图片并继续对话。

• 为 OpenAI 或 Anthropic 兼容客户端提供一个统一的本地代理。

• 通过 MCP 暴露识图、OCR、图片对比和状态检查工具。

• 连接任意 OpenAI 兼容视觉端点，并配置多供应商自动降级。

核心运行时只使用 Python 标准库。Pillow、RapidOCR 和官方 MCP SDK 都是按需安装的可选依赖。

3 分钟开始使用

1. 安装

需要 Python 3.9 或更高版本。推荐使用 pipx，避免污染系统 Python：

pipx install 'git+https://github.com/rikfish163-rgb/deepsee.git'
deepsee --version

如果终端找不到 deepsee，运行 pipx ensurepath，然后重新打开终端。

准备使用离线 OCR 时，把安装命令换成：

pipx install 'deepsee-mcp[ocr] @ git+https://github.com/rikfish163-rgb/deepsee.git'

没有 pipx 时，使用独立虚拟环境：

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install 'git+https://github.com/rikfish163-rgb/deepsee.git'

2. 完成向导

deepsee setup

向导只做三件事：

1. 选择视觉后端，用于把图片转换成文字。

2. 配置上游文本模型；只使用 CLI 或 MCP 时可以暂时留空。

3. 按检测结果安装 Claude Code Hook、Codex Skill 和 MCP 集成。

输入 API key 时终端不会回显。最终确认前，向导不会修改任何文件。

没有视觉 API key 时，可以选择：

• demo：验证安装和数据流，不会真正识别图片。

• local-ocr：离线提取图片文字，需要安装 ocr 可选依赖。

• ollama：通过本机 Ollama 的 gemma3 做完整识图，需先执行 ollama pull gemma3。

3. 立即试一次

用终端针对图片提问：

deepsee see ./screenshot.png -q "这个报错的根本原因是什么？"

或者打开本地聊天界面：

deepsee ui

deepsee ui 会启动代理和 Web 面板，并打开 http://127.0.0.1:8090。Web 对话需要在向导中配置上游文本模型。

最后运行诊断：

deepsee doctor
deepsee doctor --verify   # 联网视觉自检；可能读取最近图片或当前截图

看到视觉链配置正常后，就可以开始接入常用客户端。

选择最适合你的接入方式

如果不确定，从 deepsee setup → deepsee see 开始；确认识图正常后，再配置 Web 或代理。

常用场景

命令行识图

# 描述图片
deepsee see ./photo.jpg

# 围绕具体问题分析；提示会连同图片一起发给视觉模型
deepsee see ./chart.png -q "趋势拐点在哪里？依据是什么？"

# 明确任务类型：general / error / diagram / chart / ui / screenshot
deepsee see ./error.png --task error -q "给出最可能的修复步骤"

# 提取图片文字
deepsee ocr ./receipt.png

# 比较 2–4 张图片
deepsee compare before.png after.png -q "界面有哪些变化？"

# 把结果保存到文件
deepsee see ./diagram.png -o result.md

图片参数支持本地路径、HTTP(S) URL 和 data URI。

Claude Code

deepsee setup 会询问是否安装 Hook 和 MCP。已有配置也可以单独安装：

deepsee install --hook
deepsee install --mcp

两种方案的覆盖范围不同：

• Hook：适合 Claude Code 在交互会话中通过 Read 读取图片文件。

• MCP：让模型调用 analyze_image、ocr_image 或 compare_images。

• 路由代理：覆盖消息内粘贴的图片、headless 调用和其他图片块。

需要完整覆盖时：

deepsee route on
# 重启 Claude Code 后生效

该命令会启动本地代理，并把 Claude Code 的 ANTHROPIC_BASE_URL 写入 ~/.claude/settings.local.json。此模式依赖 deepsee 中配置的上游文本模型和可用额度。

恢复原路由：

deepsee route off

Codex

安装 Codex Skill：

deepsee install --skill

也可以把 Codex 使用的 OpenAI 兼容 provider 指向 deepsee 代理：

Base URL: http://127.0.0.1:8081/v1
Model:    你在 deepsee 中配置的上游模型名
API key: 代理 master key；仅本机且未设置 master key 时可留空

Cursor、Cline 和其他 MCP 客户端

GitHub 安装完成后，MCP Server 的启动命令是：

deepsee mcp

通用 MCP 配置：

{
  "mcpServers": {
    "deepsee": {
      "command": "deepsee",
      "args": ["mcp"]
    }
  }
}

主要工具：

仓库根目录的 mcp.json 可作为配置模板。

Cherry Studio、ChatBox、OpenCode 等 OpenAI 兼容客户端

先启动代理：

deepsee start

然后在客户端中填写：

Base URL: http://127.0.0.1:8081/v1
Model:    你在 deepsee 中配置的上游模型名
API key: 代理 master key；仅本机且未设置 master key 时可留空

不想手动找字段时，直接打印当前配置：

deepsee client-cfg

代理同时接受 OpenAI 和 Anthropic 风格的请求，并会在转发前将图片块替换为视觉描述。

deepsee 如何处理一次请求？

1. 接收本地路径、URL、data URI，或 OpenAI / Anthropic 消息中的图片块。

2. 根据用户的问题自动选择报错、技术图、图表、UI、截图或通用提示。

3. 调用视觉后端；失败时进入下一供应商，并短暂冷却故障后端。

4. 将视觉结果注入原请求，再转发给上游文本模型。

5. 对相同图片和问题使用短期内存缓存，减少重复调用。

支持的消息格式包括 OpenAI Chat、OpenAI Responses input_image，以及 Anthropic base64 / URL 图片块。

配置

默认配置文件：

~/.deepsee/config.json

查看脱敏后的当前配置：

deepsee config show

修改单个字段：

deepsee config set upstream.base_url https://api.deepseek.com/v1
deepsee config set upstream.model deepseek-chat
deepsee config set upstream.format auto

需要自定义端口、协议或文生图后端时，使用高级向导：

deepsee setup --advanced

完整的供应商预设、字段说明、环境变量和配置组合见 docs/CONFIGURATION.md。

容器和 CI

所有关键连接参数都可以通过环境变量传入，不必写配置文件：

export DEEPSEE_VISION_BASE_URL='http://127.0.0.1:11434/v1'
export DEEPSEE_VISION_MODEL='gemma3'
export DEEPSEE_UPSTREAM_BASE_URL='https://api.example.com/v1'
export DEEPSEE_UPSTREAM_MODEL='your-text-model'
export DEEPSEE_UPSTREAM_API_KEY='...'

deepsee start

常用变量：

环境变量只覆盖当前运行配置，不会在保存配置时写回磁盘。

安全默认值

• 代理和 Web 服务默认只监听 127.0.0.1。

• API key 通过向导输入时不会回显；在 POSIX 系统上，配置文件权限设为 0600。

• deepsee config show 和状态输出会隐藏密钥。

• 请求体默认限制为 25 MB。

• 如果代理监听局域网或公网地址，请先设置 DEEPSEE_PROXY_MASTER_KEY。

• 不要把 Web 配置面板直接暴露到公网，也不要提交 ~/.deepsee/config.json 或完整诊断日志。

常见问题

deepsee 命令不存在

pipx ensurepath

重新打开终端后再运行 deepsee --version。如果使用虚拟环境，确认环境已经激活。

CLI 能识图，但 Web 对话失败

CLI 和 MCP 只需要视觉后端；Web 和代理还需要上游文本模型。重新运行 deepsee setup，或在 Web 配置页补齐 upstream 地址、模型和 key。

端口 8081 或 8090 已被占用

临时换端口：

deepsee start --port 8082
deepsee web --port 8091

长期修改请运行 deepsee setup --advanced。

如何查看状态和日志？

deepsee status
deepsee doctor
deepsee doctor --verify

后台服务日志位于 ~/.deepsee/proxy.log 和 ~/.deepsee/web.log。

如何停止服务或撤销集成？

deepsee stop proxy
deepsee stop web
deepsee uninstall

uninstall 会移除集成并尽量从安装时的备份恢复客户端配置，但会保留 ~/.deepsee/config.json。

命令速查

兼容性

• Python 3.9 或更高版本；CI 当前覆盖 3.9–3.12。

• Linux、macOS 和 Windows。

• OpenAI 兼容视觉后端，以及本地 Ollama gemma3。

• OpenAI / Anthropic 兼容上游和流式转发。

• 本地路径、URL、data URI、OpenAI 图片块和 Anthropic 图片块。

• 2–4 图对比、任务化提示、短期缓存、供应商降级与失败冷却。

CI 在 Ubuntu、macOS 和 Windows 上运行离线测试。真实供应商是否可用仍取决于端点、模型、额度和网络状态。

项目结构

deepsee/
├── caption.py       识图、OCR、问答和多图对比
├── chat.py          Web 与代理共用的对话编排
├── cli.py           命令行入口
├── config.py        配置、供应商预设和环境变量
├── hook_claude.py   Claude Code PreToolUse Hook
├── installer.py     向导、集成安装、备份与回退
├── mcp_server.py    轻量 MCP Server
├── proxy.py         OpenAI / Anthropic 双协议代理
├── vision.py        视觉客户端、缓存和供应商降级链
└── web.py           Web 服务与静态界面

docs/                配置、架构和产品说明
tests/               全离线测试

开发与贡献

git clone https://github.com/rikfish163-rgb/deepsee.git
cd deepsee
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
pytest -q

测试使用隔离配置和 mock 服务，不读取真实 ~/.deepsee，也不需要 API key。

• 版本变化：CHANGELOG.md

• 贡献说明：CONTRIBUTING.md

• 架构说明：docs/architecture.md

• 安全报告：SECURITY.md

License

MIT License