pdfget 0.1.3

智能文献搜索与批量下载工具，支持高级检索和并发下载

PDFGet - 智能文献搜索与批量下载工具

智能文献搜索与批量下载工具，支持高级检索和并发下载。

1. 项目概述

PDFGet是一个专为科研工作者设计的智能文献搜索与批量下载工具，集成了PubMed、Europe PMC等权威学术数据库，通过模块化架构提供高效的文献获取和管理功能。

1.1 主要特性

• 🔍 智能文献搜索：支持高级检索语法，可按作者、期刊、年份等精确搜索
• 📊 PMCID统计分析：快速统计文献的开放获取情况，支持多种输出格式
• 📥 批量PDF下载：自动下载开放获取文献，支持并发下载和智能重试
• 📋 混合标识符下载：支持从CSV文件读取PMCID/PMID/DOI混合列表，自动识别并下载
• 🔗 多数据源支持：集成PubMed（默认）和Europe PMC数据库
• 💾 智能缓存机制：避免重复API请求和下载，提升效率
• 🎯 双模式操作：统计模式（默认）和下载模式，满足不同需求
• 📝 摘要自动补充：自动从XML获取缺失的摘要，提高数据完整性（仅Europe PMC）

2. 安装与配置

2.1 系统要求

• Python 3.12 或更高版本
• 推荐使用 uv 包管理器以获得最佳体验

详细依赖信息请查看 pyproject.toml 文件。

2.2 安装方法

# 使用pip安装
pip install pdfget

# 使用uv安装（推荐）
uv add pdfget

# 或从源码安装
git clone https://github.com/gqy20/pdfget.git
cd pdfget
pip install -e .

2.3 快速开始

安装完成后，您可以直接使用 pdfget 命令：

# 搜索文献（默认统计模式，显示PMCID信息）
pdfget -s "machine learning" -l 20

# 下载PDF（添加-d参数）
pdfget -s "deep learning" -l 50 -d

# 使用自己的邮箱和API密钥（可选，提高搜索请求限制）
pdfget -s "quantum" -l 30 -e [e-mail] -k your-api-key

# 指定Europe PMC作为数据源（自动补充摘要）
pdfget -s "quantum" -S europe_pmc -l 30

# 使用多个数据源搜索
pdfget -s "cancer immunotherapy" -S both -l 100

# 从CSV文件批量下载（支持PMCID/PMID/DOI混合）
pdfget -m examples/identifiers.csv
pdfget -m examples/identifiers.csv -c ID
pdfget -m examples/pmcids.csv -c PMCID

# 单个或多个标识符下载
pdfget -m "PMC123456"
pdfget -m "PMC123456,38238491"  # PMCID和PMID混合
pdfget -m "10.1186/s12916-020-01690-4"  # DOI下载
pdfget -m "10.1186/s12916-020-01690-4,38238491,PMC123456"  # PMCID/PMID/DOI混合

如果您使用 uv 作为包管理器，也可以：

# 使用uv运行
uv run pdfget -s "machine learning" -l 20

说明：

• 搜索时默认进入统计模式，显示PMCID统计信息
• 添加 -d 参数进入下载模式，下载开放获取的PDF
• PubMed 是默认数据源，可指定 europe_pmc 或 both
• 邮箱和API密钥是可选的，仅用于提高搜索请求限制（3→10次/秒）
• 下载功能不需要API密钥，使用公开的开放获取服务

3. 高级检索语法

PDFGet 支持两种主要模式：统计模式（默认）和下载模式（使用 -d 参数）。

3.1 免费全文过滤

方法一：PMC 全文过滤（推荐，100% 可下载）

使用 pubmed pmc[sb] 过滤器只返回在 PubMed Central 中收录的文献，所有结果都可以下载：

# 搜索 PMC 收录的癌症文献（100% 可下载）
pdfget -s "cancer AND pubmed pmc[sb]" -l 100 -d

# 基因家族研究
pdfget -s '"gene family" AND pubmed pmc[sb]' -l 200

# 配合年份限制
pdfget -s '"machine learning" AND pubmed pmc[sb] 2020:2023[pd]' -l 100 -d

方法二：免费全文过滤

使用 filter[free full text] 包含所有类型的免费全文：

# 搜索有免费全文的高血压文献
pdfget -s "hypertension filter[free full text]" -l 100

# 搜索特定领域的免费全文文献
pdfget -s "machine learning filter[free full text]" -l 50 -d

重要说明：

• pubmed pmc[sb]：只返回 PMC 收录文献，100% 可下载（推荐）
• filter[free full text]：包含所有免费全文，约 30-40% 可下载
  • 包括：期刊官网免费全文、作者主页、机构仓库等
  • 这些免费全文不一定被 PMC 收录，PDFGet 无法下载
• 较新的文献（<1年）被 PMC 收录的概率较低
• 配合年份过滤效果更好，例如："cancer AND pubmed pmc[sb] 2020:2023[pd]"

为什么有这种差异？ 许多期刊提供免费的开放获取（Open Access），但这些文献：

1. 可能只存在于期刊官网
2. 可能需要 6-12 个月的延迟才被 PMC 收录
3. 有些期刊选择不在 PMC 存放全文
4. PDFGet 只能从 PMC 下载，无法处理其他来源

建议：

• 如果需要确保可下载：使用 pubmed pmc[sb]
• 如果想发现更多免费文献（即使不能使用当前软件下载）：使用 filter[free full text]

3.2 布尔运算符

# AND: 同时包含多个关键词
pdfget -s "cancer AND immunotherapy" -l 30

# OR: 包含任意关键词
pdfget -s "machine OR deep learning" -l 20

# NOT: 排除特定词汇
pdfget -s "cancer AND immunotherapy NOT review" -l 30

# 复杂组合
pdfget -s "(cancer OR tumor) AND immunotherapy NOT mice" -l 25

# 下载模式（添加-d）
pdfget -s "cancer AND immunotherapy" -l 30 -d

3.2 字段检索

# 标题检索
pdfget -s 'title:"deep learning"' -l 15

# 作者检索
pdfget -s 'author:hinton AND title:"neural networks"' -l 10

# 期刊检索
pdfget -s 'journal:Nature AND cancer' -l 20

# 年份检索
pdfget -s 'cancer AND year:2023' -l 15

# 组合检索（PubMed风格）
pdfget -s '"machine learning"[TI] AND author:hinton' -S pubmed -l 10

3.3 短语和精确匹配

# 短语检索（用双引号）
pdfget -s '"quantum computing"' -l 10

# 混合使用
pdfget -s '"gene expression" AND (cancer OR tumor) NOT review' -l 20

3.4 实用检索技巧

• 使用括号分组复杂的布尔逻辑
• 短语用双引号确保精确匹配
• 可以组合多个字段进行精确检索
• 使用 NOT 过滤掉不相关的结果（如综述、评论等）
• 统计模式：搜索并显示PMCID统计信息（默认行为）
• 下载模式：搜索并下载开放获取的PDF（添加 -d 参数）

4. 命令行参数详解

4.1 核心参数

• -s QUERY : 搜索文献
• -m INPUT : 批量输入（支持三种模式）
  • CSV文件路径：pdfget -m data.csv
  • 单个标识符：pdfget -m "PMC123456"
  • 逗号分隔列表：pdfget -m "PMC123,38238491"（PMCID/PMID/DOI混合）
• -c COLUMN : CSV列名（默认自动检测：ID>PMCID>doi>pmid>第一列）
• -d : 下载PDF（不指定则为统计模式）

4.2 优化参数

• -l NUM : 搜索结果数量（默认200）
• -S SOURCE : 数据源选择（pubmed/europe_pmc/both，默认pubmed）
• -t NUM : 并发线程数（默认3）
• --format FORMAT : 统计输出格式（console/json/markdown，默认console）
• -v : 详细输出

4.3 NCBI API 配置

• -e EMAIL : NCBI API邮箱（提高请求限制，推荐设置）
• -k KEY : NCBI API密钥（推荐，便于监控使用情况）

配置示例：

# 使用自己的邮箱（推荐）
pdfget -s "cancer" -l 100 -e [e-mail]

# 使用邮箱和API密钥
pdfget -s "machine learning" -l 500 -e [e-mail] -k your-api-key

为什么要配置邮箱？

• 邮箱是可选的，但推荐配置以遵守NCBI使用政策
• 有助于 NCBI 在出现问题时联系您

获取 NCBI API 密钥（推荐）：

1. 访问 NCBI 账户页面
2. 创建或登录 NCBI 账户（免费）
3. 登录后访问 账户设置
4. 查找 "API Key Management" 部分创建 API 密钥
5. 提供简要的应用描述并接受服务条款

重要说明：

• API 密钥可以将请求限制从 3 次/秒提高到 10 次/秒（仅用于搜索）
• API 密钥主要用于 NCBI 监控使用情况和问题追踪
• 虽不是必需，但建议配置以获得更好的搜索性能

下载功能说明：

• PDF 下载不需要 API 密钥（使用公开的 PMC OA Service）
• 下载通过以下公开服务进行：
  • PMC Open Access Web Service
  • Europe PMC 直接下载链接
• 只有 PubMed 搜索和 PMCID 获取需要使用 NCBI E-utilities API

Europe PMC 说明：

• Europe PMC 搜索不需要 API 密钥或邮箱
• 使用开放的 REST API，建议将请求速率控制在 10-15 次/秒以下
• 官方未明确说明速率限制，但根据第三方资料约为 20 次/秒
• 如果主要使用 Europe PMC 数据源，可以不配置任何认证信息
• 自动摘要补充：当 API 返回的记录缺少摘要时，自动从 XML 文件获取完整摘要，将摘要覆盖率从 87% 提升到 97%

5. 输出格式与文件结构

5.1 搜索结果格式

[
  {
    "pmid": "32353885",
    "doi": "10.1186/s12916-020-01690-4",
    "title": "文献标题",
    "authors": ["作者1", "作者2"],
    "journal": "期刊名称",
    "year": "2023",
    "abstract": "摘要内容",
    "pmcid": "PMC7439635",
    "source": "pubmed"
  }
]

5.2 文件目录结构

data/
├── pdfs/           # 下载的PDF文件
├── cache/          # 缓存文件
└── search_results.json  # 搜索结果记录

5.3 PMCID统计结果

当使用搜索功能（不指定 -d 参数）时，会返回开放获取文献统计信息：

{
  "query": "关键词",
  "total": 5000,
  "checked": 200,
  "with_pmcid": 90,
  "without_pmcid": 110,
  "rate": 45.0,
  "elapsed_seconds": 30.5,
  "processing_speed": 6.67
}

字段说明：

• query: 搜索的关键词
• total: 数据库中匹配的文献总数
• checked: 实际检查的文献数量（由 -l 参数决定）
• with_pmcid: 有PMCID的文献数量
• without_pmcid: 无PMCID的文献数量
• rate: 有PMCID的文献百分比
• elapsed_seconds: 统计耗时
• processing_speed: 处理速度（篇/秒）

输出格式选项：

• --format console: 控制台友好格式（默认）
• --format json: 结构化JSON格式，便于程序处理
• --format markdown: Markdown格式，便于文档生成

示例：

# 生成JSON格式的统计报告
pdfget -s "cancer" -l 100 --format json

# 生成Markdown格式的统计报告
pdfget -s "cancer" -l 100 --format markdown

5.4 混合标识符输入格式

-m 参数支持三种输入模式，自动识别：

模式1：CSV文件路径

# 自动检测列名（优先级：ID>PMCID>doi>pmid>第一列）
pdfget -m examples/identifiers.csv

# 手动指定列名
pdfget -m examples/identifiers.csv -c PMCID
pdfget -m examples/identifiers.csv -c ID

示例CSV文件：

ID,Title,Journal
PMC123456,Study on AI,Nature
38238491,Deep Learning Review,Science
PMC789012,Machine Learning Methods,Cell
37851234,Neural Network Research,Cell

模式2：单个标识符

pdfget -m "PMC123456"              # PMCID
pdfget -m "38238491"                # PMID
pdfget -m "10.1186/s12916-020-01690-4"  # DOI

模式3：逗号分隔的多个标识符

pdfget -m "PMC123456,38238491"  # PMCID和PMID混合
pdfget -m "10.1186/s12916-020-01690-4,38238491,PMC123456"  # PMCID/PMID/DOI混合

支持的标识符类型：

• PMCID：支持带或不带PMC前缀（如"123456"或"PMC123456"）
• PMID：6-10位纯数字
• DOI：以"10."开头的字符串

标识符处理流程：

1. PMCID：直接下载
2. PMID：自动转换为PMCID后下载（使用NCBI ESummary API）
3. DOI：自动转换为PMCID后下载（使用Europe PMC API，支持CrossRef备选）

高级用法：

# 使用5个并发线程
pdfget -m examples/identifiers.csv -t 5

# 限制只下载前10个
pdfget -m examples/identifiers.csv -l 10

注意事项：

• PMID会自动转换为PMCID，转换成功率约80-90%（取决于文献是否被PMC收录）
• DOI会自动转换为PMCID，转换成功率约60-80%（取决于文献是否被PMC收录）
• 无法转换的PMID/DOI会被跳过，不会影响其他标识符的下载
• 列名检测不区分大小写

6. 功能实现状态

已实现功能 ✅

• PMCID直接下载（100%成功率）
• PMID自动转换为PMCID下载（80-90%成功率）
• DOI自动转换为PMCID下载（60-80%成功率）
• 高级检索语法支持
• 并发下载管理
• 智能缓存机制
• 多种输出格式（console/json/markdown）
• 混合标识符输入（PMCID/PMID/DOI）
• 批量处理CSV文件
• PMC开放获取统计分析
• Europe PMC API集成（主要数据源）
• CrossRef API辅助查询
• 批量DOI转换优化（100个DOI/30-60秒）

计划功能 📋

• 增强DOI转换（更多数据源）
• 用户认证支持（机构访问）
• 下载进度持久化
• GUI界面
• 插件系统

7. 故障排除

常见问题

PMID转换失败

问题：PMID无法转换为PMCID 可能原因：

1. 文献未被PMC收录（约10-20%的文献）
2. PMID格式不正确（应为6-10位数字）
3. NCBI API临时限制

解决方案：

1. 检查PMID格式：echo "38238491" | wc -c 应返回9
2. 使用PMC过滤搜索：pdfget -s "your query AND pubmed pmc[sb]"
3. 配置API密钥提高请求限制：-e [e-mail] -k your-api-key

下载速度较慢

问题：批量下载耗时较长 优化建议：

1. 调整并发线程数：-t 10（默认3）
2. 分批处理大量文献：-l 100 限制单次数量
3. 使用PMC过滤确保100%可下载：pubmed pmc[sb]

网络连接问题

问题：API请求超时或失败 解决方案：

1. 检查网络连接
2. 配置代理（如需要）
3. 使用Europe PMC数据源：-S europe_pmc
4. 重试失败的下载（程序会自动重试）

缓存问题

问题：使用了过期的缓存数据 解决方案：

# 清理搜索缓存
rm data/cache/search_*.json

# 清理PDF缓存（如需要）
rm data/pdfs/*.pdf

8. 许可证

本项目采用 MIT License，允许自由使用和修改。

9. 获取帮助

• 🔗 完整更新日志: CHANGELOG.md
• 📧 问题反馈: GitHub Issues

10. 相关链接

• 项目源码: GitHub Repository
• 问题反馈: GitHub Issues
• API文档:
  • NCBI E-utilities
  • Europe PMC API
  • Europe PMC XML Service