SU-OSPO/preprint-bot · 上手攻略

• 仓库：SU-OSPO/preprint-bot
• 链接：https://github.com/SU-OSPO/preprint-bot
• 分类：rag / academic-writing（形态：tool · 学术用途：literature-discovery）
• 作者：spark
• 更新：2026-10-20

一、是什么

Preprint Bot 是一个面向学术界的预印本个性化推荐系统，来自 Stanford OSPO（开源项目办公室，仓库 DOI：10.5281/zenodo.20415805）。解决的问题很具体：研究者每天面对 arXiv 海量新论文，不知道该读哪些。

工作方式：用户建研究档案（选择 arXiv 分类），上传自己的论文 PDF，系统抽取文本生成向量；每晚自动抓取 arXiv 最新公告，做语义相似度匹配，把相关的新预印本推送给用户（网页 + 邮件摘要）。

技术栈是 Django（前端）+ FastAPI（后端/管线）+ PostgreSQL 12+ with pgvector（向量检索）+ GROBID 0.8.0+（PDF 分节抽取）+ sentence-transformers（嵌入，默认 all-MiniLM-L6-v2，384 维）+ LLaMA（摘要生成）+ FAISS（管线侧匹配）。15 张表的 schema 全部由 Django migrations 管理。GPL-3.0，Python 3.10+，9 stars。

二、解决什么问题

通用推荐系统按「谁点了这篇论文」协同过滤，而学术发现里更有效的是内容相似：你的上一份论文讲了什么，新论文里哪一篇讲的东西跟它像。Preprint Bot 走的就是这条技术路线——用你自己论文的嵌入向量去 arXiv 全库里做近邻检索。

它跟 arXiv 官方订阅、Semantic Scholar 的差异在于：它是可自己部署的机构级工具，能接 ORCID 登录、能按院系/课题组定制、能定制推送频率与阈值，数据留在自己库里。对高校图书馆或实验室 wanting 自建文献雷达特别对口。

三、快速安装

3.1 系统依赖

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install postgresql postgresql-contrib postgresql-server-dev-all
sudo apt-get install build-essential python3-dev
# macOS
brew install postgresql && brew services start postgresql

装 pgvector（README 给的是 v0.8.2）：

cd /tmp
git clone --branch v0.8.2 https://github.com/pgvector/pgvector.git
cd pgvector && make && sudo make install

建库建用户开扩展：

sudo -u postgres createdb preprint_bot
sudo -u postgres psql -c "CREATE USER preprint_user WITH PASSWORD 'secure_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE preprint_bot TO preprint_user;"
sudo -u postgres psql preprint_bot -c "CREATE EXTENSION vector;"

装 GROBID（推荐 Docker）：

docker pull lfoppiano/grobid:0.8.0
docker run -t --rm -p 8070:8070 lfoppiano/grobid:0.8.0
# 验证：curl http://localhost:8070/api/isalive  应返回 true
# 手工装：下载 0.8.0.zip 后 ./gradlew run

3.2 应用

git clone https://github.com/SU-OSPO/preprint-bot.git
cd preprint-bot

python3 -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate

# 共享的 preprint-source 包（本地，不在 PyPI），必须在仓库根执行
pip install ./packages/preprint_sources

pip install ".[llama]"    # 标准安装，含默认的 LLaMA 摘要器
pip install .             # 最小安装，无 LLaMA（CI/开发用）
pip install ".[all]"
pip install ".[dev,test]"
pip install ".[s3]"       # arXiv S3 批量下载

# 套用 schema
cd django_site && python manage.py migrate

硬件需求（README 明列）：8GB 内存最低、推荐 16GB；20GB 磁盘；建议 CUDA GPU 加速嵌入与摘要生成。

四、核心用法

4.1 四个配置文件

README 强调要用四份配置，缺一份跑不起来：

cp dummy_config.py config.py                       # arXiv 分类、阈值、模型名、路径、邮件
# 根 .env：FastAPI + 管线运行时（DB 连接、API_BASE_URL、SYSTEM_USER_EMAIL、USER_AGENT）
# django_site/.env：DJANGO_SECRET_KEY / DEBUG / ALLOWED_HOSTS / API_BASE_URL / PDF_DATA_DIR
cp django_site/preprint_bot_web/local_settings.py.example \
   django_site/preprint_bot_web/local_settings.py   # ORCID 凭据、品牌、CSRF、注册开关

四份都要加进 .gitignore，README 反复强调 never commit。config.py 关键项：

ARXIV_CATEGORIES = ["cs.LG"]
DEFAULT_THRESHOLD = 0.6
SIMILARITY_THRESHOLDS = {"low": 0.4, "medium": 0.6, "high": 0.75}
DEFAULT_MODEL_NAME = "all-MiniLM-L6-v2"
DATA_DIR = Path("pdf_data")
PAPER_STORAGE_DIR = DATA_DIR / "papers"   # 按 hash 去重存储

4.2 起服务

docker run -t --rm -p 8070:8070 lfoppiano/grobid:0.8.0   # GROBID
uvicorn main:app --reload --host 0.0.0.0 --port 8000      # FastAPI
cd django_site && python manage.py runserver 8001           # Django

入口：API 在 8000，OpenAPI 文档在 http://localhost:8000/docs，Web 界面在 8001。

4.3 跑管线

preprint_bot                                       # 抓最新一期 arXiv 公告（分类自动从用户档案读）
preprint_bot --date 2026-01-15                     # 回填指定历史日期
preprint_bot --skip-download --skip-parse --skip-summarize   # 开发时跳过慢步骤
preprint_bot --summarizer transformer              # 不用 LLaMA
preprint_bot --summarizer llama --llm-model models/llama-3.2-3b-instruct-q4_k_m.gguf

完整 flag：--date / --model / --summarizer {transformer,llama} / --llm-model / --skip-download / --skip-parse / --skip-embed / --skip-summarize。

默认摘要后端是 LLaMA，需要自己下 GGUF 模型：

mkdir -p models
pip install huggingface_hub
huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF \
  Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  --local-dir models --local-dir-use-symlinks False
mv models/Llama-3.2-3B-Instruct-Q4_K_M.gguf models/llama-3.2-3b-instruct-q4_k_m.gguf

4.4 API 示例

# 建用户
curl -X POST localhost:8000/users/ -d '{"email":"user@example.com","name":"Dr. User"}'

# 建研究档案（分类决定每天抓什么）
curl -X POST localhost:8000/profiles/ -d '{
  "user_id":1,"name":"AI Research",
  "categories":["cs.LG","cs.AI"],
  "frequency":"weekly","threshold":0.7,"top_x":10
}'

# 向量近邻搜索（384 维）
curl -X POST localhost:8000/embeddings/search/similar -d '{
  "embedding":[0.1,0.2],"corpus_id":1,"threshold":0.6,"limit":10
}'

# 取推荐
curl "localhost:8000/recommendations/profile/1?limit=50"

# 发邮件摘要
curl -X POST localhost:8000/emails/send-digest -d '{"user_id":1,"profile_id":1}'

4.5 新用户引导

Django 前端对新账号首次登录会触发一次免导航页的 onboarding：先建档案，再往档案里加论文；可点「Skip setup」跳过（README 提到检测依据是 last_login）。

五、典型适用场景

• 课题组文献雷达：每人建自己的档案 + 上传自己的论文，每晚自动收到相关 arXiv 推送。
• 高校图书馆服务：自建 ORCID 登录的推荐门户，数据不出校。
• 系统综述的持续监控：设好分类与 threshold，每周拿到增量论文清单。
• 方法学参考：想搭「PDF → 分节抽取 → 嵌入 → pgvector 检索 → 邮件摘要」这条链路的人可以直接读它的 src/preprint_bot/ 目录结构。

六、坑与注意（7 条）

1. packages/preprint_sources 不在 PyPI。README 明确：这是本地包、pip 上没有，且必须在仓库根目录执行 pip install ./packages/preprint_sources，否则相对路径解析不了。影响：从别处复制代码或改目录层级会导致 import 失败。修复：cd 到仓库根再装，安装后立刻验证一次导入。
2. 最小安装跑不了默认命令。README 明说：默认 preprint_bot 会跑 LLaMA 后端，而 pip install .（无 [llama]）不装 llama-cpp-python，preflight 会直接失败。影响：按「最小安装更干净」的直觉走，却在第一次跑管线时撞墙。修复：要么装 ".[llama]" 并按 4.3 下载 GGUF，要么显式加 --summarizer transformer。
3. 四份配置文件 + 密钥管理负担。根 .env、django_site/.env、config.py、local_settings.py，内容还互相重叠（两份 .env 共享 DB 连接变量）。影响：漏配一份的报错信息往往不指向真正原因，且 README 强调这四份都不可提交。修复：按 README 的 .gitignore 命令一次性加全，部署前用 checklist 逐项确认。
4. Django 与 FastAPI 绕过 HTTP 直连同一 Postgres。README 明写：Django 通过 ORM 直接读写共享数据库，FastAPI 是给管线单独用的，Django 不会通过 HTTP 调 FastAPI。影响：想靠改 API 来调 Web 层行为是无效的；同时意味着两侧 schema 强耦合。修复：任何 schema 变更必须走 Django migrations 单一来源；调试时注意两进程可能看到不同的连接池状态。
5. 硬件门槛不低。8GB 内存起、推荐 16GB、20GB 磁盘，建议 CUDA GPU；默认安装是 CPU build。影响：在小机器上跑全量管线会很慢。修复：开发期用 --skip-download --skip-parse --skip-summarize 先打通链路；有 GPU 时按 CUDA 版本装对应 torch wheel（README 举例 cu124）。
6. PG 后端是硬依赖。PostgreSQL 12+ + pgvector 不可替换为 SQLite 之类。影响：本机起个轻量试用环境的成本被抬高。修复：直接起容器跑 Postgres + pgvector，不要试图用别的数据库凑。
7. 嵌入维度固定 384 维。默认 all-MiniLM-L6-v2。影响：换成别的 embedding 模型后维度不匹配，/embeddings/search/similar 与库内既有向量全部失效。修复：换模型必须清库重建或写迁移改维度。
8. 摘要模型需自行下载且体积不小。bartowski/Llama-3.2-3B-Instruct-GGUF Q4_K_M 要从 Hugging Face 拉。影响：首次部署耗时长；离线或内网环境需要另找渠道。修复：提前在有网环境下载并随镜像分发。
9. arXiv 抓取频率受其公告节奏约束。README 写的是「每日抓取，对齐 arXiv 公告时间表」。影响：不是实时的，节假日与公告延迟会整体后移。修复：做时效性敏感的场景时，用 --date 回填补齐漏掉的日期。

七、与同类对比

维度	preprint-bot	arXiv 官方订阅	Semantic Scholar	Elicit / Litmaps
部署	自建（Docker/裸机）	托管	托管	托管 SaaS
推荐逻辑	内容向量相似（你自己论文 vs 全库）	分类订阅	引用图 + 作者	LLM 抽取筛选
机构定制	强（ORCID、品牌、注册开关）	无	无	有限
维护成本	高（4 份配置 + GROBID + GPU 可选 + Postgres）	零	零	零
数据归属	完全自持	他人	他人	他人
推荐质量	取决于自己的论文语料	无个性化	中	高（需付费）

它的核心优势是数据自持 + 机构可定制；核心劣势是维护成本明显高于所有托管方案，而且推荐质量完全取决于你上传的论文能否代表你的研究方向——没有论文的新用户，档案再精细也难有推荐。

八、一句话推荐结论

推荐：高校、实验室或需要数据不出校的团队，如果愿意投入一台服务器 + 一个懂 Django/FastAPI 的人来维护，preprint-bot 是一份质量相当高、文档相当完整的自建方案；个人研究者只是想少读几篇论文，直接用托管工具更划算。

诚实标注：本文基于公开 README 与仓库卡片（采集 2026-10-20，最近提交 2026-10-16）撰写，未 clone 仓库、未启动任何服务、未验证 API 响应。pgvector v0.8.2 tag、GROBID 0.8.0 镜像 tag、15 张表的完整 schema、./packages/preprint_sources 的实际内容均未独立核实；仓库自述「仅列出积极维护的文件，部分待移除的遗留文件仍在仓库中但未列出」，说明目录结构可能与实际不完全一致。部署前请以仓库当前 main 的 README 与 docker-compose 配置为准。