AI补货助手：用TabPFN与Gemma让手工小店每周自动补货

一家靠手工记账的小店，最怕两件事：该卖的货没货，不该囤的货堆满货架。开发者用两个开源模型做了一个每周补货助手 tidy-predict——读入杂乱的订单导出文件，输出清洗后的数据、下周每个常售商品的预测销量区间，以及一份用大白话写的补货建议。

这个项目参加的是 Hacktoberfest 开源 AI 挑战赛第二周「副业」赛道，技术栈为 PriorLabs-TabPFN。值得一提的是，它不是一个跑在云端的 SaaS，而是一套完全跑在笔记本 CPU 上的本地工具——小店销售数据从不出本机。

它解决什么：把「手工数库存」变成「每周一张表」

项目缘起很朴素：作者认识一位开店的人，库存多少、哪个快卖完、顾客在问什么，全靠手工记录。手工一多，错误就来了——好卖的货顾客来了没有，难卖的货占满货架。

作者拿不到这家店的数据，于是用一份公开的英国礼品店订单导出数据（UCI Online Retail II，100 多万条真实匿名订单行，CC BY 4.0）替代，并故意把列名改成「Bill No、Item Code、Maal、Kitne、Tarikh、Rate」这种非常规写法来测试鲁棒性。

tidy-predict 的流程是固定四步：清洗 → 用 TabPFN-2 预测 → 用 Gemma 4 E2B 写补货建议 → 逐个核对数字，失败重试一次或退回模板。两个模型都在本地 CPU 运行，订单不经过任何 AI API。

预测的核心：TabPFN-2 给出区间，而非单点

预测环节只用一个 TabPFN-2 回归器覆盖店里 20 个常售商品。特征全部来自历史周数据：近几周销量、去年同周、几个均值、以及一年中的第几周。TabPFN 是表格基础模型，一次前向就能从训练行给出完整分布，由此得到中位数预测以及 P10–P90 区间——也就是真实销量有八成概率落在其中的范围。

作者特意选了 TabPFN-2 而非最新的 TabPFN-3.5。原因在许可证：新版对研究和测试免费，但商用需要付费授权；而 TabPFN-2 的权重在 Apache 2.0 下开放（带署名条款「Built with PriorLabs-TabPFN」）。对零预算的副业项目来说，许可证就是商业模式本身。

TabPFN（Tabular Prior-data Fitted Network）是一种基于Transformer的表格基础模型，其核心思想是在大量合成表格任务上预训练，使模型学会「从训练行到预测分布」的映射。使用时无需梯度训练或超参数调优，只需一次前向传播即可对测试样本输出完整的预测分布。这种「先验拟合」特性使其在小样本表格回归任务上表现突出，且推理速度远快于传统集成模型。TabPFN-2是该系列的一个版本，支持回归与分类，并开放了预训练权重。

一个诚实的失败案例：11 月 28 日那一周

作者主动把预测失误放在前面讲，因为这是最有用的部分。模型预测兔子夜灯会下降 58% 至 1,249 件，实际卖了 4,452 件——是该文件中表现第二好的一周，远超「忙碌周上限」2,592 件。小爆米花桶也超出了区间（实际 3,271 件，上限 2,596 件）。

整体看，20 个商品中有 17 个落在预测区间内，但中位数合计 13,386 件，实际卖出 19,101 件。11 月 28 日那一周是圣诞旺季的起点，打破了常规模式。作者的结论很克制：区间对大多数商品有效，中位数偏低，有一个商品会断货——店主应把「忙碌周上限」当作备货天花板来参考，而不是一个承诺。

P10–P90区间是分位数预测的常用表达：P10表示真实值有10%概率低于该值，P90表示有90%概率低于该值，因此真实值落在两者之间的概率约为80%。在补货场景中，P90（或「忙碌周上限」）常被用作备货天花板，以降低缺货风险；P10则可用于识别低销商品，避免过度囤货。区间宽度反映了预测的不确定性，越窄说明模型对该商品越有把握。

表头识别与数据清洗：不静默删除任何一行

真实小店的导出文件不会有整齐的英文表头。第一步先用规则找列，规则放不下的才交给本地 Gemma 4 E2B，并用 JSON schema 约束它只能从真实表头名中选择。

作者在开发中踩了坑：最初 Gemma 版本 12 组表头对了 8 组，但在可选列上做了 4 次错误猜测（比如把批号当成商品编码）。错误猜测比不猜更糟，于是改为只让 Gemma 填补日期、数量、商品三个必需缺口，结果 12/12 全对、0 错——不过同一批数据也用于调试，作者提醒 12/12 应视为乐观估计。

清洗环节同样保守：演示文件中 1,067,371 行里有 70,254 行被单独挑出，包括 34,335 条完全重复（其中 22,523 条因两个 Excel 表在 2010 年 12 月 1–9 日重叠）、5,869 条邮费与手续费、21,302 条退货、6,180 条被退货抵消的销售、2,568 条免费或负价行。剩下的 997,117 行作为销售数据。每一行被排除的数据都带原因记录在 issues.csv 中，不做静默删除。

JSON Schema是一种描述JSON数据结构的规范，可定义字段名、类型、必填项和取值范围。在调用大语言模型时，将输出约束为符合特定Schema的JSON，能有效减少模型自由发挥导致的格式错误或字段幻觉。本项目用JSON Schema限定Gemma只能从真实表头名中选择映射，相当于给模型一个封闭的候选集，从而把「猜测」变为「选择」，显著提升表头识别的可靠性。

Gemma 写建议，代码核对数字

Gemma 只看到一张小的事实表，最大涨幅和最大跌幅由代码算好。核对器会把草稿里每个数字抽出来，只要有一个不在事实表中就拒绝，Gemma 可重试一次，之后退回模板。在 12 个测试周里，12 份初稿全部通过，每份约 36 秒。

作者也承认局限：核对器无法判断数字是否配对了正确的商品，所以建议由人通读。早期提示词曾把字段名泄漏进正文（如「change vs 4wk avg pct of -53」），核对器放行了，但人一眼就能看出问题。

测试结果：与调参规则打成平手，但无需拟合

作者在 7 个验证周（2011 年 7–8 月）上选定配置，然后在最后 12 个完整周（240 个商品-周）上跑了一次测试，对手是「4 周均值乘以调参系数 k」这个强基线。

240 个测试商品-周	TabPFN-2（无店铺系数）	4 周均值×k（k 在 7–8 月拟合）
真实销量落在 P10–P90 区间内（目标 80%）	80.0%	85.4%
区间宽度/销量（越窄越好）	1.50 倍	1.78 倍
按忙碌周上限备货：剩余件数	16.0 万	17.8 万
按忙碌周上限备货：短缺件数	1.95 万	1.30 万
中位数：平均误差占销量比例	0.502	0.486

TabPFN-2 的区间恰好校准在 80% 目标上，且比调参规则窄 16%；按它备货剩余少 1.7 万件，但短缺多 6.5 千件；中位数预测打平，调参均值略优。差别在于：简单规则需要在两个月的历史数据上拟合系数，而每开一家新店就要重新拟合；TabPFN-2 不需要。

补充数据也说明这个平局有多接近：对不调参的裸 4 周均值，TabPFN-2 在 12 周中有 7 周误差更小，前 11 周领先（0.502 对 0.514），是 11 月 28 日的旺季周决定了最终平局。TabPFN-2 也优于同特征训练的梯度提升模型（0.527）和两个朴素规则（上周 0.631、去年同周 0.884）。

它做不到什么

作者列出的局限清单值得任何想做类似工具的人细读：只预测常售商品（过去 26 周中至少 20 周有销售），新品和偶售商品没有数字；只做一周预测，节假日和促销只能通过「一年中的第几周」和去年同周间接建模，11 月 28 日的失误就是证明；「非商品」规则会把不含数字的编码当成邮费，演示数据中误伤了 50 行类似 DCGSSGIRL 的真实商品；目前没有任何店铺实际使用过这个工具。

定价计划是每周 199 卢比，首月免费——作者明确说明这只是计划，尚无人付费、没有收入。成本侧倒是实打实：用 2019 年的笔记本 CPU 在命令行跑完 100 万行演示文件耗时 52 秒，不消耗任何 API token。

开源与本地化：许可证即商业模式

除了 TabPFN-2 和 Gemma 4 都是 Apache 2.0 之外，作者还验证了离线可行性：完整预测流程在一个无网络的 Linux 网络命名空间中跑通（eval/results/offline_check.log）。没有 API key，没有按次计费，模型可以一行替换。Gemma 的输出被强制约束进 JSON schema，为 CPU 速度关掉了「思考」模式。

项目 MIT 许可、28 个测试，每个数字背后都有脚本。仓库地址：github.com/xexpertai/tidy-predict。需要 Python 3.10+、约 3.5 GB 磁盘和 3 GB 空闲内存，无需 GPU 和 API key。

对做小生意的人来说，这个项目最有价值的地方或许不是预测精度，而是它的姿态：把失败案例放在最前面，把局限写清楚，把成本算明白。一个诚实的工具，比一个漂亮的承诺更接近能用的工具。

Linux网络命名空间（network namespace）是内核提供的网络隔离机制，每个命名空间拥有独立的网络接口、路由表和防火墙规则。创建一个不配置任何外部接口的命名空间，即可模拟完全离线的环境。在该环境中运行预测流程，能严格验证工具不依赖任何网络调用或API密钥，从而证明销售数据确实不出本机。这比单纯声明「本地运行」更有说服力。