parallel-web

Parallel Web Systems API

概述

此技能可访问 Parallel Web Systems API，用于网页搜索、深度研究和内容提取。它是科学写作工作流中所有网页相关操作的主要工具。

主要接口： Parallel Chat API（兼容 OpenAI），用于搜索和研究。 次要接口： Extract API，仅用于 URL 验证和特殊情况。

API 文档： https://docs.parallel.ai API 密钥： https://platform.parallel.ai 环境变量： PARALLEL_API_KEY

何时使用此技能

对于以下所有情况，请使用此技能：

• 网页搜索：任何需要搜索互联网以获取信息的查询
• 深度研究：针对任何主题撰写全面的研究报告
• 市场研究：行业分析、竞争情报、市场数据
• 时事：新闻、近期进展、公告
• 技术信息：文档、规格、产品详情
• 统计数据：市场规模、增长率、行业数据
• 一般信息：公司简介、事实、比较

仅在以下情况下使用 Extract API：

• 引用验证（确认特定 URL 的内容）
• 需要从已知 URL 获取原始内容的特殊情况

请勿在以下情况下使用此技能：

• 学术专用论文搜索（纯学术查询请使用 research-lookup，它会将查询路由至 Perplexity）
• 搜索 Google Scholar / PubMed 数据库（请使用 citation-management 技能）

---

两种功能

1. 网页搜索（search 命令）

通过 Parallel Chat API（base 模型）搜索网页，并获取带有引用来源的综合摘要。

适用于： 一般网页搜索、时事、事实查找、技术查询、新闻、市场数据。

# Basic search
python scripts/parallel_web.py search "latest advances in quantum computing 2025"

# Use core model for more complex queries
python scripts/parallel_web.py search "compare EV battery chemistries NMC vs LFP" --model core

# Save results to file
python scripts/parallel_web.py search "renewable energy policy updates" -o results.txt

# JSON output for programmatic use
python scripts/parallel_web.py search "AI regulation landscape" --json -o results.json

关键参数：

• objective：用自然语言描述你想查找的内容
• --model：要使用的聊天模型（默认为 base，也可使用 core 进行更深入的研究）
• -o：输出文件路径
• --json：以 JSON 格式输出

响应内容包括： 按主题整理的综合摘要，包含文内引用和来源列表。

2. 深度研究（research 命令）

通过 Parallel Chat API（core 模型）开展全面的多来源研究，生成带引用的详细情报报告。

适用于： 市场研究、全面分析、竞争情报、技术调查、行业报告，以及任何需要综合多个来源的研究问题。

# Default deep research (core model)
python scripts/parallel_web.py research "comprehensive analysis of the global EV battery market"

# Save research report to file
python scripts/parallel_web.py research "AI adoption in healthcare 2025" -o report.md

# Use base model for faster, lighter research
python scripts/parallel_web.py research "latest funding rounds in AI startups" --model base

# JSON output
python scripts/parallel_web.py research "renewable energy storage market in Europe" --json -o data.json

关键参数：

• query：研究问题或主题
• --model：要使用的聊天模型（深度研究默认为 core，也可使用 base 以获得更快结果）
• -o：输出文件路径
• --json：以 JSON 格式输出

3. URL 提取（extract 命令）— 仅用于验证

从特定 URL 提取内容。仅用于引用验证和特殊情况。

一般研究请改用 search 或 research。

# Verify a citation's content
python scripts/parallel_web.py extract "https://example.com/article" --objective "key findings"

# Get full page content for verification
python scripts/parallel_web.py extract "https://docs.example.com/api" --full-content

# Save extraction to file
python scripts/parallel_web.py extract "https://paper-url.com" --objective "methodology" -o extracted.md

---

模型选择指南

Chat API 支持两种研究模型。大多数搜索请使用 base，深度研究请使用 core。

模型	延迟	优势	使用场景
base	15s-100s	标准研究、事实性查询	网页搜索、快速查询
core	60s-5min	复杂研究、多来源综合	深度研究、全面报告

建议：

• search 命令默认使用 base——速度快，适用于大多数查询
• research 命令默认使用 core——研究透彻，适用于全面报告
• 需要调整研究深度与速度时，可使用 --model 覆盖默认值

---

Python API 用法

搜索

from parallel_web import ParallelSearch

searcher = ParallelSearch()
result = searcher.search(
    objective="Find latest information about transformer architectures in NLP",
    model="base",
)

if result["success"]:
    print(result["response"])  # Synthesized summary
    for src in result["sources"]:
        print(f"  {src['title']}: {src['url']}")

深度研究

from parallel_web import ParallelDeepResearch

researcher = ParallelDeepResearch()
result = researcher.research(
    query="Comprehensive analysis of AI regulation in the EU and US",
    model="core",
)

if result["success"]:
    print(result["response"])  # Full research report
    print(f"Citations: {result['citation_count']}")

提取（仅用于验证）

from parallel_web import ParallelExtract

extractor = ParallelExtract()
result = extractor.extract(
    urls=["https://docs.example.com/api-reference"],
    objective="API authentication methods and rate limits",
)

if result["success"]:
    for r in result["results"]:
        print(r["excerpts"])

---

强制要求：将所有结果保存到 Sources 文件夹

每次网页搜索和深度研究的结果都必须保存到项目的 sources/ 文件夹中。

这样可确保所有研究内容都得到保留，以便复现、审计和恢复上下文窗口。

保存规则

操作	-o 标志目标	文件名模式
网页搜索	sources/search_<topic>.md	search_YYYYMMDD_HHMMSS_<brief_topic>.md
深度研究	sources/research_<topic>.md	research_YYYYMMDD_HHMMSS_<brief_topic>.md
URL 提取	sources/extract_<source>.md	extract_YYYYMMDD_HHMMSS_<brief_source>.md

如何保存（始终使用 -o 标志）

重要：每次调用 parallel_web.py 时都必须包含 -o 标志，并将目标指向 sources/ 文件夹。

# Web search — ALWAYS save to sources/
python scripts/parallel_web.py search "latest advances in quantum computing 2025" \
  -o sources/search_20250217_143000_quantum_computing.md

# Deep research — ALWAYS save to sources/
python scripts/parallel_web.py research "comprehensive analysis of the global EV battery market" \
  -o sources/research_20250217_144000_ev_battery_market.md

# URL extraction (verification only) — save to sources/
python scripts/parallel_web.py extract "https://example.com/article" --objective "key findings" \
  -o sources/extract_20250217_143500_example_article.md

为什么要保存所有内容

1. 可复现性：最终文档中的每项主张都可以追溯到原始资料
2. 上下文窗口恢复：如果任务过程中上下文被压缩，可以从 sources/ 重新读取已保存的结果
3. 审计追踪：sources/ 文件夹完整展示了信息的收集过程
4. 跨章节复用：多个章节可以引用已保存的研究结果，无需重复调用 API
5. 成本效益：检查 sources/ 中是否已有结果，避免冗余的 API 调用
6. 支持同行评审：评审人员可以核实每项主张所依据的研究

日志记录

保存研究结果时，务必记录：

[HH:MM:SS] SAVED: Search results to sources/search_20250217_143000_quantum_computing.md
[HH:MM:SS] SAVED: Deep research report to sources/research_20250217_144000_ev_battery_market.md

发起新查询前，先检查 Sources

调用 parallel_web.py 前，检查 sources/ 中是否已有相关结果：

ls sources/  # Check existing saved results

---

与 Scientific Writer 集成

路由表

任务	工具	命令
网页搜索（任意）	parallel_web.py search	python scripts/parallel_web.py search "query" -o sources/search_<topic>.md
深度研究	parallel_web.py research	python scripts/parallel_web.py research "query" -o sources/research_<topic>.md
引用核验	parallel_web.py extract	python scripts/parallel_web.py extract "url" -o sources/extract_<source>.md
学术论文搜索	research_lookup.py	路由到 Perplexity sonar-pro-search
DOI/元数据查询	parallel_web.py extract	从 DOI URL 提取（用于核验）

撰写科学文档时

1. 撰写任何章节前，使用 search 或 research 收集背景信息——将结果保存到 sources/
2. 对于学术引用，使用 research-lookup（它会将学术查询路由到 Perplexity）——将结果保存到 sources/
3. 核验引用（确认特定 URL）时，使用 parallel_web.py extract——将结果保存到 sources/
4. 查询当前市场/行业数据时，使用 parallel_web.py research --model core——将结果保存到 sources/
5. 发起任何新查询前，检查 sources/ 中是否已有结果，避免重复调用 API

---

环境设置

# Required: Set your Parallel API key
export PARALLEL_API_KEY="your_api_key_here"

# Required Python packages
pip install openai        # For Chat API (search/research)
pip install parallel-web  # For Extract API (verification only)

在 https://platform.parallel.ai 获取 API 密钥。

---

错误处理

脚本会妥善处理错误，并返回结构化的错误响应：

{
  "success": false,
  "error": "Error description",
  "timestamp": "2025-02-14 12:00:00"
}

常见问题：

• PARALLEL_API_KEY not set：设置该环境变量
• openai not installed：运行 pip install openai
• parallel-web not installed：运行 pip install parallel-web（仅 extract 需要）
• Rate limit exceeded：等待后重试（Chat API 默认速率限制为 300 次请求/分钟）

---

互补技能

技能	用途
research-lookup	学术论文搜索（学术查询会路由到 Perplexity）
citation-management	搜索 Google Scholar、PubMed、CrossRef 数据库
literature-review	跨学术数据库开展系统性文献综述
scientific-schematics	根据研究结果生成图表