在 VoltAgent 中接入 Weights Biases 模型路由：wandb 提供方使用指南

人工智能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 模型路由Model Router对 Weights BiasesWB推理服务的官方支持展开介绍如何通过wandb/model形式的模型标识符在 Agent 中直接调用 WB Inference 提供的开源大模型。读完本文你将掌握WANDB_API_KEY与WANDB_BASE_URL的配置方法、ai-sdk/openai-compatible适配层的底层工作原理以及 WB 当前支持的 10 个模型清单并能在 VoltAgent 项目中快速落地一个可运行的 wandb Agent 示例。概述WB 提供方在 VoltAgent 中的定位VoltAgent 的模型路由体系通过统一的provider/model标识符让上层 Agent 代码无需关心具体是哪一个厂商的 API。Weights Biases 是这一体系中的一个内置提供方provider其注册信息可以在 model-provider-registry.generated.ts 中看到字段值idwandbnameWeights Biasesnpmai-sdk/openai-compatibleapi默认 Base URLhttps://api.inference.wandb.ai/v1env必需环境变量WANDB_API_KEYdoc官方文档https://weave-docs.wandb.ai/guides/integrations/inference/从该注册表可以确认WB 提供方基于 OpenAI 兼容协议接入因此无需为它单独安装 WB 专用 SDK而是复用ai-sdk/openai-compatible适配器。快速开始最小可用示例在项目依赖中安装 VoltAgent Core 后即可用如下代码创建使用 WB 模型的 Agentimport { Agent } from voltagent/core; const agent new Agent({ name: wandb-agent, instructions: You are a helpful assistant, model: wandb/Qwen/Qwen3-235B-A22B-Instruct-2507, });关键点在于model字段的值格式wandb/前缀对应提供方 id斜杠之后是 WB 侧的模型名同样带命名空间斜杠例如Qwen/Qwen3-235B-A22B-Instruct-2507。运行前必须设置 API Keyexport WANDB_API_KEYyour_wandb_inference_api_key运行时若未提供 API Key模型路由会抛出类似Missing API key for wandb. Set process.env.WANDB_API_KEY.的错误——该错误提示由 model-provider-registry.ts 中的requireApiKey逻辑生成它会遍历提供方注册表中的env列表此处即WANDB_API_KEY并校验环境变量是否存在。环境变量与 Base URL 覆盖WANDB_API_KEY必需认证凭据变量名WANDB_API_KEY用途向https://api.inference.wandb.ai/v1发起推理请求时的认证凭据作用范围仅 wandb 提供方若同时使用多个提供方各提供方的 Key 独立生效WANDB_BASE_URL可选的端点覆盖默认请求端点固定为https://api.inference.wandb.ai/v1但可以通过设置WANDB_BASE_URL覆盖适用于自建代理、私有化网关或测试环境等场景export WANDB_BASE_URLhttps://your-proxy.example.com/v1从底层实现看Base URL 的解析顺序定义在 model-provider-registry.ts 的resolveBaseUrl中优先读取提供方env列表中名称匹配ENDPOINT/BASE_URL/BASEURL的环境变量其次读取惯例命名的${PROVIDER_ID}_BASE_URL将提供方 id 转大写并将连字符替换为下划线即WANDB_BASE_URL均未设置时回退到注册表中的api字段默认值。因此即使不显式配置WANDB_BASE_URL模型路由也会自动使用默认端点无需任何额外代码。Provider packageOpenAI 兼容适配层如何工作WB 提供方指定的 Provider package 为ai-sdk/openai-compatible。在 VoltAgent 中不同 npm 包会映射到不同的适配器实现映射表见 model-provider-registry.ts 的PACKAGE_ADAPTERS。ai-sdk/openai-compatible对应buildOpenAICompatibleProvider见 model-provider-registry.ts其核心行为是通过requireApiKey(config)校验WANDB_API_KEY是否已设置通过resolveBaseUrl(config)确定最终请求端点调用createOpenAICompatible({ name, baseURL, apiKey, supportsStructuredOutputs: true })构造提供方实例其中name取提供方 idwandbsupportsStructuredOutputs被显式开启表示该端点支持结构化输出。也就是说WB 推理端点只需遵循 OpenAI Chat Completions 协议即可被 VoltAgent 直接使用这也解释了为何本文的快速开始示例中无需 import 任何 WB 专属模块。模型路由的解析过程wandb/Qwen/Qwen3-235B-A22B-Instruct-2507这类标识符在内部由 resolveLanguageModel 处理解析流程如下splitModelId以第一个/切分模型标识符得到提供方 idwandb与模型 idQwen/Qwen3-235B-A22B-Instruct-2507详见 model-provider-registry.ts从注册表静态内置表 本地缓存 动态刷新中查找wandb提供方首次使用时懒加载ai-sdk/openai-compatible模块并通过适配器构建提供方实例用解析出的模型 id 调用提供方工厂函数返回可供 Agent 使用的LanguageModel。值得注意的是模型路由在非生产环境下默认启动自动刷新每 30 分钟检查一次https://models.dev/api.json源并会把最新的提供方/模型快照缓存到用户目录下的~/.voltagent/model-registry/provider-registry.json相关常量见 model-provider-registry.ts。这意味着模型清单可能随刷新而更新本文列出的模型以当前仓库注册表快照为准。支持的模型列表以下是当前仓库注册表快照中 wandb 提供方支持的 10 个模型类型定义见 model-provider-types.generated.ts模型名说明Qwen/Qwen3-235B-A22B-Instruct-2507通义千问 Qwen3 指令模型Qwen/Qwen3-235B-A22B-Thinking-2507通义千问 Qwen3 思考模型Qwen/Qwen3-Coder-480B-A35B-Instruct通义千问 Qwen3 代码模型deepseek-ai/DeepSeek-R1-0528DeepSeek R1 推理模型deepseek-ai/DeepSeek-V3-0324DeepSeek V3 通用模型meta-llama/Llama-3.1-8B-InstructLlama 3.1 8B 指令模型meta-llama/Llama-3.3-70B-InstructLlama 3.3 70B 指令模型meta-llama/Llama-4-Scout-17B-16E-InstructLlama 4 Scout 多模态模型microsoft/Phi-4-mini-instructPhi-4 mini 轻量指令模型moonshotai/Kimi-K2-InstructKimi K2 指令模型在 Agent 中切换模型时只需将model字段改为wandb/上表中的模型名例如model: wandb/meta-llama/Llama-3.3-70B-Instruct在项目中使用 wandb 提供方的注意事项依赖安装ai-sdk/openai-compatible由 VoltAgent Core 按需动态 import见 model-provider-registry.ts 的createProviderLoader需确保该包已安装若缺失路由会提示Failed to load provider wandb from ai-sdk/openai-compatible. Install the package and try again.。标识符格式model必须使用wandb/模型名形式且模型名自带厂商命名空间双斜杠是正常现象不要省略中间层。密钥管理不要把WANDB_API_KEY硬编码进源码建议通过.env文件或部署平台的环境变量注入多提供方并存时各 Key 互不干扰。端点覆盖仅当请求需经过代理或私有网关时才设置WANDB_BASE_URL普通使用无需配置。进一步探索提供方注册数据源与自动刷新机制见 model-provider-registry.ts单元测试覆盖了 Base URL 覆盖等行为参见 model-provider-registry-minimax.spec.ts。全部提供方总览及各提供方所需环境变量对照表见 website/models-docs/providers/overview.md其中 Weights Biases 一行的模型前缀为wandb、环境变量为WANDB_API_KEY。各提供方页面均由 website/scripts/generate-model-docs.js 根据注册表快照自动生成模型清单会随注册表刷新而更新。如果希望了解其他 OpenAI 兼容提供方如 Vultr、Vivgrid、Xiaomi 等的接入方式它们在注册表中均使用ai-sdk/openai-compatible适配层接入步骤与本指南完全一致。赞分享人工智能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 中使用 GitHub Copilot 模型github-copilot/model 模型路由接入指南在 VoltAgent 中使用 GitHub Copilot 模型github copilot/model 模型路由接入指南 本篇基于 VoltAgent人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音Dragonfly实体系统从怪物AI到自定义实体的完整实现Dragonfly实体系统从怪物AI到自定义实体的完整实现 探索Dragonfly实体系统的强大功能了解如何从基础怪物AI到高级自定义实体的完整实现流程。D人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音在 VoltAgent 模型路由中使用 Inceptioninception/mercury接入指南与源码级原理在 VoltAgent 模型路由中使用 Inceptioninception/mercury接入指南与源码级原理 本指南讲解如何在 VoltAgent 的人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇告别网盘限速困扰九大平台直链下载助手的完整使用指南下一篇acwj 编译器移植 QBE 后端以 SSA 中间语言替代手写 x86-64 代码生成器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考