人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载本篇指南聚焦 VoltAgent 模型路由器中 Fireworks AI 提供方fireworks-ai的完整接入方式如何使用fireworks-ai/model字符串零导入地创建 Agent、FIREWORKS_API_KEY与 base URL 的解析规则以及注册表中收录的 16 个模型。读完本文你可以直接复制可用的配置代码并能从源码层面理解模型 ID 如何被拆分为提供方与模型、OpenAI 兼容适配器在何处被构建便于排查鉴权与路由问题。一、集成方式总览一条fireworks-ai/model字符串即可路由Fireworks AI 在 VoltAgent 中的接入遵循统一的零导入模型字符串模式无需手动import任何提供方 SDK只需在Agent配置中传入fireworks-ai/前缀的模型 ID运行时由ModelProviderRegistry完成解析与懒加载。提供方元数据来自自动生成文件 model-provider-registry.generated.ts其中 Fireworks AI 的注册表条目为fireworks-ai: { id: fireworks-ai, name: Fireworks AI, npm: ai-sdk/openai-compatible, api: https://api.fireworks.ai/inference/v1/, env: [FIREWORKS_API_KEY], doc: https://fireworks.ai/docs/, },该文件头部注释表明它由 models.dev 数据源自动生成Generated from https://models.dev/api.json请勿手工编辑。各字段含义与实际用途如下字段值运行时作用idfireworks-ai模型 ID 的前缀路由时按第一个/之前的部分匹配大小写不敏感npmai-sdk/openai-compatible首次使用该提供方时才会动态import的包名apihttps://api.fireworks.ai/inference/v1/默认 base URL可被环境变量覆盖env[FIREWORKS_API_KEY]鉴权所需的 API Key 环境变量名dochttps://fireworks.ai/docs/官方文档入口注册表记录供参考二、快速开始最小可运行示例按官方文档fireworks-ai.md给出的 Quick start创建使用 Fireworks AI 模型的最小 Agent 如下import { Agent } from voltagent/core; const agent new Agent({ name: fireworks-ai-agent, instructions: You are a helpful assistant, model: fireworks-ai/accounts/fireworks/models/deepseek-r1-0528, });运行前唯一的前提条件进程环境中设置了FIREWORKS_API_KEY。模型 ID 是如何被拆分的值得注意的是Fireworks AI 的模型 ID 自身就包含多级斜杠accounts/fireworks/models/...。从源码看model-provider-registry.ts 中的splitModelId只按第一个/切分前缀fireworks-ai作为提供方 ID剩余整段accounts/fireworks/models/deepseek-r1-0528作为传给底层适配器的模型 ID。因此多级路径模型名无需任何转义直接原样书写即可。若 ID 中不含/或误用:之外的分隔符会抛出Invalid model id ... Use provider/model.错误。三、环境变量与鉴权规则Fireworks AI 提供方要求的鉴权环境变量为FIREWORKS_API_KEY这是注册表env字段声明的唯一变量。源码中的鉴权解析逻辑位于 model-provider-registry.tsconst apiKeyEnvNames (config: ModelProviderRegistryEntry): string[] { const envNames config.env ?? []; const keyNames envNames.filter((name) /KEY|TOKEN|SECRET/i.test(name)); return keyNames.length ? keyNames : envNames; }; const requireApiKey (config: ModelProviderRegistryEntry): ProviderEnvMatch { const envNames apiKeyEnvNames(config); const match resolveEnvValue(envNames); if (!match) { throw new Error(Missing API key for ${config.id}. Set ${formatEnvList(envNames)}.); } return match; };由此可以得出两条实践要点空值等同于未设置resolveEnvValue会trim后再判断FIREWORKS_API_KEY也会触发缺失错误错误信息可直接定位未设置时会抛出Missing API key for fireworks-ai. Set process.env.FIREWORKS_API_KEY.按提示设置即可。四、Base URL默认值与覆盖方式注册表为 Fireworks AI 声明的默认 base URL 是https://api.fireworks.ai/inference/v1/如需指向自建网关或其他端点可以设置环境变量FIREWORKS_AI_BASE_URL命名规则为PROVIDER_ID去掉连字符转下划线后拼接_BASE_URL由 envKeyForProvider 生成。base URL 的最终取值由 resolveBaseUrl 决定优先级从高到低为注册表env列表中名称匹配/ENDPOINT|BASE_URL|BASEURL/i的环境变量本提供方未声明此类变量故跳过约定俗成的FIREWORKS_AI_BASE_URL注册表api字段中的默认地址。若三者皆不可用例如移除了注册表api字段且未设置覆盖变量适配器构建阶段会抛出Missing base URL for fireworks-ai. ...错误——对当前仓库版本而言默认地址始终存在这一分支实际不会触发。五、底层实现OpenAI 兼容适配器的构建过程文档声明 Fireworks AI 的 Provider 包为ai-sdk/openai-compatible即走通用 OpenAI 兼容路径而非专有 SDK。该包不是VoltAgent 的默认依赖而是在首次解析到fireworks-ai/...模型时才按需加载createProviderLoader 返回一个懒加载闭包执行await import(ai-sdk/openai-compatible)由于npm字段匹配PACKAGE_ADAPTERS中的ai-sdk/openai-compatible: buildOpenAICompatibleProvider交由该适配器构建buildOpenAICompatibleProvider 调用包内导出的createOpenAICompatibleconst provider createFn({ name: config.id, // fireworks-ai baseURL, // 按第四节优先级解析 apiKey: apiKeyMatch.value, // FIREWORKS_API_KEY 的值 supportsStructuredOutputs: true, // 开启结构化输出支持 });两点值得注意supportsStructuredOutputs: true是注册表统一注入的选项意味着经由fireworks-ai/路由的模型会启用 OpenAI 兼容协议的结构化输出能力动态加载失败例如未安装该包时resolveLanguageModel 外层会包装为Failed to load provider fireworks-ai from ai-sdk/openai-compatible. Install the package and try again.提示需要先安装对应 npm 包。六、当前注册表收录的模型清单16 个以下模型清单与 fireworks-ai.md 的 Models 章节一致并与类型文件 model-provider-types.generated.ts 中的fireworks-ai元组逐条对应该类型文件过滤了已标记deprecated的模型。使用时一律采用fireworks-ai/ 模型 ID 前缀模型 ID前缀fireworks-ai/系列accounts/fireworks/models/deepseek-r1-0528DeepSeek R1accounts/fireworks/models/deepseek-v3-0324DeepSeek V3accounts/fireworks/models/deepseek-v3p1DeepSeek V3accounts/fireworks/models/deepseek-v3p2DeepSeek V3accounts/fireworks/models/glm-4p5GLMaccounts/fireworks/models/glm-4p5-airGLMaccounts/fireworks/models/glm-4p6GLMaccounts/fireworks/models/glm-4p7GLMaccounts/fireworks/models/gpt-oss-120bGPT-OSSaccounts/fireworks/models/gpt-oss-20bGPT-OSSaccounts/fireworks/models/kimi-k2-instructKimi K2accounts/fireworks/models/kimi-k2-thinkingKimi K2accounts/fireworks/models/minimax-m2MiniMax M2accounts/fireworks/models/minimax-m2p1MiniMax M2accounts/fireworks/models/qwen3-235b-a22bQwen3accounts/fireworks/models/qwen3-coder-480b-a35b-instructQwen3 Coder类型安全的模型 ID为获得 IDE 自动补全可以使用 model-provider-registry.ts 中定义的联合类型import type { ModelRouterModelId } from voltagent/core; const modelId: ModelRouterModelId fireworks-ai/accounts/fireworks/models/kimi-k2-instruct;该类型由生成文件按{ 提供方 } / { 模型 }模板拼接而成上表中的每个 ID 都是合法的联合成员同时保留(string {})兜底允许注册表之外的自定义 ID。七、进阶用法运行时动态选模与自定义请求头按请求上下文动态选择模型model字段支持接收函数在每次生成时根据上下文返回不同的模型 ID。例如面向不同层级用户路由到不同 Fireworks 模型const agent new Agent({ name: runtime-router, model: ({ context }) { const tier (context.get(tier) as string) || fast; return tier fast ? fireworks-ai/accounts/fireworks/models/gpt-oss-20b : fireworks-ai/accounts/fireworks/models/deepseek-v3p2; }, });需要自定义 headers 时直接注入 LanguageModel模型字符串路径不支持自定义请求头。若 Fireworks AI 网关要求附加 header可按 Models overview 的Custom headers方案直接传入 ai-sdk 的LanguageModelVoltAgent 在所有期望LanguageModel的位置都接受它import { Agent } from voltagent/core; import { createOpenAICompatible } from ai-sdk/openai-compatible; const fireworks createOpenAICompatible({ name: fireworks-ai, baseURL: https://api.fireworks.ai/inference/v1/, apiKey: process.env.FIREWORKS_API_KEY, headers: { X-Client-Source: voltagent-docs, }, }); const agent new Agent({ name: fireworks-custom, model: fireworks(accounts/fireworks/models/kimi-k2-instruct), });八、文档与注册表的生成、刷新机制本文引用的 fireworks-ai.md 由 website/scripts/generate-model-docs.js 自动生成文件头注释THIS FILE IS AUTO-GENERATED ... DO NOT EDIT MANUALLY即由此而来。该脚本解析 model-provider-registry.generated.ts 与 model-provider-types.generated.ts 两个文件为每个提供方输出包含 Quick start、环境变量、Provider 包、默认 base URL、官方文档链接与折叠模型列表的页面——本文第二、四、六节的内容即忠实继承自该页面。运行时还有一层活的刷新机制从源码结构看主要服务于非生产环境默认刷新间隔 30 分钟DEFAULT_AUTO_REFRESH_INTERVAL_MS 30 * 60 * 1000启动时 model-provider-registry.ts 在NODE_ENV ! production下调用startAutoRefresh刷新拉取 models.dev 数据后写入~/.voltagent/model-registry/缓存目录并在生产环境NODE_ENV production跳过缓存加载因此若模型清单与本文不一致以你所用版本内置的注册表快照为准。九、接入检查清单按以下顺序验证 Fireworks AI 接入每一步都有明确的可观察信号安装voltagent/core并将ai-sdk/openai-compatible纳入应用依赖懒加载失败时会提示Install the package and try again设置FIREWORKS_API_KEY非空未设置时报错信息会明确给出变量名可选设置FIREWORKS_AI_BASE_URL覆盖默认端点https://api.fireworks.ai/inference/v1/使用本文第六节清单中的fireworks-ai/model字符串创建Agent调用generateText验证端到端链路若提供方 ID 拼写错误如fireworks路由会抛出No provider registered for fireworks. Available providers: ...错误信息中列出全部可用提供方可据此核对前缀。至此本文完整覆盖了 Fireworks AI 提供方页面的全部要素——Quick start、环境变量、Provider 包、默认 base URL 与覆盖方式、官方文档入口和 16 个模型清单——并结合 model-provider-registry.ts 的解析、鉴权与适配器构建源码给出了每个配置项背后的实际行为可作为接入与排障的完整参考。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐Tiled自动化映射深度解析如何实现高效地图绘制的完整指南Tiled自动化映射深度解析如何实现高效地图绘制的完整指南 Tiled地图编辑器的自动化映射Automapping功能是游戏地图制作中的革命性工具它通过人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音VoltAgent 模型路由与注册表实战用 provider/model 字符串一行接入任意 LLMVoltAgent 模型路由与注册表实战用 provider/model 字符串一行接入任意 LLM VoltAgent 的 Model Router 让人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音OpenClaw Fireworks 插件接入 Fireworks 模型提供商的完整实践OpenClaw Fireworks 插件接入 Fireworks 模型提供商的完整实践 本文以 OpenClaw 仓库中的 Fireworks 插件参考文档AI 应用AI Agent交互助手后端即时通讯网关上一篇Activepieces HTTP (OAuth2) Piece 深入指南从构建到发送带 Bearer Token 的授权请求下一篇couplet-dataset数据集详解训练seq2seq对联生成模型的终极资源创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
