Perplexity 研究

由 Perplexity Agent API 驱动的研究助手，具备网络搜索与推理能力。

快速开始

Perplexity 客户端位于本技能文件夹下的 scripts/perplexity_client.py。

默认模型：openai/gpt-5.2（GPT 最新版本）

核心能力：

• 网络搜索以获取最新信息
• 高推理强度，支持深度分析
• 多模型对比
• 流式响应
• 成本追踪

常见研究模式

1. 深度研究查询

适用于需结合网络搜索与深度推理的综合性分析：

# 从技能脚本目录导入
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent / "scripts"))
from perplexity_client import PerplexityClient

client = PerplexityClient()
result = client.research_query(
    query="您的研究问题",
    model="openai/gpt-5.2",
    reasoning_effort="high",
    max_tokens=2000
)

if "error" not in result:
    print(result["answer"])
    print(f"Tokens: {result['tokens']}, Cost: ${result['cost']}")

2. 快速网络搜索

适用于对时效性或当前事件信息有较高要求的场景：

result = client.search_query(
    query="关于当前事件的问题",
    model="openai/gpt-5.2",
    max_tokens=1000
)

3. 模型对比

适用于输出质量至关重要的场景：

results = client.compare_models(
    query="您的问题",
    models=["openai/gpt-5.2", "anthropic/claude-3-5-sonnet", "google/gemini-2.0-flash"],
    max_tokens=300
)

for result in results:
    if "error" not in result:
        print(f"\n{result['model']}: {result['answer']}")

4. 长响应流式处理

适用于需提升用户体验的长篇幅分析场景：

client.stream_query(
    query="您的问题",
    model="openai/gpt-5.2",
    use_search=True,
    max_tokens=2000
)

研究工作流

开展研究时建议遵循以下流程：

1. 初步探索：启用网络搜索，调用 research_query()
2. 验证发现：使用 compare_models() 在多个模型间比对关键结论
3. 深入挖掘：针对特定维度启用流式响应进行详细分析
4. 成本意识：在返回结果中持续监控 token 使用量与费用

模型选择

默认模型：openai/gpt-5.2（GPT 最新版本）

可选替代模型：

• anthropic/claude-3-5-sonnet —— 推理能力强，性能均衡
• google/gemini-2.0-flash —— 响应速度快，成本效益高
• meta/llama-3.3-70b —— 开源替代方案

根据以下因素切换模型：

• 质量需求（追求最佳效果时选用 GPT-5.2）
• 速度要求（需快速响应时选用 Gemini Flash）
• 成本约束（参考返回结果中的 cost 字段进行比对）

推理强度等级

通过 reasoning_effort 参数控制分析深度：

• "low" —— 快速回答，最小化推理开销
• "medium" —— 平衡型推理（大多数查询的默认设置）
• "high" —— 深度分析，全面研究（推荐用于研究类任务）

环境配置

请确保已设置 PERPLEXITY_API_KEY：

export PERPLEXITY_API_KEY='your_api_key_here'

或在技能的 scripts/ 目录下创建 .env 文件：

PERPLEXITY_API_KEY=your_api_key_here

错误处理

所有方法均返回包含错误信息的对象：

result = client.research_query("您的问题")

if "error" in result:
    print(f"Error: {result['error']}")
    # 合理处理错误
else:
    # 处理成功响应
    print(result["answer"])

成本优化建议

• 使用 max_tokens 限制响应长度
• 优先尝试较低推理强度，必要时再提升
• 对于简单问题，优先使用 search_query() 而非 research_query()
• 通过 result["cost"] 字段实时监控费用

集成示例

投资研究

client = PerplexityClient()

# 市场分析
result = client.research_query(
    query="分析 AI 芯片市场的近期发展及主要竞争者",
    reasoning_effort="high"
)

# 公司深度调研
result = client.search_query(
    query="英伟达 2025 财年第四季度最新财报"
)

# 多模型交叉验证
results = client.compare_models(
    query="半导体行业面临的主要风险有哪些？",
    models=["openai/gpt-5.2", "anthropic/claude-3-5-sonnet"]
)

趋势分析

# 结合网络搜索获取当前趋势
result = client.research_query(
    query="可持续投资与 ESG 采纳率的新兴趋势",
    reasoning_effort="high",
    max_tokens=2000
)

# 流式获取实时进展
client.stream_query(
    query="量子计算商业化领域的最新进展",
    use_search=True
)

多轮次研究

# 在多次查询中构建上下文
messages = [
    {"role": "user", "content": "核聚变能源目前处于什么发展阶段？"},
    {"role": "assistant", "content": "...上一轮响应内容..."},
    {"role": "user", "content": "该领域有哪些领先企业？"}
]

result = client.conversation(
    messages=messages,
    use_search=True
)

最佳实践

1. 默认使用 research_query() —— 大多数研究任务应首选该方法，它同时启用网络搜索与高推理强度
2. 启用流式响应 —— 面向终端用户的应用中，应使用流式响应展示处理进度
3. 执行模型对比 —— 对关键决策或质量敏感型任务，务必进行多模型比对
4. 合理设定 max_tokens —— 摘要类任务建议设为 1000；深度分析建议 ≥2000
5. 持续追踪成本 —— 通过 result["cost"] 和 result["tokens"] 字段获取用量数据
6. 优雅处理错误 —— 始终检查返回结果中是否存在 "error" 键

API 参考文档

完整 API 文档请参阅 reference.md，或直接查阅 scripts/perplexity_client.py 获取：

• 全部方法签名
• 其他可选参数
• CLI 使用示例
• 实现细节

命令行使用方式

请在技能根目录下运行：

# 研究模式
python scripts/perplexity_client.py research "您的问题"

# 网络搜索
python scripts/perplexity_client.py search "您的问题"

# 流式响应
python scripts/perplexity_client.py stream "您的问题"

# 多模型对比
python scripts/perplexity_client.py compare "您的问题"