google-scholar-api

# 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 密钥获取 - 搜索参数详解 - 结果字段说明 - 错误处理和最佳实践 ## 文件结构 ``` 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 变化，更新脚本以保持兼容性。