Shoebox：本地Gemma 3打造离线收据转表格工具

当收据堆成山，数据却不想上云

自由设计师、小店主、承包商，几乎每个小生意人都有一个“鞋盒”——里面塞满了皱巴巴的收据和发票。月底要把它们录入 Excel，往往要耗掉一个周末。市面上的自动化工具不少，但绝大多数要求你把发票照片上传到别人的服务器。这些票据上带着客户名称、税号和具体交易金额，对小本生意来说，交出去的不只是几张图，而是生意的底牌。

开发者 ayushkr23 在 Hacktoberfest 开源 AI 挑战赛第二周提交了一个名为 Shoebox 的项目，思路很直接：把收据照片拖进去，导出一张干净的表格，而所有数据始终留在你的笔记本电脑上。它用 Ollama 在本机运行 Gemma 3（4B）视觉模型，前端是纯 HTML/CSS/JS，后端用 FastAPI 和 Pydantic 做校验，全程不需要 API key，也不依赖任何云服务。

它到底能做什么

Shoebox 是一个本地 Web 应用，支持 JPG、PNG、WEBP、HEIC 格式的收据照片。每张图会被模型读取，提取出日期、商家、货币、小计、税额（GST）、总额、支付方式、分类、行项目以及模型自己的置信度评分，最后可以人工核对、编辑并导出为 CSV。

值得留意的是它对“不确定性”的处理方式。当置信度低于 0.6、字段缺失，或者行项目之和与总额偏差超过 2% 时，对应行会变成琥珀色。点击该行会打开一个侧边抽屉，左边是原始图片，右边是可编辑字段，方便对照修正。这种设计承认了 4B 小模型的局限，而不是假装一切都很准。

整个处理流程是逐张串行的，状态通过 Server-Sent Events 推送（排队、扫描中、完成或需要复核），结果写入 SQLite，刷新页面不会丢数据。图片在推理前会被 Pillow 缩放到长边 1600 像素，导出的 CSV 带 UTF-8 BOM，确保 ₹ 符号和日期在 Excel 里正常显示。

Server-Sent Events（SSE） 是一种基于 HTTP 的服务器推送技术。与 WebSocket 不同，SSE 是单向的：服务器可以持续向浏览器发送文本事件流，而浏览器无需轮询。在 Shoebox 中，每张收据的处理是串行进行的，状态从“排队”到“扫描中”，再到“完成”或“需要复核”，这些状态变化通过 SSE 实时推送到前端，用户无需手动刷新就能看到进度。SSE 的优点是实现简单、自动重连，且兼容普通 HTTP 基础设施，非常适合这种“服务器处理、客户端只读状态”的场景。

Pydantic 是 Python 生态中广泛使用的数据校验库。它允许开发者用 Python 类型注解定义数据模型（schema），并自动完成类型转换、必填校验和错误提示。Shoebox 用 Pydantic v2 校验每条模型返回的 JSON，确保日期、金额等字段格式正确；校验失败时触发修复重试，而不是让整批任务崩溃，这是保证流水线鲁棒性的关键一环。

为什么本地跑，而不是调用云 OCR

作者在文中算了一笔很诚实的账。云 OCR 并没有想象中贵——AWS Textract 的收据发票 API 大约每页 1 美分，按每月 300 张收据算，也就 3 美元左右。所以如果宣称 Shoebox 是为了省 API 费用，那就是过度营销。

真正的成本在别处。第一是时间：项目假设每张收据手动录入需要 90 秒（这是估算，不是实测），300 张就是每月 7.5 小时的机械劳动。第二是隐私：票据承载客户名、税号和营收数据，很多店主不愿意上传。第三是上手门槛：小店老板不会去配置 AWS 账户和 API 调用，但一个双击就能运行的本地应用是另一回事。

因为模型在本地，第 500 张收据的边际成本只是一点电费。作者的定价设想是一次性授权 49 美元（印度市场 3,999 卢比），包含一年模型与解析器更新。没有云服务器账单，所以收订阅费在他看来“不诚实”。

云 OCR 服务（如 AWS Textract、Google Document AI、Azure Form Recognizer）将图片上传到云端，由服务商的大规模模型完成文字识别和结构化提取。它们的优势是准确率高、支持表格和表单、无需本地算力，按页计费。Textract 的收据 API 约 1 美分/页，对小批量用户确实不贵。但云 OCR 的隐性成本在于：数据离开本地带来合规与隐私风险；需要配置云账号、API 密钥和权限；以及长期订阅的累积支出。Shoebox 选择本地推理，本质是用一次性硬件投入和稍低的准确率，换取数据不出门、零配置和零边际成本，适合对隐私敏感、票据量不大的小生意人。

技术栈：小模型、强校验、可替换

Shoebox 的架构选择围绕一个目标：用开源小模型把结构化提取做稳。

模型层：Gemma 3（4B）通过 Ollama 的 /api/chat 接口接收图片输入，并约束输出为 JSON。模型名由 MODEL_NAME 环境变量控制，未来有更强的 Gemma 发布，改一行即可切换。
校验层：每条模型回复都用 Pydantic v2 按 schema 验证。JSON 格式错误会触发一次修复提示重试，仍然失败的单据标记为“需要复核”，而不是让整批任务崩掉。
数学检查：行项目加总与总额不符时打上“Math mismatch”标记。
容错：损坏图片不会中断批处理，持久化层用 SQLite 保证编辑不丢失。

作者特别提到，开放模型带来的不只是省钱：他能直接检查原始多模态输出，针对 Gemma 3 的 JSON 行为定制两阶段修复循环，并在不跟黑盒 API 较劲的情况下加入 2% 数学偏差检查。这些都是闭源 API 难以做到的。

Ollama 是一个开源的本地大模型运行工具，提供统一的命令行和 HTTP API，支持一键拉取和运行 Gemma、Llama、Mistral 等模型。它自动处理模型量化、GPU/CPU 调度和内存管理，让开发者无需深入底层推理框架就能在笔记本上跑起视觉语言模型。Shoebox 通过 Ollama 的 /api/chat 接口传入图片和提示词，并约束输出为 JSON；模型名由环境变量控制，换模型只需改一行配置。Ollama 的存在大幅降低了“本地跑多模态模型”的工程门槛，是这类离线 AI 工具能快速落地的关键基础设施。

实测表现与诚实的边界

作者在 3 张合成收据上做了基准测试：一张干净的咖啡馆账单、一张带 3D 噪声和旋转的皱褶五金店收据、一张手写的自由职业出租车凭证。日期、商家、总额、税额四项准确率均为 100%，平均每张耗时 2.32 秒，硬件是 RTX 4050 笔记本 GPU（6GB 显存）、Ryzen 7 7840HS 和 16GB 内存。

但作者自己把这称为“冒烟测试，而非真实世界准确率声明”。在重褶皱、热敏墨水褪色的收据上，4B 视觉模型难以分辨手写数字到底是小费、折扣还是税额。测试中有一张倾斜照片，行项目合计 ₹430 加 ₹21.50 税，但手写总额被褶皱盖住，Gemma 3 漏掉了手写部分，导致行项目之和与总额不符。Shoebox 的数学检查抓住了超过 2% 的偏差，标出琥珀色警告，并引导用户在侧边抽屉里放大原图核对，而不是悄悄编造一个平衡的数字。

作者列出的限制也很直接：测试样本只有 4 张收据（其中 3 张用于基准评估），准确率是快照而非保证；4B 模型对潦草连笔、严重折痕和褪色热敏纸吃力；推理速度高度依赖硬件，RTX 4050 笔记本上 2.3 秒，纯 CPU 机器会明显更慢。

第一位真实用户和它的商业逻辑

作者把 Shoebox 拿给一位自由职业摄像师朋友试用，对方拖入了五张拍摄日的开销单据：器材租赁单、油费小票和揉皱的剧组午餐收据。这位用户反馈说，他以前经常因为手动录入太麻烦而自己吞掉一半剧组午餐和打车费用，而 Shoebox 第一次就从一个折叠过的账单上读出了商家和税额。

被问到是否愿意付费时，对方说愿意一次性付 2,500 卢比（约 30 美元），只为避开月度云订阅并保住客户账单隐私。他提出的第一个功能需求是加客户/项目标签，以便按拍摄项目归组收据，直接向客户报销。这个需求也点出了 Shoebox 后续最自然的产品方向。

开源 AI 工具的一种务实样本

Shoebox 并不是要证明本地小模型全面超越云服务。它的价值在于展示了一条被很多人忽略的路径：当任务足够垂直（收据转表格）、输出格式足够结构化（JSON + schema 校验）、并且有人工复核兜底（琥珀色标记 + 侧边抽屉）时，一个 4B 的开源视觉模型完全可以在本地跑出可用的结果。

项目以 MIT 协议开源，eval/test_suite.py 里的端到端集成测试覆盖 8 个阶段，包括静态端点、健康检查、串行 Ollama 提取、SQLite 内联编辑持久化、损坏图片容错和带 BOM 的 CSV 导出，作者称全部通过。安装只需 ollama pull gemma3:4b、pip install -r requirements.txt，然后运行 run.bat 或 run.sh。没有托管链接，因为按设计它就该跑在你自己的电脑上。

对于在意数据主权、又不想每月为几百张收据支付订阅费的小生意人来说，这种“鞋盒进、表格出、数据不出门”的工具，可能比一个功能更全但要求上传一切的 SaaS 更对胃口。