企业官网建设流程全解析

AI SDK Moonshot AI Provider 能力全景：从 moonshot-v1 到 Kimi K3 的模型接入、思考推理与多模态实现

【免费下载链接】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-sdk/moonshotai包的 CHANGELOG.md 及其源码实现，系统梳理该 Provider 从moonshot-v1系列到kimi-k3的完整能力演进：包括思考/推理控制、结构化输出、视频等多模态输入、动态工具加载、流式 usage 与错误码保留等核心特性。读完本文，你将掌握在 AI SDK 中接入 Kimi 系列模型的完整配置方式，并理解每项 Provider 选项背后的模型家族门控与请求参数映射原理。

包概览：从 openai-compatible 依赖到自研实现

@ai-sdk/moonshotai是 AI SDK（The AI Toolkit for TypeScript）官方提供的 Moonshot AI（Kimi 开放平台）语言模型 Provider。包当前版本为 3.0.48，声明为 ESM-only 模块（"type": "module"），要求 Node.js >= 22（engines字段，见 package.json），运行时依赖仅保留@ai-sdk/provider与@ai-sdk/provider-utils两个核心包。

CHANGELOG 记录了一次重要的架构转折：3.0.32 版本中，"the provider no longer builds on@ai-sdk/openai-compatible"，即该包不再基于 OpenAI 兼容层搭建，而是自持完整的 Chat 实现——消息转换器（converter）、语言模型类与辅助函数全部由本包拥有。此后版本升级的依赖列表中@ai-sdk/openai-compatible不再出现，只剩 provider 与 provider-utils，这与 package.json 中dependencies的实际声明完全吻合。这意味着 Moonshot 独有的video_url内容部分、thinking.keep、reasoning_effort、prompt_cache_key等 API 能力不再受 OpenAI 兼容层的形状约束，可以原生透传。

npm i @ai-sdk/moonshotai

安装后即可导入默认 Provider 实例并创建模型：

import { moonshotai } from '@ai-sdk/moonshotai'; import { generateText } from 'ai'; const { text } = await generateText({ model: moonshotai('kimi-k3'), prompt: 'Write a JavaScript function that sorts a list:', });

Provider 工厂createMoonshotAI(options)支持apiKey（缺省读取MOONSHOT_API_KEY环境变量）、baseURL（默认https://api.moonshot.ai/v1）、headers与自定义fetch四项配置，见 moonshotai-provider.ts 与 createMoonshotAI 实现。创建出的 Provider 同时暴露chatModel与languageModel两种创建方式，并统一注入ai-sdk/moonshotai/{version}的 User-Agent 后缀。

模型支持矩阵与模型家族分类

MoonshotAIChatModelId类型完整列出官方支持的模型 ID，见 moonshotai-chat-options.ts：

CHANGELOG 3.0.40 中 "Add first-class Moonshot V1 auto and vision-preview model IDs while preserving custom and retired model ID support" 正是上述列表的来历——官方模型 ID 获得一等支持，同时(string & {})联合类型保留了自定义/已退役模型 ID 的透传能力。

getMoonshotAIModelFamily（moonshotai-chat-options.ts）将模型归入kimi-k2.5/kimi-k2.6/kimi-k2.7/kimi-k3/moonshot-v1/unknown六类。这个家族判定是整个 Provider 的门控中枢：思考配置、reasoningEffort、采样参数（temperature/topP/frequencyPenalty/presencePenalty）是否发送、reasoningHistory: 'preserved'是否可用，都由模型家族决定。

思考与推理：thinking、reasoningEffort 与推理历史保留

按模型家族的思考门控

Provider 选项thinking（{ type: 'enabled' | 'disabled' }）与reasoningEffort（'low' | 'high' | 'max'，默认max，见 moonshotai-chat-options.ts）的语义完全因模型而异。核心逻辑集中在 moonshotai-chat-language-model.ts 的switch (modelFamily)中：

• kimi-k3：始终推理，不接受thinking字段（传入会告警并省略）；reasoningEffort优先取显式设置，否则将 AI SDK 通用reasoning选项按minimal→low、low→low、medium→high、high→high、xhigh→max映射为reasoning_effort请求字段；
• kimi-k2.7：思考不可关闭，thinking.type: 'disabled'或reasoning: 'none'都会产生 unsupported 告警并被省略；
• kimi-k2.6：可开可关；当reasoningHistory: 'preserved'时追加keep: 'all'，映射为请求体中的thinking: { type: 'enabled', keep: 'all' }（这正是 CHANGELOG 3.0.32 所述 "reasoningHistory: 'preserved' now maps to Moonshot'sthinking.keep: 'all'request field (previously a no-op, the API ignoresreasoning_history)"）；
• kimi-k2.5：支持 thinking 开关，但preserved不被支持（产生告警）；
• moonshot-v1：thinking与reasoning均不支持，全部省略并告警。

保留推理历史的多轮对话

Kimi K2.7 Code 始终开启思考并默认保留推理（"Preserved Thinking"）。要在多轮对话中保留推理历史，使用reasoningHistory: 'preserved'：

import { moonshotai, type MoonshotAILanguageModelOptions, } from '@ai-sdk/moonshotai'; import { generateText } from 'ai'; const { text, reasoningText } = await generateText({ model: moonshotai('kimi-k2.7-code'), prompt: 'Solve this problem step by step: What is 15% of 240?', providerOptions: { moonshotai: { thinking: { type: 'enabled' }, reasoningHistory: 'preserved', } satisfies MoonshotAILanguageModelOptions, }, }); console.log(reasoningText); console.log(text);

reasoningHistory的disabled与interleaved是兼容值，不会改变请求；preserved只在 kimi-k2.6 上映射为thinking.keep: 'all'，kimi-k2.7 与 k3 默认即保留推理。Kimi K2.6 的 thinking/非 thinking 模式则用thinking: { type: 'enabled' }或thinking: { type: 'disabled' }控制。

reasoning 内容在流式与一次性调用中的输出

doGenerate会读取响应中的reasoning_content并将其作为独立的reasoning内容段置于文本之前（moonshotai-chat-language-model.ts）；doStream中则按reasoning-start → reasoning-delta → reasoning-end → text-start → text-delta → text-end的顺序派发流式事件，并在文本或工具调用开始时结束推理段（L689-L749）。这就是上层generateText中reasoningText与text分离的来源。

结构化输出：从 JSON Schema 规范化到原生支持

结构化输出是本包演进最密集的能力之一，CHANGELOG 中可梳理出清晰的脉络：

• 3.0.1：kimi-2.6与2.7-code支持结构化输出；
• 3.0.3：kimi-k2.5支持结构化输出；
• 3.0.35：新增normalize-json-schema-for-mfjs——为 Moonshot 的 MFJS 校验器规范化工具 Schema：tuple 的items数组转为prefixItems、anyOf旁的type移入各分支、非object根 Schema 直接在客户端抛出清晰错误（而非 Moonshot 返回晦涩的 400）；
• 3.0.39：官方 Moonshot V1 模型使用原生 JSON Schema 结构化输出，并默认开启严格校验（strictJsonSchema默认true）；
• 3.0.40：kimi-k3等模型获得一等支持，同时保留自定义/已退役模型 ID 的兼容。

请求构造逻辑见 moonshotai-chat-language-model.ts：当响应格式为json且模型支持结构化输出时，发送response_format: { type: 'json_schema', json_schema: { name, strict, schema } }；supportsStructuredOutputs的判定在 moonshotai-provider.ts，覆盖所有kimi-k*模型与全部 moonshot-v1 系列。实现中有一个值得注意的细节：AI SDK 注入的顶层$schema关键字会被剥离后再发送给 Moonshot（kimi-k2.5 在携带该关键字时会产生无意义输出），而原始完整 Schema 仍用于结果校验。对不支持结构化输出的场景，则回退为response_format: { type: 'json_object' }。

多模态输入：图像、视频与 ms:// 文件引用

自 3.0.32 "own the chat implementation, support video input" 起，本包原生支持视频输入。消息转换器convertToMoonshotAIChatMessages（convert-to-moonshotai-chat-messages.ts）将 AI SDK 的通用文件部分映射为 Moonshot 的内容部分：

• 图片（image/jpeg、png、gif、webp、bmp、heic、heif）→image_url内容部分；
• 视频（video/mp4、mpeg、mov、avi、x-flv、mpg、webm、wmv、3gpp）→video_url内容部分，面向kimi-k3、kimi-k2.7-code、kimi-k2.6、kimi-k2.5等视频能力模型；
• 文本文件（text/*）→ 内联文本内容（支持 URL 或 data 两种来源）；
• 音频与 PDF：在发送前直接抛出客户端错误（"Audio and PDF file parts now throw client-side"），而不是让 API 返回 400——这是 3.0.39 "Reject unsupported image and video media types before sending" 与 3.0.32 行为的延续；
• ms:// 引用：Moonshot Files API 的ms://文件引用原生透传（resolveProviderReference后必须匹配ms://前缀），并在模型层的supportedUrls中声明image/*与video/*仅接受ms://协议（moonshotai-chat-language-model.ts）。这与模型注释一致：Moonshot 不直接抓取外部 URL，AI SDK 负责下载并内联 URL 文件部分，ms://引用则直传。

工具调用：Schema 规范化、required 门控与动态加载

工具 Schema 与 tool_choice 处理

prepareTools（moonshotai-prepare-tools.ts）负责将 AI SDK 工具转换为 Moonshot 函数工具：parameters经normalizeJsonSchemaForMFJS规范化，strict字段按需透传。toolChoice的auto/none直接映射；tool映射为{ type: 'function', function: { name } }；而required对kimi-k2.6、kimi-k2.7-code、kimi-k2.7-code-highspeed会被省略并产生告警（"Moonshot AI rejects required tool choice for this model"），这正是 CHANGELOG 3.0.39 "Omit required tool choice with a warning for Moonshot Kimi models that reject it" 的源码落点。

Kimi K3 动态工具加载

3.0.40 "Support Kimi K3 dynamic tool-loading system messages"：Kimi K3 允许在对话中途通过 system 消息动态加载函数工具。使用方式是在 system 消息的 providerOptions 中传入tools数组（type、name、description、inputSchema、strict，见 moonshotai-chat-options.ts）。转换器强制约束：动态工具必须挂在 system 消息上且内容必须为空（"the API forbids content alongside tools"），并且仅对kimi-k3家族生效——其他模型会收到 unsupported 告警并被省略。

流式工具调用健壮性

3.0.39 "Accept Moonshot streaming tool calls without indices"：流式场景下部分 Moonshot 返回的tool_calls增量不含index，实现中通过toolCallDelta.index ?? index回退到遍历序号（moonshotai-chat-language-model.ts），再交由StreamingToolCallTracker完成跨 chunk 的拼接与索引纠正。配套测试夹具覆盖了显式索引、无索引、畸形索引三种情况（见__fixtures__目录下的moonshotai-stream-*-tool-call-*.chunks.txt）。

流式输出、usage 与日志概率

流式 usage 的演进

2.0.3 修复了流式场景缺失 usage 的问题；3.0.39 进一步 "preserve choice-level usage"。当前doStream同时跟踪两个 usage 来源：chunk 顶层usage（经stream_options: { include_usage: true }请求）与choice.usage，结束时以顶层优先、choice 兜底合并（moonshotai-chat-language-model.ts 与 L766）。usage 转换器convertMoonshotAIChatUsage保留完整原始对象（3.0.41 "preserve complete raw usage objects"），并处理推理 token 计数——3.0.38 修复了 "Prevent negative text output token counts when providers report reasoning tokens"，将推理 token 与完成 token 分开统计。

日志概率与原始元数据

3.0.39 "Add Moonshot Chat Completions log probability options and provider metadata"：logprobs: true或topLogprobs（整数，0–20，设置后自动启用 logprobs）会发送logprobs与top_logprobs请求字段；响应中的choice.logprobs.content在流式场景累积并在finish事件中随 providerMetadata 输出。此外，responseObject、choiceIndex、messageRole、toolCallTypes等原始响应元数据被完整保留在 providerMetadata 中（一次性与流式均覆盖）。

高级选项：Predicted Output、缓存与安全标识

Provider 选项还包含三个面向性能与合规的字段（moonshotai-chat-options.ts）：

• prediction（3.0.40 "add predicted output support"）：当输出中大部分内容可预知时，传入静态预测内容以加速响应，{ type: 'content', content: string | Array<{ type: 'text', text }> }，直接映射为请求体prediction字段；
• promptCacheKey：为相似请求复用响应缓存、提高命中率，通常是会话或任务 ID，映射为prompt_cache_key；
• safetyIdentifier：帮助 Moonshot 识别违反使用政策的用户，建议对用户名或邮箱做哈希，映射为safety_identifier。

Partial Mode：续写末条助手消息

3.0.40 "Add Moonshot AI Partial Mode support for continuing a final assistant message"：在最后一条 assistant 消息上设置providerOptions.moonshotai.partial: true，请求中发送partial: true让 Moonshot 续写该消息。约束有三：仅限 assistant 角色、必须是 prompt 的最后一条消息、不能与 JSON object 响应格式组合（违反会抛出InvalidPromptError，见 convert-to-moonshotai-chat-messages.ts 与 L292-L309）。

错误处理：Moonshot 错误码的完整保留

3.0.39 与 3.0.41 两度强化错误语义："normalize mid-stream provider error events ... into public StreamProviderError instances and preserve provider-owned type, code, status, retry, and raw payload metadata" 与 "Preserve documented Moonshot API error codes in HTTP and streaming errors"。实现上有两层：

• HTTP 层：createJsonErrorResponseHandler基于moonshotAIErrorSchema（error.message/error.type/error.code）解析失败响应，见 moonshotai-chat-api-types.ts；
• 流中层：createMoonshotAIStreamError将 Moonshot 文档化错误类型映射为标准的statusCode与isRetryable语义（moonshotai-chat-language-model.ts）：rate_limit_exceeded/rate_limit_error→ 429 可重试，server_error/api_error/internal_server_error→ 500 可重试，overloaded_error/service_unavailable→ 503 可重试，timeout→ 504 可重试，认证/权限/未找到/请求错误 → 401/403/404/400 不可重试。这样上层 AI SDK 的重试策略与错误分类可以对齐 Moonshot 的真实语义。

平台级演进：ESM-only、Node 版本与工作流序列化

3.0.0 是 v7 预发布中的大版本，带来了三项全仓级变更：

• 移除 CommonJS 导出：所有包转为 ESM-only（"type": "module"），require()消费方必须改用 ESMimport；
• 最低 Node.js 版本提升到 22，支持 22/24/26；
• 工作流序列化支持：所有 Provider 模型类新增WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE静态方法（moonshotai-chat-language-model.ts），配合 provider-utils 的serializeModel()只提取可序列化属性（过滤函数与含函数的对象），使模型实例可以安全跨越 workflow 步骤边界。同时headers在 Provider 配置类型中变为可选，便于在认证单独提供的工作流边界反序列化模型。

此外 3.0.0 还统一了各 Provider 的代码模式与导出符号命名（旧名称通过 deprecated 别名继续可用），并在 README 中加入了 AI Gateway 提示。CHANGELOG 中频繁出现的 "Updated dependencies" 条目（provider / provider-utils 的补丁升级）也印证了 Moonshot Provider 与 AI SDK 核心层的同步演进关系。

测试与质量保障

本包对上述能力均有对应的测试与夹具支撑，是理解实现细节的最佳入口：

• 单元测试：moonshotai-chat-language-model.test.ts、convert-to-moonshotai-chat-messages.test.ts、moonshotai-provider.test.ts、moonshotai-prepare-tools.test.ts、normalize-json-schema-for-mfjs.test.ts、convert-moonshotai-chat-usage.test.ts；
• 类型测试：moonshotai-chat-options.test-d.ts、moonshotai-message-provider-options.test-d.ts、moonshotai-provider.test-d.ts；
• 真实 API 响应夹具：src/fixtures目录下覆盖错误响应、日志概率、推理内容、流式 usage 优先级、显式/无索引/畸形索引工具调用等场景的 JSON 与 SSE chunks 文本。

测试脚本见 package.json（test:node与test:edge分别跑 Node 与 Edge 环境的 vitest），可在安装依赖后通过pnpm --filter @ai-sdk/moonshotai test复现。

总结

从moonshot-v1到kimi-k3，@ai-sdk/moonshotai的演进主线清晰：脱离 OpenAI 兼容层实现能力自主 → 逐模型家族落地思考/推理控制与结构化输出 → 补齐视频、动态工具、Predicted Output 等 Moonshot 特有 API 的原生支持 → 全链路保留错误码与 usage 等原始元数据。对开发者而言，理解"模型家族门控"这一核心设计——同一个选项在不同模型上的启用、省略或告警——是正确使用该 Provider 的关键；官方模型 ID 列表（moonshotai-chat-options.ts）与上述各项配置示例，可直接作为接入 Kimi 系列模型的速查手册。

【免费下载链接】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