OpenContracts（演示站点）

一个开源平台，用于构建人类与 AI 智能体（AI agents）可协同工作的知识库。

后端 CI/CD
元信息

---

大多数知识都存在于文档中——合同、法规、研究论文、政策——这些内容决定了组织实际如何运作。但这些知识通常被“困住”了：锁在 PDF 中，散落在各个存储空间里，只有少数碰巧在正确时间读过相关内容的人才能完全理解。

OpenContracts 于 2019 年启动，基于一个简单的信念：知识需要精心整理（curated），而机器学习系统的效果取决于其底层数据的质量。该平台最初是为人类协作者（如律师、研究人员、分析师）设计的，让他们能够共同标注文档，并生成高质量的训练数据。

然而，这些协作者大多从未出现。平台推出得太早，问题过于小众，价值也难以被看见。

随后，大语言模型（Large Language Models, LLMs）出现了，世界突然迫切需要 OpenContracts 一直在构建的东西：结构化、已标注、版本可控的知识库，让 AI 能够真正进行推理。平台原本为之设计的协作者终于出现了——只不过他们其实是 AI 智能体。

如今，OpenContracts 是一个可自托管（self-hosted）的平台，团队可以基于自己的文档构建知识库，而 AI 智能体则与人类并肩工作，对知识进行搜索、分析和扩展。核心信念没有改变：最好的 AI 系统仍然依赖于精心整理的数据。不同的是，现在数据整理与 AI 推理发生在同一个地方。

AI 智能体 可配置的助手，可在你的知识库中进行搜索、标注和推理	MCP 服务器 将你的语料库（corpus）暴露给 Claude、Cursor 及任何兼容 MCP 的 AI 工具	多模态搜索 跨文档和标注的向量嵌入（vector embeddings）与全文搜索
协作 各级别支持带话题的讨论、@提及、投票和审核	数据提取 通过 LLM 驱动的查询，在数百份文档中进行结构化提取	格式保留 通过 PAWLS 实现 PDF 布局高保真还原，并提供精确的文本到坐标映射

---

有何不同

以人类知识为基础

这并非又一个“与你的 PDF 聊天”的工具。OpenContracts 将人类标注视为事实依据（ground truth）。团队可定义自定义标签体系，对文档进行精确选择（包括跨多页的片段），并建立概念之间的关联。AI 在此基础上工作——而非取而代之。

构建知识库，而非文件柜

文档被组织成语料库（corpuses）——具有文件夹层级、细粒度权限控制和完整历史记录的版本化集合。你可以派生（fork）一个公开语料库，在他人标注的基础上继续构建；可恢复任意历史版本；所有变更均被追踪。

这是知识领域的 git：你可以分支、构建、共享，且永不丢失工作成果。

与你所构建内容协同工作的 AI 智能体

可配置的 AI 智能体能够搜索你的文档、查询你的标注，并参与讨论——所有行为都基于你团队创建的结构化知识。它们不会凭空幻觉（hallucinate），而是基于真实、经过整理的数据进行推理。

在讨论线程中 @ 提及一个智能体，让它比较上百份合同中的条款，或让它揭示你团队上个季度标注出的模式。智能体的能力源自其底层知识库的质量。

在知识所在之处协作

在各个层级（全局、语料库级、文档级）提供论坛式的话题讨论。可 @ 提及文档、语料库和 AI 智能体。为最佳分析点赞，置顶关键发现。讨论就发生在原始材料旁边，而非另一个独立工具中。

共享知识产生复利效应

将语料库设为公开。其他人可派生它，优化标注，添加文档，并分享改进成果。排行榜和徽章表彰贡献者。分析面板展示哪些知识库正获得关注，以及社区最活跃的区域。

这是 DRY（Don’t Repeat Yourself）原则在机构知识中的应用：标注一次，永久复用。

---

实际效果演示

PDF 标注流程

文本格式支持

---

快速开始

开发环境

git clone https://github.com/JSv4/OpenContracts.git
cd OpenContracts
docker compose -f local.yml up

生产环境

# 首先应用数据库迁移
docker compose -f production.yml --profile migrate up migrate

# 启动服务
docker compose -f production.yml up -d

---

文档

浏览完整文档请访问 jsv4.github.io/OpenContracts，或在本仓库中查看：

指南	描述
快速开始	几分钟内通过 Docker 快速运行
核心概念	核心工作流与术语
PDF 数据格式	文本如何映射到 PDF 坐标
LLM 框架	PydanticAI 集成与智能体（agents）
向量存储（Vector Stores）	语义搜索架构
流水线概览	解析器（Parser）与嵌入器（Embedder）系统
自定义提取器	构建你自己的数据提取任务
v3.0.0.b3 版本说明	最新功能与迁移指南

---

架构

数据格式

OpenContracts 使用一种标准化格式来表示 PDF 页面上的文本与布局，从而支持在不同工具间移植注释：

处理流水线

模块化流水线支持自定义解析器（Parsers）、嵌入器（Embedders）和缩略图生成器（Thumbnailers）：

每个组件均继承自一个具有明确定义接口的基类：

• 解析器（Parsers） — 从文档中提取文本与结构
• 嵌入器（Embedders） — 为搜索生成向量嵌入（vector embeddings）
• 缩略图生成器（Thumbnailers） — 创建文档预览图

有关创建自定义组件的详细信息，请参阅 流水线文档。

---

遥测（Telemetry）

OpenContracts 收集匿名使用数据以指导开发优先级：包括安装事件、功能使用统计和聚合计数。我们不会收集文档内容、提取的数据、用户身份或查询内容。

禁用后端遥测：在 Django 设置中设置 TELEMETRY_ENABLED=False。
禁用前端分析：在 frontend/public/env-config.js 中不设置 REACT_APP_POSTHOG_API_KEY。

---

支持的格式

• PDF（完整支持布局与注释）
• 基于文本的格式（纯文本、Markdown）

即将推出：由 Docxodus 提供支持的 DOCX 查看与注释功能。

---

致谢

本项目基于以下工作的成果：

• AllenAI PAWLS — PDF 注释数据格式与相关概念
• NLMatics nlm-ingestor — 文档解析流水线

---

许可证

AGPL-3.0 — 详情请参见 LICENSE。

OpenContracts 快速上手指南

OpenContracts 是一个开源平台，用于构建人类与 AI 智能体可协同工作的结构化知识库，特别适用于合同、法规、政策等文档的管理与智能分析。

环境准备

• 操作系统：Linux / macOS / Windows（推荐 Linux 或 macOS）
• Docker：版本 ≥ 20.10
• Docker Compose：版本 ≥ 2.0（已集成在新版 Docker 中）
• 内存建议：至少 4GB 可用内存（生产环境建议 8GB+）
• 网络：确保可访问 GitHub（国内用户建议配置镜像加速）

💡 国内加速建议：
可使用阿里云或 DaoCloud 的 Docker 镜像加速服务，提升镜像拉取速度。
若克隆缓慢，可尝试使用 GitHub 镜像站（如 https://ghproxy.com/）代理仓库地址。

安装步骤

1. 克隆代码仓库

git clone https://github.com/JSv4/OpenContracts.git
cd OpenContracts

国内用户若遇网络问题，可尝试：

git clone https://ghproxy.com/https://github.com/JSv4/OpenContracts.git

2. 启动服务

开发环境（快速体验）

docker compose -f local.yml up

服务启动后，访问 http://localhost:3000 即可使用。

生产环境

# 先执行数据库迁移
docker compose -f production.yml --profile migrate up migrate

# 启动所有服务
docker compose -f production.yml up -d

默认服务端口为 80（HTTP）或 443（HTTPS），请确保端口未被占用。

基本使用

1. 首次访问：打开浏览器，进入 http://localhost:3000（开发模式）或你的服务器地址（生产模式）。
2. 创建知识库（Corpus）：点击 “Create Corpus”，上传 PDF 或文本文件。
3. 标注文档：在文档中选中文本，添加自定义标签（如“付款条款”、“责任限制”等）。
4. 调用 AI 智能体：在讨论区 @AI 助手，例如：

   @contract-analyzer 请找出所有违约责任条款并比较差异。
   

5. 搜索知识：使用顶部搜索框进行全文或语义搜索，结果包含文档内容与人工标注。

✅ 提示：平台支持 PDF 原始排版保留、多页跨段落标注、版本控制及团队协作功能，适合法律、合规、研究等专业场景。

更多高级功能（如自定义提取器、MCP 接入 Claude/Cursor 等）请参考官方文档：https://jsv4.github.io/OpenContracts/