1. 这个项目到底在解决什么问题

标题里带“翻译”两个字，是因为这套思路最早来自一份外文分享的整理，我把它复现了一遍，又在自己的业务里迭代到第四个版本。核心诉求一句话说完：把一张图片里的表格，变成可以双击修改、可以排序筛选、可以另存为 Excel 的真表格。不是“识别出一堆文字”，也不是“给你一段 Markdown 的竖线”，而是行列对齐、合并单元格还原、数字还是数字、日期还是日期的那种可编辑状态。做报表、做对账、做资料归档的人应该都懂这个痛点：截图好拿，数据难抄。一份几十行的费用明细，肉眼抄二十分钟，抄完还要核对三遍。

这个项目解决的就是中间这段“人工搬运”的活。输入是一张图——手机拍的纸质表、截图、PDF 转出来的图片都行；输出是一个 DataFrame，用户在界面上直接改，改完点一下导出 xlsx。适合谁来参考？我觉得三类人：一是做内部工具的开发者，手上有一堆“帮我把这个表录进系统”的需求；二是做数据整理的分析岗，不想再买按量计费的商业识别服务；三是对多模态模型结构化输出感兴趣、想看看怎么把它约束成“稳定的接口”而不是“会聊天的玩具”的人。代码层面只需要会一点 Python 和 pandas，界面层用的是 Streamlit，四版迭代下来我最大的感受是：难的不是让模型看图说话，难的是让它每次都说成同一个格式，且错得有迹可循。

1.1 从“看得见”到“改得动”的差距

很多人第一反应是：这不就是 OCR 吗？我一开始也这么想，用传统 OCR 加规则解析试了两周，最后放弃。传统 OCR 输出的是“带坐标的文本块”，它不知道哪一行是表头，不知道这一列是金额还是数量，更不知道第 3 行的第 2 个格子被合并跨了四行。你要自己写一套版面分析：找横线竖线、聚类成单元格、判断表头、判断合并、处理空单元格——这套东西在有线框的标准表格上勉强能用，一遇到三线表、无框表、截图压缩后线条断裂，准确率断崖式下跌。而且这套规则是“一张表一套逻辑”，换个业务方的报表模板就得重调。

视觉大模型的价值恰好在这里：它是在“理解”这张图在表达什么，而不是在“检测像素”。它看到“合计”两个字出现在最后一行，会知道这是一行汇总；看到某列全是 ¥ 开头的字符串，会把它当金额。我们要做的，是把这个理解能力约束成一个可编程的接口，把不确定性挡在边界上。所以我这个项目真正的技术含量不在“调模型”，而在三件事：图像进来之前怎么处理、提示词怎么把它逼进固定结构、输出之后怎么校验和兜底。

1.2 四版迭代踩出来的路线图

把四个版本的演进摊开看，其实就是一部“踩坑史”，写在这里是想让你少走我走过的弯路：

第一版最天真，直接让模型“把表格转成 Markdown”，然后自己用|切。问题在于模型很自由，有时候给你 6 列，有时候把“备注”两列合成一列，遇到跨行合并直接把内容重复填满。第二版加了 JSON Schema 约束，效果立竿见影，但新问题是：模型输出有 token 上限，一张 100 行的表跑到一半就断了，最后几行凭空消失，比报错更可怕，因为它不报错。第三版才开始动图像：分块、放大、纠偏，配合“先描述结构、再逐块填数据”的两段式调用，才把大表跑稳。到了第四版，我把重心从“识别”挪到“可信”——让用户能看见模型不确定的地方，能一键改，能对比原图核验。这个转变很关键，后面会详细讲。

2. 整体设计与技术选型拆解

整套东西的数据流我定成四段：图像预处理 → 结构探测 → 分块抽取 → 还原导出。每一段都有明确的输入输出契约，任何一段出问题都能单独重跑，不用推倒重来。这个设计的初衷是我早期吃过亏：一开始写成一个大函数，从上传到导出一条龙，结果某张图识别错了，我想重试只能从头再传一遍，调试的时候简直折磨。拆成四段之后，结构和数据分开存，用户可以只重跑“数据抽取”而不用重新上传，也可以在“还原”这步手动修结构，效率提升非常明显。

2.1 为什么绕开传统 OCR 直接上视觉大模型

先说结论：有线框、印刷清晰、批量固定的表格，传统 OCR + 模板解析仍然是最便宜的方案，一张图几毫秒，成本几乎为零。但只要你的输入是“杂”的——来源杂、版式杂、清晰度杂——视觉模型的综合成本反而更低，因为它的“适配成本”几乎是零，换个模板不用改代码。

具体到我这个场景，三个决定性因素。第一是合并单元格。传统方案要靠线段检测推断合并，斜线表头、跨页续表基本必挂；视觉模型看到“这个格子的内容横跨了下面四行的高度”，会自然理解成跨行。第二是语义纠错。纸质表上有“OO1”这种把 0 打成 O 的，OCR 会老老实实输出 OO1，而理解了上下文的模型有概率纠正回 001——注意是有概率，这个特性是双刃剑，第 6 节会讲怎么防它乱纠。第三是开发速度。我用两天做出了第一版可跑的东西，同样的时间用传统方案只够把线段检测调到“勉强不崩”。

代价也很明确：单张成本从“几乎免费”变成“几分钱一张”，延迟从毫秒变成几秒，还需要处理网络超时、限流、模型版本漂移。这笔账怎么算，取决于你的表格量级和人工成本。我的判断线是：如果一份表人工录入要 10 分钟以上，且每月超过 50 份，上视觉模型就值。

2.2 为什么界面层选 Streamlit

界面这块我没纠结太久。这个工具的使用者是内部同事，不需要精美 UI，需要的是“上传、看结果、改、下载”四步闭环，而且改动频繁、需求天天变。Streamlit 的最大优势是把状态和渲染揉在一份 Python 文件里，改一个控件就是改一行，不用碰前后端分离那一套。四版下来，界面代码始终控制在 300 行以内。

但它有两个必须提前知道的坑。第一是每次交互整页重跑，任何一次点击都会从头执行脚本，所以昂贵的抽取调用必须靠缓存挡住，否则用户改一个单元格就重新调一次模型，账单直接起飞。第二是状态不自动保存，重跑之后局部变量全丢，必须把结果塞进st.session_state。这两点我在第四版做了系统性处理，具体代码在 4.5 节。

提示：如果你的团队要求权限体系、多人协作、审批流，Streamlit 就不是好选择，老老实实上常规 Web 框架。它的定位是“内部工具快速落地”，别指望它扛生产级门户。

2.3 四段式数据流的契约设计

把契约写清楚，是这套东西能迭代四版还没变成屎山的关键。我给每段定了一个中间产物：

• 第一段输入原始图片字节，输出“标准化图像 + 预处理报告”（是否纠偏、是否放大、切了几块）。报告很有用，出问题时一眼能看出是不是预处理背锅。
• 第二段输入标准化图像，输出“结构描述”：列数、表头占几行、每列推测的语义类型（文本/数字/日期/金额）、是否有合并、是否有汇总行。这一步不抽数据，只抽骨架。
• 第三段输入结构描述 + 图像块，输出“稠密矩阵”：每个物理单元格一个值，合并区域先按填满处理。这个设计是整个项目的核心 trick，后面细说。
• 第四段输入稠密矩阵 + 结构描述，输出 DataFrame 和 xlsx 字节流，同时把合并信息还原成 Excel 的合并区域。

中间产物全部可序列化成 JSON 存下来，用户点“导出过程记录”就能拿到，方便我复盘某张图到底是哪一步错了。这个习惯救过我很多次，因为模型的错误往往是偶发的，不存现场根本复现不了。

3. 核心细节：把“看起来像表格”变成“结构上真是表格”

这一段是我认为最值得抄的部分。很多人用视觉模型做表格识别，卡在“结果时好时坏”，根因通常不在模型能力，而在没有把“结构”和“数据”分开约束。让模型一次性输出“这是一个 8 列 30 行的表，表头两行，第 2 列合并，数据是……”，它要同时做太多判断，错误会互相污染：行列数判错了，数据自然就错位。拆成两问，第一问只回答骨架，第二问在给定骨架下填格子，准确率会有肉眼可见的提升。

3.1 图像预处理的几个硬指标

预处理这块我不追求花哨，只盯四个指标：有效宽度、倾斜角、对比度、噪点。

有效宽度指的是表格内容占的像素宽度。经验值：表格主体宽度低于 800px 时，小字号数字（尤其是 8pt 的金额）识别错误率会明显上升；理想区间是 1400–2200px。截图通常够，手机拍照往往不够，所以我会做一个“短边不足 1000px 就按 2 倍双三次插值放大”的动作。注意是插值放大，不是变清晰，它不能让模糊的字变清楚，但能让模型的图像分块不要把一个字切成两半，实测对 8pt 小字有改善。

倾斜角用霍夫直线估计：灰度化 → Canny 边缘 → 概率霍夫变换拿到所有长直线的角度 → 取中位数。超过 0.6 度就旋转校正，低于这个值别动，因为旋转本身会引入插值模糊。0.6 度这个阈值是试出来的，再低会把正常的水平线误判成倾斜，反而越纠越歪。

对比度用 CLAHE（限制对比度的自适应直方图均衡），clipLimit=2.0、tileGridSize=(8,8)。扫描件和手机拍照的对比度普遍偏低，这一步很有效。噪点用 3×3 中值滤波，只对灰度图做，别对彩色图做，颜色信息在判断“红色负数”时有用。

注意：二值化不要无脑上。我第二版加了大津法二值化，结果把浅灰色表头线全部弄没了，模型反而判不出表头行数。印刷清晰的图保留灰度即可，只有扫描件、传真件这类噪点很重的才做自适应二值化。

3.2 提示词与输出结构的约束

提示词我改了二十多版，最后稳定下来的模板有几个原则。第一，明确禁止它做任何计算和推断，只做“转写”。不加这句，模型会自己算合计、补全空值、把“同上”替换成上一行的内容，这些“聪明”的行为对我们是灾难。第二，明确空单元格的表示，我规定用null，不能用空字符串、不能用"-"、不能用"无"，因为后面要靠 null 区分“真的空”和“写了个横杠”。第三，所有值一律输出字符串，包括数字。这是为了防止 JSON 序列化把1.10变成1.1、把 18 位订单号搞成科学计数法。类型转换放到后面用代码做，可控得多。

输出结构我用 JSON Schema 强制，核心字段是这样的思路：

{ "header_rows": 2, "columns": [ {"index": 0, "name": "序号", "type": "int"}, {"index": 1, "name": "费用项目", "type": "text"}, {"index": 2, "name": "金额（元）", "type": "decimal"} ], "merged": [{"r1": 2, "c1": 3, "r2": 5, "c2": 3}], "rows": [["1", "差旅费", "1280.50"], ["2", "办公用品", "336.00"]], "warnings": ["第7行金额列疑似模糊，置信度低"] }

注意最后那个warnings字段，这是第四版加的，非常有用。我明确告诉模型：“如果你对某个单元格不确定，不要猜，写进 warnings，值照常给但标记出来”。这样前端可以把这些单元格标黄，用户一眼看到哪里要核对。让模型承认不确定，比让它硬答然后悄悄错掉，价值大得多。

3.3 合并单元格、跨页表格与脏数据的处理策略

合并单元格的处理逻辑是：模型按“稠密矩阵”输出，也就是合并区域的每一个物理位置都填上同一个值。比如第 3 到 5 行的第 2 列合并成“华东区”，模型就输出三行，每行第 2 列都是“华东区”，同时在merged里记录{r1:3, c1:2, r2:5, c2:2}。到了还原阶段，程序按merged把重复值清空、写 Excel 合并区域。为什么不直接让模型只输出一次？因为它一旦只输出一次，后面的行就会左移一列，整个表全歪。先填满再收起，是唯一稳定的做法。

跨页表格要处理的是“续表”问题。我的做法是分块后逐块抽取，每块都带上前一块的列名作为上下文，抽完之后用“表头指纹”判断是否需要拼接：如果这一块的第一行内容和上一块的列名高度重合，说明它重复了表头，丢掉这一行；如果这一块的列数比上一块少，大概率是最后一页的残缺行，做左对齐补 null。这块逻辑看着粗糙，但实测比我尝试过的任何自动版面分析都稳。

脏数据主要是三类。一类是“同上”“－”“／”这种占位符，我在提示词里明确要求原样转写，不做语义替换，由后端决定怎么处理。二类是单位和数字混排，比如“12,800.00 元”，我要求拆成值12800.00和单位记在列名上，如果列名里没有单位信息，就写在 warnings 里。三类是括号负数，财会表格里(1,280.00)表示负一千二百八，这个必须显式在提示词里约定转换规则，否则模型有时候给你保留括号、有时候给你转成负数，前后不一致。

4. 实操过程：从一张截图到可编辑表格的完整链路

这一段我把可复现的代码贴出来，都是我在第四版里实际跑的版本，去掉了业务耦合的部分。整体依赖很少：streamlit、pandas、pillow、opencv-python、openpyxl、xlsxwriter，再加一个多模态模型的调用客户端。

4.1 环境与依赖

python -m venv .venv source .venv/bin/activate pip install streamlit pandas pillow opencv-python openpyxl xlsxwriter

模型的调用客户端各家 SDK 写法不太一样，但核心就一件事：把图片按 base64 塞进消息体，把 JSON Schema 塞进约束参数。我在项目里做了一层薄封装vision_extract(image_bytes, prompt, schema) -> dict，把厂商差异挡在外面。这样做的实际好处是：模型换版本、换供应商，只改这一个函数，上层四段流水线完全不动。第四版迭代期间我换过两次模型，上层代码一行没改，这就是抽象层的价值。

4.2 图像预处理代码

import cv2 import numpy as np from PIL import Image import io def normalize_image(raw: bytes, min_side: int = 1000, max_side: int = 2400) -> tuple[bytes, dict]: """返回标准化后的 PNG 字节和预处理报告""" img = Image.open(io.BytesIO(raw)).convert("RGB") report = {"orig_size": img.size, "rotated": 0.0, "upscaled": 1.0, "clahe": False} # 1) 短边放大：小字识别率的关键 w, h = img.size if min(w, h) < min_side: scale = min_side / min(w, h) img = img.resize((int(w * scale), int(h * scale)), Image.BICUBIC) report["upscaled"] = round(scale, 2) # 2) 过大则等比缩小，控制 token 消耗 w, h = img.size if max(w, h) > max_side: scale = max_side / max(w, h) img = img.resize((int(w * scale), int(h * scale)), Image.LANCZOS) arr = cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR) gray = cv2.cvtColor(arr, cv2.COLOR_BGR2GRAY) # 3) 倾斜校正：超过阈值才动，避免引入插值模糊 edges = cv2.Canny(gray, 50, 150) lines = cv2.HoughLinesP(edges, 1, np.pi / 180, threshold=100, minLineLength=gray.shape[1] // 3, maxLineGap=20) if lines is not None: angles = [] for x1, y1, x2, y2 in lines[:, 0]: if x2 != x1: a = np.degrees(np.arctan2(y2 - y1, x2 - x1)) if abs(a) < 15: angles.append(a) if angles: angle = float(np.median(angles)) if abs(angle) > 0.6: m = cv2.getRotationMatrix2D( (arr.shape[1] / 2, arr.shape[0] / 2), angle, 1.0) arr = cv2.warpAffine(arr, m, (arr.shape[1], arr.shape[0]), flags=cv2.INTER_CUBIC, borderValue=(255, 255, 255)) report["rotated"] = round(angle, 2) # 4) 对比度增强 + 轻度降噪 lab = cv2.cvtColor(arr, cv2.COLOR_BGR2LAB) l, a, b = cv2.split(lab) l = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8)).apply(l) arr = cv2.cvtColor(cv2.merge([l, a, b]), cv2.COLOR_LAB2BGR) report["clahe"] = True out = Image.fromarray(cv2.cvtColor(arr, cv2.COLOR_BGR2RGB)) buf = io.BytesIO() out.save(buf, format="PNG", optimize=True) report["final_size"] = out.size report["png_kb"] = round(len(buf.getvalue()) / 1024, 1) return buf.getvalue(), report

这套参数是我拿 200 张真实样本调出来的。min_side=1000再往上，识别率提升就很有限了，但 token 消耗线性上涨；max_side=2400是因为超过这个尺寸后模型端会自己缩放，传上去纯属浪费。预处理报告里的png_kb是我特意加的，用来监控成本：一张 A4 扫描件转 PNG 通常在 300–800KB，转 base64 之后膨胀约 1.33 倍，如果某天突然出现 5MB 的图，说明有人传了原图，得在前端挡一下。

4.3 结构化抽取与 JSON 校验

两段式抽取的核心代码：

import json STRUCT_PROMPT = """你是表格结构解析器。只做转写，不做任何计算、补全、纠错。 输出严格的 JSON，字段如下： - header_rows: 表头占的行数，整数 - columns: 数组，每项 {index, name, type}，type 取值 text/int/decimal/date - merged: 合并单元格数组，坐标以数据区左上角为 (0,0) 的行列索引 - rows: 二维字符串数组，空单元格必须是 null - warnings: 数组，每个元素描述你不确定的单元格位置和原因 规则： 1) 所有值输出字符串，数字不要转成 JSON number 2) 合并区域按物理位置填满，同一个值重复出现在每一行 3) 不要输出合计以外的任何计算值 4) 模糊不清的字按最接近的字转写，同时写入 warnings """ def probe_structure(image_bytes: bytes, client) -> dict: raw = client.vision_extract(image_bytes, STRUCT_PROMPT) data = safe_json_loads(raw) # 结构自检：列数必须与每行列数一致 ncol = len(data["columns"]) for i, row in enumerate(data["rows"]): if len(row) != ncol: raise StructureError(f"第{i}行列数{len(row)}与表头{ncol}不一致") return data def safe_json_loads(text: str) -> dict: """模型偶尔会在 JSON 外面套一段解释，这里做容错""" text = text.strip() if text.startswith("```"): text = text.split("```")[1] text = text.split("\n", 1)[1] if "\n" in text else text start, end = text.find("{"), text.rfind("}") if start == -1 or end == -1: raise ValueError("响应中未找到 JSON 主体") return json.loads(text[start:end + 1])

这里有两个细节值得单独说。一是列数自检。我强制要求每一行的长度必须等于表头列数，不等就直接抛异常让用户重试，绝对不能让残缺行混进 DataFrame——pandas 对不齐的列表会补 NaN，看起来“能用”，实际上数据已经整体错位，这种错误最难发现。二是 JSON 容错解析。即使你要求只输出 JSON，模型仍有概率在前面加一句“这是解析结果：”，或者给你套个 markdown 代码块。用花括号定位首尾是最稳的兜底，别指望用正则匹配整段。

4.4 DataFrame 还原与 Excel 导出

还原阶段要做三件事：类型转换、合并收起、样式写入。

import pandas as pd import re def to_dataframe(struct: dict) -> pd.DataFrame: cols = [c["name"] for c in struct["columns"]] df = pd.DataFrame(struct["rows"], columns=cols) for c in struct["columns"]: name, typ = c["name"], c["type"] if typ in ("int", "decimal"): df[name] = df[name].map(parse_number) elif typ == "date": df[name] = pd.to_datetime(df[name], errors="coerce") # 合并单元格：把重复值收起，仅保留首行 for m in struct.get("merged", []): r1, c1, r2, c2 = m["r1"], m["c1"], m["r2"], m["c2"] if c1 == c2 and r2 > r1: # 纵向合并 col = cols[c1] df.loc[r1 + 1:r2, col] = None return df NUM_RE = re.compile(r"^\(?-?[\d,]+(\.\d+)?\)?$") def parse_number(v): if v is None or v == "": return None s = str(v).strip().replace(",", "").replace("，", "") neg = s.startswith("(") and s.endswith(")") s = s.strip("()") if not NUM_RE.match(str(v)): return None # 宁可为空，不要错误数值 num = float(s) return -num if neg else num

parse_number里那个“宁可为空”的判断很关键。我早期版本的写法是float(re.sub(r"[^\d.-]", "", s))，看起来能兜住一切，结果把“待定”这种文本洗成了空字符串，反而让用户以为这一格是 0。现在的逻辑是：不符合数字模式的直接回 None，同时在前端把这行标红提示人工确认。在数据清洗里，静默的错误比显式的空值危险十倍。

Excel 导出有两个必须处理的坑：订单号变成科学计数法、中文 CSV 乱码（如果是导 CSV 的话）。前者靠显式设置单元格格式为文本解决，后者靠utf-8-sig编码。

import xlsxwriter def export_xlsx(df: pd.DataFrame, struct: dict) -> bytes: buf = io.BytesIO() with pd.ExcelWriter(buf, engine="xlsxwriter") as writer: df.to_excel(writer, index=False, sheet_name="Sheet1") wb, ws = writer.book, writer.sheets["Sheet1"] # 长数字列强制文本格式，防止订单号被转科学计数法 for idx, col in enumerate(df.columns): if df[col].dtype == object and \ df[col].astype(str).str.len().max() >= 15: fmt = wb.add_format({"num_format": "@"}) ws.set_column(idx, idx, 22, fmt) else: ws.set_column(idx, idx, max(12, len(str(col)) * 2)) # 写回合并区域 for m in struct.get("merged", []): ws.merge_range(m["r1"] + 1, m["c1"], m["r2"] + 1, m["c2"], None) return buf.getvalue()

这里我用xlsxwriter而不是默认的openpyxl，原因是它对merge_range和列宽格式的支持更直接。代价是它不能读写已有文件，只能新建，我们这里是“从零生成”，正好合适。

4.5 Streamlit 第四版界面改造要点

第四版改动最大的是界面，从“一屏到底”改成“三步走”。核心目标只有一个：让用户能核验、能修改、能反悔。

import streamlit as st import hashlib st.set_page_config(page_title="表格图像转可编辑表格", layout="wide") if "struct" not in st.session_state: st.session_state.struct = None if "df" not in st.session_state: st.session_state.df = None uploaded = st.file_uploader("上传表格图片", type=["png", "jpg", "jpeg"]) # 关键：用字节 hash 做缓存 key，而不是用 UploadedFile 对象 raw = uploaded.getvalue() if uploaded else None img_hash = hashlib.md5(raw).hexdigest() if raw else None @st.cache_data(show_spinner="正在抽取结构…", max_entries=32) def cached_probe(img_hash: str, img_bytes: bytes): norm, report = normalize_image(img_bytes) return probe_structure(norm, client), report if raw and st.session_state.struct is None: struct, report = cached_probe(img_hash, raw) st.session_state.struct = struct st.session_state.df = to_dataframe(struct) if st.session_state.df is not None: st.subheader("第二步：核对并修改") edited = st.data_editor(st.session_state.df, use_container_width=True, num_rows="dynamic") if st.button("导出 Excel"): xlsx = export_xlsx(edited, st.session_state.struct) st.download_button("下载", xlsx, "result.xlsx", mime="application/vnd.openxmlformats-" "officedocument.spreadsheetml.sheet")

这段代码里藏着两个我踩过的坑，必须点出来。

注意：st.cache_data的 key 绝对不能用UploadedFile对象本身。每次交互重跑时 Streamlit 会重新构造这个对象，内存地址变了，缓存永远不命中，等于每次改一个单元格都重新调一次模型，账单能吓死人。正确做法是用getvalue()拿到的字节算 hash。

注意：st.data_editor返回的是用户改过的 DataFrame，但列的数据类型会变。原本是 float 的金额列，用户一旦手动输入，整列会退化成 object，导出时又变回字符串。所以导出的地方要么重新做一次类型规整，要么在 UI 上就明确告诉用户“这一列请只填数字”。

第三步我加了一个“原图对照”的折叠面板，把原图和编辑表格并排显示，用户核对的时候不用来回切窗口。这一步看着小，实际上是把工具从“玩具”变成“能交给同事用”的分水岭——因为再准的模型也有错的时候，用户需要的不是 100% 准确，而是错了能查出来、能改掉。

5. 参数、成本与准确率的账怎么算

做这种工具，老板一定会问两句话：准不准？多少钱？这两个问题不能拍脑袋回答，得有可量化的口径。我在第四版里专门加了一个离线的评估脚本和一个在线成本计数器，加起来不到 100 行，但让我在跟人解释的时候底气完全不同。

5.1 图像分辨率与 token 的换算思路

视觉模型的计费口径各家不同，但大方向一致：图片被切成若干固定大小的方块，每块折算成固定 token，再外加一个基础量。我记得某个时期常见口径的经验公式大概是“基础 85 token，每 512×512 的块 170 token”。这个公式我只用来做预算估算，具体数值请以你实际用到的接口文档为准，我这里给的是一个计算框架。

拿一张 1600×1200 的截图举例：横向ceil(1600/512)=4块，纵向ceil(1200/512)=3块，共 12 块。按下限计约170 × 12 + 85 ≈ 2125输入 token。一张 A4 扫描件按 300DPI 出来是 2480×3508，尺寸过大会被模型等比缩小到长边约 2048，折算下来大约是4 × 4 = 16块，约 2800 token。这意味着你的预处理把图放大到多少，直接决定了成本。我最初无脑按 3000px 短边放大，结果一张图成本翻了三倍，识别率只提升了一个百分点，纯属浪费。

实际的成本感是这样的：一张普通截图量级的表格，单次抽取的输入 token 在两千上下，输出几百；一张大表切成 4 块，总计约一万输入。按常见定价换算下来，一份中等复杂度的表格单页成本在几分钱量级，比人工录入的时薪便宜两个数量级。但要注意，如果界面上没做好缓存，用户改个错别字也触发一次调用，成本会成倍膨胀——这就是 4.5 节那个 hash key 的实际价值。

5.2 准确率怎么量化评估

“准确率 90%”这种说法在我这里是不许出现的，因为没有定义。我的口径是单元格级完全匹配率：拿 200 张真实表格做金标准，人工逐格录入，然后逐格对比。匹配要求字符串完全一致，数字要求数值相等（1.10和1.1算匹配，因为数值相同），日期归一化后比较。

关键在于要分类统计，不能只看总和。我的经验是文本类单元格准确率普遍高，因为容错大；数字类和日期类才是雷区。第一版跑出来总体 71%，拆开看文本 89%、数字 62%，问题全出在数字上：千分位逗号、括号负数、单位混排。针对性地改提示词里数字的转换规则、加上parse_number的严格校验之后，数字类升到 93%，总体到 92%。

后来我又加了一层“数字二次校验”：把识别出的数字列和原图裁出的对应区域做一次独立复核，只对数字列发起一次小范围调用，问“这个格子里的数字是不是 1280.50”。这一步让我把数字类准确率推到 96% 以上，代价是成本增加约 20%。值不值取决于你的数据敏感度，财务类数据我认为值，内部统计类没必要。

我还做了个“置信度分层”的做法，比单纯追准确率实用：把结果按 warnings 数量和数字复核是否通过分成三档——绿（直接可用）、黄（需抽检）、红（必须人工核）。实测下来黄档占比约 15%，用户只需要重点看这 15%，效率比逐行核对高三倍以上。

5.3 批量场景的限流与重试

单张跑和批量跑是两个世界。批量最容易出的问题是限流和超时，而且往往在你最不希望的时候出现——比如月底一百多份报表一起传。我的处理是三层：

第一层是客户端并发控制，用concurrent.futures开 4 个 worker，不要贪多。我试过 16 并发，结果一半请求返回限流错误，重试反而更慢。4 个是我在常见配额下的稳定值。

第二层是指数退避重试，只对可重试的错误（限流、超时、5xx）重试，最多 3 次，间隔 2s、4s、8s 加随机抖动。对“内容不合规”“JSON 解析失败”这类错误不重试，重试也没用，直接标记失败让用户重传。

第三层是断点续跑。批量任务我落一张 SQLite 表记录每张图的状态（待处理/成功/失败/原因），中断之后从断点继续，不用从头再来。这个功能是我某次跑到第 87 张断了之后痛定思痛加的，当时没有它，重跑了一百多张。

提示：批量场景一定要给用户一个“只处理前 5 张看看效果”的按钮。我见过太多人一口气传两百张，跑到一半发现提示词有问题，全部白跑，时间和钱都打水漂。

6. 常见问题与排查技巧实录

这一节是我四版下来攒的问题库，按出现频率排。每一条都有具体的现场描述，你可以对照自己的现象找。

6.1 表格错位与列数漂移

这是最典型、也最让人抓狂的问题：导出的表看起来很正常，但某几行整体右移了一列，导致金额跑到了备注列里。根因几乎都是某一行里出现了列分隔符的误判，比如文本里本身带了一个|，或者某个单元格的内容被模型拆成了两格。

排查思路是三段定位法：先看原图那一行有没有异常的竖线或空格；再看模型返回的rows里这一行的长度是不是和表头一致；最后看merged里有没有把这一行卷进去。我在probe_structure里加的那句列数自检就是专门抓这个的，任何长度不一致直接抛错，绝不放进 DataFrame。宁可让用户重试一次，也不能让错位数据静默流到下游。

根治的办法是提示词里明确“一个物理单元格对应一个数组元素，单元格内部的换行和竖线属于内容，不构成新列”，并且在预处理阶段把图里的细线加粗一点（形态学闭运算），让分隔线更明确。

6.2 数字、日期、金额的格式陷阱

这一类问题最隐蔽，因为它不报错。我遇到过几种：1,280.00被转成1280.00是对的，但1.280,00（欧洲写法）被转成1.28就完蛋了；2024/03/05和2024-3-5混用；3月5日被当成字符串；最坑的是1-2这种，既可能是日期区间也可能是编号。

我的处理原则是先按列统一格式，再逐格转换。程序先看整列的模式，如果 90% 以上符合金额特征，就按金额解析，剩下的 10% 标记为待确认，而不是逐格猜。日期同理，先统计整列的格式分布，取众数作为该列的解析规则，不符合的标黄。

另一个高频陷阱是前导零丢失。007会被模型输出成7，然后 Excel 里就永远是 7。解法是在导出时对“长度固定且全为数字”的列显式设成文本格式，而不是靠事后补救。

6.3 模型“编造”内容的识别与拦截

视觉模型有个我最初没预料到的行为：它会把看不清的地方“补”成合理的内容。一张模糊的金额128?.50，它可能直接给你1280.50，而且答得毫不犹豫。这在财务场景是致命的。

我用了三个办法叠加。第一是提示词里强烈约束“模糊处按最接近字形转写并写入 warnings，禁止推断”，有改善但不能根除。第二是低置信度区域二次调用，把 warnings 里的单元格坐标裁出来放大单独问一次，两次结果不一致就标红。第三是跨字段一致性检查，比如表里有“数量”和“单价”和“金额”三列，就抽查几行看数量 × 单价是否接近金额，偏差超过 1% 就整行标黄。这个检查用代码做，成本为零，抓错率却很高。

注意：不要指望用“让模型自查一遍”来兜底。我试过让它复核自己的输出，它绝大部分情况会坚持原答案，甚至给出理由来“圆”这个错误。自查对逻辑错误有效，对感知错误基本无效。

6.4 导出后样式丢失与中文乱码

导出这块的坑比较琐碎但很影响体验。最常见的三个：订单号变科学计数法（前面讲过，用文本格式解决）、长文本被截断显示（设列宽或开自动换行）、中文导出 CSV 用 Excel 打开乱码（用utf-8-sig，带 BOM）。还有一个不太被提到的是首行冻结，表格一长，用户滚下去就看不到表头，加一行ws.freeze_panes(1, 0)体验立刻不一样，成本是一行代码。

ws.freeze_panes(1, 0) # 冻结表头 ws.autofilter(0, 0, len(df), len(df.columns) - 1) # 开筛选

这两行我建议所有导表格的场景都加上，属于投入产出比极高的细节。

6.5 问题速查表

6.6 我个人的几条经验

第一条，别追求一步到位的高准确率，先追求“错得可见”。我第三版的准确率其实和第四版差不太多，但第四版有 warnings、有标黄、有原图对照，用户敢用了。可信度比准确率更能决定一个工具能不能落地。

第二条，提示词版本要进 Git。我改提示词改到第二十版的时候，发现某一版效果反而更好，但已经记不清当时改了什么。后来每次改提示词都写在一个单独的.txt里提交，配一句改了什么、为什么改，回滚的时候非常省事。

第三条，样本库比模型重要。我攒了一个 200 张的真实样本库，覆盖截图、扫描、手机拍照、三线表、无框表、超宽表六种类型。每次改提示词或者换模型，跑一遍样本库，看分类准确率的变化，比凭感觉判断靠谱得多。这个库建起来花了大概两天，但后面每一次迭代都在受益。

第四条，给用户留一个“我改完了”的确认动作。不要自动把识别结果当成最终数据往下游传。我在界面上强制用户点一次“确认并导出”，并记录是谁、什么时候、改了几格。这个小小的摩擦，挡掉了很多“没人核对就直接用”的事故。

最后分享一个我最近才加的小功能：导出的时候顺带生成一份“变更记录”sheet，列出用户手动修改过的单元格（原值、新值、位置）。这东西对复盘极有价值——如果某一类单元格总是被人工改，说明那一类就是我下一版要重点优化的地方。等于说，用户的每一次修改，都在帮你标注训练数据。这个思路我觉得比任何自动评估都更贴近真实场景，也是在用了一段时间之后才慢慢体会到的。