ContextGem：从文档中轻松提取 LLM 数据

包
质量
工具
文档
AI 代理
社区

ContextGem 是一个免费、开源的 LLM（大型语言模型）框架，它通过最少的代码量，使从文档中提取结构化数据和见解变得极其容易。

---

💎 为什么选择 ContextGem？

大多数流行的用于从文档中提取结构化数据的 LLM 框架都需要大量的样板代码才能提取基本信息。这显著增加了开发时间和复杂性。

ContextGem 通过提供一个灵活、直观的框架来解决这一挑战，能够以最小的努力从文档中提取结构化数据和见解。复杂且最耗时的部分由强大的抽象处理，消除了样板代码并减少了开发开销。

📖 在文档中阅读更多关于项目 动机 的信息。

⭐ 核心功能

内置抽象	ContextGem	其他 LLM 框架*
自动化动态提示词	🟢	◯
自动化数据建模和验证器	🟢	◯
精确的细粒度引用映射（段落与句子）	🟢	◯
理由说明（支撑提取的推理）	🟢	◯
神经分割（使用 wtpsplit 的 SaT 模型）	🟢	◯
多语言支持（无需提示词的输入/输出）	🟢	◯
单一统一的提取管道（声明式、可复用、完全序列化）	🟢	🟡
具有特定角色任务的分组 LLM	🟢	🟡
嵌套上下文提取	🟢	🟡
统一、完全序列化的结果存储模型（文档）	🟢	🟡
带示例的提取任务校准	🟢	🟡
内置并发 I/O 处理	🟢	🟡
自动化用量与成本追踪	🟢	🟡
降级与重试逻辑	🟢	🟢
多个 LLM 提供商	🟢	🟢

🟢 - 完全支持 - 无需额外设置
🟡 - 部分支持 - 需要额外设置
◯ - 不支持 - 需要自定义逻辑

* 请参阅 描述 了解 ContextGem 抽象，以及使用 ContextGem 与其他流行开源 LLM 框架的具体实现示例的 比较。

💡 你能构建什么

通过最少的代码，你可以：

• 从文档中提取结构化数据（文本、图像）
• 识别并分析文档内的关键方面（主题、话题、类别）(了解更多)
• 从文档中提取特定概念（实体、事实、结论、评估）(了解更多)
• 通过简单直观的 API 构建复杂的提取工作流
• 创建多级提取管道（包含概念的方面、分层方面）

📦 安装

使用 uv（推荐）：

uv add contextgem

或使用 pip：

pip install -U contextgem

🚀 快速开始

以下示例演示了如何使用 ContextGem 从法律文档中提取异常——这是一个需要上下文理解的复杂概念。与可能忽略细微不一致的传统 RAG（检索增强生成）方法不同，ContextGem 分析整个文档上下文来识别不相关的内容，并提供完整的来源引用和理由说明。

# Quick Start Example - Extracting anomalies from a document, with source references and justifications

import os

from contextgem import Document, DocumentLLM, StringConcept


# Sample document text (shortened for brevity)
doc = Document(
    raw_text=(
        "Consultancy Agreement\n"
        "This agreement between Company A (Supplier) and Company B (Customer)...\n"
        "The term of the agreement is 1 year from the Effective Date...\n"
        "The Supplier shall provide consultancy services as described in Annex 2...\n"
        "The Customer shall pay the Supplier within 30 calendar days of receiving an invoice...\n"
        "The purple elephant danced gracefully on the moon while eating ice cream.\n"  # 💎 anomaly
        "Time-traveling dinosaurs will review all deliverables before acceptance.\n"  # 💎 another anomaly
        "This agreement is governed by the laws of Norway...\n"
    ),
)

# Attach a document-level concept
doc.concepts = [
    StringConcept(
        name="Anomalies",  # in longer contexts, this concept is hard to capture with RAG
        description="Anomalies in the document",
        add_references=True,
        reference_depth="sentences",
        add_justifications=True,
        justification_depth="brief",
        # see the docs for more configuration options
    )
    # add more concepts to the document, if needed
    # see the docs for available concepts: StringConcept, JsonObjectConcept, etc.
]
# Or use `doc.add_concepts([...])`

# Define an LLM for extracting information from the document
llm = DocumentLLM(
    model="openai/gpt-4o-mini",  # or another provider/LLM
    api_key=os.environ.get(
        "CONTEXTGEM_OPENAI_API_KEY"
    ),  # your API key for the LLM provider
    # see the docs for more configuration options
)

# Extract information from the document
doc = llm.extract_all(doc)  # or use async version `await llm.extract_all_async(doc)`

# Access extracted information in the document object
anomalies_concept = doc.concepts[0]

or doc.get_concept_by_name("Anomalies")

for item in anomalies_concept.extracted_items: print("Anomaly:") print(f" {item.value}") print("Justification:") print(f" {item.justification}") print("Reference paragraphs:") for p in item.reference_paragraphs: print(f" - {p.raw_text}") print("Reference sentences:") for s in item.reference_sentences: print(f" - {s.raw_text}") print()

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/shcherbak-ai/contextgem/blob/main/dev/notebooks/readme/quickstart_concept.ipynb)

---

🧠 工作原理

📝 步骤 1：定义提取上下文

📄 文档 (Document)
创建一个包含文本和/或视觉内容的 Document，代表您的文档（合同、发票、报告、简历等），LLM 从中提取信息（方面和/或概念）。了解更多

document = Document(raw_text="Non-Disclosure Agreement...")

🎯 步骤 2：定义要提取的内容

🔍 方面 (Aspects)	💡 概念 (Concepts)
定义 Aspects 以从文档中提取文本片段（章节、主题、主题）。您可以分层组织内容并结合 Concept 进行全面分析。了解更多	定义 Concept 以提取特定数据点，具备智能推理能力：实体、见解、结构化对象、分类、数值计算、日期、评级和评估。了解更多

# Extract document sections
aspect = Aspect(
    name="Term and termination",
    description="Clauses on contract term and termination",
)
# Extract specific data points
concept = BooleanConcept(
    name="NDA check",
    description="Is the contract an NDA?",
)
# Add these to the document instance for further extraction
document.add_aspects([aspect])
document.add_concepts([concept])

🔄 替代方案：配置 提取管道 (Extraction Pipeline)
创建可重用的预定义 Aspect 和 Concept 集合，以便在多个文档之间实现一致的提取。了解更多

🧠 步骤 3：运行 LLM 提取

🤖 大语言模型 (LLM)	🤖🤖 替代方案：LLM 组 (高级)
配置云或本地 LLM，用于从文档中提取方面和/或概念。DocumentLLM 支持回退模型和基于角色的任务路由以实现最佳性能。了解更多	配置一组具有独特角色的 LLM，用于复杂的提取工作流。您可以将不同的方面和/或概念路由到专门的 LLM（例如，简单提取与推理任务）。了解更多

llm = DocumentLLM(
    model="openai/gpt-5-mini",  # or another provider/LLM
    api_key="...",
)
document = llm.extract_all(document)
# print(document.aspects[0].extracted_items)
# print(document.concepts[0].extracted_items)

📖 了解更多关于 ContextGem 的 核心组件 及其在实际中的示例。

📚 使用示例

🌟 基本用法：

• 从文档提取方面
• 提取带有子方面的方面
• 从方面提取概念
• 从文档提取概念（文本）
• 从文档提取概念（视觉）
• 带工具调用的 LLM 聊天界面

🚀 高级用法：

• 提取包含概念的方面
• 从文档提取方面和概念
• 使用多 LLM 管道从多个文档提取数据

🔄 文档转换器

要为 LLM 分析创建 ContextGem 文档，您可以直接传递原始文本，或使用内置转换器处理各种文件格式。

📄 DOCX 转换器

ContextGem 提供了一个内置转换器，可以轻松地将 DOCX 文件转换为 LLM 就绪的数据。

• 全面提取文档元素：段落、标题、列表、表格、注释、脚注、文本框、页眉/页脚、链接、嵌入图像和内联格式
• 保留文档结构，并附带丰富元数据以改进 LLM 分析
• 内置转换器，直接处理 Word XML

🚀 v0.17.1 版本性能提升：DOCX 转换器现在转换速度快约 2 倍。

# Using ContextGem's DocxConverter

from contextgem import DocxConverter


converter = DocxConverter()

# Convert a DOCX file to an LLM-ready ContextGem Document
# from path
document = converter.convert("path/to/document.docx")
# or from file object
with open("path/to/document.docx", "rb") as docx_file_object:
    document = converter.convert(docx_file_object)

# Perform data extraction on the resulting Document object
# document.add_aspects(...)
# document.add_concepts(...)
# llm.extract_all(document)

# You can also use DocxConverter instance as a standalone text extractor
docx_text = converter.convert_to_text_format(
    "path/to/document.docx",
    output_format="markdown",  # or "raw"
)

📖 在文档中了解更多关于 DOCX 转换器功能 的信息。

🎯 聚焦文档分析

ContextGem 利用 LLM（大语言模型）的长上下文窗口，从单个文档中提供卓越的提取精度。与经常 难以处理复杂概念和细微见解 的 RAG（检索增强生成）方法不同，ContextGem 利用了不断扩展的上下文容量、进化的 LLM 能力和下降的成本。这种聚焦方法实现了从完整文档中直接提取信息，消除了检索不一致性，同时优化了深入的单文档分析。虽然这为单个文档提供了更高的准确性，但 ContextGem 目前尚不支持跨文档查询或语料库范围的检索——对于这些用例，现代 RAG 框架（例如 LlamaIndex, Haystack）仍然更为合适。

📖 在文档中阅读更多关于 ContextGem 如何工作 的内容。

🤖 支持的 LLM

ContextGem 通过 LiteLLM 集成支持基于云和本地的 LLM：

• 云端 LLM：OpenAI, Anthropic, Google, Azure OpenAI, xAI 等
• 本地 LLM：使用 Ollama, LM Studio 等提供商在本地运行模型
• 模型架构：适用于具备推理/CoT（思维链）能力（如 gpt-5）和非推理模型（如 gpt-4.1）
• 简单 API：所有 LLM 的统一接口，轻松切换提供商

💡 模型选择说明： 为了可靠的结构化提取，我们建议使用性能相当于或超过 gpt-4o-mini 的模型。较小的模型（如 8B 参数模型）可能在 ContextGem 的详细提取指令上遇到困难。如果您在使用较小模型时遇到问题，请参阅我们的 故障排除指南 以获取潜在解决方案。

📖 在文档中了解更多关于 支持的 LLM 提供商和模型，如何 配置 LLM，以及 LLM 提取方法 的信息。

⚡ 优化

ContextGem 文档提供了关于优化策略的指导，以最大化性能、最小化成本并提高提取精度：

• 针对精度的优化
• 针对速度的优化
• 针对成本的优化
• 处理长文档
• 选择合适的 LLM
• 小型模型的故障排除

💾 序列化结果

ContextGem 允许您使用内置的 serialization（序列化）方法保存和加载 Document 对象、pipeline（管道）和 LLM 配置：

• 保存已处理的文档以避免重复昂贵的 LLM 调用
• 在不同系统之间传输提取结果
• 持久化 pipeline 和 LLM 配置以便以后重用

📖 在文档中了解更多关于 serialization 选项 的信息。

📚 文档

📖 完整文档： contextgem.dev

⚠️ 官方文档通知： https://contextgem.dev/ 是 ContextGem 文档的唯一官方来源。请注意可能存在包含过时或不正确信息的未经授权副本或镜像。

🤖 AI 驱动的代码探索： DeepWiki 为代码库提供可视化架构映射和自然语言问答。

📈 变更历史： 请查看 CHANGELOG 以了解版本历史、改进和错误修复。

💬 社区

🐛 发现错误或有任何功能请求？ 在 GitHub 上 提交问题。

💭 需要帮助或想要讨论？ 在 GitHub Discussions 中开启一个线程。

🤝 贡献

我们欢迎社区的贡献——无论是修复拼写错误还是开发完全新功能！

📋 开始： 查看我们的 贡献者指南。

🤖 对 AI 智能体友好

此仓库遵循现代开发实践，并提供对 AI 编码助手的一流支持：

• AGENTS.md - 针对使用此代码库的 AI 助手的指南 (agents.md 标准)
• CLAUDE.md - Claude Code 的配置

这些文件为 AI 助手提供特定于项目的上下文、编码约定、架构模式和贡献工作流程——从而实现更准确和一致的 AI 辅助开发。

🔐 安全

本项目使用多种安全工具自动扫描安全漏洞：

• CodeQL - GitHub 的语义代码分析引擎，用于漏洞检测
• Bandit - Python 安全 linter（代码检查器），用于常见安全问题
• Snyk - 依赖项漏洞监控（按需使用）

🛡️ 安全策略： 详细信息请参见 SECURITY 文件。

💖 致谢

ContextGem 依赖于这些优秀的开源包：

• aiolimiter: 用于异步操作的强大速率限制
• colorlog: Python 日志模块的彩色格式化器
• docstring-parser: 用于自动生成工具架构的文档字符串解析
• fastjsonschema: 超快速的 JSON 架构验证
• genai-prices: LLM（大型语言模型）定价数据和实用工具（由 Pydantic 提供），用于自动估算成本
• Jinja2: 用于提示词渲染的快速、表达力强且可扩展的模板引擎
• litellm: 多个 LLM 提供商的统一接口，支持无缝切换提供商
• lxml: 用于解析 DOCX 文档结构的高性能 XML 处理库
• pillow: 用于本地模型图像处理的图像处理库
• pydantic: 数据验证的黄金标准
• python-ulid: 用于唯一对象标识的高效 ULID 生成
• tenacity: Python 通用重试库
• typing-extensions: 最新类型特性的向后移植版本，用于增强类型注解
• wtpsplit-lite: wtpsplit 的轻量级版本，使用 wtpsplit 的 SaT 模型进行最先进的段落/句子分割

🌱 支持项目

ContextGem 才刚刚开始，您的支持对我们意义重大！

⭐ 如果您觉得 ContextGem 有用，请给项目加星
📢 分享给可能受益的其他人
🔧 通过反馈、问题报告或代码改进来贡献

您的参与是这个项目成长的关键！

📄 许可证与联系方式

许可证： Apache 2.0 许可证 - 详见 LICENSE 和 NOTICE 文件。

版权： © 2025 Shcherbak AI AS — 企业人工智能工程。我们构建改变企业运营方式的 AI 智能体。

联系： 如有疑问或合作想法，请联系 LinkedIn 或 X。

在挪威奥斯陆用心打造。

📦 Shcherbak AI 更多产品

包名	描述
tethered	Python 运行时网络出口控制。一次函数调用即可阻止所有未经授权的出站连接——零依赖，无需更改基础设施。适用于供应链防御、AI 智能体护栏和测试隔离。

ContextGem 快速上手指南

ContextGem 是一个免费的开源 LLM 框架，旨在通过极简代码从文档中提取结构化数据和洞察。它提供了强大的抽象能力，消除了繁琐的样板代码，支持多语言、神经分割及自动引用映射等功能。

环境准备

• Python 版本: 3.10 及以上 (支持 3.10 | 3.11 | 3.12 | 3.13 | 3.14)
• 依赖项: 无额外系统级依赖，需配置 LLM 提供商的 API Key（如 OpenAI）
• 网络: 需要访问 PyPI 及 LLM 服务接口

安装步骤

推荐使用 uv 进行快速安装：

uv add contextgem

或者使用 pip 安装：

pip install -U contextgem

基本使用

以下示例演示如何从文档中提取异常信息（Anomalies），包含源引用和理由说明。

# Quick Start Example - Extracting anomalies from a document, with source references and justifications

import os

from contextgem import Document, DocumentLLM, StringConcept


# Sample document text (shortened for brevity)
doc = Document(
    raw_text=(
        "Consultancy Agreement\n"
        "This agreement between Company A (Supplier) and Company B (Customer)...\n"
        "The term of the agreement is 1 year from the Effective Date...\n"
        "The Supplier shall provide consultancy services as described in Annex 2...\n"
        "The Customer shall pay the Supplier within 30 calendar days of receiving an invoice...\n"
        "The purple elephant danced gracefully on the moon while eating ice cream.\n"  # 💎 anomaly
        "Time-traveling dinosaurs will review all deliverables before acceptance.\n"  # 💎 another anomaly
        "This agreement is governed by the laws of Norway...\n"
    ),
)

# Attach a document-level concept
doc.concepts = [
    StringConcept(
        name="Anomalies",  # in longer contexts, this concept is hard to capture with RAG
        description="Anomalies in the document",
        add_references=True,
        reference_depth="sentences",
        add_justifications=True,
        justification_depth="brief",
        # see the docs for more configuration options
    )
    # add more concepts to the document, if needed
    # see the docs for available concepts: StringConcept, JsonObjectConcept, etc.
]
# Or use `doc.add_concepts([...])`

# Define an LLM for extracting information from the document
llm = DocumentLLM(
    model="openai/gpt-4o-mini",  # or another provider/LLM
    api_key=os.environ.get(
        "CONTEXTGEM_OPENAI_API_KEY"
    ),  # your API key for the LLM provider
    # see the docs for more configuration options
)

# Extract information from the document
doc = llm.extract_all(doc)  # or use async version `await llm.extract_all_async(doc)`

# Access extracted information in the document object
anomalies_concept = doc.concepts[0]