91 lines
6.5 KiB
Markdown
91 lines
6.5 KiB
Markdown
# 使用指南
|
|
|
|
先在已确认的远程环境安装项目，使用 `paper-atlas`。从源码运行时，将命令前缀替换为 `python3 -B -m paper_atlas`，其余参数相同。数据目录位于仓库外。
|
|
|
|
## PostgreSQL 查询
|
|
|
|
在远程环境安装 `.[postgres]`，通过权限为 `0600` 的 libpq service 文件连接，不把密码放入 URL、命令行或仓库。
|
|
|
|
```sh
|
|
export PGSERVICEFILE=/etc/paper-atlas/pg_service.conf
|
|
paper-atlas query --pg-service foundry-research --stats
|
|
paper-atlas query --pg-service foundry-research --query '"language model"' --tag arxiv:category=cs.CL
|
|
paper-atlas query --pg-service foundry-research --status rejected --outcome accepted --limit 20
|
|
paper-atlas query --pg-service foundry-research --paper 123
|
|
```
|
|
|
|
使用只读一致性事务，支持论文 ID、会议别名、年份、轨道、标签、最新决定和跨会议录用筛选。全文检索使用 PostgreSQL `websearch_to_tsquery('english', ...)`，支持引号短语、`OR` 和减号排除；与 SQLite FTS5 的语法及分词结果不完全相同。JSON 来源列保留原始文本；转成 `jsonb` 前须确认原始值符合该类型的限制。
|
|
|
|
CLI 自动还原迁移中的 NUL/SOH 文本转义，详情中的来源摘要和筛选参数保留原字符。直接 SQL 读取可能看到 `U+0001` 转义序列；跨项目 ETL 应按迁移元数据中的 `text_codec` 使用 `paper_atlas.postgres.text.encode/decode`。存储格式和无损哈希验收见[运行维护](operations.md#postgresql-迁移)。
|
|
|
|
迁移与切换见[运行维护](operations.md#postgresql-迁移)。`import records`、`import arxiv` 和 `maintain backfill` 均支持 `--pg-service` 和可选 `--pg-schema`；与 `--db` 二选一。SQLite 导入仅用于未切换的索引或独立样本。尚未适配 PostgreSQL 的维护、覆盖审计命令仍可只读检查冻结备份，不能当作主库的当前状态。
|
|
|
|
## 1. 下载固定快照
|
|
|
|
`paper-atlas download --help` 说明大小、校验和与续传参数。各来源的固定版本与具体命令见[数据源说明](data-sources.md)。下载成功只表示原始文件已核验。
|
|
|
|
## 2. 采集并核对清单
|
|
|
|
```sh
|
|
paper-atlas collect pmlr --cache /data/paper-index/raw/http-cache --out /data/paper-index/collected
|
|
paper-atlas collect cvf --cache /data/paper-index/raw/http-cache --out /data/paper-index/collected
|
|
paper-atlas collect ecva --cache /data/paper-index/raw/http-cache --out /data/paper-index/collected
|
|
paper-atlas catalogue dblp --help
|
|
paper-atlas audit iclr --help
|
|
paper-atlas collect public-openreview --help
|
|
paper-atlas collect icml-public-archive --help
|
|
paper-atlas audit public-openreview --help
|
|
```
|
|
|
|
采集输出 JSONL、manifest 和逐卷或逐年 catalogue。逐项检查 blocked、partial、缺失摘要及目标会议归属。DBLP 候选目录还需核验届次和 track，不能直接当作主会录用名单。
|
|
|
|
其他会议的公开拒稿使用 `collect public-openreview`，再以 `audit public-openreview` 核对既有投稿身份和决定冲突。来源版本、逐文件状态盘点和未解决记录分别保存在 inventory 与 held 清单中，具体命令见[数据源说明](data-sources.md#其他会议的公开拒稿)。这类公开子集不能当作会议完整投稿名单。
|
|
|
|
## 3. 串行导入
|
|
|
|
PostgreSQL 主库逐文件导入已经核验的资料：
|
|
|
|
```sh
|
|
paper-atlas import records --pg-service foundry-research \
|
|
/data/paper-index/collected/selected-file.jsonl
|
|
paper-atlas maintain backfill --pg-service foundry-research \
|
|
--queue /data/paper-index/collected/audited-identity-queue.json
|
|
```
|
|
|
|
文件和 queue 须替换为实际核验通过的路径。会议导入按文件提交，失败时该文件的论文、标签和决定更改全部回滚，失败批次日志保留；重跑会按来源标识与决定证据去重。回填使用已有源记录，只合并经独立身份佐证的投稿，不重新导入文本。所有写入者须遵守同一数据库/schema 的会话锁；其他项目也应通过相同的写入接口更新共享论文和投稿。
|
|
|
|
未来需要导入新的 arXiv 元数据包时使用 `paper-atlas import arxiv --pg-service foundry-research --archive ... --storage-path ...`。每 500 行提交断点，恢复同一文件时保留已提交 ID 和标签证据；`--storage-path` 指定运行主机上要监测的文件系统，在数据库主机执行时应指向数据库卷。已完成的历史压缩包不需要重复导入。
|
|
|
|
SQLite 独立样本的首次 arXiv 导入使用 `paper-atlas import arxiv --db ... --archive ...`。SQLite 协调器仍适用于未切换的索引：
|
|
|
|
```sh
|
|
paper-atlas maintain merge --db /data/paper-index/samples/example.sqlite \
|
|
--archive /data/paper-index/raw/arxiv-metadata.zip \
|
|
/data/paper-index/collected/selected-file.jsonl
|
|
```
|
|
|
|
上例的 selected-file 须换成实际通过核验的文件。协调器会维护本项目的 arXiv 断点、序列化写入并检查外键；已完成的 arXiv 批次不会重启。持久批次应作为一次性 systemd 任务运行，详见[运行维护](operations.md)。
|
|
|
|
## 4. 查询与分析前检查
|
|
|
|
```sh
|
|
paper-atlas query --db /data/paper-index/papers.sqlite --query '"language model"' --limit 20
|
|
paper-atlas query --db /data/paper-index/papers.sqlite --tag arxiv:category=cs.AI
|
|
paper-atlas query --db /data/paper-index/papers.sqlite --venue ICLR --year 2025 --status rejected
|
|
paper-atlas query --db /data/paper-index/papers.sqlite --paper 123
|
|
paper-atlas coverage --db /data/paper-index/papers.sqlite --out /data/paper-index/collected/coverage.json
|
|
```
|
|
|
|
`--status rejected` 筛选某次投稿的最新已知决定。它并不表示论文在所有会议均未录用；分析转投情况时查看该论文的完整投稿历史。年份表示会议届次，观察时间和决定日期分别保留。
|
|
|
|
例如，查找在 ICLR 有拒稿记录、但在其他已知投稿中已有录用的论文：
|
|
|
|
```sh
|
|
paper-atlas query --db /data/paper-index/papers.sqlite \\
|
|
--venue ICLR --status rejected --outcome accepted
|
|
```
|
|
|
|
`known_acceptances` 列出目前仍为录用状态的各次投稿及会议、年份、track 和决定证据，`publication_outcome` 汇总为 accepted 或 no_known_acceptance。汇总会检查所有会议和 track，不把某次拒稿覆盖到整篇论文；同一次投稿的后续撤稿也会更新该次状态并保留原决定。no_known_acceptance 只表示现有来源中没有查到录用，不能称为“从未录用”。
|
|
|
|
`--stats` 中 papers 是当前规则下的论文实体数；source_records 是来源记录数；decisions 是决定观察数。一个投稿可能有多个来源和多条观察，不能相加当作论文数。
|