之前在做智能体应用开发时经常需要整合多个大模型的能力但不同模型的API接口、调用方式和上下文管理差异很大调试和切换成本很高。最近Perplexity推出的Agent API特别是集成了Kimi K3模型为开发者提供了一个统一、强大的智能体构建平台。本文将手把手带你从零开始完成Perplexity Agent API的环境配置、核心功能调用并实现一个具备联网搜索和长上下文处理能力的智能体应用附上完整可运行的代码和避坑指南。1. Perplexity Agent API 与 Kimi K3 核心概念解析在深入代码之前我们需要先理清几个关键概念这有助于理解我们正在构建的是什么以及为什么选择这个组合。Perplexity Agent API是知名AI搜索公司Perplexity面向开发者推出的一个服务接口。它不仅仅是一个大模型聊天接口更是一个智能体Agent框架。与传统的大模型API如OpenAI的ChatCompletion不同Agent API内置了工具调用Tool Calling、长上下文管理和实时网络搜索等核心能力。开发者可以通过简单的API调用快速构建出能够自主规划、使用工具如搜索、计算、查数据库来完成复杂任务的智能体而无需自己从零搭建复杂的Agent逻辑框架。Kimi K3是月之暗面Moonshot AI推出的最新一代大语言模型。它以超长的上下文处理能力最高支持128K tokens和优秀的代码、推理能力著称。Perplexity选择将Kimi K3集成到其Agent API中意味着开发者现在可以直接通过Perplexity的接口调用这个在长文本理解和处理方面表现突出的模型来驱动自己的智能体。为什么这个组合值得关注开箱即用的智能体能力你不需要自己实现ReAct、CoT等Agent思维框架API已经封装好了。内置联网搜索无需额外申请和集成搜索API智能体可以直接获取最新、最实时的信息。强大的长上下文支持借助Kimi K3智能体可以处理非常长的对话历史或文档内容适合进行深度分析、总结和跨文档问答。统一的接口用一个API同时获得了顶尖的模型能力Kimi K3和智能体框架Perplexity Agent简化了技术栈。应用场景举例智能研究助手用户提出一个复杂问题智能体自动规划搜索关键词从网络获取多篇最新文章阅读、对比并生成一份结构化的研究报告。客服升级助手在客服对话中当遇到复杂问题时自动调用搜索工具查找产品最新文档或解决方案辅助客服快速响应。长文档分析机器人上传一份数十页的技术白皮书或法律合同要求智能体提取关键条款、总结要点并回答基于全文的细节问题。2. 环境准备与账号配置要开始使用Perplexity Agent API你需要准备好开发环境和必要的凭证。2.1 基础环境要求操作系统Windows 10/11, macOS, 或 Linux (如Ubuntu 20.04)。Python环境推荐使用 Python 3.8 及以上版本。这是与大多数AI库兼容性最好的版本范围。包管理工具pip或conda。代码编辑器或IDEVS Code, PyCharm, Jupyter Notebook 等均可。网络环境需要能够正常访问国际互联网。2.2 获取 Perplexity API Key这是调用API的通行证必不可少。访问 Perplexity AI 官网 。注册并登录你的账户。进入账户的“Settings”或“API”部分通常位于用户头像下拉菜单中。在API设置页面你应该能看到创建或查看API Key的选项。点击“Create new API key”。为你的Key命名例如“MyAgentApp”然后复制生成的一长串以pplx-开头的密钥字符串。请务必妥善保存因为它只显示一次。2.3 创建并激活 Python 虚拟环境为了避免包依赖冲突强烈建议使用虚拟环境。# 在项目目录下创建虚拟环境以venv为例 python -m venv venv # 激活虚拟环境 # Windows (PowerShell) .\venv\Scripts\Activate.ps1 # Windows (CMD) .\venv\Scripts\activate.bat # macOS / Linux source venv/bin/activate激活后你的命令行提示符前会出现(venv)字样。2.4 安装必要的 Python 库核心需要安装的是Perplexity官方的Python SDK如果已提供或直接使用通用的HTTP请求库。目前Perplexity API兼容OpenAI的格式因此我们可以使用openai这个库但需要配置自定义base_url。# 安装 openai 库和 requests 库用于可能的自定义请求 pip install openai requests python-dotenvpython-dotenv用于从.env文件安全地加载环境变量如API Key。2.5 项目结构初始化创建一个清晰的项目文件夹例如perplexity_agent_demo结构如下perplexity_agent_demo/ ├── .env # 存储敏感信息API Key ├── .gitignore # Git忽略文件 ├── requirements.txt # 项目依赖列表 ├── config.py # 配置文件 ├── agent_demo.py # 主演示脚本 └── utils/ # 工具函数目录可选 └── __init__.py在项目根目录创建.env文件并填入你的API Key# .env PERPLEXITY_API_KEYpplx-你的实际API密钥字符串重要确保将.env添加到.gitignore文件中避免将密钥提交到代码仓库。3. 核心 API 调用与参数详解Perplexity Agent API 主要提供了创建会话Session和发送消息Message的能力。一个会话代表一次连续的、有状态的对话API会自动管理上下文。3.1 初始化客户端与基础配置我们将使用openai库但指向 Perplexity 的端点。# config.py import os from dotenv import load_dotenv from openai import OpenAI # 加载 .env 文件中的环境变量 load_dotenv() # 初始化 OpenAI 客户端但配置为使用 Perplexity 的 API client OpenAI( api_keyos.getenv(PERPLEXITY_API_KEY), # 从环境变量读取密钥 base_urlhttps://api.perplexity.ai, # Perplexity API 的基地址 ) # 定义我们要使用的模型 MODEL_NAME kimi-3 # 指定使用 Kimi K3 模型3.2 创建会话Session会话是Agent交互的核心。你可以为每个独立的对话任务创建一个会话。# agent_demo.py from config import client, MODEL_NAME def create_agent_session(): 创建一个新的智能体会话。 返回的会话ID用于后续的所有消息交互。 try: # 注意Perplexity Agent API 创建会话的端点可能与标准Chat不同。 # 这里假设其遵循类似 /chat/sessions 的路径。实际需查阅最新文档。 # 以下为示例性代码展示概念。 response client.chat.sessions.create( modelMODEL_NAME, # 可以在此处指定初始系统指令塑造Agent的角色和行为 # system_prompt你是一个专业、严谨的科技领域研究助手。, ) session_id response.id print(f✅ 会话创建成功会话ID: {session_id}) return session_id except Exception as e: print(f❌ 创建会话失败: {e}) return None # 在实际调用中Perplexity可能将“会话”概念隐含在连续的对话中 # 即不需要显式创建session而是通过messages数组维护上下文。 # 下面的send_message函数展示了更通用的方式。3.3 发送消息与工具调用核心这是与智能体交互的核心函数。我们将消息历史包含用户问题和Assistant回复发送给API并允许Agent决定是否调用工具如搜索。# agent_demo.py def send_message_with_agent(messages, modelMODEL_NAME, streamFalse): 向Perplexity Agent API发送消息并处理可能的工具调用如搜索。 Args: messages (list): 消息历史列表格式为 [{role: user, content: ...}, ...] model (str): 使用的模型名称。 stream (bool): 是否使用流式输出。 Returns: dict: 包含完整响应信息的字典。 try: # 关键在创建Completion时通过 tools 参数启用网络搜索工具。 # Perplexity 可能内置了名为 search 或 internet_search 的工具。 response client.chat.completions.create( modelmodel, messagesmessages, tools[{ # 定义可供Agent调用的工具 type: function, function: { name: search_the_web, # 工具函数名需与API支持的工具名匹配 description: 在互联网上搜索最新信息以回答问题。, parameters: { type: object, properties: { query: { type: string, description: 用于搜索的查询关键词。 } }, required: [query] } } }], tool_choiceauto, # 让模型自动决定是否调用工具 streamstream, ) # 处理非流式响应 if not stream: completion response assistant_message completion.choices[0].message # 检查回复中是否包含了工具调用的请求 tool_calls assistant_message.tool_calls final_content assistant_message.content # 如果Agent决定调用工具比如搜索 if tool_calls: print(f Agent 决定调用工具: {[tc.function.name for tc in tool_calls]}) # 在实际应用中这里需要执行工具调用如发起网络搜索 # 并将搜索结果作为新的消息附加到对话历史中再次调用API。 # 但Perplexity Agent API的一个巨大优势是它可能**自动处理了工具的执行**。 # 这意味着当启用搜索工具时API内部会执行搜索并将结果融入最终回复。 # 因此final_content 可能已经包含了搜索得到的信息。 # 具体行为需以官方文档为准。 return { role: assistant, content: final_content, tool_calls: tool_calls } else: # 流式处理逻辑略用于实现打字机效果 collected_chunks [] for chunk in response: if chunk.choices[0].delta.content is not None: content chunk.choices[0].delta.content print(content, end, flushTrue) collected_chunks.append(content) print() # 换行 return {role: assistant, content: .join(collected_chunks)} except Exception as e: print(f❌ 调用API失败: {e}) return None关键参数解析model: 必须指定为kimi-3来使用Kimi K3模型。messages: 对话历史列表。每条消息是一个字典包含role(system,user,assistant,tool) 和content。API会根据整个历史来生成回复这就是上下文的维护。tools: 一个列表定义Agent可以调用的函数工具。示例中我们定义了一个search_the_web函数。Perplexity Agent API 很可能预置了名为internet_search或类似的内置工具你需要查阅最新文档使用正确的名称。如果API内置了搜索且自动执行那么你甚至可能不需要显式定义tools只需在请求中开启某个开关如search_domain参数。tool_choice: 设置为auto让模型决定none禁用工具{type: function, function: {name: xxx}}强制使用某个工具。4. 完整实战案例构建联网搜索研究助手现在我们将整合上面的代码构建一个完整的命令行交互式研究助手。这个助手能理解复杂问题自动进行网络搜索并给出综合答案。4.1 项目依赖文件创建requirements.txt确保团队或未来部署时环境一致。# requirements.txt openai1.0.0 requests2.28.0 python-dotenv1.0.04.2 主程序实现创建一个research_assistant.py文件。# research_assistant.py import os import json from datetime import datetime from config import client, MODEL_NAME class ResearchAssistant: def __init__(self): self.client client self.model MODEL_NAME self.conversation_history [] # 存储完整的对话历史 # 可以添加一个初始系统提示设定Agent的角色 self.system_prompt { role: system, content: 你是一个专业的研究助手擅长通过整合网络信息来回答复杂问题。 当用户的问题涉及需要最新数据、事实核查或多元观点时你应该主动使用联网搜索功能。 你的回答应当严谨、客观并注明信息可能来源于网络搜索。对于有争议的话题应呈现多角度信息。 请用中文回答。 } self.conversation_history.append(self.system_prompt) def _call_perplexity_api(self, messages, use_searchTrue): 封装对Perplexity Agent API的调用逻辑。 try: # 构建请求参数 request_params { model: self.model, messages: messages, stream: False, } # 根据Perplexity最新文档启用搜索的方式可能是参数 search_domain 或 internet_search # 这里提供两种常见方式的示例实际使用时请根据官方文档调整其一。 # 方式A通过 search_domain 参数如果API支持 if use_search: request_params[search_domain] all # 或 general, scholar 等 # 方式B通过 tools 参数如果API要求显式定义工具 # if use_search: # request_params[tools] [{ # type: function, # function: { # name: internet_search, # description: Search the internet for current information., # } # }] # request_params[tool_choice] auto response self.client.chat.completions.create(**request_params) assistant_msg response.choices[0].message return assistant_msg.content, assistant_msg.tool_calls except Exception as e: print(fAPI调用出错: {e}) # 可以在这里添加重试逻辑 return None, None def ask(self, question, use_searchTrue): 向研究助手提问。 if not question.strip(): print(问题不能为空。) return print(f\n[用户] {question}) # 1. 将用户问题加入历史 user_message {role: user, content: question} self.conversation_history.append(user_message) # 2. 调用API print( 思考中..., end, flushTrue) answer, tool_calls self._call_perplexity_api(self.conversation_history, use_search) print(\r, end) # 清除“思考中”提示 if not answer: print(抱歉助手暂时无法回答。) return # 3. 处理工具调用如果API返回了工具调用请求且未自动执行 # 本例假设Perplexity API在启用搜索后会自动执行并返回结果所以这部分可能不需要。 # 如果API返回的是工具调用请求则需要在此执行工具并将结果作为 tool 角色消息加入历史再次调用API。 # 4. 将助手回复加入历史并输出 assistant_message {role: assistant, content: answer} self.conversation_history.append(assistant_message) print(f[助手] {answer}) # 5. 可选保存本次对话到文件用于记录或后续分析 self._save_conversation_snapshot(question, answer) def _save_conversation_snapshot(self, question, answer): 将对话片段保存到JSON文件方便复盘。 os.makedirs(conversation_logs, exist_okTrue) log_entry { timestamp: datetime.now().isoformat(), question: question, answer: answer[:500] ... if len(answer) 500 else answer # 截断长回复 } filename fconversation_logs/log_{datetime.now().strftime(%Y%m%d_%H%M%S)}.json try: with open(filename, w, encodingutf-8) as f: json.dump(log_entry, f, ensure_asciiFalse, indent2) except Exception as e: print(f保存日志失败: {e}) def clear_history(self): 清空当前对话历史但保留系统提示。 self.conversation_history [self.system_prompt] print(对话历史已清空。) def show_history(self): 打印当前对话历史。 print(\n 当前对话历史 ) for msg in self.conversation_history: if msg[role] system: continue # 跳过系统提示 print(f{msg[role].upper()}: {msg[content][:100]}...) print(\n) def main(): 命令行交互主循环。 assistant ResearchAssistant() print(*50) print(Perplexity Agent (Kimi K3) 研究助手已启动) print(输入您的问题助手将尝试联网搜索回答。) print(输入 clear 清空历史history 查看历史exit 退出。) print(*50) while True: try: user_input input(\n您的问题 ).strip() if user_input.lower() exit: print(再见) break elif user_input.lower() clear: assistant.clear_history() continue elif user_input.lower() history: assistant.show_history() continue elif not user_input: continue # 判断是否需要强制关闭搜索例如用户输入以“#本地”开头 use_search not user_input.startswith(#本地) question user_input[3:] if user_input.startswith(#本地) else user_input assistant.ask(question, use_searchuse_search) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f发生未知错误: {e}) if __name__ __main__: main()4.3 运行与验证确保你的.env文件已正确配置PERPLEXITY_API_KEY。在终端中激活虚拟环境并运行程序cd /path/to/your/perplexity_agent_demo source venv/bin/activate # 或相应的激活命令 python research_assistant.py程序启动后尝试提出一些需要最新信息的问题。示例交互您的问题 2024年巴黎奥运会新增了哪些比赛项目 思考中... [助手] 根据最新的网络信息2024年巴黎奥运会新增了多个比赛项目旨在吸引年轻观众并体现时代特色。主要新增项目包括 1. **霹雳舞Breaking**首次作为正式比赛项目亮相奥运会。 2. **滑板**继东京奥运会后再次保留设有街式和碗池两个小项。 3. **运动攀岩**速度赛将从全能项目中分离出来成为独立小项。 4. **冲浪**继续保留。 此外举重和拳击的项目设置和参赛人数有所调整。请注意具体项目设置以国际奥委会最终公布为准。 信息综合自近期体育新闻网站您的问题 #本地 请用一句话介绍一下Python的特点。 [助手] Python是一种高级、解释型、通用的编程语言以其简洁明了的语法、强大的标准库和丰富的第三方生态而著称特别适用于快速开发、数据科学、人工智能和网络应用。4.4 结果说明当提出需要最新信息的问题时如第一个例子助手会利用Perplexity Agent API内置的联网搜索能力获取信息并生成回答。你可以在回答中看到它引用了网络来源。当使用#本地前缀时我们通过参数禁用了搜索助手仅依靠Kimi K3模型的内置知识来回答。程序维护了对话历史你可以进行多轮对话助手能理解上下文。所有对话都被记录在conversation_logs/目录下的JSON文件中。5. 常见问题与排查思路在集成和使用过程中你可能会遇到以下问题。问题现象可能原因排查与解决思路AuthenticationError或401错误1. API Key 错误或失效。2. Key 未正确设置到环境变量或代码中。3. 账户欠费或未开通API权限。1. 检查.env文件中的PERPLEXITY_API_KEY值是否正确前后有无空格。2. 在代码中打印os.getenv(PERPLEXITY_API_KEY)的前几位确认已加载。3. 登录Perplexity官网检查API页面Key状态和账户余额。RateLimitError或429错误请求频率超过API限制。1. 查看官方文档的速率限制说明通常有RPM-每分钟请求数和TPM-每分钟tokens数限制。2. 在代码中增加请求间隔如time.sleep(1)。3. 考虑升级API套餐。InvalidRequestError(如model not found)1. 模型名称拼写错误。2. 该模型在你所在区域不可用或已下线。1. 确认模型名称为kimi-3最新名称请查文档。2. 尝试使用基础模型如sonar测试API连通性。3. 查阅Perplexity官方公告或文档。Agent 不执行搜索1. 未正确启用搜索功能。2. 问题本身不需要搜索模型已有足够知识。3. API的搜索功能调用方式已变更。1. 检查_call_perplexity_api函数中use_search参数是否生效以及启用搜索的API参数search_domain或tools是否正确。2. 尝试问一个明确需要最新信息的问题如“今天纽约时报的头条新闻是什么”。3.最重要的仔细阅读Perplexity Agent API的最新官方文档确认启用搜索的正确姿势。响应速度慢1. 网络延迟。2. 问题复杂或使用了搜索需要更长的处理时间。3. 上下文过长虽然Kimi支持长上下文但处理需要时间。1. 检查本地网络。2. 对于简单问题尝试关闭搜索 (use_searchFalse)。3. 如果对话历史很长可以考虑定期总结历史或清除旧消息。流式输出不工作或乱码1. 流式响应处理代码有误。2. 终端不支持某些字符。1. 参考send_message_with_agent函数中的流式处理逻辑确保正确迭代response。2. 对于复杂输出先使用非流式 (streamFalse) 确保基础功能正常。长上下文下回复质量下降1. 模型在超长上下文末尾可能出现“中间丢失”现象。2. 无关历史信息干扰了当前问题。1. 对于超长文档分析尝试将文档分段处理或只将最相关的片段放入上下文。2. 实现一个“上下文窗口管理”策略只保留最近N轮对话或最重要的系统提示。6. 最佳实践与工程建议将Perplexity Agent API投入实际项目时遵循以下建议可以提升稳定性、安全性和可维护性。6.1 配置与密钥管理永远不要硬编码API Key必须使用环境变量或安全的密钥管理服务如AWS Secrets Manager, HashiCorp Vault。使用配置类像示例中的config.py一样集中管理API端点、模型名称、超时时间等配置方便不同环境开发、测试、生产切换。设置合理的超时和重试网络请求可能失败使用tenacity等库实现带退避策略的自动重试。# 示例使用tenacity增加重试机制 from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def call_api_safely(messages): # ... 原有的API调用代码6.2 会话与上下文管理为每个用户/会话创建独立实例避免不同用户的对话历史相互污染。实施上下文截断策略Kimi K3支持128K但成本和处理时间随上下文长度增加。可以设定一个token上限如8000超过时优先保留系统提示和最近几轮对话或使用模型对早期历史进行总结。持久化会话对于Web应用将会话历史存储到数据库如Redis, PostgreSQL而不是仅保存在内存中以便用户下次访问时恢复。6.3 错误处理与用户体验友好的错误提示不要将原始的API错误堆栈直接抛给用户。捕获异常后转换为用户能理解的信息如“网络开小差了请稍后重试”。设置Fallback机制当Perplexity API不可用时可以降级到本地模型或返回缓存的通用回答保证服务基本可用。添加Usage统计记录每次调用的token消耗、是否使用搜索等信息用于成本分析和优化。6.4 搜索功能的精细控制选择性启用搜索不是所有问题都需要联网。可以通过关键词识别、用户指令如示例中的#本地或分类模型来判断是否开启搜索以节省成本和时间。指定搜索领域如果API支持如通过search_domain参数可以根据问题类型指定搜索范围如“学术”、“新闻”、“通用”提高信息相关性。结果验证与引用对于关键事实理想情况下应要求Agent提供信息来源引用。虽然当前API可能不直接返回链接但你可以提示模型在回答中说明“根据XX网站报道”。6.5 安全与合规内容过滤在将用户输入发送给API前以及将API回复返回给用户前实施必要的内容安全过滤防止生成有害、偏见或不合规的内容。用户数据隐私明确告知用户对话可能被用于服务改进根据Perplexity政策并避免在提示词或对话历史中泄露用户个人身份信息PII。合规使用确保你的应用场景符合Perplexity API的使用条款特别是关于自动化、商业用途等方面的规定。通过本文的步骤你应该已经成功搭建了一个基于Perplexity Agent API和Kimi K3模型的智能研究助手原型。这个组合的强大之处在于它将复杂的智能体逻辑和强大的模型能力封装成了简单的API调用让开发者可以更专注于构建应用本身的价值。接下来你可以尝试将其集成到你的网站、聊天机器人或内部工具中探索更多如文档上传分析、多Agent协作等高级功能。 基于Perplexity Agent API与Kimi K3构建联网搜索智能体实战指南
之前在做智能体应用开发时经常需要整合多个大模型的能力但不同模型的API接口、调用方式和上下文管理差异很大调试和切换成本很高。最近Perplexity推出的Agent API特别是集成了Kimi K3模型为开发者提供了一个统一、强大的智能体构建平台。本文将手把手带你从零开始完成Perplexity Agent API的环境配置、核心功能调用并实现一个具备联网搜索和长上下文处理能力的智能体应用附上完整可运行的代码和避坑指南。1. Perplexity Agent API 与 Kimi K3 核心概念解析在深入代码之前我们需要先理清几个关键概念这有助于理解我们正在构建的是什么以及为什么选择这个组合。Perplexity Agent API是知名AI搜索公司Perplexity面向开发者推出的一个服务接口。它不仅仅是一个大模型聊天接口更是一个智能体Agent框架。与传统的大模型API如OpenAI的ChatCompletion不同Agent API内置了工具调用Tool Calling、长上下文管理和实时网络搜索等核心能力。开发者可以通过简单的API调用快速构建出能够自主规划、使用工具如搜索、计算、查数据库来完成复杂任务的智能体而无需自己从零搭建复杂的Agent逻辑框架。Kimi K3是月之暗面Moonshot AI推出的最新一代大语言模型。它以超长的上下文处理能力最高支持128K tokens和优秀的代码、推理能力著称。Perplexity选择将Kimi K3集成到其Agent API中意味着开发者现在可以直接通过Perplexity的接口调用这个在长文本理解和处理方面表现突出的模型来驱动自己的智能体。为什么这个组合值得关注开箱即用的智能体能力你不需要自己实现ReAct、CoT等Agent思维框架API已经封装好了。内置联网搜索无需额外申请和集成搜索API智能体可以直接获取最新、最实时的信息。强大的长上下文支持借助Kimi K3智能体可以处理非常长的对话历史或文档内容适合进行深度分析、总结和跨文档问答。统一的接口用一个API同时获得了顶尖的模型能力Kimi K3和智能体框架Perplexity Agent简化了技术栈。应用场景举例智能研究助手用户提出一个复杂问题智能体自动规划搜索关键词从网络获取多篇最新文章阅读、对比并生成一份结构化的研究报告。客服升级助手在客服对话中当遇到复杂问题时自动调用搜索工具查找产品最新文档或解决方案辅助客服快速响应。长文档分析机器人上传一份数十页的技术白皮书或法律合同要求智能体提取关键条款、总结要点并回答基于全文的细节问题。2. 环境准备与账号配置要开始使用Perplexity Agent API你需要准备好开发环境和必要的凭证。2.1 基础环境要求操作系统Windows 10/11, macOS, 或 Linux (如Ubuntu 20.04)。Python环境推荐使用 Python 3.8 及以上版本。这是与大多数AI库兼容性最好的版本范围。包管理工具pip或conda。代码编辑器或IDEVS Code, PyCharm, Jupyter Notebook 等均可。网络环境需要能够正常访问国际互联网。2.2 获取 Perplexity API Key这是调用API的通行证必不可少。访问 Perplexity AI 官网 。注册并登录你的账户。进入账户的“Settings”或“API”部分通常位于用户头像下拉菜单中。在API设置页面你应该能看到创建或查看API Key的选项。点击“Create new API key”。为你的Key命名例如“MyAgentApp”然后复制生成的一长串以pplx-开头的密钥字符串。请务必妥善保存因为它只显示一次。2.3 创建并激活 Python 虚拟环境为了避免包依赖冲突强烈建议使用虚拟环境。# 在项目目录下创建虚拟环境以venv为例 python -m venv venv # 激活虚拟环境 # Windows (PowerShell) .\venv\Scripts\Activate.ps1 # Windows (CMD) .\venv\Scripts\activate.bat # macOS / Linux source venv/bin/activate激活后你的命令行提示符前会出现(venv)字样。2.4 安装必要的 Python 库核心需要安装的是Perplexity官方的Python SDK如果已提供或直接使用通用的HTTP请求库。目前Perplexity API兼容OpenAI的格式因此我们可以使用openai这个库但需要配置自定义base_url。# 安装 openai 库和 requests 库用于可能的自定义请求 pip install openai requests python-dotenvpython-dotenv用于从.env文件安全地加载环境变量如API Key。2.5 项目结构初始化创建一个清晰的项目文件夹例如perplexity_agent_demo结构如下perplexity_agent_demo/ ├── .env # 存储敏感信息API Key ├── .gitignore # Git忽略文件 ├── requirements.txt # 项目依赖列表 ├── config.py # 配置文件 ├── agent_demo.py # 主演示脚本 └── utils/ # 工具函数目录可选 └── __init__.py在项目根目录创建.env文件并填入你的API Key# .env PERPLEXITY_API_KEYpplx-你的实际API密钥字符串重要确保将.env添加到.gitignore文件中避免将密钥提交到代码仓库。3. 核心 API 调用与参数详解Perplexity Agent API 主要提供了创建会话Session和发送消息Message的能力。一个会话代表一次连续的、有状态的对话API会自动管理上下文。3.1 初始化客户端与基础配置我们将使用openai库但指向 Perplexity 的端点。# config.py import os from dotenv import load_dotenv from openai import OpenAI # 加载 .env 文件中的环境变量 load_dotenv() # 初始化 OpenAI 客户端但配置为使用 Perplexity 的 API client OpenAI( api_keyos.getenv(PERPLEXITY_API_KEY), # 从环境变量读取密钥 base_urlhttps://api.perplexity.ai, # Perplexity API 的基地址 ) # 定义我们要使用的模型 MODEL_NAME kimi-3 # 指定使用 Kimi K3 模型3.2 创建会话Session会话是Agent交互的核心。你可以为每个独立的对话任务创建一个会话。# agent_demo.py from config import client, MODEL_NAME def create_agent_session(): 创建一个新的智能体会话。 返回的会话ID用于后续的所有消息交互。 try: # 注意Perplexity Agent API 创建会话的端点可能与标准Chat不同。 # 这里假设其遵循类似 /chat/sessions 的路径。实际需查阅最新文档。 # 以下为示例性代码展示概念。 response client.chat.sessions.create( modelMODEL_NAME, # 可以在此处指定初始系统指令塑造Agent的角色和行为 # system_prompt你是一个专业、严谨的科技领域研究助手。, ) session_id response.id print(f✅ 会话创建成功会话ID: {session_id}) return session_id except Exception as e: print(f❌ 创建会话失败: {e}) return None # 在实际调用中Perplexity可能将“会话”概念隐含在连续的对话中 # 即不需要显式创建session而是通过messages数组维护上下文。 # 下面的send_message函数展示了更通用的方式。3.3 发送消息与工具调用核心这是与智能体交互的核心函数。我们将消息历史包含用户问题和Assistant回复发送给API并允许Agent决定是否调用工具如搜索。# agent_demo.py def send_message_with_agent(messages, modelMODEL_NAME, streamFalse): 向Perplexity Agent API发送消息并处理可能的工具调用如搜索。 Args: messages (list): 消息历史列表格式为 [{role: user, content: ...}, ...] model (str): 使用的模型名称。 stream (bool): 是否使用流式输出。 Returns: dict: 包含完整响应信息的字典。 try: # 关键在创建Completion时通过 tools 参数启用网络搜索工具。 # Perplexity 可能内置了名为 search 或 internet_search 的工具。 response client.chat.completions.create( modelmodel, messagesmessages, tools[{ # 定义可供Agent调用的工具 type: function, function: { name: search_the_web, # 工具函数名需与API支持的工具名匹配 description: 在互联网上搜索最新信息以回答问题。, parameters: { type: object, properties: { query: { type: string, description: 用于搜索的查询关键词。 } }, required: [query] } } }], tool_choiceauto, # 让模型自动决定是否调用工具 streamstream, ) # 处理非流式响应 if not stream: completion response assistant_message completion.choices[0].message # 检查回复中是否包含了工具调用的请求 tool_calls assistant_message.tool_calls final_content assistant_message.content # 如果Agent决定调用工具比如搜索 if tool_calls: print(f Agent 决定调用工具: {[tc.function.name for tc in tool_calls]}) # 在实际应用中这里需要执行工具调用如发起网络搜索 # 并将搜索结果作为新的消息附加到对话历史中再次调用API。 # 但Perplexity Agent API的一个巨大优势是它可能**自动处理了工具的执行**。 # 这意味着当启用搜索工具时API内部会执行搜索并将结果融入最终回复。 # 因此final_content 可能已经包含了搜索得到的信息。 # 具体行为需以官方文档为准。 return { role: assistant, content: final_content, tool_calls: tool_calls } else: # 流式处理逻辑略用于实现打字机效果 collected_chunks [] for chunk in response: if chunk.choices[0].delta.content is not None: content chunk.choices[0].delta.content print(content, end, flushTrue) collected_chunks.append(content) print() # 换行 return {role: assistant, content: .join(collected_chunks)} except Exception as e: print(f❌ 调用API失败: {e}) return None关键参数解析model: 必须指定为kimi-3来使用Kimi K3模型。messages: 对话历史列表。每条消息是一个字典包含role(system,user,assistant,tool) 和content。API会根据整个历史来生成回复这就是上下文的维护。tools: 一个列表定义Agent可以调用的函数工具。示例中我们定义了一个search_the_web函数。Perplexity Agent API 很可能预置了名为internet_search或类似的内置工具你需要查阅最新文档使用正确的名称。如果API内置了搜索且自动执行那么你甚至可能不需要显式定义tools只需在请求中开启某个开关如search_domain参数。tool_choice: 设置为auto让模型决定none禁用工具{type: function, function: {name: xxx}}强制使用某个工具。4. 完整实战案例构建联网搜索研究助手现在我们将整合上面的代码构建一个完整的命令行交互式研究助手。这个助手能理解复杂问题自动进行网络搜索并给出综合答案。4.1 项目依赖文件创建requirements.txt确保团队或未来部署时环境一致。# requirements.txt openai1.0.0 requests2.28.0 python-dotenv1.0.04.2 主程序实现创建一个research_assistant.py文件。# research_assistant.py import os import json from datetime import datetime from config import client, MODEL_NAME class ResearchAssistant: def __init__(self): self.client client self.model MODEL_NAME self.conversation_history [] # 存储完整的对话历史 # 可以添加一个初始系统提示设定Agent的角色 self.system_prompt { role: system, content: 你是一个专业的研究助手擅长通过整合网络信息来回答复杂问题。 当用户的问题涉及需要最新数据、事实核查或多元观点时你应该主动使用联网搜索功能。 你的回答应当严谨、客观并注明信息可能来源于网络搜索。对于有争议的话题应呈现多角度信息。 请用中文回答。 } self.conversation_history.append(self.system_prompt) def _call_perplexity_api(self, messages, use_searchTrue): 封装对Perplexity Agent API的调用逻辑。 try: # 构建请求参数 request_params { model: self.model, messages: messages, stream: False, } # 根据Perplexity最新文档启用搜索的方式可能是参数 search_domain 或 internet_search # 这里提供两种常见方式的示例实际使用时请根据官方文档调整其一。 # 方式A通过 search_domain 参数如果API支持 if use_search: request_params[search_domain] all # 或 general, scholar 等 # 方式B通过 tools 参数如果API要求显式定义工具 # if use_search: # request_params[tools] [{ # type: function, # function: { # name: internet_search, # description: Search the internet for current information., # } # }] # request_params[tool_choice] auto response self.client.chat.completions.create(**request_params) assistant_msg response.choices[0].message return assistant_msg.content, assistant_msg.tool_calls except Exception as e: print(fAPI调用出错: {e}) # 可以在这里添加重试逻辑 return None, None def ask(self, question, use_searchTrue): 向研究助手提问。 if not question.strip(): print(问题不能为空。) return print(f\n[用户] {question}) # 1. 将用户问题加入历史 user_message {role: user, content: question} self.conversation_history.append(user_message) # 2. 调用API print( 思考中..., end, flushTrue) answer, tool_calls self._call_perplexity_api(self.conversation_history, use_search) print(\r, end) # 清除“思考中”提示 if not answer: print(抱歉助手暂时无法回答。) return # 3. 处理工具调用如果API返回了工具调用请求且未自动执行 # 本例假设Perplexity API在启用搜索后会自动执行并返回结果所以这部分可能不需要。 # 如果API返回的是工具调用请求则需要在此执行工具并将结果作为 tool 角色消息加入历史再次调用API。 # 4. 将助手回复加入历史并输出 assistant_message {role: assistant, content: answer} self.conversation_history.append(assistant_message) print(f[助手] {answer}) # 5. 可选保存本次对话到文件用于记录或后续分析 self._save_conversation_snapshot(question, answer) def _save_conversation_snapshot(self, question, answer): 将对话片段保存到JSON文件方便复盘。 os.makedirs(conversation_logs, exist_okTrue) log_entry { timestamp: datetime.now().isoformat(), question: question, answer: answer[:500] ... if len(answer) 500 else answer # 截断长回复 } filename fconversation_logs/log_{datetime.now().strftime(%Y%m%d_%H%M%S)}.json try: with open(filename, w, encodingutf-8) as f: json.dump(log_entry, f, ensure_asciiFalse, indent2) except Exception as e: print(f保存日志失败: {e}) def clear_history(self): 清空当前对话历史但保留系统提示。 self.conversation_history [self.system_prompt] print(对话历史已清空。) def show_history(self): 打印当前对话历史。 print(\n 当前对话历史 ) for msg in self.conversation_history: if msg[role] system: continue # 跳过系统提示 print(f{msg[role].upper()}: {msg[content][:100]}...) print(\n) def main(): 命令行交互主循环。 assistant ResearchAssistant() print(*50) print(Perplexity Agent (Kimi K3) 研究助手已启动) print(输入您的问题助手将尝试联网搜索回答。) print(输入 clear 清空历史history 查看历史exit 退出。) print(*50) while True: try: user_input input(\n您的问题 ).strip() if user_input.lower() exit: print(再见) break elif user_input.lower() clear: assistant.clear_history() continue elif user_input.lower() history: assistant.show_history() continue elif not user_input: continue # 判断是否需要强制关闭搜索例如用户输入以“#本地”开头 use_search not user_input.startswith(#本地) question user_input[3:] if user_input.startswith(#本地) else user_input assistant.ask(question, use_searchuse_search) except KeyboardInterrupt: print(\n\n程序被中断。) break except Exception as e: print(f发生未知错误: {e}) if __name__ __main__: main()4.3 运行与验证确保你的.env文件已正确配置PERPLEXITY_API_KEY。在终端中激活虚拟环境并运行程序cd /path/to/your/perplexity_agent_demo source venv/bin/activate # 或相应的激活命令 python research_assistant.py程序启动后尝试提出一些需要最新信息的问题。示例交互您的问题 2024年巴黎奥运会新增了哪些比赛项目 思考中... [助手] 根据最新的网络信息2024年巴黎奥运会新增了多个比赛项目旨在吸引年轻观众并体现时代特色。主要新增项目包括 1. **霹雳舞Breaking**首次作为正式比赛项目亮相奥运会。 2. **滑板**继东京奥运会后再次保留设有街式和碗池两个小项。 3. **运动攀岩**速度赛将从全能项目中分离出来成为独立小项。 4. **冲浪**继续保留。 此外举重和拳击的项目设置和参赛人数有所调整。请注意具体项目设置以国际奥委会最终公布为准。 信息综合自近期体育新闻网站您的问题 #本地 请用一句话介绍一下Python的特点。 [助手] Python是一种高级、解释型、通用的编程语言以其简洁明了的语法、强大的标准库和丰富的第三方生态而著称特别适用于快速开发、数据科学、人工智能和网络应用。4.4 结果说明当提出需要最新信息的问题时如第一个例子助手会利用Perplexity Agent API内置的联网搜索能力获取信息并生成回答。你可以在回答中看到它引用了网络来源。当使用#本地前缀时我们通过参数禁用了搜索助手仅依靠Kimi K3模型的内置知识来回答。程序维护了对话历史你可以进行多轮对话助手能理解上下文。所有对话都被记录在conversation_logs/目录下的JSON文件中。5. 常见问题与排查思路在集成和使用过程中你可能会遇到以下问题。问题现象可能原因排查与解决思路AuthenticationError或401错误1. API Key 错误或失效。2. Key 未正确设置到环境变量或代码中。3. 账户欠费或未开通API权限。1. 检查.env文件中的PERPLEXITY_API_KEY值是否正确前后有无空格。2. 在代码中打印os.getenv(PERPLEXITY_API_KEY)的前几位确认已加载。3. 登录Perplexity官网检查API页面Key状态和账户余额。RateLimitError或429错误请求频率超过API限制。1. 查看官方文档的速率限制说明通常有RPM-每分钟请求数和TPM-每分钟tokens数限制。2. 在代码中增加请求间隔如time.sleep(1)。3. 考虑升级API套餐。InvalidRequestError(如model not found)1. 模型名称拼写错误。2. 该模型在你所在区域不可用或已下线。1. 确认模型名称为kimi-3最新名称请查文档。2. 尝试使用基础模型如sonar测试API连通性。3. 查阅Perplexity官方公告或文档。Agent 不执行搜索1. 未正确启用搜索功能。2. 问题本身不需要搜索模型已有足够知识。3. API的搜索功能调用方式已变更。1. 检查_call_perplexity_api函数中use_search参数是否生效以及启用搜索的API参数search_domain或tools是否正确。2. 尝试问一个明确需要最新信息的问题如“今天纽约时报的头条新闻是什么”。3.最重要的仔细阅读Perplexity Agent API的最新官方文档确认启用搜索的正确姿势。响应速度慢1. 网络延迟。2. 问题复杂或使用了搜索需要更长的处理时间。3. 上下文过长虽然Kimi支持长上下文但处理需要时间。1. 检查本地网络。2. 对于简单问题尝试关闭搜索 (use_searchFalse)。3. 如果对话历史很长可以考虑定期总结历史或清除旧消息。流式输出不工作或乱码1. 流式响应处理代码有误。2. 终端不支持某些字符。1. 参考send_message_with_agent函数中的流式处理逻辑确保正确迭代response。2. 对于复杂输出先使用非流式 (streamFalse) 确保基础功能正常。长上下文下回复质量下降1. 模型在超长上下文末尾可能出现“中间丢失”现象。2. 无关历史信息干扰了当前问题。1. 对于超长文档分析尝试将文档分段处理或只将最相关的片段放入上下文。2. 实现一个“上下文窗口管理”策略只保留最近N轮对话或最重要的系统提示。6. 最佳实践与工程建议将Perplexity Agent API投入实际项目时遵循以下建议可以提升稳定性、安全性和可维护性。6.1 配置与密钥管理永远不要硬编码API Key必须使用环境变量或安全的密钥管理服务如AWS Secrets Manager, HashiCorp Vault。使用配置类像示例中的config.py一样集中管理API端点、模型名称、超时时间等配置方便不同环境开发、测试、生产切换。设置合理的超时和重试网络请求可能失败使用tenacity等库实现带退避策略的自动重试。# 示例使用tenacity增加重试机制 from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def call_api_safely(messages): # ... 原有的API调用代码6.2 会话与上下文管理为每个用户/会话创建独立实例避免不同用户的对话历史相互污染。实施上下文截断策略Kimi K3支持128K但成本和处理时间随上下文长度增加。可以设定一个token上限如8000超过时优先保留系统提示和最近几轮对话或使用模型对早期历史进行总结。持久化会话对于Web应用将会话历史存储到数据库如Redis, PostgreSQL而不是仅保存在内存中以便用户下次访问时恢复。6.3 错误处理与用户体验友好的错误提示不要将原始的API错误堆栈直接抛给用户。捕获异常后转换为用户能理解的信息如“网络开小差了请稍后重试”。设置Fallback机制当Perplexity API不可用时可以降级到本地模型或返回缓存的通用回答保证服务基本可用。添加Usage统计记录每次调用的token消耗、是否使用搜索等信息用于成本分析和优化。6.4 搜索功能的精细控制选择性启用搜索不是所有问题都需要联网。可以通过关键词识别、用户指令如示例中的#本地或分类模型来判断是否开启搜索以节省成本和时间。指定搜索领域如果API支持如通过search_domain参数可以根据问题类型指定搜索范围如“学术”、“新闻”、“通用”提高信息相关性。结果验证与引用对于关键事实理想情况下应要求Agent提供信息来源引用。虽然当前API可能不直接返回链接但你可以提示模型在回答中说明“根据XX网站报道”。6.5 安全与合规内容过滤在将用户输入发送给API前以及将API回复返回给用户前实施必要的内容安全过滤防止生成有害、偏见或不合规的内容。用户数据隐私明确告知用户对话可能被用于服务改进根据Perplexity政策并避免在提示词或对话历史中泄露用户个人身份信息PII。合规使用确保你的应用场景符合Perplexity API的使用条款特别是关于自动化、商业用途等方面的规定。通过本文的步骤你应该已经成功搭建了一个基于Perplexity Agent API和Kimi K3模型的智能研究助手原型。这个组合的强大之处在于它将复杂的智能体逻辑和强大的模型能力封装成了简单的API调用让开发者可以更专注于构建应用本身的价值。接下来你可以尝试将其集成到你的网站、聊天机器人或内部工具中探索更多如文档上传分析、多Agent协作等高级功能。