alterlab-perplexity

Perplexity 搜索

通过 LiteLLM 和 OpenRouter，使用 Perplexity Sonar 模型进行 AI 网页搜索。Perplexity 会返回基于实时网页信息、带有来源引用的回答，非常适合查询最新信息、近期文献以及超出模型训练截止时间的事实。一个 OpenRouter 密钥即可用于所有模型；无需单独注册 Perplexity 账号。

何时使用此技能

适用于：最新动态、近期发表的文献、带引用的回答、根据当前来源核实说法，或任何超出训练截止时间的信息。

不适用于：算术／逻辑、代码执行，或训练数据中已有的事实（直接回答）。

不适用场景

场景	改用
不确定该用哪个搜索后端；希望自动路由并将结果保存到 sources/	alterlab-research-lookup
使用 Parallel 进行一般网页、市场或技术研究，或提取已知 URL 的内容	alterlab-parallel-web
获取每篇论文的结构化实验数据（样本量、效应量、质量评分）	alterlab-bgpt-search
通过 MeSH 词或 PMID 对生物医学数据库进行可复现的搜索	alterlab-pubmed

设置（一次性）

# 1. Get a key at https://openrouter.ai/keys and add credits ($5+ recommended)
# 2. Configure (either form works; setup_env.py writes .env with owner-only permissions)
export OPENROUTER_API_KEY='sk-or-v1-your-key-here'
python scripts/setup_env.py --api-key sk-or-v1-your-key-here   # writes .env

# 3. Install LiteLLM
uv pip install litellm

# 4. Verify
python scripts/perplexity_search.py --check-setup

--check-setup 会读取当前环境，而非 .env。运行 setup_env.py 后，请使用 set -a; source .env; set +a 加载文件（单独运行 source 不会导出变量），或使用 python-dotenv，以确保变量确实在作用域内。请让用户自行设置密钥，不要让他们将密钥粘贴到对话中。完整的设置、安全和故障排除说明请参阅 references/openrouter_setup.md。

基本用法

python scripts/perplexity_search.py "What are the latest developments in CRISPR gene editing?"
python scripts/perplexity_search.py "Recent CAR-T therapy clinical trials" --output results.json
python scripts/perplexity_search.py "Compare mRNA and viral vector vaccines" --model sonar-pro-search
python scripts/perplexity_search.py "Quantum computing for drug discovery" --verbose

CLI 接受不带前缀的模型名称（例如 sonar-pro）；脚本会自动添加 openrouter/perplexity/ 前缀。

模型

使用 --model 选择模型（或设置 DEFAULT_MODEL）：

模型	适用场景
sonar-pro（默认）	一般研究，兼顾成本与质量
sonar-pro-search	最先进的 Agentic 多步搜索；全面比较。成本最高；仅限 OpenRouter
sonar	简单事实查询、对成本敏感的批量查询
sonar-reasoning-pro	需要明确逐步推理的任务

sonar-reasoning 已在 OpenRouter 上停用（截至 2026-09-23 已不再列出），CLI 也不再接受该模型；过时的 DEFAULT_MODEL=sonar-reasoning 现在会立即报错并给出明确提示。详细的权衡、定价、上下文窗口及以编程方式使用 sonar-deep-research 的说明，请参阅 references/model_comparison.md。

编写优质查询

请具体说明（领域 + 时间范围 + 期望输出）。以下示例效果良好：

• “2024 年发表的 B 细胞淋巴瘤 CAR-T 疗法最新临床试验结果”
• “比较 PyTorch 与 TensorFlow 在 Transformer 训练方面的易用性、性能和生态系统，并参考近期基准测试”
• “间歇性禁食对 2 型糖尿病成人 HbA1c 的影响证据；重点关注随机对照试验”

添加来源偏好（如“同行评审”“clinicaltrials.gov”“FDA 批准”），可获得质量更高、依据更充分的回答。完整的查询设计模式、领域模板和常见问题见 references/search_strategies.md。

编程访问

from scripts.perplexity_search import search_with_perplexity

result = search_with_perplexity(
    query="What are the latest CRISPR developments?",
    model="openrouter/perplexity/sonar-pro",  # full path required when calling directly
    max_tokens=4000,
    temperature=0.2,
)
if result["success"]:
    print(result["answer"])
    print(f"Tokens: {result['usage']['total_tokens']}")
else:
    print(f"Error: {result['error']}")

保存的 JSON（--output）包含 answer、model、usage 和 citations 字段。citations 是去重后的 {url, title} 列表，汇集自 OpenRouter 的 url_citation 注释以及 Perplexity 的 citations／search_results 字段；仅当模型返回来源时才会提供。可使用 jq '.answer' 或 jq '.citations[].url' 进行处理。请引用底层来源，而不是 Perplexity；引用任何来源时都应打开原文：回答是生成的摘要，可能会错误归属某项说法。

费用

按 token 计费（sonar-pro-search 另收取每次请求费用）；每次查询的大致费用从低到高为：sonar < sonar-pro < sonar-reasoning-pro < sonar-pro-search。选择与查询相匹配的模型、限制 --max-tokens，并在 OpenRouter 控制面板中设置支出上限，以控制费用。在 https://openrouter.ai/activity 查看用量。具体费率：references/model_comparison.md 和 https://openrouter.ai/perplexity。

环境变量

• OPENROUTER_API_KEY（必需）
• DEFAULT_MODEL（默认为 sonar-pro）、DEFAULT_MAX_TOKENS（默认为 4000）、DEFAULT_TEMPERATURE（默认为 0.2）——作为 CLI 默认值生效；可在每次调用时通过相应的标志覆盖。

资源

• scripts/perplexity_search.py — 搜索 CLI／可导入函数
• scripts/setup_env.py — 密钥设置与验证
• references/openrouter_setup.md — 设置、安全与故障排查
• references/model_comparison.md — 模型选择与定价
• references/search_strategies.md — 查询设计
• assets/.env.example — 环境模板

属于 AlterLab Academic Skills 套件。