内容
# 开放代码视觉 👁️
[](https://pypi.org/project/opencode-vision)
[](https://pypi.org/project/opencode-vision)
[](https://github.com/NickRivers1983/opencode-vision)
**为开放代码文本模型赋予视觉能力**
赋予 **任何** 纯文本模型视觉能力 — big-pickle、DeepSeek、MiMo、MiniMax 或其他任何原生不支持图像处理的模型。
```bash
pip install opencode-vision[paddle]
```
---
## 问题
开放代码支持许多模型，但大多数开源和免费模型都是 **纯文本** 模型。当您粘贴图像或尝试 `read()` 时，您会收到：
```
错误：无法读取图像（此模型不支持图像输入）。
```
这不是配置问题 — 这是模型架构的基本限制。纯文本模型没有视觉神经元。
## 解决方案
`opencode-vision` 是一个 **MCP 服务器**，作为纯文本模型的“导盲犬”。它通过双引擎架构处理图像分析：
```
┌──────────────────────────────────────┐
│ opencode-vision MCP 服务器 │
│ │
[big-pickle] ────►│ 1. PaddleOCR (PP-OCRv5, SOTA) ────►│──► 文本
[DeepSeek] ────►│ • 基准测试中 0% 错误率 │
[MiMo] ────►│ • 100+ 种语言 │
│ • ~15MB 模型占用 │
│ │
│ 2. Gemini Vision API（备用） ────►│──► 文本
│ • 手写体和场景文本 │
│ • 每天 1,500 次免费请求 │
│ • 零安装 │
└──────────────────────────────────────┘
```
### 为什么选择 PaddleOCR（而不是 Tesseract）？
| 指标 | PaddleOCR（PP-OCRv5） | Tesseract 5 |
|--------|---------------------|-------------|
| 字符错误率 | **4.5%** | 18.2%（4 倍更差） |
| 发票准确率 | **100%**（0 错误） | 87.5%（3 错误） |
| OmniDocBench 分数 | **92.86**（SOTA） | N/A |
| 旋转文本 | ✓ 高度鲁棒 | ✗ 失败 >5° |
| 场景文本准确率 | **85–90%** | 60–70% |
| 模型大小 | ~15MB | ~30MB |
| 许可证 | Apache 2.0 | Apache 2.0 |
2026 年的社区共识很明确：**Tesseract 已经不再具有竞争力**，适用于生产环境的 OCR。PaddleOCR 的深度学习流程提供了 4 倍更低的错误率，处理旋转和退化文本，并支持 100+ 种语言。
### Gemini 备用
PaddleOCR 在手写体识别方面存在困难（14.4% 准确率）。当置信度低于 70% 时，服务器会备用 **Google Gemini 2.5 Flash Vision API**（免费层，每天 1,500 次请求，无需信用卡），该 API 在手写文本上实现了 86%+ 的准确率，并完美处理场景文本。
## 快速开始
### 1. 安装
```bash
pip install opencode-vision[paddle] # 推荐：PaddleOCR + Pillow
pip install opencode-vision # 最小化：仅 Gemini API
```
### 2. 获取 Gemini API 密钥
在 [aistudio.google.com](https://aistudio.google.com/) 获取免费密钥（每天 1,500 次请求，无需信用卡）。
在 `~/.config/opencode/.env` 中设置：
```bash
echo 'GOOGLE_API_KEY=your_key_here' >> ~/.config/opencode/.env
```
或直接导出：
```bash
export GOOGLE_API_KEY=your_key_here
```
### 3. 添加到 OpenCode 配置
在 `~/.config/opencode/opencode.json` 中添加：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"vision": {
"type": "local",
"command": ["python3", "-m", "opencode_vision.server"],
"enabled": true,
"timeout": 30000
}
}
}
```
### 4. 重启 OpenCode
启动新会话。`vision_describe`、`vision_ocr` 和 `vision_analyze` 工具将适用于所有模型 — 甚至是纯文本模型。
### 5. 查询图像
```
用户：这张图像中有什么？
模型：[调用 vision_describe("/path/to/image.png")]
"一个带有 'Nicolás Ríos Herrera' 的深色渐变横幅..."
```
## 工具
| 工具 | 描述 | 何时使用 |
|---|---|---|
| `vision_describe(path, prompt?)` | 详细描述图像 | "这显示了什么？" |
| `vision_ocr(path)` | 提取所有可见文本 | "这张截图中的文本是什么？" |
| `vision_analyze(path)` | 元数据 + 描述 + OCR | 全面理解 |
## 依赖项
| 组件 | 是否必需？ | 备注 |
|---|---|---|
| Python >= 3.10 | ✅ 必需 | |
| `GOOGLE_API_KEY` | ✅ 必需 | 在 aistudio.google.com 上获取免费密钥 |
| `pillow` | 📦 推荐 | `pip install pillow` 用于元数据 + 自动调整大小 |
| `paddleocr` | 🚀 推荐 | `pip install paddleocr` 用于本地 SOTA OCR |
| `tesseract-ocr` | ❌ 已弃用 | 不再使用。PaddleOCR 完全取代它。 |
服务器自动从以下位置检测 API 密钥（按顺序）：
1. `GOOGLE_API_KEY` 环境变量
2. `GOOGLE_GENERATIVE_AI_API_KEY` 环境变量
3. `~/.config/opencode/.env` 文件
4. `~/.env` 文件
5. `$PWD/.env` 文件
## CLI 使用（无需 OpenCode）
```bash
# 启动 MCP 服务器（用于 OpenCode 集成）
opencode-vision
# 直接分析
opencode-vision describe ~/screenshot.png
opencode-vision ocr ~/scanned-document.png
opencode-vision analyze ~/photo.jpg
# 自定义提示
opencode-vision describe ~/chart.png "这个图表中的值是什么？"
```
## 架构
### 为什么选择 Python？
所有现有的 OpenCode MCP 视觉服务器都是 **Node.js/TypeScript**，需要 `npm install` 或 `npx`。`opencode-vision` 是纯 Python，因为：
- Python 已经安装在每个开发人员机器上
- `pillow`（PIL）是标准的图像处理库
- PaddleOCR 是可用的最佳开源 OCR 引擎
- MCP 协议是简单的 JSON-RPC，基于 stdio — 无需框架
- 零 `node_modules`，零 `npm`，零 `npx`
### 模块化设计（v2.0）
```
opencode-vision/
├── opencode_vision/
│ ├── __init__.py # 包元数据
│ ├── __main__.py # CLI 入口点
│ ├── server.py # MCP 服务器（薄路由器）
│ ├── mcp.py # MCP 传输协议
│ ├── ocr.py # OCR 引擎（PaddleOCR + Gemini 备用）
│ ├── gemini.py # Gemini Vision API 客户端
│ └── image.py # 图像处理实用程序
├── pyproject.toml
└── README.md
```
### OCR 策略
```
┌────────────────────────────┐
│ PaddleOCR（PP-OCRv5） │
│ • 深度学习 OCR │
用户图像 ──────►│ • 基准测试中 0% 错误率 │───► 置信度 ≥ 70% ──► 返回文本
│ • 100+ 种语言 │
└─────────┬──────────────────┘
│ 置信度 < 70% / 错误
▼
┌────────────────────────────┐
│ Gemini 2.5 Flash Vision │
│ • 手写体 / 场景文本 │───► 返回文本
│ • 每天 1,500 次免费请求 │
└────────────────────────────┘
```
### 成本：$0
- Gemini 2.5 Flash：**每天 1,500 次免费请求**，通过 Google AI Studio API 密钥
- PaddleOCR：**免费和开源**（Apache 2.0）
- Pillow：**免费和本地**，用于元数据
- 不消耗 OpenCode Go 积分 — API 调用发生在视觉服务器中，而不是通过 OpenCode 的模型代理
## 与替代方案比较
| 功能 | opencode-vision v2 | opencode-vision v1 | opencode-minimax-easy-vision | qwen-vision-mcp |
|---|---|---|---|---|
| **运行时** | Python（标准库） | Python（标准库） | Node.js + npm | Node.js + npm |
| **OCR 引擎** | PaddleOCR（SOTA） | Tesseract（旧版） | 无（仅 API） | 无（仅 API） |
| **OCR 准确率** | **0% 错误率** | ~18% CER | N/A | N/A |
| **手写体** | Gemini Vision API | ❌ 不支持 | ❌ | ❌ |
| **依赖项** | `pip install opencode-vision[paddle]` | `pip install opencode-vision` | `npm install` | `npx` |
| **API 成本** | $0（Gemini 免费层） | $0 | MiniMax 定价 | $0（本地） |
| **自动 .env** | ✓ 读取 ~/.config/opencode/.env | ✓ | ✗ 手动环境变量 | ✗ |
| **图像调整大小** | ✓ Pillow 自动调整大小 | ✓ Pillow | ✗ | ✗ |
| **安装大小** | ~200 KB + 可选 15MB 模型 | ~200 KB | ~30 MB | ~30 MB |
## 为什么是“模型无关”？
关键的架构洞察：**模型永远不需要看到像素**。MCP 服务器在外部执行所有视觉处理并返回文本。这意味着：
- 与 **任何** 纯文本模型（big-pickle、DeepSeek、MiMo、MiniMax 等）兼容
- 也与 **任何** 多模态模型兼容（它不会干扰）
- 无需模型特定的配置
- 无需提供商特定的设置
- 可以在不重新配置视觉的情况下随时更改模型
## 许可证
MIT
---
由 [Nicolás Ríos Herrera](mailto:nrios@icesi.edu.co) 为 OpenCode 社区构建。
