AI SDK Perplexity Provider 深度解析Sonar 实时联网搜索、Citations 引用与 Token 计费的完整演进【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/aiai-sdk/perplexity 是 AI SDK 官方 Perplexity 接入包让 TypeScript 应用通过统一的generateText/streamText等接口调用 Perplexity Sonar API获得带实时 Web 搜索锚点的回答能力。本文以 packages/perplexity/CHANGELOG.md 为主线结合 packages/perplexity 源码梳理该 Provider 从 0.0.1 到 4.0.42 的功能演进脉络并逐项剖析 Web 搜索参数、Citations 引用、图像/PDF 输入、reasoning tokens、成本元数据与 Embedding 支持等核心能力的底层实现帮助你快速上手并理解其工作原理。一、快速上手安装、鉴权与第一个联网搜索示例Perplexity Provider 的定位是带实时 Web 搜索能力的答案引擎。根据 packages/perplexity/README.md安装只需一条命令npm i ai-sdk/perplexity使用时从包中导入默认实例perplexity配合ai包的generateText即可完成一次带实时搜索锚点的文本生成import { perplexity } from ai-sdk/perplexity; import { generateText } from ai; const { text } await generateText({ model: perplexity(sonar-pro), prompt: What are the latest developments in quantum computing?, });鉴权方面perplexity-provider.ts 会通过loadApiKey从环境变量PERPLEXITY_API_KEY读取密钥并以Authorization: Bearer key形式附加到请求头若通过createPerplexity({ apiKey })显式传入则优先使用传入值。请求头中还带ai-sdk/perplexity/${VERSION}的 User-Agent 后缀便于服务端识别 SDK 版本对应 CHANGELOG 中1cad0ab: feat: add provider version to user-agent header。模型 ID 一览当前版本支持的语言模型 ID 定义在 perplexity-options.ts包括模型 ID定位sonar轻量级追求速度与成本sonar-pro复杂任务增强版提供约 2 倍引用数量sonar-reasoning带推理过程的推理模型sonar-reasoning-pro推理增强版sonar-deep-research深度研究模型由 CHANGELOG 2.0.0 中78e4cfc引入模型 ID 类型为(string {})的联合意味着新模型上线后无需升级 SDK 也能直接以字符串传入。二、版本演进主线从 OpenAI 兼容封装到 V4 原生 ProviderCHANGELOG 记录了该包完整的功能演进史可以归纳为四个阶段。2.0.0 之前基于 openai-compatible 起步包最初0.0.1commit5a5b668依赖ai-sdk/openai-compatible构建。早期版本的关键能力0.0.718713a5支持return_images允许在响应中返回图片搜索结果1.0.02e898b4重写 Provider 并支持 sources引用来源——不再依赖 openai-compatible改为原生实现这是 Citations 功能的基础1.0.x系列修复了错误响应数据格式6a12e44并增强对空值null的容错08f7fec。2.xAI SDK 5 时代的多模态与深度研究2.0.0随 AI SDK 5 发布d5f588f亮点包括2a9732b支持图像输入Sonar 模型开始具备多模态能力78e4cfc新增sonar-deep-research模型e2aceaf支持 raw chunk原始流式数据块透传d1a034f/205077b内部 schema 迁移到 Zod 4 并改善兼容性。3.xProvider-V3 与推理计费3.0.0AI SDK 6 beta引入 Provider-V3 架构ed329cb、8dac895此阶段关键变更4b06776支持 PDF 输入e623580新增 reasoning tokens推理 token支持cbf52cd暴露原始 finish reason3bd2689扩展 token 用量统计8d9e8ad从EmbeddingModelV3移除泛型textEmbeddingModel(...)更名为embeddingModel(...)。4.xv7 预发布与 ESM-only4.0.0是面向 AI SDK v7 的破坏性大版本从 CHANGELOG 的 Major Changes 段落 可以提取四条主线变更影响ef992f8移除 CommonJS 导出所有包改为 ESM-onlytype: modulerequire()用户必须切换到import7fc6bd6提升 Node 最低版本最低 Node.js 22支持 22 / 24 / 26package.json 中engines.node 22与此一致c29a26fProvider References 与文件上传Provider 可按自身能力声明文件上传支持04e9009统一 Provider 实现模式重命名部分导出符号旧名通过 deprecated 别名继续可用4.x 的功能增量同样丰富d976e8a在providerMetadata中暴露供应商报告的成本b3976a2为所有 Provider 模型加入WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE静态方法配合provider-utils的serializeModel()让模型实例可跨 workflow 步骤边界序列化且 provider 配置中的headers变为可选58eee2c新增embedding 模型支持4.0.322214258修复了推理 token 导致输出文本 token 计数为负的问题——Perplexity 的推理 token 从此与 completion token 分开统计4.0.39d4a22b0则保证完整的原始 chat usage 对象被保留。三、核心能力源码级剖析3.1 Web 搜索锚点Citations 与 Sources联网搜索的答案通常附带引用来源。在非流式响应中doGenerate会将响应中的citations数组转换为source类型的内容项perplexity-language-model.ts每条引用包含自动生成的id与来源url流式响应则在首个 chunk 到达时立即派发全部引用同文件L326-L342。这意味着在 AI SDK 层面引用与正文一起进入标准内容管线可以原样呈现在 UI 上。3.2 图像与 PDF多模态输入支持图像输入2.0.0 引入消息转换层支持图像 partPDF 输入3.0.0 引入4b067764.0.87927171专门修复了文件 part 中不支持的媒体类型与顶层 PDF 媒体类型的 prompt 转换问题确保 PDF 内容能正确编码进请求图片结果当请求开启return_images时响应中的图片含image_url、origin_url、宽高会进入providerMetadata.perplexity.imagesperplexity-language-model.ts。3.3 Reasoning Tokens 与 Usage 转换convertPerplexityUsageconvert-perplexity-usage.ts展示了推理计费的处理策略outputTokens: { // Perplexity reports reasoning tokens separately from completion tokens. total: completionTokens reasoningTokens, text: completionTokens, reasoning: reasoningTokens, }即outputTokens.total由 completion 与 reasoning 两部分相加而text只统计纯文本 token。这正是 CHANGELOG4.0.32所修复的负数计数问题若把推理 token 误并回文本计数当供应商单独上报推理 token 时会产生矛盾结果。4.0.39则通过保留原始rawusage 对象确保调用方永远能拿到供应商的完整原始统计数据。3.4 成本元数据Cost自4.0.0d976e8a起providerMetadata.perplexity.cost会暴露供应商报告的input_tokens_cost、output_tokens_cost、request_cost与total_costperplexity-language-model.ts。底层 schemaperplexityCostSchema还包含reasoning_tokens_cost、citation_tokens_cost、search_queries_cost等字段并带有catchall(z.json())兜底避免 API 新增字段导致解析失败。3.5 Embedding 支持4.0.1658eee2c为 Provider 增加 embedding 能力。在 perplexity-provider.ts 中embedding与embeddingModel指向同一实现旧名textEmbeddingModel作为 deprecated 别名保留CHANGELOG366f50b曾声明该别名在 3.x 中被加入。注意 Provider 的imageModel会直接抛出NoSuchModelError即 Perplexity 当前不提供图像生成模型。3.6 流式模式与原始 chunkdoStream会把stream: true追加到请求体使用createEventSourceResponseHandler解析 SSE 流perplexity-language-model.ts。2.0.0引入的 raw chunk 支持意味着当includeRawChunks为 true 时每个未解析的原始 chunk 会先于解析结果被派发同文件L314-L317。流式 chunk 的解析 schemaperplexityChunkSchema允许role可选、content可为空4.0.4的00ff2f0修复以兼容流式过程中可能出现的空 delta。四、语言模型配置参数全表4.0.78bc6172为 Provider 新增了PerplexityLanguageModelOptions类型与 Zod schema定义在 perplexity-language-model-options.ts。这些参数通过 AI SDK 的providerOptions传入例如await generateText({ model: perplexity(sonar-pro), prompt: 2025 年 AI 领域最重要的论文有哪些, providerOptions: { perplexity: { search_recency_filter: month, search_domain_filter: [arxiv.org], search_mode: web, return_images: true, }, }, });全部参数如下参数类型说明search_recency_filterhour \| day \| week \| month \| year过滤发布时间窗口不能与其他日期过滤器同时使用search_domain_filterstring[]限定搜索结果的域名/URL前缀-表示排除search_language_filterstring[]按 ISO 639-1 语言码过滤搜索结果search_after_date_filter/search_before_date_filterstring限定发布时间的起止日期last_updated_after_filter/last_updated_before_filterstring限定最后更新时间窗口search_modeweb \| academic \| sec搜索来源Web / 学术 / SECenable_search_classifierboolean为 true 时由模型自行决定是否需要联网搜索disable_searchboolean为 true 时禁用联网搜索return_related_questionsboolean响应中附带相关问题列表return_imagesboolean响应中包含图片搜索结果image_domain_filterstring[]限定图片来源域名-前缀排除image_format_filterstring[]限定图片文件格式media_response.overrides.return_videosboolean响应中附带视频结果stream_modefull \| concise控制流式事件格式reasoning_effortminimal \| low \| medium \| high控制模型推理投入程度language_preferencestring偏好回复语言ISO 639-1web_search_options.search_context_sizelow \| medium \| high注入模型搜索上下文的大小web_search_options.search_typefast \| pro \| auto快速 / 专业 / 自动路由搜索web_search_options.user_location{ latitude, longitude, country, city, region }用于搜索结果个性化的用户位置web_search_options.image_results_enhanced_relevanceboolean对图片结果启用增强相关性过滤标准参数与不支持项的说明除上述扩展参数外getArgsperplexity-language-model.ts还会把 AI SDK 的标准参数映射到 Sonar APItemperature、top_p、top_k、maxOutputTokens → max_tokens、frequencyPenalty → frequency_penalty、presencePenalty → presence_penalty并将responseFormat.type json映射为json_schema响应格式。需要注意的是topK、stopSequences、seed在当前实现中不受支持传入时会产生unsupported类型警告reasoning参数若传入自定义配置也会被拒绝isCustomReasoning检查因为 Perplexity 的推理控制应通过reasoning_effort实现。这些行为与 CHANGELOG5259a95对不支持新 reasoning 参数的 Provider 发出警告一致。五、响应解析与 Finish Reason 映射Provider 采用精简 schema catchall 兜底的策略解析响应源码注释明确说明这是为了避免 API 变更时频繁破坏并提升效率。perplexityResponseSchema只解析id、created、model、choices、citations、images与usageperplexityUsageSchema则覆盖prompt_tokens、completion_tokens、total_tokens、search_context_size、citation_tokens、num_search_queries、reasoning_tokens与cost并通过catchall(z.json())保留未知字段——这正是4.0.39preserve complete raw chat usage objects 的实现基础。错误处理方面perplexityErrorSchema解析{ error: { code, message, type } }失败信息优先取message其次type否则回退为unknown error1.0.4曾专门修复错误响应数据格式。结束原因映射在 map-perplexity-finish-reason.ts只有stop与length会原样映射为统一 finish reason其余一律归为other原始值通过finishReason.raw保留对应 3.x 的cbf52cd变更。providerMetadata.perplexity.usage中还包含citationTokens与numSearchQueries便于统计一次搜索消费的引用 token 数与查询次数。六、迁移要点与破坏性变更汇总从 CHANGELOG 中可提炼出升级到 4.x 时必须注意的破坏性变更ESM-only4.0.0起不再提供 CommonJS 导出require(ai-sdk/perplexity)会失败需改用 ESMimportNode 版本最低 Node.js 22支持 22/24/26API 重命名textEmbeddingModel已废弃统一使用embeddingModel其他被重命名的导出符号均提供 deprecated 别名过渡依赖版本4.0.42 依赖ai-sdk/provider4.0.13与ai-sdk/provider-utils5.0.39见 package.json 与 CHANGELOG 最新条目zod 的 peer 依赖范围为^3.25.76 || ^4.1.8工作流支持模型实例现已具备WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE静态方法可跨 workflow 步骤边界序列化自定义 Provider 构建模型配置时可省略headers。七、总结纵观 packages/perplexity/CHANGELOG.mdai-sdk/perplexity的演进清晰呈现出一条主线从 OpenAI 兼容的轻量封装起步逐步沉淀出原生实现并在每一次 AI SDK 大版本迭代中同步获得多模态输入、PDF、推理 token、成本元数据、Embedding 与工作流序列化等能力。当前 4.0.42 版本已是一个完整的 V4 Provider实时 Web 搜索含引用与图片、深度研究模型、灵活的搜索过滤参数与精细化计费统计构成了它的核心价值。对于需要在应用中快速接入带实时联网能力 AI 回答的场景perplexity(sonar-pro)配合providerOptions.perplexity中的搜索参数即可在 AI SDK 的统一接口下获得完整的搜索增强体验。如果你想进一步深入可以继续阅读 packages/perplexity/src/perplexity-language-model.ts 的请求构造与流式转换实现以及 packages/perplexity/src/convert-to-perplexity-messages.ts 中文本、图像与文件 part 的消息转换逻辑配套测试见 convert-to-perplexity-messages.test.ts 与 perplexity-language-model.test.ts。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考