ContextGem：开源文档结构化数据提取框架

ContextGem 是由 Shcherbak AI AS 维护的开源 Python 框架，用于从文档中提取结构化数据和洞察。你用自然语言描述要找的信息，配置合适的模型，再由程序读取提取结果。它适合开发者搭建文档处理流程，尤其是需要明确字段类型、检查来源、重复处理同类材料的场景。

通俗易懂：ContextGem 是干什么用的？

可以把 ContextGem 理解成一套“教 AI 按要求读文件、把答案整理成数据”的开发工具。比如你有一批服务合同，想知道每份合同的付款期限、终止条件和月度费用。人工处理时，需要逐份阅读、查找，再把结果录入系统；使用 ContextGem 时，开发者先定义这些信息的含义与数据类型，再让模型按照同一套规则逐份提取。

它的价值不仅是生成一段摘要，还在于把答案变成程序能继续使用的日期、数字、标签或 JSON 对象，并按配置附上原文依据。这样，后续程序可以接收数据，审核人员也能回到对应段落核对。它提供的是 Python 框架与文档，不应把它理解为注册账号后直接上传文件的通用在线聊天网站。

从条款到字段：Aspects、Concepts 与来源回查

ContextGem 用两类抽象表达提取需求。Aspect 负责找出围绕某个主题的原文片段，例如“付款条款”或“终止合同的约定”；Concept 负责提取具体值或判断，例如付款天数、到期日期、是否允许无理由解约，或者费用明细对象。

Concept 可以作用于整份文档，也可以只在某个 Aspect 内分析。Aspects 还能继续划分子主题，帮助模型在合适的上下文中完成任务。支持的结果类型包括字符串、数值、日期、布尔值、分类标签、评分与 JSON 对象。例如提取服务费时，可以明确要求返回服务名称、月费和计费方式，而不是收到一段需要再次解析的文字。

对需要复核的 LLM 提取任务，可启用段落或句子引用，并根据需要附上解释。这便于定位答案来自哪里，但引用存在不代表答案一定正确。付款金额、日期和重要业务判断仍应与原文逐项比对；模型的格式校验也不能替代业务规则校验。

如何完成一次真实的文档信息抽取

建议先选择一份已知正确答案的小样本文档，跑通输入、提取和检查，再扩大处理规模。

1. 准备受支持的 Python 环境。当前安装文档要求 Python 3.11–3.14；Intel Mac 使用 Python 3.11–3.13，Alpine 等 musl 系统还存在依赖安装限制。
2. 执行 pip install -U contextgem。如果需要接入 PDF、Word 等文件，安装 pip install -U "contextgem[docling]"。
3. 纯文本可创建 Document(raw_text=...)。文件则先用 Docling 的 DocumentConverter().convert(file) 转换，再通过 Document.from_docling(result.document) 创建文档对象。
4. 为文档添加 Aspects 和 Concepts，写清需要查找的主题、字段含义、结果类型与引用要求。例如“每项服务的月度费用”应明确包含哪些字段。
5. 配置 DocumentLLM，填写所选模型标识与必要的 API 凭据或本地端点；密钥应通过环境变量管理。
6. 调用 doc = llm.extract_all(doc)，从返回文档的 get_concept_by_name(...).extracted_items 读取结果，同时查看可用的引用与页码。
7. 检查字段缺失、表格错位、含糊措辞等情况，再把验证过的提取规则复用于其他文件。

官方快速入门提供完整示例。Docling 接入文档说明了 PDF、DOCX、PPTX、XLSX 和 HTML 等输入如何转换，并保留文件结构与可用的来源页码。格式转换与语义提取是两个步骤；转换后的文本、表格和结构质量都会影响最终答案。

云端大模型、本地模型与决策模型怎么选？

通过 LiteLLM，ContextGem 可以连接官方文档支持的云端模型，以及 Ollama、LM Studio 等本地后端。LLM 适合需要生成开放式答案、提取多种字段或处理受支持图像输入的任务。小型本地模型可能无法稳定遵循复杂提取指令，应使用自己的典型文档验证效果。

决策模型适合封闭问题，例如“是否包含某项条款”“属于哪个标签”“落在哪个评分等级”，也可用于文本 Aspect 选择。它返回候选答案的概率，并允许配置决策阈值，而不是生成开放式文字。不要把它理解成拥有与 LLM 完全相同的图像、任意 JSON 或长文本生成能力。

模型组可以按角色分配 Aspects 和 Concepts，并配置回退模型。实际选择时，应同时观察结果质量、延迟与调用成本。概率可以帮助设计分流条件，阈值是否合适仍需通过样本验证，不能直接当成业务正确率。

复用提取流程，接入数据系统与 AI Agent

ExtractionPipeline 可以保存需要重复使用的主题与字段定义，减少对同类文件逐次编写规则。文档、流程和受支持的模型配置可序列化；通过 to_dict()、to_json() 等方法，结果能够交给后续应用保存或处理。写入数据库、生成表格、组织审核队列等动作仍需由你的应用完成，不应把结构化输出等同于自带完整业务系统。

官方 Agent 工作流说明展示了三种接入位置：在文档入库时提取元数据；作为 Agent 可调用的提取工具；在工作流分支处回答封闭问题。开发者也可以将 Python 工具通过 MCP 服务暴露给其他系统。输出语言配置可控制字符串答案和解释的语言，引用仍保留原文语言。

ContextGem 的重点是深入分析单份文档，可按段落分批处理。它本身不提供整个资料库的跨文档检索，因此需要“先从大量文件中找到相关材料”的场景，通常还要配合检索系统。长文档的分批策略、模型能力与调用次数也会影响质量、速度和费用。

免费开源的边界，以及文档数据会发往哪里

截至 2026 年 10 月 29 日，ContextGem 框架免费，并采用 Apache 2.0 许可证。商业使用需遵守许可证条件。调用云模型时，相关服务商可能另外计费；本地推理则需要自己的算力与运行环境。这里没有可适用于所有用户的统一 API 价格，也不能把框架免费理解为模型调用无限免费。

官方安全政策说明，ContextGem 不收集遥测，文档及生成的提示词通过运行在本地环境中的 LiteLLM 发往你配置的模型。选择云服务时，应查看该提供商的数据保留和处理条款；选择本地后端时，应检查端点与回退模型，避免意外转发到云端。

本地推理也不等于整个环境默认断网：依赖安装、首次下载分句模型、更新模型价格信息等仍可能访问公共资源。处理敏感材料前，应确认实际配置、网络行为与组织要求，不要仅凭“开源”或“支持本地模型”就推断全部数据处理条件。

常见问题

ContextGem 可以永久免费使用吗？

框架本身免费开源，但所选模型 API、服务器、硬件与部署维护可能产生独立费用。官方没有为所有模型提供统一的免费调用额度。

它能直接从 PDF 或 Word 中提取信息吗？

官方文件流程是先通过 Docling 转换，再用 Document.from_docling(result.document) 接入。提取前应检查转换后的内容，尤其是扫描件、复杂排版和表格，避免把输入转换错误带入字段结果。

可以接本地模型处理私有文档吗？

可以使用官方支持的 Ollama、LM Studio 等本地后端。需要自行配置并检查模型质量、云端回退与依赖下载行为；支持本地接入并不等于默认完成所有隐私配置。

它能代替 RAG 搜索整个文档库吗？

它主要分析单份文档，不自行完成资料库检索或跨文档查询。可以把它作为检索系统或 Agent 流程中的提取环节，让其他系统负责发现文件，再由 ContextGem 深入读取。

官方资源与开发者社区

• 安装要求与平台限制：核对 Python 版本、Intel Mac 与容器环境要求。
• 支持的云端与本地模型：查看后端选择与接入说明。
• GitHub Discussions：讨论接入方式与使用问题。
• 问题与功能反馈：提交可复现的错误或功能需求。
• 1.0 迁移指南：旧版应用升级前检查类名、参数与默认行为变化。