khoj-ai/openpaper · 上手攻略

  • 仓库：khoj-ai/openpaper
  • 链接：https://github.com/khoj-ai/openpaper
  • 分类：research-tool
  • 作者：Jay
  • 更新：2026-08-13

是什么

Open Paper 是一个研究文献管理工作台，定位为"读论文的 IDE"。核心功能是把 PDF 上传、AI 生成摘要、highlight 标注、AI 问答、跨文献综合、Zotero 同步全部收敛到一个 Web 应用里，AI 回答强制附带可点击溯源的精确引用（citation-grounded），并配套专门的 ResearchQA 基准 来量化回答质量。

解决什么问题

读论文的割裂感：PDF 在本地、笔记在 Notion、引用管理在 Zotero、术语查 Google，跨上下文切换消耗大量注意力。Open Paper 的思路是把这些全部收进同一个页面，AI 每次引用都直接指向 PDF 原文第几段，降低"信任 AI 幻觉"的风险。

快速安装

项目是三服务架构（Server · Client · Jobs），本地运行需要 Docker + Python 3.12+ + Node.js + Yarn。

# 前置：Docker 运行中（RabbitMQ + Redis 由 docker-compose 拉起）
git clone git@github.com:khoj-ai/openpaper.git && cd openpaper

# Server
cd server && uv sync && cp .env.example .env
# 手动编辑 .env，填入 DATABASE_URL、GEMINI_API_KEY、AWS S3 相关变量等

python3 app/scripts/run_migrations.py

# Jobs（与 server 共用部分 .env 变量）
cd ../jobs && uv sync

# Client
cd ../client && yarn

# 启动（三个终端各自跑）
# 终端 1：Jobs（Celery worker + Beat + Jobs API）
cd jobs && uv run start

# 终端 2：Server（FastAPI）
cd server && uv run start

# 终端 3：Client（Next.js）
cd client && yarn dev

启动后访问： - http://localhost:3000 — Web UI - http://localhost:8000/docs — FastAPI 文档

⚠️ 注意：README 明确说"built primarily as a hosted service, isn't optimized for self-hosting"——自部署需要手动配置 PostgreSQL、S3 存储（兼容 Cloudflare R2）、LLM API key（当前用 Gemini），有一定的工程门槛。托管版在 https://openpaper.ai 可直接使用。

核心用法

上传与阅读

  1. 打开 http://localhost:3000，用 Google OAuth 登录（GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET 需在 .env 配置）。
  2. 上传 PDF，自动生成 AI brief 和引导性问题。
  3. 高亮任意文字，右侧可附加注释或直接发给 AI 助手深入解释。

AI 问答（带溯源引用）

# API 直接调用示例
curl -X POST http://localhost:8000/api/v1/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "这篇论文的贡献是什么？", "paper_ids": ["<uuid>"]}'

返回的每条引用都是可点击跳转的精确段落的 URL。

项目跨文献提问

# 创建一个项目并加入多篇论文，通过 API 提问
curl -X POST http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"name": "我的 RAG 研究", "paper_ids": ["<id1>", "<id2>"]}'

# 跨项目综合提问
curl -X POST http://localhost:8000/api/v1/projects/<project_id>/query \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"query": "这些论文在 RAG 评估方法上有什么共识？"}'

Zotero 同步

在 jobs/.env 设置 ZOTERO_SYNC_INTERVAL_SECONDS=60（测试用）和 JOBS_INTERNAL_SECRET，Celery Beat 会自动定期拉取 Zotero 文献库。

本地开发命令参考

服务 端口 开发命令
Client（Next.js） 3000 cd client && yarn dev
Server（FastAPI） 8000 cd server && uv run start
Jobs API 8001 cd jobs && uv run start
Flower（可选） 5555 jobs/./scripts/start_flower.sh

典型适用场景

  • 文献调研阶段：上传几十篇论文，用 AI 快速了解每篇的核心贡献与创新点。
  • 跨文献对比：把同一主题的多篇论文放进同一个 Project，问"它们的方法有什么本质区别"。
  • 论文精读辅助：边读边 highlight，AI 解释术语时直接溯源到原文段落。
  • 研究笔记管理：注释关联原文，方便日后回溯"当时为什么会这样标注"。
  • 团队共享文献库：多个研究者共建项目，AI 辅助发现遗漏的相关工作。

坑与注意

  1. 自托管门槛高：README 直言不推荐生产自部署，需要同时运维 PostgreSQL + S3/R2 + RabbitMQ + Redis + Gemini API key，比普通 Docker Compose 应用复杂得多。
  2. LLM 默认用 Gemini：国内用户需要配置 GEMINI_API_KEY，暂不支持 OpenAI/Anthropic 等其他模型（需自行确认 server 侧是否支持扩展）。
  3. Jobs 服务独立部署：server + jobs 共用部分 .env 变量但独立运行，首次部署容易漏填 JOBS_INTERNAL_SECRET 导致 Zotero 同步失败。
  4. 文件存储依赖 S3：本地开发必须配置一个 S3 兼容服务（MiniIO 或 Cloudflare R2），纯本地无外部依赖的场景需要额外配置。
  5. PDF 解析依赖 Celery Worker：大文件上传后若 jobs 服务未启动，解析会静默失败，UI 不会提示。
  6. OAuth 登录必须有公网域名：Google OAuth 重定向在生产环境需要 ONESSH_PUBLIC_URL 同等机制（此处是 CLIENT_DOMAIN），本地 127.0.0.1 可能不被 Google 接受。

与同类对比

工具 定位 AI 引用 Zotero 同步 自托管 跨文献综合
Open Paper 研究阅读工作台 ✅ 可点溯源 ✅ 自动 ⚠️ 门槛高 ✅ Project 级
Khoj 个人知识库 AI ✅ ❌ ✅ 简单 有限
ChatPaper 单篇 AI 摘要 有限 ❌ ✅ ❌
Zotero + GPT 文献管理 + AI ❌ ✅ ✅ ❌
SciSpace (Copilot) 论文阅读辅助 ✅ ❌ SaaS ❌
Mendeley / EndNote 传统文献管理 ❌ ✅ ✅ ❌

Open Paper 的差异化在于"每句回答都有可验证的 PDF 段来源"，而非笼统的 RAG 问答。加上专门的 ResearchQA 基准 量化 citation 准确率，是目前其他工具较少强调的工程方向。

一句话推荐结论

如果你在写文献综述或深度精读论文，需要 AI 回答时直接告诉你"第几段第几行这么说的"，Open Paper 是目前开源里这个方向做得最彻底的；但自部署需要接受三服务 + S3 + Gemini 的工程复杂度，建议先用 https://openpaper.ai 托管版体验，确认工作流匹配后再考虑自托管。

原始 commit：https://github.com/khoj-ai/openpaper（README + DEVELOPMENT.md，fetch 日期 2026-08-13）