给 AI 装上眼睛：本地化 GLM-OCR 模型集成
你会学到：让不具备视觉能力的文本模型"看懂"图片。两条技术路线的取舍（本地视觉模型 vs 本地 OCR）、智谱开源 GLM-OCR（0.9B）的选型理由、用一句话提示词把它集成为本地 MCP 服务 + skill 的完整实战（含识别错乱的排查实录）、工程化收尾（跨平台安装脚本），以及"本地跑模型还是走云端 API"的价格决策。
场景：模型看不见图
01节的开局动作是把目标 ER 图截图发给模型分析。当时能这么做，是因为 Claude Code 的 Coding Plan 自带读图能力。但这个前提并不总成立：
- 很多模型不是多模态模型，不具备视觉理解能力，图片发过去等于白发
- 编码套餐普遍提供视觉理解的 MCP 接口（和搜索接口并列），但这类第三方接口通常有每周/每月的用量限制，批量处理文档图片时额度先见底
需求由此而来：让本地的、普通的文本模型也稳定拥有"看图"能力。
方案一：本地跑一个视觉模型——先算硬件账
直觉方案是找一个小参数量的视觉模型跑在本地，图片发给它推理。但算一笔账就发现门槛不低：
| 模型规模 | 权重体积（BF16） | 显存要求 | 理解力 |
|---|---|---|---|
| 2B 级视觉模型 | 约 4-5 GB | 至少 8 GB 显存 | 较弱，复杂图表识别有偏差 |
| 6B-32B 视觉模型 | 12-60+ GB | 单张消费级显卡放不下 | 强 |
在 Hugging Face 或 ModelScope 搜 "OCR"/"vision" 能看到大量候选（还包括面向手机操作等端侧场景的专用小模型），拖动参数量滑块从 6B 到 32B，体积翻着倍往上涨。为了"读图"这一个能力去配专业显卡，显然不合理。机器性能一般时，这条路直接排除。
方案二：OCR——绝大多数办公场景的正确答案
换个角度想：办公场景里我们要的往往不是"图里有几条狗、狗在哪"（分类/检测），而是图里的文字、表格、公式、代码这些可以继续加工的结构化信息。这正是 OCR（光学字符识别）的定义域——把图中文字提取出来，一张图的核心信息就到手了，剩下的交给文本模型。
在 ModelScope 上搜 OCR 关键词、按下载量排序，会看到一个下载量很高的模型：智谱开源的 GLM-OCR。它的选型理由（2026-10 官方数据）：
| 维度 | 数据 |
|---|---|
| 参数量 | 仅 0.9B——普通电脑可用 |
| 架构 | GLM-V 编码器-解码器：CogViT 视觉编码器 + 高效 token 下采样跨模态连接器 + GLM-0.5B 语言解码器，训练引入 MTP（Multi-Token Prediction）损失 |
| 流水线 | 基于 PP-DocLayout-V3 的两阶段：先版面分析，再并行识别 |
| 成绩 | OmniDocBench V1.5 综合 94.62 分排名第一；文本/公式/表格/信息抽取细分均 SOTA，官方口径性能接近 Gemini-3-Pro，文档解析强于 PaddleOCR、MinerU 等专项方案 |
| 许可 | 模型权重 MIT，仓库代码 Apache 2.0（内置版面组件 PP-DocLayoutV3 为 Apache 2.0） |
| 部署 | vLLM / SGLang / Ollama / mlx-vlm（Apple Silicon）全支持 |
能力边界要先说清：GLM-OCR 只识别字符类内容（文字、表格、公式、代码、水印都行），让它数图里有几只动物、判断图片的构图意图，做不到或做得很差。办公文档场景刚好全部落在它的能力圈内——这是"折中"而非"降级"。
集成实战：一句话创建 MCP 服务 + skill
提示词事先准备好，直接粘贴：
在本地创建一个 MCP 服务（mcp-ocr 或 ocr-mcp 均可），以 GLM-OCR 作为本地化模型。
你需要从 ModelScope 下载 GLM-OCR 模型到项目的 models 目录，
同时为这个 OCR 设计一个本地的 skill（/ocr），用于解析图片。
markdown
指令本身只有三句话：建什么（MCP 服务 + skill）、用什么模型、下载到哪。执行过程中 AI 全程自决：自己思考采用何种推理方式、探测当前环境可用的推理后端（Ollama/transformers）、创建目录结构、写 server 代码、写 skill 文件。全程无需人工干预。
踩坑实录：识别结果错乱
集成完成后必须验证真实能力，而不是看它"跑通了"就收工。实测两张之前生成的 ER 图截图：
- 第一张：识别出"用户、商品分类、商品订单项"等实体，但漏了
address和coupon——有偏差 - 第二张：竟然回答"这是一张 Node.js API 文档"——明显错误
排查方法论是从源头查起：先验证模型本身的输出（绕过 MCP 服务层直接调模型），确认模型没问题再查服务层。把排查任务交给 AI 后它定位到了根因：之前课程验证时创建过一个同名的 glm-ocr 服务，与当前服务名称冲突。让它修正——一次修复成功，模型和运行环境全部就绪。重测同样的两张图：实体、字段、连图片水印都准确识别出来了。
这个案例的价值不在结论，而在过程：AI 搭建的东西也会坏，坏了就"从源头、分层"地查——先模型、后服务、再集成。
非停止问题：在 server 层解决
GLM-OCR 有个已知怪癖：识别完正文后不会自然停止，会继续吐英文摘要和重复内容（连续代码块、整段重复、幻觉题目），直到撞满输出上限。本地 MCP server 层的解法（课程落地版已内置，直接用返回值即可）：
- 调用时设
num_predict=6144+repeat_penalty=1.2，让它完整跑完 - 返回前用清理函数在最早的"硬标志"处截断（连续 ``` 块、标点重复、连续相同行），并删除 UI 噪音行
课程落地版：/glm-ocr skill 详解
课程最终的落地形态是本地 MCP server（Ollama 后端，Apple Silicon 原生）+ skill，注册后工具全名为 mcp__glm-ocr__*：
| 工具 | 用途 | 关键参数 |
|---|---|---|
ocr_image | 单张图片 OCR | image_path（必填）、prompt（可选） |
ocr_pdf | PDF 逐页 OCR | pdf_path（必填）、pages（如 "1-5,8"） |
ocr_batch | 批量识别（图片 + PDF 混合） | file_paths（字符串数组） |
ocr_status | 检查服务/模型状态 | 无 |
prompt 参数按任务覆盖默认行为（默认自动识别全部内容，表格转 Markdown、公式转 LaTeX）：
| 任务 | prompt |
|---|---|
| 提取表格 | 请将图片中的表格转为 Markdown 表格。 |
| 识别公式 | 请识别图片中的数学公式，用 LaTeX 输出。 |
| 识别代码 | 请识别图片中的代码，保持缩进与格式。 |
| 手写文字 | 请仔细识别图片中的手写文字。 |
| 结构化提取 | 请按 JSON 提取图片中的关键信息。 |
部署三步：
# 1. 拉模型
ollama pull glm-ocr
# 2. 装 MCP server（首次）
cd ~/Projects/mcp-servers/glm-ocr && ./install.sh
# 3. 确认 Ollama 在跑
ollama serve # 或 curl http://localhost:11434/api/tags 验证
bash
注册到 Claude Code（写入 ~/.claude.json 的全局 mcpServers）：
"glm-ocr": {
"command": "/Users/<user>/Projects/mcp-servers/glm-ocr/.venv/bin/python",
"args": ["-m", "glm_ocr_server"]
}
json
排错速查：
| 现象 | 原因 | 解法 |
|---|---|---|
mcp__glm-ocr__* 工具不出现 | server 未注册或未启动 | 按上方部署三步检查 |
unknown model architecture: 'glmocr' | Ollama 版本过旧 | 升级到 > 0.16.2；brew 升级被镜像源卡死时换源：HOMEBREW_BOTTLE_DOMAIN=https://mirrors.ustc.edu.cn/homebrew-bottles brew reinstall ollama |
model_not_found | 本地没有模型 | ollama pull glm-ocr |
| 连接错误 | Ollama 没在跑 | curl http://localhost:11434/api/tags 确认后重启 |
工程化收尾：让项目可分发
自己能用只是及格线。再补一段提示词，把项目升华成别人也能用的工具：
这个项目后续要供其他人使用：准备依赖环境的安装脚本并测试。
安装完成后：本地下载对应模型到 models 目录、自动配置推理环境、
适配 macOS 与 Windows、测试 MCP 服务并安装 skill
（提示用户选择安装到全局还是项目局部）。
markdown
实测产出：macOS/Linux 的 install.sh 与 Windows 的 install.ps1 两套安装脚本、六项测试全部通过、全局安装验证通过。提醒一句：AI 一次跑通不等于稳，最好在另一台 Windows 或 macOS 机器上真实验证一次再对外发布。
云端替代：什么时候不自己搭
本地跑模型不是唯一解。按 2026-10 智谱官方定价算账：
| 方案 | 价格 | 适合 |
|---|---|---|
| GLM-OCR API（MaaS） | 输入输出同价 0.2 元/百万 tokens；官方口径 1 元约处理 2000 张 A4 扫描图或 200 份 10 页 PDF，约为传统 OCR 成本的 1/10 | 偶发、低量、不想维护环境 |
| GLM-4.6V（多模态视觉理解） | 输入 1 元/百万、输出 3 元/百万 tokens（较 4.5V 降 50%）；128K 上下文、原生 Function Calling；GLM-4.6V-Flash 免费 | 需要真正的视觉理解（读 UI、理解图意），不只是提文字 |
| 本地 Ollama + GLM-OCR | 0 元/次，一次性占约 2-3 GB 内存 | 隐私文档不出机器、内网/离线、批量高并发 |
官方 SDK 也把云地两端的切换做得很顺：pip install glmocr 后 CLI 一行 glmocr parse 图片.png（MaaS 模式无需 GPU）；要自部署 GPU 服务时用 vLLM/SGLang：
# vLLM 部署（官方推荐参数，MTP 投机解码加速）
pip install -U "vllm>=0.19.0"
vllm serve zai-org/GLM-OCR --port 8080 \
--speculative-config '{"method":"mtp","num_speculative_tokens":3}' \
--served-model-name glm-ocr
bash
小结
- 让文本模型"看图"的两条路：本地视觉模型（2B 起 8GB 显存，为读图配卡不合理）vs 本地 OCR（0.9B 的 GLM-OCR 普通电脑可跑）——办公场景选后者
- GLM-OCR 的竞争力：0.9B 参数做到 OmniDocBench V1.5 94.62 分 SOTA、模型权重 MIT、Ollama 一条命令拉取
- 集成方式：一句话提示词让 AI 建 MCP 服务 + skill；识别错乱时从源头分层排查（本例根因是旧服务名冲突）
- 工程化收尾：跨平台安装脚本 + 自动化测试，让个人工具变成可分发项目
- 这套"给 AI 加器官"的思路可以继续延伸：眼睛（OCR）之外还有手脚（工具执行）——MCP 生态的每一类 server 都是在回答这个问题
相关章节：01-专业图表的方案调研（本节服务的读图场景）；第3章 03 节（MCP 服务器集成与自建）
↑