LangChain.js 集成 Perplexity 完全指南Chat 模型、联网检索器与搜索工具实战【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjslangchain/perplexity是 LangChain.js 官方提供的 Perplexity AI 集成包封装了 Perplexity 的对话补全Chat Completions、Agent APIResponses 兼容与独立搜索接口/search。本文基于当前仓库中 langchain-perplexity/README.md 及其 源码实现系统讲解 ChatPerplexity 聊天模型的配置参数、流式输出、JSON Schema 结构化输出、推理模型的think标签处理以及PerplexitySearchRetriever检索器与PerplexitySearchResults搜索工具并深入剖析底层参数映射与 API 路由逻辑帮助你直接在 LangChain.js 生态中搭建带实时联网搜索能力的智能体应用。包概览与安装该包版本见 package.json当前为0.3.0同时提供三类能力Chat 模型ChatPerplexity基于 OpenAI SDK 访问 Perplexity 的 Chat 与 Agent 端点检索器PerplexitySearchRetriever调用 Perplexity Search API 并返回 LangChainDocument工具PerplexitySearchResults将同一/search端点包装成 LangChainTool供 Agent 直接调用。安装命令如下需要同时安装核心包Peer 依赖要求langchain/core为^1.0.0npm install langchain/perplexity langchain/core包默认构建为 ESM/CJS 双格式产物Node.js 版本要求20见 package.json。环境准备API Key 配置使用前需要 Perplexity API Key。聊天模型读取PERPLEXITY_API_KEY环境变量而检索器与搜索工具额外兼容PPLX_API_KEY这一历史别名变量源码见 retrievers.ts 与 tools.ts。export PERPLEXITY_API_KEYyour-api-key也可以在构造函数中直接传入apiKey字段覆盖环境变量。三种方式都未配置时构造器会抛出Perplexity API key not found错误——这一点在 chat_models.test.ts 与 retrievers.test.ts 中均有对应单测覆盖。聊天模型内部使用 OpenAI SDK 并固定baseURL为https://api.perplexity.ai见 chat_models.ts。基本对话ChatPerplexity 快速上手最简单的用法是实例化模型并通过invoke发送消息import { ChatPerplexity } from langchain/perplexity; const model new ChatPerplexity({ model: sonar, }); const response await model.invoke([ [human, What is the capital of France?], ]); console.log(response.content); // Citations are available in additional_kwargs console.log(response.additional_kwargs.citations);要点说明消息以[human, ...], [ai, ...], [system, ...]的元组形式传入内部messageToPerplexityRole会将其映射为 Perplexity API 的user/assistant/system三种角色见 chat_models.ts不支持的消息类型会抛出Unknown message type错误联网回答的引用链接citations不会出现在content里而是存放在返回消息的additional_kwargs.citations中非流式与流式场景下都适用流式时仅挂载在首个 chunk 上。流式输出Streaming开启streaming: true后可用model.stream()逐 token 消费输出import { ChatPerplexity } from langchain/perplexity; const model new ChatPerplexity({ model: sonar, streaming: true, }); const stream await model.stream([[human, Explain quantum computing]]); for await (const chunk of stream) { process.stdout.write(chunk.content as string); }底层实现上_streamResponseChunks会请求 Chat 端点并逐 chunk 解析增量内容同时把finish_reason写入generationInfo如果设置了streaming: true又调用invoke()则会把所有 chunk 聚合为一条完整生成结果见 chat_models.ts。单测 chat_models.test.ts 验证了流式 chunk 的拼接、引用仅挂在首 chunk、空内容 chunk 跳过等行为。结构化输出基于 JSON SchemaPerplexity 通过 JSON Schema 支持结构化输出。使用withStructuredOutput传入 Zod schema 即可获得强类型结果import { ChatPerplexity } from langchain/perplexity; import { z } from zod; const model new ChatPerplexity({ model: sonar, }); const structured model.withStructuredOutput( z.object({ capital: z.string(), country: z.string(), population: z.number().optional(), }) ); const result await structured.invoke(What is the capital of India?); console.log(result); // { capital: New Delhi, country: India, population: ... }需要注意的限制均体现在 chat_models.ts 的实现中只支持jsonSchema方法传入method: functionCalling会直接抛错不支持strict模式设置{ strict: true }会抛出strict mode is not supported for this model.模型内部把 schema 转换为response_format.type json_schema的请求参数支持includeRaw: true获取{ raw, parsed }原始消息与解析结果若模型名包含reasoning如sonar-reasoning解析器会自动替换为专门剥离think标签的推理版解析器见下文。推理模型与 标签自动剥离Perplexity 提供带逐步思考过程的推理模型如sonar-reasoning。普通聊天时无需额外处理import { ChatPerplexity } from langchain/perplexity; const model new ChatPerplexity({ model: sonar-reasoning, }); const result await model.invoke([ [human, What are the most popular LLM frameworks?], ]); console.log(result.content);而当推理模型配合结构化输出时响应中可能夹杂think.../think思考片段直接解析 JSON 会失败。为此包内提供了两个专用解析器源码见 utils/output_parsers.tsReasoningStructuredOutputParser先剥离think标签再按 Zod schema 解析ReasoningJsonOutputParser先剥离think标签再按原始 JSON 解析。withStructuredOutput会依据模型名是否包含reasoning自动选用上述解析器无需手动干预。剥离逻辑stripThinkTags支持多个think片段、空标签、标签前后空白等边界情况对应单测见 utils/tests/output_parsers.test.ts。搜索行为配置让模型实时联网Perplexity 模型默认可联网搜索通过构造参数可以精细控制搜索范围与方式import { ChatPerplexity } from langchain/perplexity; const model new ChatPerplexity({ model: sonar-pro, searchDomainFilter: [wikipedia.org, arxiv.org], searchRecencyFilter: week, searchMode: academic, webSearchOptions: { search_context_size: high, user_location: { latitude: 37.7749, longitude: -122.4194, country: US, }, }, });其中webSearchOptions的search_context_size可取low最小化上下文以节省成本、medium均衡或high最大化上下文以获得全面回答user_location用经纬度与两位国家代码近似定位以精化结果类型定义见 chat_models.ts。也可以完全关闭联网只用训练数据const model new ChatPerplexity({ model: sonar, disableSearch: true, });另外enableSearchClassifier: true可让模型内置的分类器自动判断当前问题是否需要触发搜索。参数映射规则camelCase 到 snake_case所有配置最终通过invocationParams()组装成 API 请求体见 chat_models.ts。LangChain 侧统一使用 camelCase发送前映射为 Perplexity API 的 snake_case 字段LangChain 参数API 字段说明maxTokensmax_tokens最大生成长度topPtop_p核采样topKtop_ktop-k 采样presencePenaltypresence_penalty存在惩罚frequencyPenaltyfrequency_penalty频率惩罚returnImagesreturn_images返回图片returnRelatedQuestionsreturn_related_questions返回相关问题searchDomainFiltersearch_domain_filter域过滤searchRecencyFiltersearch_recency_filter时间过滤searchModesearch_modeacademic或webreasoningEffortreasoning_effort深度研究模型的思考强度disableSearchdisable_search关闭搜索enableSearchClassifierenable_search_classifier搜索分类器webSearchOptionsweb_search_options上下文规模与位置该映射行为在 chat_models.test.ts 的invocationParams用例中有逐字段断言。配置参考完整参数表以下为ChatPerplexity支持的全部构造参数源自 README.md 与 chat_models.ts 的类型定义参数类型说明modelstring必填。模型名如sonar、sonar-pro、sonar-reasoning、深度研究模型等。apiKeystringAPI Key默认取PERPLEXITY_API_KEY环境变量。temperaturenumber采样温度0–2。maxTokensnumber最大生成 token 数。topPnumber核采样参数0–1。topKnumberTop-k 采样参数1–2048。presencePenaltynumber存在惩罚-2 到 2。frequencyPenaltynumber频率惩罚 0。streamingboolean启用流式响应。timeoutnumber请求超时毫秒。searchDomainFilterunknown[]将引用限制到指定域名。searchRecencyFilterstring时间过滤month、week、day、hour。searchModestringacademic优先学术来源或web。returnImagesboolean响应中返回图片。returnRelatedQuestionsboolean返回相关问题。reasoningEffortstringlow、medium或high用于深度研究模型。disableSearchboolean完全关闭联网搜索。enableSearchClassifierboolean自动判断是否需要搜索。webSearchOptionsobject搜索上下文规模与用户位置。searchAfterDateFilterstring仅包含此日期之后发布的内容。searchBeforeDateFilterstring仅包含此日期之前发布的内容。lastUpdatedAfterFilterstring仅包含此日期之后更新的内容。lastUpdatedBeforeFilterstring仅包含此日期之前更新的内容。useResponsesApiboolean是否强制走 Agent APIResponses 兼容端点见下节。进阶Agent APIResponses自动路由从源码看ChatPerplexity还支持 Perplexity Agent APIResponses 兼容端点即POST /v1/agent别名为/v1/responses。路由判定逻辑位于 chat_models.ts 与_useResponsesApi辅助函数中规则为显式指定useResponsesApi: true/false时直接遵循自动检测请求负载中出现内置工具web_search、fetch_url、finance_search、people_search等即type非function的工具或任何 Responses-only 字段previousResponseId、instructions、input、include时自动切换。走 Responses 路由时调用选项可透传toolsOpenAI 风格函数工具或 Perplexity 内置工具、previousResponseId延续上一轮对话、instructions系统指令、input原生输入会替换messages与include附加响应字段。响应通过convertResponsesToChatResult转成标准ChatResult其中citations、images、related_questions、search_results等元数据会写入response_metadata流式事件如response.output_text.delta、response.completed、response.error则由convertResponsesEventToChunk逐条转换见 chat_models.ts。路由行为在 chat_models_responses.test.ts 中有完整断言。Perplexity Search 检索器PerplexitySearchRetriever直接调用 Perplexity Search APIPOST https://api.perplexity.ai/search将每条结果包装为 LangChainDocumentpageContent为结果摘要snippetmetadata中携带title、url、date、last_updated四个字段实现见 retrievers.ts。import { PerplexitySearchRetriever } from langchain/perplexity; const retriever new PerplexitySearchRetriever({ k: 5, searchRecencyFilter: week, searchDomainFilter: [wikipedia.org], }); const docs await retriever.invoke(Latest LLM benchmarks); for (const doc of docs) { console.log(doc.metadata.title, doc.metadata.url); console.log(doc.pageContent); }请求体由buildRequestBody按需组装默认始终携带query、max_results、max_tokens、max_tokens_per_page其余过滤参数仅在显式设置时加入API 返回非 2xx 状态码时会抛出包含状态码的Perplexity Search API error见 retrievers.test.ts。Perplexity Search 工具PerplexitySearchResults是同一/search端点的 LangChainTool包装工具名为perplexity_search_results_json_call返回 JSON 编码的结果数组每个元素形如{ title, url, snippet, date, last_updated }实现见 tools.tsimport { PerplexitySearchResults } from langchain/perplexity; const tool new PerplexitySearchResults({ maxResults: 5, searchRecencyFilter: week, }); const json await tool.invoke(Latest LLM benchmarks); console.log(JSON.parse(json));与检索器不同工具在请求失败时不会抛异常而是返回Perplexity search failed: HTTP 状态码 错误信息或Perplexity search failed: 错误类型这类字符串便于 Agent 把错误当作工具输出继续推理见 tools.test.ts 的错误路径用例。搜索参数表两类搜索组件共享同一套 Perplexity Search 过滤参数参数类型说明apiKeystringAPI Key默认取PERPLEXITY_API_KEY或PPLX_API_KEY环境变量。k/maxResultsnumber最大结果数1–20默认10。maxTokensnumber仅检索器。所有结果合计最大 token 数默认25000。maxTokensPerPagenumber仅检索器。单页最大 token 数默认1024。countrystringISO 国家代码如US。searchDomainFilterstring[]最多限制 20 个域名。searchRecencyFilterday \| week \| month \| year时间过滤。searchAfterDatestring仅包含此日期之后的内容格式%m/%d/%Y。searchBeforeDatestring仅包含此日期之前的内容格式%m/%d/%Y。其中检索器与工具在时间过滤上的取值略有差异检索器/工具支持day/week/month/year而聊天模型的searchRecencyFilter为month/week/day/hour使用时需注意区分。组合实战带联网搜索的 RAG 智能体将以上组件组合即可搭建先搜索、后回答的检索增强流程。例如把检索器接入createRetrieverTool或直接把PerplexitySearchResults交给 Agent 作为工具import { ChatPerplexity, PerplexitySearchResults } from langchain/perplexity; import { createAgent } from langchain/langgraph/prebuilt; const model new ChatPerplexity({ model: sonar-pro }); const tool new PerplexitySearchResults({ maxResults: 5 }); const agent createAgent({ llm: model, tools: [tool], });模型负责生成搜索工具负责实时取证Agent 根据工具返回的 JSON 结果组织带引用的回答。若需要纯向量检索之外的文档化结果则优先选择PerplexitySearchRetriever配合createRetrieverTool或直接retriever.invoke()使用。常见问题与注意事项API Key 缺失构造器立即抛错务必在实例化前配置PERPLEXITY_API_KEY结构化输出的限制strict模式与functionCalling方法均不受支持只能使用jsonSchema推理模型与普通模型解析器不同withStructuredOutput会根据模型名自动切换无需手动指定流式引用位置citations 只挂在首个流式 chunk 的additional_kwargs上聚合消费时建议从首 chunk 读取搜索工具的错误处理策略工具失败返回错误字符串而非抛错注意在 Agent 提示词中说明这一行为相对路径说明本文涉及的全部源码与测试文件位于仓库libs/providers/langchain-perplexity/目录下可结合 README.md、chat_models.ts、retrievers.ts、tools.ts 及对应测试文件进一步研读。通过本文的配置参数、源码映射与路由规则说明你已经可以在 LangChain.js 中完整使用 Perplexity 的对话、推理、结构化输出与联网搜索能力为上层 RAG 或 Agent 应用提供实时、可引用的数据来源。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考