Google Scholar API 技能#

概述#

本技能提供通过 SerpAPI 访问 Google Scholar 的功能，实现学术论文的智能检索和下载。包含完整的 Python 脚本、配置示例和使用指南。

快速开始#

1. 安装依赖#

bash

pip install google-search-results requests

2. 设置 API 密钥#

bash

export SERP_API_KEY="your_serpapi_key_here"

3. 基本搜索示例#

python

from scripts.google_scholar_search import GoogleScholarSearch

# 初始化客户端
client = GoogleScholarSearch()

# 搜索论文
results = client.search("machine learning", num_results=5)
papers = client.parse_results(results)

for paper in papers:
    print(f"标题: {paper['title']}")
    print(f"作者: {paper['authors']}")
    print(f"年份: {paper['year']}")
    if 'pdf_link' in paper:
        print(f"PDF 可用: {paper['pdf_link']}")

核心功能#

1. 论文搜索（基于 SerpAPI）#

• 基本搜索: 关键词、短语搜索
• 高级搜索: 作者搜索 ( author:"姓名")、来源搜索 ( source:"期刊")
• 时间过滤: 按年份范围筛选 ( as_ylo, as_yhi)
• 排序选项: 相关性、日期（仅摘要）、日期（全部内容）
• 引用搜索: 搜索引用特定文章的文献 ( cites 参数)
• 版本搜索: 搜索文章的所有版本 ( cluster 参数)

2. 结果解析#

• 完整元数据: 标题、作者、年份、期刊、摘要
• 引用信息: 引用次数、引用ID、集群ID
• 作者详情: 作者姓名、Google Scholar链接、作者ID
• 资源链接: PDF、HTML、相关页面、引用链接
• 搜索统计: 总结果数、处理时间、搜索状态

3. PDF 下载#

• 智能检测: 自动识别可用的PDF链接
• 批量下载: 支持批量下载多个论文
• 文件命名: 按"年份_标题"格式自动命名
• 下载跟踪: 记录下载状态和路径
• 错误处理: 网络超时、链接失效等异常处理

4. 高级功能#

• 作者专搜: 专门搜索某位作者的所有论文
• 引用分析: 分析某篇文章的引用网络
• 版本追踪: 查找文章的所有版本
• 多语言: 支持多种语言搜索 ( hl 参数)
• 综述筛选: 仅显示综述文章 ( as_rr 参数)

工作流程#

步骤 1: 准备环境#

1. 获取 SerpAPI 密钥（免费注册）
2. 安装 Python 依赖
3. 设置环境变量或直接传递密钥

步骤 2: 执行搜索#

python

# 基础搜索
client.search("deep learning", num_results=10)

# 高级搜索（带过滤）
client.search(
    query="transformer",
    year_from=2020,
    year_to=2024,
    sort_by="date"
)

步骤 3: 处理结果#

python

# 解析结果
papers = client.parse_results(search_data)

# 检查 PDF 可用性
for paper in papers:
    if 'pdf_link' in paper:
        print(f"可下载: {paper['title']}")

步骤 4: 下载文件#

python

# 单个文件下载
client.download_pdf(pdf_url, "paper.pdf")

# 批量搜索和下载
result = client.search_and_download(
    query="reinforcement learning",
    download_dir="./papers",
    max_papers=5
)

使用示例#

示例 1: 简单文献调研#

python

# 搜索某个主题的最新论文
client = GoogleScholarSearch()
results = client.search("quantum machine learning", num_results=15, sort_by="date")
papers = client.parse_results(results)

print(f"找到 {len(papers)} 篇相关论文")
for i, paper in enumerate(papers[:5]):
    print(f"{i+1}. {paper['title']} ({paper['year']}) - {paper['cited_by']} 次引用")

示例 2: 下载特定年份的论文#

python

# 下载 2020-2023 年的论文
result = client.search_and_download(
    query="computer vision",
    download_dir="./cv_papers",
    max_papers=10,
    year_from=2020,
    year_to=2023
)

print(f"成功下载 {result['successful_downloads']} 篇论文")

示例 3: 命令行使用#

bash

# 直接运行脚本
python scripts/google_scholar_search.py "artificial intelligence" --num 10 --output ./ai_papers

SerpAPI 配置#

API 密钥和计划#

• 免费计划: 每月 250 次搜索，50次/小时吞吐量
• Starter: $25/月，1000次搜索，200次/小时
• Developer: $75/月，5000次搜索，1000次/小时
• Production: $150/月，15000次搜索，3000次/小时
• Big Data: $275/月，30000次搜索，6000次/小时

重要限制#

• 每页结果: 1-20 条（ num 参数）
• 分页: 通过 start 参数（0, 10, 20...）
• 缓存: 默认启用，1小时有效期
• 异步模式: 支持异步请求 ( async 参数)
• 输出格式: JSON（默认）或原始HTML

搜索参数详解#

• q: 搜索查询（支持 author:, source: 语法）
• num: 每页结果数（1-20，默认10）
• start: 分页起始位置（0, 10, 20...）
• as_ylo/ as_yhi: 年份范围过滤
• scisbd: 排序方式（0=相关性, 1=日期仅摘要, 2=日期全部）
• hl: 语言代码（en, zh-CN, ja 等）
• as_vis: 是否包含引用（0=包含, 1=排除）
• as_rr: 是否仅显示综述文章（0=全部, 1=仅综述）
• cites: 搜索引用特定文章的文献
• cluster: 搜索文章的所有版本

下载设置#

• download_dir: 下载目录（默认 "./downloads"）
• 自动创建目录
• 文件按论文标题命名

错误处理#

常见问题#

1. API 密钥错误: 检查密钥是否正确设置
2. 额度不足: 免费计划每月 100 次搜索
3. 网络问题: 检查网络连接和代理设置
4. PDF 不可用: 并非所有论文都有公开 PDF

调试建议#

python

import logging
logging.basicConfig(level=logging.DEBUG)

try:
    results = client.search("test query")
except Exception as e:
    print(f"错误详情: {e}")
    # 检查环境变量
    print(f"API Key: {os.getenv('SERP_API_KEY')}")

最佳实践#

搜索优化#

1. 使用具体、相关的关键词
2. 添加引号进行精确匹配
3. 合理设置结果数量避免超限
4. 使用年份过滤获取最新研究

资源管理#

1. 缓存常用搜索结果
2. 分批处理大量请求
3. 定期清理下载目录
4. 备份重要论文

合规使用#

1. 仅用于个人学术研究
2. 尊重版权和访问条款
3. 不要大规模批量下载
4. 遵守目标网站的 robots.txt

资源文件#

scripts/ 目录#

包含可执行的 Python 脚本：

1. google_scholar_search.py - 核心搜索和下载脚本
   • 主要功能类 GoogleScholarSearch
   • 支持搜索、解析、下载完整流程
   • 命令行接口
2. config_example.py - 配置和使用示例
   • 基础搜索示例
   • PDF 下载示例
   • 高级搜索示例
3. requirements.txt - 依赖包列表
   • google-search-results: SerpAPI Python 客户端
   • requests: HTTP 请求库

references/ 目录#

包含详细参考文档：

1. api_guide.md - API 使用指南

   • SerpAPI 密钥获取
   • 搜索参数详解
   • 结果字段说明
   • 错误处理和最佳实践

文件结构#

text

google-scholar-api/
├── SKILL.md (本文件)
├── scripts/
│   ├── google_scholar_search.py (核心脚本)
│   ├── config_example.py (配置示例)
│   └── requirements.txt (依赖列表)
└── references/
    └── api_guide.md (API 指南)

使用提示#

在 OpenClaw 中使用#

当用户请求搜索学术论文时：

1. 检查是否设置了 SERP_API_KEY 环境变量
2. 使用 scripts/google_scholar_search.py 执行搜索
3. 根据需要下载 PDF 文件
4. 提供格式化的搜索结果

常见用户请求模式#

• "帮我搜索关于机器学习的论文"
• "下载最近3年关于深度学习的PDF"
• "查找引用次数超过1000的经典论文"
• "批量下载某个研究主题的相关文献"

响应格式建议#

markdown

## 搜索结果：机器学习

找到 15 篇相关论文，其中 8 篇有 PDF 可用：

1. **Attention Is All You Need** (2017)
   - 作者：Vaswani et al.
   - 引用：125,000+
   - PDF: ✅ 可用
   - 下载：`python scripts/google_scholar_search.py "Attention Is All You Need"`

2. **Deep Residual Learning for Image Recognition** (2015)
   - 作者：He et al.
   - 引用：85,000+
   - PDF: ✅ 可用
   - 下载：`python scripts/google_scholar_search.py "Deep Residual Learning"`

...

注意事项#

限制和约束#

1. API 限制: SerpAPI 免费计划每月 100 次搜索
2. PDF 可用性: 并非所有论文都有公开 PDF
3. 下载速度: 受网络和服务器响应影响
4. 版权遵守: 仅用于个人学术研究

扩展建议#

如需更多功能，可考虑：

1. 集成其他学术数据库（arXiv、PubMed 等）
2. 添加引用管理功能（BibTeX 导出）
3. 实现论文推荐系统
4. 添加文献综述自动生成

---

技能维护: 定期检查 SerpAPI 的 API 变化，更新脚本以保持兼容性。