企业官网建设流程全解析

1. GLM-OCR 本地跑通之后，为什么还卡在“最后一公里”

GLM-OCR 是智谱开源的一个 0.9B 参数量文档解析模型，主打把图片、PDF 里的版面结构还原成 Markdown，适合做知识库入库、票据识别、论文解析这类场景。它同时支持 API 调用、vLLM/SGLang/Transformers 部署，以及 ollama 本地拉取，看起来选择很多。但真正上手的人会发现：模型能跑起来，不代表链路能通。ollama 拉完模型，终端里敲ollama run glm-ocr却吐不出有效内容；vLLM 起完服务，客户端请求又卡在鉴权和通道配置上。问题往往不在模型本身，而在 Key 管理和后端适配这一层。

我自己在 macOS 上用 ollama 跑 glm-ocr 时，显存占用不到 3GB，模型加载很快，但直接传图片路径没有任何输出。后来才意识到，ollama 这条链路读的是编码内容而不是文件路径，而 base64 串太长，终端里根本没法手动粘贴。vLLM 那边则是另一套问题：服务起来了，但客户端要配 base_url、api_key、model 三个字段，换一个后端就要改一遍配置，来回切换非常折腾。

这篇就聚焦这个收尾问题：用 TaoToken 统一 Key 把 ollama 和 vLLM 两个后端的配置骨架固定下来，给出settings.json和config.toml的可复制模板，最后用一次真实的 OCR 请求验证通道是否连通。适合已经跑通模型、但卡在 Key 与通道配置的开发者。

2. TaoToken 前置：统一 Key 解决什么问题

TaoToken 在这里扮演的角色是统一接入层。它的官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。核心价值是：不管你后端接的是 ollama 本地服务、vLLM 起的 OpenAI 兼容接口，还是远程模型，客户端侧只需要维护一套 Key 和 base_url，不用每个后端改一次配置。

对 GLM-OCR 这个场景来说，痛点很具体。ollama 的接口格式和 vLLM 的 OpenAI 兼容接口并不完全一致，前者走/api/generate或/api/chat，后者走/v1/chat/completions。如果你在代码里硬编码后端地址，换环境就要改代码。用 TaoToken 统一 Key 之后，客户端只认一个 base_url 和一个 api_key，后端切换通过配置层完成，代码不动。

你需要先拿到 Key。进入控制台创建 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建完在 API Keys 页面复制，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，配置字段和报错码都能在里面查到。

注意：Key 只创建一次就够，ollama 和 vLLM 共用同一个 Key，不要为每个后端单独建，否则又回到多 Key 管理的老问题。

3. 可复制配置：settings.json 与 config.toml 骨架

下面给出两个配置骨架。settings.json用于客户端侧，固定 base_url 和 api_key；config.toml用于后端侧，声明 ollama 和 vLLM 两个 profile，切换时只改一个字段。

3.1 settings.json 客户端骨架

{ "taotoken": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey", "timeout": 120, "default_backend": "ollama" }, "ocr": { "model": "glm-ocr", "max_image_mb": 10, "max_pdf_mb": 50, "max_pdf_pages": 100, "image_format": ["jpg", "jpeg", "png", "pdf"] }, "backends": { "ollama": { "endpoint": "http://127.0.0.1:11434", "mode": "native" }, "vllm": { "endpoint": "http://127.0.0.1:8000/v1", "mode": "openai" } } }

这里default_backend决定当前走哪条链路，backends里两个 endpoint 分别指向本地 ollama 和 vLLM 服务。mode字段是关键：native表示走 ollama 原生接口，openai表示走 OpenAI 兼容接口，客户端根据这个字段决定请求路径和 body 结构。

3.2 config.toml 后端骨架

[taotoken] base_url = "https://taotoken.net/api" api_key = "sk-你的TaoTokenKey" [backend.ollama] type = "ollama" host = "127.0.0.1" port = 11434 model = "glm-ocr" keep_alive = "5m" [backend.vllm] type = "openai" host = "127.0.0.1" port = 8000 model = "glm-ocr" max_model_len = 8192 gpu_memory_utilization = 0.85 [ocr.limits] image_max_mb = 10 pdf_max_mb = 50 pdf_max_pages = 100

config.toml里backend.ollama和backend.vllm是两个独立段，切换后端时改[taotoken]下面加一行active_backend = "vllm"即可。keep_alive控制 ollama 模型在内存里的驻留时间，gpu_memory_utilization控制 vLLM 的显存占用比例，这两个参数按你机器实际情况调。

3.3 启动 vLLM 服务的命令

python -m vllm.entrypoints.openai.api_server \ --model zai-org/GLM-OCR \ --served-model-name glm-ocr \ --host 127.0.0.1 \ --port 8000 \ --max-model-len 8192 \ --gpu-memory-utilization 0.85

启动后确认服务在监听：

curl http://127.0.0.1:8000/v1/models

返回里能看到glm-ocr就说明 vLLM 侧就绪。ollama 侧则用ollama list确认glm-ocr已经在本地。

4. 验证请求：一次 OCR 调用打通两条链路

配置写完，必须用一次真实请求验证。下面这段 Python 代码读取settings.json，根据default_backend自动选择请求路径，把本地图片转成 base64 后发出去。

import base64 import json import requests with open("settings.json", "r") as f: cfg = json.load(f) base_url = cfg["taotoken"]["base_url"] api_key = cfg["taotoken"]["api_key"] backend_name = cfg["taotoken"]["default_backend"] backend = cfg["backends"][backend_name] with open("test.png", "rb") as f: img_b64 = base64.b64encode(f.read()).decode("utf-8") img_data = f"data:image/png;base64,{img_b64}" headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } if backend["mode"] == "openai": url = f"{base_url}/v1/chat/completions" payload = { "model": "glm-ocr", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "请解析这张图片的版面并输出Markdown"}, {"type": "image_url", "image_url": {"url": img_data}} ] } ] } else: url = f"{base_url}/api/chat" payload = { "model": "glm-ocr", "messages": [ {"role": "user", "content": "请解析这张图片的版面并输出Markdown", "images": [img_b64]} ], "stream": False } resp = requests.post(url, headers=headers, json=payload, timeout=120) print("status:", resp.status_code) print(resp.json())

跑通后，status返回 200，响应体里能看到 Markdown 格式的解析结果。如果走的是 vLLM，返回结构是 OpenAI 标准的choices[0].message.content；如果走 ollama，返回结构里是message.content。两种结构在客户端做一层适配就能统一。

实测下来，同一张倾斜拍摄的书本图片，vLLM 后端返回的 Markdown 里表格结构保留得更完整，ollama 后端在长文档上偶尔会出现段落合并。这跟后端推理参数有关，不是 Key 的问题。

提示：验证阶段先用一张小图（小于 1MB）跑通链路，确认 200 之后再换大图或 PDF，避免在鉴权问题上浪费时间。

5. 本篇常见错排查

5.1 400 报错：OCR 仅支持 PDF、JPG、PNG

这个报错最常见，原因是传了本地文件路径而不是 base64 编码。GLM-OCR 的接口不接受裸路径，必须转成data:image/png;base64,前缀的编码串。检查你的代码里有没有base64.b64encode这一步，以及前缀格式是否正确。jpeg 图片前缀写data:image/jpeg;base64,，png 写data:image/png;base64,，写错也会报 400。

5.2 ollama 终端无输出

ollama run glm-ocr之后敲Text Recognition: 图片路径没有反应，是因为 ollama 这条链路读的是编码内容，不是路径。终端里没法粘贴超长 base64 串，所以这条路本身不适合手动测试。正确做法是走上面的 Python 脚本，或者用 ollama 的 API 接口发请求。如果你只是想快速验证模型能不能跑，可以先跑一个纯文本 prompt，确认模型有输出，再换图片。

5.3 vLLM 启动报显存不足

gpu_memory_utilization设太高会 OOM。0.9B 的模型本身占用不大，但 vLLM 会预分配 KV cache。如果机器上还有其他进程占显存，把--gpu-memory-utilization降到 0.6 到 0.7 之间再试。另外--max-model-len设太大也会增加显存压力，8192 对 OCR 场景够用。

5.4 401 鉴权失败

检查api_key有没有带Bearer前缀，以及 base_url 是不是https://taotoken.net/api。如果 base_url 末尾多写了/v1，而代码里又拼了一次/v1/chat/completions，路径会变成/v1/v1/chat/completions，直接 404。统一在配置里写根路径，拼接逻辑放在代码里。

5.5 返回结果解析失败

GLM-OCR 的 API 返回是裸 JSON，没有统一包装。vLLM 走 OpenAI 格式，ollama 走原生格式，两者字段名不同。在客户端加一层判断：如果响应里有choices，取choices[0].message.content；如果有message，取message.content。不要硬编码一种结构。

6. 长期编码与 Agent 场景的接入建议

如果你只是偶尔跑一次 OCR，上面的配置够用。但如果你要把 GLM-OCR 接进长期的编码流程或 Agent 工作流，比如自动解析文档后喂给代码生成模型，那 Key 和通道的稳定性就很重要。这时候建议用 Coding Plan 来管理额度，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它适合需要持续调用、多后端切换的场景。

模型对话调试可以用 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，在里面直接发请求看返回，不用写代码就能验证 Key 是否生效。ClaudeCode 相关的接入配置在 https://taotoken.net/claudecode?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite ，如果你用 Claude Code 做开发，可以把 GLM-OCR 的解析结果直接喂进去。

最后说一个实际经验：ollama 和 vLLM 双后端切换时，最容易出问题的不是模型本身，而是请求路径和 body 结构不一致。把mode字段作为唯一判断依据，所有分支逻辑围绕它写，配置层只改default_backend一个值，这样换后端不用动代码。GLM-OCR 的最后一公里，卡的不是模型能力，是这层适配骨架有没有搭好。