OpenContracts

OpenContracts：开源文档智能平台

从堆积如山到触手可及：文档智能的新范式

场景切入： 想象你是一位合同审查律师，桌面上堆着 300 份 PDF 合同，每份少则 10 页、多则上百页。客户问：「这些合同里，有多少份包含竞业限制条款？哪些允许甲方单方面终止？」你只能一行行手动搜索，还是可以让 AI 在几秒内给你答案？

OpenContracts 正是为解决这类场景而生。它是一个开源的文档智能平台，支持对海量文档（PDF、Word、Excel、邮件等）进行 OCR 识别、结构化提取、AI 标注、向量检索和多轮对话，并且内置 MCP（Model Context Protocol）服务器，可被 AI 助手直接调用。

背景与起源

OpenContracts 由 Open Source Legal 团队开发维护，核心作者为 John Scrudato IV，项目采用 MIT 许可证完全开源。项目官方 demo 部署于 https://contracts.opensource.legal，任何人都可以在线体验其核心功能。

项目的核心理念是：文档即数据，标注即代码。传统文档管理系统（DMS）只负责存储和检索，而 OpenContracts 将文档视为结构化知识来源，通过 AI 将非结构化文本转化为可编程的引用图谱（Citation Graph），支持构建法律审查、学术研究、合规审计等多种知识密集型应用。

核心技术架构

OpenContracts 的架构设计体现了现代 AI 应用的专业分工理念：

后端技术栈（Django + Channels）：

• Django 5.2 作为主 Web 框架，提供 REST API 和 GraphQL 接口
• Django Channels + Daphne + Redis 实现 WebSocket 实时通信，支持文档处理进度推送
• Celery 分布式任务队列处理文档解析、OCR、嵌入生成等耗时任务
• PostgreSQL + pgvector 提供关系型存储 + 向量相似度搜索（支持 HNSW 索引）
• GraphQL API（schema.graphql）提供灵活的数据查询接口

前端技术栈（React + Apollo）：

• React 18 + TypeScript 构建，依赖 @apollo/client 进行 GraphQL 通信
• 富文本编辑器基于 TipTap（@tiptap/react），支持文档内联标注
• UI 组件库使用 @os-legal/ui（团队自研），图表基于 D3.js
• PDF 渲染使用 pdfjs-dist，支持在浏览器中直接预览文档
• 状态管理采用 Jotai（原子化状态）

AI/ML 管道（Pipeline Architecture）：

项目实现了高度模块化的文档处理管道（opencontractserver/pipeline/），各环节可插拔替换：

模块	负责	关键依赖
解析器（Parsers）	PDF/DOCX/Excel 等格式提取文本和结构	docling, PyMuPDF
OCR（EasyOCR）	扫描件和图片文字识别	easyocr
分块（Chunking）	将长文档切分为语义块	spaCy NLP
嵌入（Embeddings）	文本向量化（Sentence-Transformers）	sentence-transformers
向量化存储（Vector Stores）	pgvector 存储 + 相似度搜索	pgvector-python
分析器（Analyzers）	基于 LLM 的标注和结构化提取	支持多 LLM Provider
LLM 提供商（LLM Providers）	统一 LLM 调用接口	OpenAI / Anthropic / 本地模型

项目预置了多种模型下载脚本（model_preloaders/），包括 GLiNER（实体识别）、Docling（文档布局分析）、Sentence-Transformers（文本嵌入）和 spaCy（NLP 分词）。

Agent 框架（MCP Server）：

opencontractserver/mcp/ 实现了 MCP（Model Context Protocol）服务器，这是一个被 AI 助手广泛支持的标准化协议。通过 MCP 接口，外部 AI 助手可以直接读取 OpenContracts 中的文档内容、标注数据，进行检索增强生成（RAG）。这使得 OpenContracts 成为了AI Agent 的外部知识库。

多语言支持：

• 后端通过 django-locale 支持多语言国际化
• 前端支持多语言界面

图1：OpenContracts Web UI 主界面

核心功能详解

1. 文档导入与处理管道

用户上传文档后，系统自动触发处理管道：

• 格式检测：自动识别 PDF、DOCX、XLSX、PPTX、Email 等格式
• OCR 识别：对扫描件和图片进行文字提取（EasyOCR）
• 布局分析：Docling 模型识别标题、段落、表格、页眉页脚等结构
• 文本分块：基于语义边界切分，保持段落完整性
• 向量化：生成 384 维嵌入向量（multi-qa-MiniLM-L6-cos-v1）存入 pgvector

2. 标注与引用图谱

OpenContracts 支持多种类型的标注：

• 手动标注：用户在 Web UI 中选中文本，创建高亮、注释和标签
• AI 标注：通过 Analyzer 模块调用 LLM 自动识别实体、关系和关键条款
• 结构化提取：将非结构化文本提取为 JSON Schema 定义的结构化字段

所有标注形成引用图谱（Citation Graph），每个标注都带有原文引用（文本片段 + 文档来源 + 位置），确保可溯源、可审计。

3. 检索与问答

• 向量语义检索：基于语义相似度搜索相关段落
• 关键词检索：支持精确匹配的 Boolean 查询
• Reranking：对初步检索结果进行 LLM 驱动的重排序
• 多轮对话：结合对话历史（Conversations 模块）进行上下文感知的问答

4. Agent 集成（MCP Server）

MCP Server 提供以下只读工具：

• get_public_corpus：获取公开语料库信息
• get_public_document：获取文档内容和元数据
• search_public_corpus：在语料库中进行向量检索
• get_document_annotations：获取文档标注数据

这使得 OpenContracts 可以作为 AI 助手的可信知识源，特别适合法律/合规领域的 RAG 应用。

容器化与部署

多阶段 Docker 构建：

• 后端 Dockerfile 基于 python:3.12.7-slim-bookworm 多阶段构建，包含编译阶段（python-build-stage）和运行阶段
• 前端 Dockerfile 使用 node:20-alpine 构建 React 应用，然后打包进 nginx:1.27.5-alpine 镜像
• CI/CD 流程会自动将构建好的 Docker 镜像推送到 ghcr.io，main 分支推送后可直接 pull 使用，大幅缩短部署时间

docker-compose 编排（local.yml）： services 包含 django（Django + Daphne ASGI）、frontend（Nginx）、postgres（PostgreSQL + pgvector）、redis（缓存 + Celery broker）、celery（Celery worker）、flower（Celery 监控界面）。

一键启动命令：docker compose -f local.yml up，约 20 分钟完成首次部署（包含模型下载）。硬件需求：4GB RAM、10GB 磁盘，无需 GPU（CPU 推理）。

适用场景与局限性

适用场景：

• 法律团队合同审查与条款分析
• 学术研究的文献管理与信息提取
• 合规审计的文档扫描与风险标注
• 企业内部知识库构建（支持 RAG）

局限性：

• 默认 CPU 推理，大文档处理较慢（建议有 GPU 加速）
• 主要面向英文文档，中文支持需额外配置嵌入模型
• MCP Server 目前仅支持只读操作，写入需通过 GraphQL/REST API
• 部署复杂度中等，需要 Docker 和 PostgreSQL 基础知识

行业意义

OpenContracts 代表了文档管理从「存储检索」到「智能理解」的技术跃迁。它不仅是 DMS，更是AI Agent 的可信知识基础设施。随着 MCP 协议的普及，OpenContracts 这类支持标准化 Agent 接入的文档平台将成为 AI Native 应用栈中的重要一环。

项目的 GitHub 活跃度较高，topics 覆盖 agent、agentic-ai、llm、vector-database 等热点方向，在开源文档智能领域具有较强的参考价值和技术领先性。

---

分析时间：2026-06-14 | 数据来源：GitHub API + 官方文档