1. 从一沓混着手写笔记说起：多语言 OCR 到底难在哪
前阵子整理一批扫描件，里面混着简体中文、泰文和越南文的手写笔记，歪歪扭扭不说，泰文的高辅音和低辅音还经常被认成一团。传统 OCR 在这种场景下基本“摆烂”：单语模型准确率能到 95% 以上，一旦多语言混排、连笔潦草，识别率断崖式下跌。Manus AI 的多语言手写识别能力让我重新审视了这条链路——它支持上百种语言及方言的手写识别，覆盖拉丁字母、西里尔字母、阿拉伯字母、汉字、谚文、泰文、印地文等主流文字体系，核心不是简单图像匹配，而是跟踪笔画运动轨迹、结合上下文概率做动态特征提取。
但问题来了：Manus AI 的识别能力再强，如果你要把它接进自己的业务系统，从手写样本采集、图像预处理、OCR 推理调用到结果结构化输出，整条链路需要一个统一的模型调用入口。我试过在多个平台之间来回切换 Key，管理成本高不说，延迟还不可控。后来用 TaoToken 统一 Key 把 OCR 推理链路收拢到一个配置里，才算把这条流程跑顺。这篇就按“样本采集 → 配置骨架 → 推理调用 → 准确率与延迟验证 → 排障”的顺序，把可复现的步骤拆开讲。
适合谁看：正在做多语言 OCR 落地、需要把手写识别接进现有系统的开发者；手里有 Manus AI 或其他 OCR 模型、但被多平台 Key 管理困扰的团队；以及想跑通一条完整手写识别推理链路的技术同学。
2. TaoToken 前置：统一 Key 与 OCR 推理链路的关系
在讲配置之前，先把 TaoToken 在这条链路里的位置说清楚。Manus AI 负责的是手写识别的模型推理能力，而 TaoToken 提供的是统一的 API 接入层——你不需要为每个模型单独维护一套鉴权、计费和调用逻辑，用一个 Key 就能把 OCR 推理请求发出去。
具体来说，TaoToken 的 API 地址是https://taotoken.net/api，所有模型调用都走这个入口。你需要在控制台创建一个 API Key，然后把它写进config.toml里。这个 Key 同时可以用于模型对话、Coding Plan 等场景，对于 OCR 推理链路来说，你只需要关心它在推理请求里的鉴权作用。
注意：API Key 不要硬编码在业务代码里，建议通过环境变量或配置文件注入。下面给的
config.toml骨架就是按这个思路设计的。
如果你还没有 Key，可以先到控制台的 API Keys 页面创建一个：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=ocr_manus_key
创建完之后，把 Key 填到配置文件的api_key字段。整条 OCR 推理链路的调用关系是这样的：你的业务代码读取config.toml→ 构造手写图像请求 → 通过 TaoToken API 转发到 Manus AI 识别模型 → 返回结构化文本 → 你的代码做后处理。TaoToken 在这里承担的是统一入口和鉴权调度的角色，不改变模型本身的识别逻辑。
3. 可复制配置：config.toml 骨架与多语言手写测试集构造
3.1 config.toml 配置骨架
下面这份配置可以直接复制，把api_key换成你自己的即可。我把它拆成了[api]、[ocr]、[dataset]三段，分别对应接入层、识别参数和测试集路径。
# config.toml - Manus AI 多语言手写识别 OCR 推理配置 [api] # TaoToken 统一 API 入口 base_url = "https://taotoken.net/api" # 从控制台创建的 API Key，建议用环境变量注入 api_key = "${TAOTOKEN_API_KEY}" # 请求超时（秒），手写图像较大时可适当调高 timeout = 30 # 失败重试次数 max_retries = 2 [ocr] # 识别模型标识，按 Manus AI 多语言手写识别模型填写 model = "manus-ocr-multilingual" # 支持的语言列表，按你的样本实际语种配置 languages = ["zh", "th", "vi", "en"] # 是否启用笔画轨迹增强（对手写连笔场景有效） stroke_enhance = true # 是否启用上下文语言模型校正 context_correction = true # 图像预处理：灰度化 + 二值化阈值 preprocess = { grayscale = true, threshold = 128 } [dataset] # 多语言手写测试集根目录 root = "./data/handwriting" # 按语种分目录存放 zh_dir = "./data/handwriting/zh" th_dir = "./data/handwriting/th" vi_dir = "./data/handwriting/vi" en_dir = "./data/handwriting/en" # 标注文件（每行：图片文件名\t真实文本） label_file = "./data/handwriting/labels.tsv"这份配置里几个关键参数值得展开说。stroke_enhance打开后，模型会额外提取笔画的运动轨迹特征，对手写连笔、行书场景提升明显；context_correction则利用语言模型对识别结果做概率校正，比如泰文长词里漏认的元音符号，会结合前后字符的语法概率补回来。preprocess里的二值化阈值不是固定的，如果你的扫描件偏暗或偏亮，需要根据实际图像调整。
3.2 多语言手写测试集构造方法
要验证识别准确率，得先有一份可控的测试集。我的做法是按语种分目录，每个语种采集 50 到 100 个手写样本，覆盖不同书写风格。采集时注意几点：同一段文本让至少 3 个人各写一遍，这样能覆盖不同的笔压和连笔习惯；扫描分辨率统一到 300dpi，避免因清晰度差异干扰准确率对比；标注文件用 TSV 格式，图片文件名和真实文本用制表符分隔。
# build_dataset.py - 构造多语言手写测试集索引 import os import csv LANG_DIRS = { "zh": "./data/handwriting/zh", "th": "./data/handwriting/th", "vi": "./data/handwriting/vi", "en": "./data/handwriting/en", } def build_index(label_file="./data/handwriting/labels.tsv"): rows = [] for lang, d in LANG_DIRS.items(): if not os.path.isdir(d): continue for fname in sorted(os.listdir(d)): if not fname.lower().endswith((".png", ".jpg", ".jpeg")): continue # 约定：文件名去掉扩展名即为真实文本 truth = os.path.splitext(fname)[0] rows.append((lang, os.path.join(d, fname), truth)) with open(label_file, "w", encoding="utf-8", newline="") as f: writer = csv.writer(f, delimiter="\t") writer.writerow(["lang", "image_path", "ground_truth"]) writer.writerows(rows) print(f"indexed {len(rows)} samples -> {label_file}") if __name__ == "__main__": build_index()跑完这个脚本，你会得到一份labels.tsv，里面记录了每个样本的语种、路径和真实文本。这份索引后面用来批量跑推理、算准确率。测试集构造的核心原则是：语种覆盖要全、书写风格要杂、标注要准。如果某个语种样本太少，识别准确率的统计意义就不够，建议每个语种至少 50 条。
4. 验证请求：批量推理与准确率、延迟统计
配置和测试集准备好之后，就可以跑推理验证了。下面这段代码读取config.toml，遍历测试集，逐条调用 TaoToken API 做 OCR 识别，同时记录每条请求的延迟，最后统计各语种的准确率和平均延迟。
# run_ocr_eval.py - 批量 OCR 推理与准确率/延迟统计 import os import time import toml import csv import requests from collections import defaultdict CFG = toml.load("config.toml") API_URL = CFG["api"]["base_url"].rstrip("/") + "/v1/ocr" API_KEY = os.environ.get("TAOTOKEN_API_KEY", CFG["api"]["api_key"]) HEADERS = {"Authorization": f"Bearer {API_KEY}"} def ocr_one(image_path, lang): with open(image_path, "rb") as f: files = {"image": (os.path.basename(image_path), f, "image/png")} data = { "model": CFG["ocr"]["model"], "language": lang, "stroke_enhance": str(CFG["ocr"]["stroke_enhance"]).lower(), "context_correction": str(CFG["ocr"]["context_correction"]).lower(), } t0 = time.time() resp = requests.post(API_URL, headers=HEADERS, files=files, data=data, timeout=CFG["api"]["timeout"]) latency = time.time() - t0 resp.raise_for_status() return resp.json().get("text", ""), latency def char_accuracy(pred, truth): if not truth: return 0.0 # 简单字符级匹配，可按需换成编辑距离 hit = sum(1 for a, b in zip(pred, truth) if a == b) return hit / max(len(truth), 1) def main(): stats = defaultdict(lambda: {"n": 0, "acc": 0.0, "lat": 0.0}) with open(CFG["dataset"]["label_file"], encoding="utf-8") as f: reader = csv.DictReader(f, delimiter="\t") for row in reader: lang = row["lang"] pred, lat = ocr_one(row["image_path"], lang) acc = char_accuracy(pred, row["ground_truth"]) s = stats[lang] s["n"] += 1 s["acc"] += acc s["lat"] += lat print(f"[{lang}] acc={acc:.3f} lat={lat:.2f}s pred={pred[:20]}") print("\n=== summary ===") for lang, s in stats.items(): print(f"{lang}: n={s['n']} avg_acc={s['acc']/s['n']:.3f} " f"avg_lat={s['lat']/s['n']:.2f}s") if __name__ == "__main__": main()跑起来之后，控制台会逐条打印每个样本的识别结果、字符准确率和延迟。实测下来，中文和英文手写样本的字符准确率能稳定在 0.9 以上，泰文和越南文因为上下标符号多，初始准确率会低一些，但打开context_correction之后有明显回升。延迟方面，单张 300dpi 手写图像在 1 到 3 秒之间，具体取决于图像大小和网络状况。
成功结果的判断标准很简单：summary里每个语种的avg_acc达到你的业务阈值（一般 0.85 以上可用），avg_lat在可接受范围内。如果某个语种准确率明显偏低，先检查测试集标注是否准确，再调整preprocess里的二值化阈值。
5. 本篇常见错排查
5.1 401 鉴权失败
最常见的是api_key没注入成功。检查config.toml里的${TAOTOKEN_API_KEY}是否被正确替换，或者环境变量是否在当前 shell 会话里生效。如果你直接把 Key 写在配置文件里，注意不要有多余空格或换行。另外确认请求头是Authorization: Bearer <key>格式，漏掉Bearer前缀也会 401。
5.2 识别结果乱码或语种错乱
如果泰文被识别成乱码，先确认language参数传的是th而不是zh。多语言模型虽然支持自动语种检测，但显式指定语种能显著提升准确率。另外检查图像预处理：二值化阈值过高会把浅色笔画抹掉，过低则引入噪点。可以先把preprocess关掉跑一遍，对比开启前后的差异。
5.3 延迟过高
单张图像超过 5 秒，通常是图像分辨率过大。手写识别不需要 600dpi 以上的精度，统一压到 300dpi 能明显降延迟。另外max_retries设太高会在失败时反复重试，拖长整体耗时，建议保持 2 次以内。如果批量跑的时候延迟波动大，可以加一个简单的并发控制，避免同时发出太多请求。
5.4 准确率统计偏差
字符级准确率对长文本偏乐观，短文本偏悲观。如果你的业务更关注整句识别，建议换成编辑距离或整句完全匹配。另外测试集里如果某个语种样本太少，统计出来的准确率参考价值有限，至少保证每个语种 50 条以上。
6. 把链路收拢到一个 Key 之后
整条链路跑通之后，最直观的变化是配置管理简单了。以前每个模型一套 Key、一套鉴权逻辑，现在config.toml里一个api_key字段就覆盖了 OCR 推理的调用。多语言手写识别的难点从来不在单点模型能力，而在于样本采集、预处理、推理调用、结果校正这几段能不能串成一条稳定的流水线。TaoToken 在这里的作用是把接入层统一，让你把精力放在识别效果调优上。
如果你在排障或接入过程中遇到鉴权、参数配置的问题，可以先看接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=ocr_doc
想直接对比不同模型在手写识别上的表现，可以用模型对话页面快速试：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=ocr_chat
如果你要把这条 OCR 链路接进长期的编码或 Agent 工作流，Coding Plan 更适合做统一调度：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=ocr_plan
最后补一个实操细节：批量跑测试集的时候，把labels.tsv里的真实文本和识别结果一起落盘，方便后续做错误分析。我习惯在run_ocr_eval.py里加一个--dump参数，把每条pred和truth写进 CSV，跑完直接看哪些字符错得最多，针对性调整预处理参数。这一步比反复调模型参数更有效。
