Perplexity AI

Perplexity AI 是一个 Python 模块，利用 Emailnator 自动生成 Gmail 账户，从而实现无限次 Pro 查询。它同时支持同步（synchronous）和异步（asynchronous）API，并提供 Web 界面，方便偏好图形用户界面（GUI）的用户使用。

功能特性

• 账户生成：通过 Emailnator 自动创建 Gmail 账户
• 无限 Pro 查询：通过创建新账户绕过查询次数限制
• Web 界面：通过浏览器自动化账户创建与使用
• 同步与异步 API：完整支持同步和异步编程模式
• 类型安全：提供完整的类型提示（type hints），提升 IDE 支持体验
• 健壮的错误处理：自定义异常，便于错误管理
• 全面的日志记录：结构化日志，便于调试
• 文件上传：支持文档分析与问答
• 流式响应：实时流式返回响应内容
• 重试机制：自动重试并采用指数退避策略（exponential backoff）
• 速率限制：内置限速机制，防止滥用

安装

基础安装

pip install -e .

含驱动支持（用于 Web 界面）

pip install -e ".[driver]"
patchright install chromium

含 MCP 服务器支持

pip install -e ".[mcp]"

开发环境安装

pip install -e ".[dev]"

此安装包含测试工具（pytest、pytest-cov、pytest-asyncio）、代码格式化与检查工具（flake8、black、isort、mypy）以及所有可选依赖项。

MCP 服务器

本项目包含一个 MCP（Model Context Protocol，模型上下文协议）服务器，可将 Perplexity 搜索功能作为工具暴露给 Claude Code 等 MCP 客户端使用。该服务器无需 API 密钥，而是通过与本库其他部分相同的逆向工程 Web 接口实现功能。

安装

pip install -e ".[mcp]"

启动服务器

服务器支持两种传输方式，由环境变量 MCP_TRANSPORT 控制（默认为 stdio）。

stdio（默认）

适用于本地 MCP 客户端，如 Claude Code 和 Claude Desktop。客户端会直接启动该进程。

perplexity-mcp

添加到 Claude Code：

claude mcp add perplexity -- perplexity-mcp

手动配置示例：

{
  "mcpServers": {
    "perplexity": {
      "command": "perplexity-mcp",
      "env": {
        "PERPLEXITY_COOKIES": "{\"next-auth.session-token\": \"...\"}"
      }
    }
  }
}

HTTP（网络/远程）

启动一个持久化的 HTTP 服务器，允许多个客户端通过网络连接。适用于在多台客户端或机器间共享同一个服务器实例的场景。

1. 启动服务器：

MCP_TRANSPORT=http perplexity-mcp

默认监听 127.0.0.1:8000。若需绑定所有接口或更改端口：

MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=9000 perplexity-mcp

若需包含 Cookie：

MCP_TRANSPORT=http PERPLEXITY_COOKIES='{"next-auth.session-token": "..."}' perplexity-mcp

MCP 端点将可通过 http://<host>:<port>/mcp 访问。

2. 添加到 Claude Code：

claude mcp add --transport http perplexity http://127.0.0.1:8000/mcp

如果更改了主机或端口，请相应调整 URL。对于远程机器，请将 127.0.0.1 替换为其实际地址。

3. 验证配置：

claude mcp list

---

PERPLEXITY_COOKIES 环境变量对两种传输方式均为可选。若未设置，服务器将以匿名模式运行，仅能访问免费（auto 模式）查询功能。若设置为有效的 Perplexity Cookie JSON 字符串，则可启用 Pro、推理（reasoning）和深度研究（deep research）模式。获取 Cookie 的方法请参见 如何获取 Cookie。

可用工具

工具	模式	描述
perplexity_ask	auto	通用问答
perplexity_research	deep research	对主题进行深入研究
perplexity_reason	reasoning	分步推理解决问题
perplexity_search	pro + 网络来源	网络搜索

与官方 MCP 的差异

官方 @perplexity-ai/mcp-server 需要付费的 Perplexity API 密钥，而本服务器使用的是逆向工程的 Web 接口。因此，以下官方 MCP 支持的功能在本服务器中不支持：

功能	官方 MCP	本服务器
无需 API 密钥	否	是
messages 数组输入	是	否（仅支持单个 query 字符串）
search_recency_filter	是	否
search_domain_filter	是	否
search_context_size	是	否
reasoning_effort	是	否
strip_thinking	是	否
结构化搜索结果（引用、图片等）	是	否（仅返回纯文本答案）

快速开始

基础用法

import perplexity

# 创建客户端
client = perplexity.Client()

# 发起查询
response = client.search("什么是人工智能？")
print(response['answer'])

使用账户（启用增强功能）

import perplexity

# 你的 Perplexity Cookie
cookies = {
    'next-auth.csrf-token': 'your-token',
    'next-auth.session-token': 'your-session',
}

client = perplexity.Client(cookies)

# 使用增强模式
response = client.search(
    "复杂的查询内容",
    mode='pro',
    model='gpt-5.2',
    sources=['scholar']
)

流式响应

for chunk in client.search("解释量子计算", stream=True):
    if 'answer' in chunk:
        print(chunk['answer'], end='', flush=True)

异步用法

import asyncio
import perplexity_async

async def main():
    client = await perplexity_async.Client()
    response = await client.search("什么是机器学习？")
    print(response['answer'])

asyncio.run(main())

文档

• 示例 - 常见使用场景的实用示例
• 更新日志 - Bug 修复与变更历史
• 改进计划 - 建议的改进方向与路线图
• API 参考 - 完整的 API 文档

使用说明

Web 界面

Web 界面在浏览器中自动完成账号创建和使用。Patchright 使用 "Chrome 用户数据目录" 来实现完全无痕，Windows 系统下的路径为 C:\Users\YourName\AppData\Local\Google\Chrome\User Data，如下所示：

import os
from perplexity.driver import Driver

cli = Driver()
cli.run(rf'C:\\Users\\{os.getlogin()}\\AppData\\Local\\Google\\Chrome\\User Data')

若要使用你自己的 Chrome 实例，请启用远程调试（在 Cloudflare 中可能会陷入死循环）：

1. 在 Chrome 快捷方式的目标中添加 --remote-debugging-port=9222。
2. 将端口传递给 Driver.run() 方法：

cli.run(rf'C:\\Users\\{os.getlogin()}\\AppData\\Local\\Google\\Chrome\\User Data', port=9222)

API 使用

同步 API

以下是一个简单用法的示例代码，不使用自有账号，也不生成新账号。

import perplexity

perplexity_cli = perplexity.Client()

# model = 模式对应的模型，仅限自有账号使用，取值如下：
#     'auto': [None],
#     'pro': [None, 'sonar', 'gpt-5.2', 'claude-4.5-sonnet', 'grok-4-1'],
#     'reasoning': [None, 'gpt-5.2-thinking', 'claude-4.5-sonnet-thinking', 'gemini-3.0-pro', 'kimi-k2-thinking', 'grok-4.1-reasoning'],
#     'deep research': [None]
# sources = ['web', 'scholar', 'social']
# files = 字典，键为文件名，值为文件内容
# stream = 启用时返回生成器，禁用时仅返回最终响应
# language = 所需语言的 ISO 639 代码
# follow_up = 用于后续查询的上一次查询信息，可直接传入前一次查询的响应，见下方第二个示例
# incognito = 启用无痕模式，适用于使用自有账号的用户
resp = perplexity_cli.search('Your query here', mode='auto', model=None, sources=['web'], files={}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)

# 第二个示例展示如何使用后续查询和流式响应
for i in perplexity_cli.search('Your query here', stream=True, follow_up=resp):
    print(i)

以下是使用自有账号的方式，你需要获取自己的 cookies 才能使用自有账号。参见 如何获取 Cookies：

import perplexity

perplexity_cookies = { 
    <your cookies here>
}

perplexity_cli = perplexity.Client(perplexity_cookies)

resp = perplexity_cli.search('Your query here', mode='reasoning', model='gpt-5.2-thinking', sources=['web'], files={'myfile.txt': open('file.txt').read()}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)

最后是账号生成功能，你需要获取 Emailnator 的 cookies 才能使用此功能。参见 如何获取 Cookies：

import perplexity

emailnator_cookies = { 
    <your cookies here>
}

perplexity_cli = perplexity.Client()
perplexity_cli.create_account(emailnator_cookies) # 创建一个新的 Gmail 账号，从而重置你的 5 次 Pro 查询额度。

resp = perplexity_cli.search('Your query here', mode='reasoning', model=None, sources=['web'], files={'myfile.txt': open('file.txt').read()}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)

异步 API

以下是一个简单用法的示例代码，不使用自有账号，也不生成新账号。

import asyncio
import perplexity_async

async def test():
    perplexity_cli = await perplexity_async.Client()

    # mode = ['auto', 'pro', 'reasoning', 'deep research']
    # model = 模式对应的模型，仅限自有账号使用，取值如下：
    #     'auto': [None],
    #     'pro': [None, 'sonar', 'gpt-5.2', 'claude-4.5-sonnet', 'grok-4-1'],
    #     'reasoning': [None, 'gpt-5.2-thinking', 'claude-4.5-sonnet-thinking', 'gemini-3.0-pro', 'kimi-k2-thinking', 'grok-4.1-reasoning'],
    #     'deep research': [None]
    # sources = ['web', 'scholar', 'social']
    # files = 字典，键为文件名，值为文件内容
    # stream = 启用时返回生成器，禁用时仅返回最终响应
    # language = 所需语言的 ISO 639 代码
    # follow_up = 用于后续查询的上一次查询信息，可直接传入前一次查询的响应，见下方第二个示例
    # incognito = 启用无痕模式，适用于使用自有账号的用户
    resp = await perplexity_cli.search('Your query here', mode='auto', model=None, sources=['web'], files={}, stream=False, language='en-US', follow_up=None, incognito=False)
    print(resp)

    # 第二个示例展示如何使用后续查询和流式响应
    async for i in await perplexity_cli.search('Your query here', stream=True, follow_up=resp):
        print(i)

asyncio.run(test())

以下是使用自有账号的方式，你需要获取自己的 cookies 才能使用自有账号。参见 如何获取 Cookies：

import asyncio
import perplexity_async

perplexity_cookies = { 
    <your cookies here>
}

async def test():
    perplexity_cli = await perplexity_async.Client(perplexity_cookies)

    resp = await perplexity_cli.search('Your query here', mode='reasoning', model='gpt-5.2-thinking', sources=['web'], files={'myfile.txt': open('file.txt').read()}, stream=False, language='en-US', follow_up=None, incognito=False)
    print(resp)

asyncio.run(test())

最后是账号生成功能，你需要获取 emailnator 的 cookies 才能使用此功能。参见 如何获取 Cookies：

import asyncio
import perplexity_async

emailnator_cookies = { 
    <your cookies here>
}

async def test():
    perplexity_cli = await perplexity_async.Client()
    await perplexity_cli.create_account(emailnator_cookies) # 创建一个新的 Gmail 账号，从而重置你的 5 次 Pro 查询额度。

    resp = await perplexity_cli.search('Your query here', mode='reasoning', model=None, sources=['web'], files={'myfile.txt': open('file.txt').read()}, stream=False, language='en-US', follow_up=None, incognito=False)
    print(resp)

asyncio.run(test())

如何获取 Cookies

Perplexity（用于使用自有账号）

• 打开 Perplexity.ai 网站并登录你的账号。
• 按下 F12 或 Ctrl + Shift + I 打开检查器（Inspector）。
• 在检查器中切换到 "Network"（网络）标签页。
• 刷新页面，右键点击第一个请求，将鼠标悬停在 "Copy"（复制）上，然后点击 "Copy as cURL (bash)"（以 cURL (bash) 格式复制）。
• 现在前往 CurlConverter，将你复制的代码粘贴进去。Cookies 字典将会显示出来，复制并在你的代码中使用即可。

Emailnator（用于账号生成）

• 打开 Emailnator 网站并完成人机验证。
• 按下 F12 或 Ctrl + Shift + I 打开开发者工具（inspector）。
• 在开发者工具中切换到 "Network"（网络）标签页。
• 刷新页面，右键点击第一个请求，将鼠标悬停在 "Copy"（复制）上，然后点击 "Copy as cURL (bash)"（以 cURL (bash) 格式复制）。
• 现在前往 CurlConverter，将你复制的代码粘贴进去。此时会生成 cookies 字典，请将其复制并在你的代码中使用。
• Emailnator 的 cookies 是临时的，需要持续更新。

API 参考

Client 类

class Client:
    def __init__(self, cookies: Optional[Dict[str, str]] = None):
        """
        初始化 Perplexity 客户端。
        
        Args:
            cookies: 可选的 Perplexity 账号 cookies，用于启用增强功能
        """
    
    def search(
        self,
        query: str,
        mode: str = 'auto',
        model: Optional[str] = None,
        sources: List[str] = ['web'],
        files: Dict[str, Union[str, bytes]] = {},
        stream: bool = False,
        language: str = 'en-US',
        follow_up: Optional[Dict] = None,
        incognito: bool = False
    ) -> Union[Dict, Generator]:
        """
        使用 Perplexity AI 进行搜索。
        
        Args:
            query: 搜索查询内容
            mode: 搜索模式（'auto', 'pro', 'reasoning', 'deep research'）
            model: 使用的模型（取决于 mode）
            sources: 信息来源（['web', 'scholar', 'social']）
            files: 要上传的文件 {文件名: 内容}
            stream: 启用流式响应
            language: ISO 639 语言代码
            follow_up: 用于上下文的上一次查询
            incognito: 启用无痕模式
            
        Returns:
            包含 'answer' 键的响应字典，或当 stream=True 时返回生成器
        """
    
    def create_account(self, emailnator_cookies: Dict[str, str]):
        """
        使用 Emailnator 创建新账号。
        
        Args:
            emailnator_cookies: 用于账号创建的 Emailnator cookies
        """

可用模型

{
    'auto': [None],
    'pro': [None, 'sonar', 'gpt-5.2', 'claude-4.5-sonnet', 'grok-4-1'],
    'reasoning': [None, 'gpt-5.2-thinking', 'claude-4.5-sonnet-thinking', 'gemini-3.0-pro', 'kimi-k2-thinking', 'grok-4.1-reasoning'],
    'deep research': [None]
}

自定义异常

from perplexity.exceptions import (
    PerplexityError,          # 基础异常
    AuthenticationError,      # 认证失败
    RateLimitError,          # 超出速率限制
    NetworkError,            # 网络问题
    ValidationError,         # 参数无效
    ResponseParseError,      # 响应解析失败
    AccountCreationError,    # 账号创建失败
    FileUploadError,         # 文件上传失败
)

测试

运行所有测试

pytest tests/ -v

带覆盖率报告

pytest tests/ --cov=perplexity --cov=perplexity_async --cov-report=html

运行特定测试

pytest tests/test_utils.py -v
pytest tests/test_config.py -v

开发

设置开发环境

# 克隆仓库
git clone https://github.com/yourusername/perplexity-ai.git
cd perplexity-ai

# 以开发模式安装
pip install -e ".[dev]"

# 运行测试
pytest

# 格式化代码
black perplexity perplexity_async

# 类型检查
mypy perplexity perplexity_async

# 代码检查
flake8 perplexity perplexity_async

贡献代码

1. Fork 本仓库
2. 创建特性分支（git checkout -b feature/amazing-feature）
3. 进行修改
4. 运行测试和代码检查
5. 提交更改（git commit -m 'Add amazing feature'）
6. 推送到分支（git push origin feature/amazing-feature）
7. 提交 Pull Request

故障排除

常见问题

问题: 响应返回 None

• 解决方案: API 结构可能已变更。请查看 Changelog 获取更新信息。

问题: 账号创建失败

• 解决方案: Emailnator cookies 会频繁过期。请从 Emailnator.com 获取新的 cookies。

问题: 文件上传失败

• 解决方案: 确保你拥有有效的 Perplexity 账号，并且有可用的文件上传配额。

问题: 触发速率限制

• 解决方案: 使用内置的速率限制功能，或在请求之间增加等待时间。考虑使用异步 API 以获得更好的并发性能。

获取帮助

• 查看 examples/ 目录中的可运行示例代码
• 阅读 文档
• 在 GitHub 上提交 issue

更新日志

详细变更和错误修复请参阅 CHANGELOG.md。

路线图

计划中的改进和功能请参阅 IMPROVEMENTS.md。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

致谢

• Perplexity.ai 提供了出色的 AI 搜索引擎
• Emailnator 提供了临时邮箱服务
• 所有帮助改进本项目的贡献者

免责声明

这是一个非官方的 API 封装库。请负责任地使用，并遵守 Perplexity.ai 的服务条款。本项目仅用于教育目的。

Perplexity AI 开源工具快速上手指南

环境准备

• Python 版本：3.8 或更高
• 操作系统：Windows / macOS / Linux 均支持
• 可选依赖：
  • 如需使用 Web 界面（自动创建账号），需安装 Chromium（推荐通过 patchright 安装）
  • 国内用户建议配置 pip 镜像源（如清华源）加速安装：

    pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
    

安装步骤

基础安装（仅 API 功能）

pip install -e .

安装 Web 界面支持（用于自动创建 Gmail 账号）

pip install -e ".[driver]"
patchright install chromium

安装 MCP Server（用于与 Claude Code 等客户端集成）

pip install -e ".[mcp]"

开发者安装（包含测试、格式化、类型检查等工具）

pip install -e ".[dev]"

💡 提示：国内网络环境下，若 patchright install chromium 下载缓慢，可手动下载 Chromium 并配置环境变量，或使用代理。

基本使用

1. 最简查询（匿名模式，免费额度）

import perplexity

client = perplexity.Client()
response = client.search("什么是人工智能？")
print(response['answer'])

2. 流式响应（实时输出）

for chunk in client.search("解释量子计算", stream=True):
    if 'answer' in chunk:
        print(chunk['answer'], end='', flush=True)

3. 异步调用（需安装基础包即可）

import asyncio
import perplexity_async

async def main():
    client = await perplexity_async.Client()
    response = await client.search("机器学习是什么？")
    print(response['answer'])

asyncio.run(main())

✅ 提示：以上示例无需账号即可运行，使用 Perplexity 的免费“auto”模式。如需使用 pro、reasoning 或 deep research 模式，请配置你的 Perplexity Cookie（获取方式见项目 README 中的 How To Get Cookies 部分）。