10 月 26 日晚上,一个做合同审核的朋友发来链接问:ContextGem 1.0 能不能替掉他们那套正则?我打开 Product Hunt 页面,发布日期 2026-10-26,版本号写着 1.0。顺手去 PyPI 拉元数据,最新版已经是 1.4.1,而 1.0.0 是 10 月 16 日上线的。
这个错位说明一件事:这类更新很快的小众框架,二手信息从写出来那天就开始过期。所以我没直接回答,而是把三条一手数据对了一遍。
数据从哪来
三个来源都不用密钥:PyPI 的 JSON 接口给版本列表、每版发布时间、requires_python、全部依赖约束;GitHub 的仓库接口给星数、协议、主语言、最近推送;CHANGELOG 给每版改了什么、哪些是破坏性变更。三份合起来,够判断一个库「现在是什么状态」。
再用两个二手来源对照:Product Hunt 产品页,和两篇 10 月的中英文介绍文——「搜到就用」的典型入口。
怎么处理的
没写代码,就是把三份 JSON 的字段拉平按时间排序,再把二手文逐条对回一手数据。四个字段最关键:版本次数、版本间隔、requires_python、依赖钉的版本号。
顺手记个数:PyPI 上累计 58 个 release,最早是 2025 年 7 月的 0.9.0。一年走 58 个版本,说明它本来就快,不是 1.0 之后才提速。
发现一:十天七个版本,「发布日」不是「上线日」
把 1.0 之后的版本按天排开:1.0.0(10-16)、1.1.0(10-16,同一天)、1.2.0(10-21)、1.2.1(10-22)、1.3.0(10-25)、1.4.0(10-26)、1.4.1(10-26)。十一天七个版本,其中两天各发两个。
对照二手来源:PH 标 10-26,一家聚合站写「10 月 19 日发布」,而 PyPI 上 1.0.0 的 upload_time 是 10 月 16 日 01:37。三个日期都不算错——PH 是上架日、聚合站是转发日、PyPI 是真实可装时刻。
但如果你按 PH 的日期判断「这库刚出、还很生」,就会漏掉「已经迭代七轮、填了一批坑」这个事实。这类项目看 PyPI 的 upload_time,别看发布会日期:前者是代码能装的时间,后者是营销能看的时间。
发现二:Python 3.10 被砍了,但二手文没改口
这条最该提醒。PyPI 上 1.4.1 的 requires_python 是 <3.15,>=3.11——3.10 装不上,3.15 还不行。
而两篇 10 月的介绍文分别写着「supports Python 3.10 through 3.14」和「requires Python 3.10 or later」,后者连上界都没有。按二手文在 3.10 环境里 pip install,报的是找不到匹配版本,不是语法错误,这种错最难猜,容易被当成网络问题。
README 里其实写了:「Upgrading from 0.x? … Python 3.10 is no longer supported.」这句藏在迁移指南的提示框里,很容易跳过。判断它不需要读代码,看 PyPI 那个字段,五秒钟。
发现三:依赖钉得很死,这是「描述即抽取」的代价
1.4.1 的依赖里,litellm==1.105.2、openai==2.54.0、genai-prices==0.1.13 三个精确钉死,pydantic 要 >=2.10.6,<3,pillow 要 >=11.3,<14,onnxruntime 只在 Python 3.14 以上才装。
原因写在 CHANGELOG:1.2.1 是安全修复,某个根证书被攻破,而 litellm 校验厂商连接用的正是它,于是把 certifi 提到 2026.10.19 以上;同版把 Pillow 上限放到 14,因为 12.3.0 有 39 个安全公告、4 个严重。
对装在内网的项目,这意味着两件事:环境里已有的 openai 或 litellm 只要版本不匹配,pip 会直接换掉,可能影响同环境其他服务;升级 ContextGem 等于升级一批传递依赖,得单独给它一个虚拟环境。
框架形状也得说清:它走「整篇文档喂进长上下文」,不做切片检索;你声明 Aspect(章节/主题)和 Concept(要抽的字段),它生成提示词、用 Pydantic 校验、把结果映射回原句。1.0 新增的 decision model 只处理闭合问题——是/否、选标签、打等级,返回各选项概率;开放问题仍走 LLM。
这和站内 发票 OCR 字段提取那篇 是同一件事的两个阶段:那篇把像素变文字,这篇把文字变结构化字段。两段都做完,才算一条能落库的流水线。
这些结论怎么用
字段固定、格式稳定、量很大,别换。正则零成本、毫秒级、可复现;换 LLM 抽取每条要付 token,还得处理抽错抽漏和「格式对但内容错」。这种错不报错,就像站内 日历合并那篇 说的:能打开但内容全乱,是最坏的一种失败。
版式每份都不一样、字段带语义(「付款条件」「异常条款」),这才是它的场景。价值不在抽得多准,在每条结果都能指回原文哪一句——审核场景里,人要复核的是依据,不是一个字段值。
要跑在完全离线、没 GPU 的机器上,先别急。它自身不含模型,LLM 走 LiteLLM 转出去,本地模型能接,但 README 明说小模型可能跟不上抽取指令,建议先抽样试。这条我信:指令细、输出要严格按 schema,小模型最容易在这步翻车。
一条实操建议:pip install contextgem 只装核心,读 PDF、DOCX 得再装 contextgem[docling],那个 extra 会拉进 Docling 一整套依赖。只想试文本抽取的,用 raw_text 构造 Document 就能跑。
最后是数据纪律。上面所有数字都来自 10 月 28 日当天的接口返回:2,023 星、186 fork、Apache-2.0、主语言 Python、最近推送 2026-10-27。这些每天在变,引用要写抓取日期——有篇介绍文写 1,854 星,那是更早的快照,不算错,但读者会误判活跃度。这跟站内 世行 GDP 那篇 里「缺失不插值、引用标 lastupdated」是同一条纪律。
常见问题
1.0 升级会不会把老代码搞坏?
会,而且是大改。一批「只跟 LLM 有关」的名字改成通用名:DocumentLLMGroup→DocumentModelGroup、llm_role→model_role、LLMPricing→ModelPricing、LLMAPIError→ModelAPIError,旧名字直接报错。更麻烦的是序列化数据,老版本存的配置不能直接反序列化,得按迁移指南改。
1.1 到 1.4 还要不要跟?
1.2.1 是安全修复,跟;1.3.0 加了 ModelRefusalError,把「拒答」和「格式不对」分开,生产值得跟;1.4.1 修同步方法不关连接的 socket 泄漏,循环里连调的必须跟。
本地模型能用吗?
能,通过 LiteLLM 接 Ollama 之类。但 README 说得很直白:测试用的是托管大模型,小模型可能跟不上抽取指令。1.3.0 还加了 supports_vision、supports_reasoning 等参数,用于 LiteLLM 自动探测出错时手动声明能力。
它会把文档内容发出去吗?
它自己不发,发的是你配置的模型。要注意 1.4.1 之前,校验失败的日志会把字段值写进 ERROR 日志;1.4.1 改成只说「哪个字段不合法」不带值。
跑一次多少钱?
内置按 token 计价,但价格表会变,且对不认识的模型只警告、成本记 0,别拿它的估算当账单。

