alterlab-parallel-web

Parallel Web Systems API

概述

此技能可调用 Parallel Web Systems API 进行网页搜索、深度研究和内容提取。在科学写作工作流中，它是获取一般网络信息的默认工具，适用于新闻、市场和技术数据以及文档；学术论文检索则使用 alterlab-research-lookup。

主要接口： Chat API（Beta，兼容 OpenAI，POST /v1beta/chat/completions），用于搜索和研究。 次要接口： Extract API v1（POST /v1/extract），用于 URL 验证和特殊情况。

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

何时使用此技能

在以下情形使用此技能：

• 网页搜索：需要从互联网获取最新信息的查询
• 深度研究：针对某个主题的全面多来源研究报告
• 市场研究：行业分析、竞争情报、市场数据
• 时事：新闻、近期动态、公告
• 技术信息：文档、规格、产品详情
• 统计数据：市场规模、增长率、行业数据

仅在验证引用（确认特定 URL 的内容）以及需要从已知 URL 获取原始内容时使用 Extract API。

不适用情形

情形	改用
查找可引用的同行评审论文；学术查询会自动路由到 Perplexity	alterlab-research-lookup
明确需要 Perplexity Sonar 模型（例如 sonar-pro-search）	alterlab-perplexity
Google Scholar / PubMed 查询以及 DOI → BibTeX 转换	alterlab-citation-mgmt
咨询风格的市场研究报告（框架、LaTeX、50+ 页）	alterlab-market-research
使用 PRISMA 筛选的系统性文献综述	alterlab-literature-review

---

三种能力

1. 网页搜索（search 命令）

通过 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：要使用的 Chat 模型（默认 base，也可使用更深入研究的 core）
• -o：输出文件路径
• --json：以 JSON 格式输出

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

2. 深度研究（research 命令）

通过 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：要使用的 Chat 模型（深度研究默认使用 core，也可使用 base 以更快获取结果）
• -o：输出文件路径
• --json：以 JSON 格式输出

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

从指定 URL 提取内容（每次最多 20 个）。用于验证引用和处理特殊情况；一般研究请使用 search 或 research。

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

# Also return the full page as markdown (excerpts are always returned)
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 覆盖默认值

Parallel 还提供了该脚本未封装的 API（参见 references/api_reference.md）：Search API v1（提供带摘录的排序 URL，支持 turbo/fast/basic/advanced 模式及域名来源策略）、Task API（使用从 lite 到 ultra8x 的处理器进行异步深度研究），以及 Responses API（兼容 OpenAI Responses，使用模型 parallel，支持 reasoning.effort 的 low/medium/high 选项；于 2026 年 7 月推出，Parallel 文档中的 Chat API 快速入门现已重定向至该 API）。需要指定域名、结构化输出或异步运行时，可通过 parallel-web SDK 或 HTTP 调用这些 API。

---

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

每次调用时都传入指向 sources/ 的 -o：

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

# Deep research
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)
python scripts/parallel_web.py extract "https://example.com/article" --objective "key findings" \
  -o sources/extract_20250217_143500_example_article.md

开始新查询前，检查是否已有相关结果（ls sources/），如有则重新阅读，而不要再次调用 API。保存后，记录该文件：

[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

---

路由

任务	工具
网页搜索、时事、市场/技术查询	parallel_web.py search（此技能）
综合研究报告	parallel_web.py research --model core（此技能）
引文验证 / 已知 URL 的 DOI 元数据	parallel_web.py extract（此技能）
学术论文检索（用于引用的同行评审期刊）	alterlab-research-lookup（路由至 Perplexity）
Google Scholar / PubMed / CrossRef 数据库搜索	alterlab-citation-mgmt

撰写科学文档时：起草章节前，先用 search/research 收集背景信息；用 extract 验证任何具体 URL；纯学术论文搜索则路由至 alterlab-research-lookup。先检查 sources/，并将每项结果保存回该文件夹。

---

环境设置

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

# Python packages
uv pip install openai          # Chat API (search/research)
uv pip install parallel-web    # Extract API v1 (>= 1.0; imports as `parallel`)
# Or run ad hoc without a venv:
#   uv run --with openai --with parallel-web scripts/parallel_web.py search "query"

在 https://platform.parallel.ai 获取 API 密钥。该脚本会将你的查询和 URL 发送到 Parallel 的服务器。

---

错误处理

该脚本会返回结构化错误响应，而不是抛出异常：

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

常见问题：

• PARALLEL_API_KEY not set：设置该环境变量
• openai not installed：运行 uv pip install openai
• parallel-web not installed：运行 uv pip install parallel-web（仅提取操作需要）
• 'BetaResource' object has no attribute 'extract'：旧版脚本调用了 parallel-web 1.0 中已移除的 Beta 方法——请使用此技能的当前脚本（client.extract()）
• 超出速率限制：等待后重试（默认值：Chat 每分钟 300 次请求，Extract 每分钟 600 次请求）

---

配套技能

有关 alterlab-research-lookup（学术论文）和 alterlab-citation-mgmt（Scholar/PubMed/CrossRef），请参阅上方的路由表。另外：

技能	用途
alterlab-literature-review	跨学术数据库开展系统性文献综述
alterlab-scientific-schematics	根据研究发现生成示意图

属于 AlterLab Academic Skills 套件的一部分。