From 1922d458969f2b1791a40f39090922663ef94827 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Fri, 6 Nov 2026 02:44:01 +0800 Subject: [PATCH] Document Paper Atlas purpose and operational workflow --- .gitignore | 10 ++++++ README.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 .gitignore create mode 100644 README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..adfd07a --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +__pycache__/ +*.pyc +*.sqlite +*.sqlite-* +*.zip +*.part +.env +.DS_Store +raw/ +data/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..17edc73 --- /dev/null +++ b/README.md @@ -0,0 +1,99 @@ +# Paper Atlas · 论文元数据与投稿历史索引 + +Paper Atlas 是一个**长期维护、按需或按批次运行的研究数据工具项目**。它不是一次性的下载脚本,也不需要为了采集而持续启动 Web 服务。目标是把 arXiv、重要 AI 会议论文集及公开投稿决定整合成可追溯、可查询、可持续更新的数据库,供后续研究趋势、跨会投稿、主题演化等分析使用。 + +## 项目目标与当前进度 + +目标包括:完整历史元数据导入、逐年会议目录、跨平台论文去重、公开拒稿/撤稿信息、平台标签与自定义标签隔离、可恢复更新和覆盖率报告。 + +**目前仍在开发,不能视为完整数据集。** 已实现 SQLite 数据结构、arXiv 元数据 ZIP 流式导入、断点恢复、DOI/标识合并和只读查询脚本。服务器上进行过合成样本验证;全量快照下载与历史导入尚未完成。会议适配器、跨平台模糊匹配复核流程、完整覆盖率核验与 CI 仍待实现。`venues.json` 的 41 个会议是候选覆盖范围,不代表已完成采集,也不是与 COLM 比较的客观排名。 + +## 数据范围与来源 + +- arXiv:官方推荐的 Cornell/Kaggle 元数据快照,包含标识、作者、标题、摘要、类别、版本与外部索引。默认导入整个快照,通过类别筛选 AI 论文,避免永久丢弃交叉领域记录。 +- 会议论文集:优先官方来源,计划接入 OpenReview、PMLR、ACL Anthology、NeurIPS、CVF、ECVA、AAAI、IJCAI;DBLP 用于补充会议目录、标识与出版信息。GitHub 聚合名单只作发现线索,不能作为未经核验的决定证据。 +- 投稿历史:只收录公开可访问并有证据的记录;没有录用信息不等于拒稿,不能据此推断“从未中会”。 +- 当前不下载 PDF、LaTeX、图片或补充材料,不提取论文全文,不推断匿名作者身份。 + +官方入口: + +- [arXiv bulk metadata](https://info.arxiv.org/help/bulk_data/index.html) +- [arXiv metadata snapshot](https://www.kaggle.com/datasets/Cornell-University/arxiv) +- [OpenReview 数据接口说明](https://docs.openreview.net/how-to-guides/data-retrieval-and-modification/how-to-get-all-notes-for-submissions-reviews-rebuttals-etc) +- [PMLR](https://proceedings.mlr.press/) +- [ACL Anthology 权威 XML 与 API](https://aclanthology.org/info/development/) +- [NeurIPS](https://proceedings.neurips.cc/) +- [COLM](https://proceedings.colm.cc/) +- [CVF](https://openaccess.thecvf.com/) +- [ECVA](https://www.ecva.net/papers.php) +- [IJCAI](https://www.ijcai.org/all_proceedings/) +- [AAAI](https://ojs.aaai.org/index.php/AAAI/issue/archive) +- [DBLP](https://dblp.org/db/conf/) + +## 数据模型 + +| 表 | 用途 | +| --- | --- | +| `papers` / `papers_fts` | 稳定论文实体、代表性标题摘要、FTS5 全文检索 | +| `identifiers` | arXiv ID、DOI 等唯一外部标识 | +| `source_records` / `sources` | 平台记录、原平台标题摘要与索引元数据、来源 URL 和抓取时间 | +| `venues` / `editions` | 会议或期刊系列、年份与 track,区分主会、Findings 和 workshop | +| `edition_sources` | 每届每个来源的覆盖状态、预计/已导入数量、错误与断点 | +| `submissions` / `decisions` | 多次投稿及带证据的决定历史,支持改投、撤稿和决定变更 | +| `tags` / `paper_tags` | 平台标签与人工标签,使用命名空间隔离 | +| `match_candidates` | 证据不充分的潜在重复记录及人工复核状态 | +| `ingest_runs` | 导入批次、状态、错误和恢复位置 | + +决定状态为 `accepted`、`rejected`、`desk_rejected`、`withdrawn`、`under_review`、`unknown`。一篇论文可以对应多次投稿和多个决定,不能用单一“最终会议”字段覆盖历史。查询中按观察时间选择最近状态;后续分析需要同时检查来源覆盖率。 + +当前确定性去重使用 arXiv ID 和单个 DOI。保留各平台源记录,避免合并后丢失出处。规范化标题只建检索索引,尚未实现模糊匹配流程;**现阶段不保证跨平台去重已经完成**。不同平台标签不自动等同,自定义标签应使用 `custom:*` 命名空间。 + +## 运行与查询 + +依赖 Python 3 标准库和带 FTS5 的 SQLite,目前无第三方 Python 依赖,无项目构建步骤。服务器已检查为 Python 3.14.4。所有运行数据放在仓库外,不提交数据库、下载包或访问凭据。 + +服务器暂存目录:`/data/paper-index/`,快照目录:`/data/paper-index/raw/`,运行代码目录:`/data/paper-index/code/`。这些路径不是对外访问的 API。 + +下载完成并验证 ZIP 后,在服务器运行: + +```sh +python3 -B import_arxiv.py \ + --db /data/paper-index/papers.sqlite \ + --archive /data/paper-index/raw/arxiv-metadata.zip +``` + +导入直接读取压缩包,不落盘展开整个 JSON。每 500 条提交一次事务并保存断点。若同一快照的导入异常中断,用相同命令恢复;恢复阶段需要重新顺序读取并跳过已提交行。不得同时启动多个写入进程。待恢复批次的文件路径、大小和修改时间必须一致;下载快照校验信息应保存在 `raw/arxiv-manifest.json`。 + +全量导入是有实质磁盘和 I/O 成本的操作。先检查 `df -h`,保持足够空间;数据库、FTS 索引和 WAL 都会增长,压缩包大小不是最终数据库占用。索引和数据库生成属于数据处理,不会构建应用镜像。 + +```sh +# 导入状态、记录量与覆盖状态 +python3 -B query.py --db /data/paper-index/papers.sqlite --stats + +# 查询标题或摘要,支持 SQLite FTS5 查询语法 +python3 -B query.py --db /data/paper-index/papers.sqlite --query '"language model"' --limit 20 + +# 按 arXiv 平台类别筛选 +python3 -B query.py --db /data/paper-index/papers.sqlite --tag arxiv:category=cs.AI + +# 会议与决定查询(会议数据导入后才有结果) +python3 -B query.py --db /data/paper-index/papers.sqlite --venue COLM --year 2025 --status rejected +``` + +查询连接使用 SQLite 只读模式,结果输出 JSON。当前没有公共 Web 页面或网络查询服务。 + +## 长期维护与更新 + +1. 每次采集先核对来源、许可、可访问性、空闲空间和现有运行批次。保持低并发,遵守来源限流、重试与人机验证要求。 +2. 下载先写 `.part`,确认完整 HTTP 响应和 ZIP 目录,再记录 SHA-256 与时间后切换为正式文件。正式导入会读至 EOF,从而验证成员 CRC。 +3. 每次导入保留来源证据和批次,按会议/年份/track 报告覆盖状态。缺失摘要留空,不编造文本;缺失决定保留未知。 +4. 核验行数、唯一标识、外键、全文查询和 SQLite 完整性后,再将批次视为交付。样本通过不能证明全量正确。 +5. 数据库备份使用 SQLite backup API 或一致性快照,不能在写入过程中只复制 `.sqlite` 主文件而遗漏 WAL。按明确保留策略轮换备份,避免无上限积累。 +6. 不为每次数据更新生成新 Docker 镜像;不常驻下载器;不自动创建定时任务。本项目的更新任务应按需或经用户授权调度。 +7. 代码通过工作分支和 PR 交付;构建或 CI 只能使用用户确认的远程 runner,不在本机触发构建。 + +## 当前访问限制 + +2026-11-06 从目标服务器测试:Kaggle 元数据 GET 可下载;OpenReview 会议 group 接口可读,但 notes 接口返回 `ChallengeRequiredError`。拒稿记录导入尚受此限制,不能用录用名单替代全部投稿,也不能声称已覆盖全部拒稿。需通过平台支持的访问方式或有合法来源的公开数据导出继续补全。 + +全量导入、会议适配器、正式 runner 配置与 PR 交付状态应随实现及时更新本 README。