在 VoltAgent 中使用 Scaleway 生成式 AI：OpenAI 兼容模型路由完整配置指南

人工智能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 的模型路由器中接入 Scaleway Generative APIs 的开发者完整介绍scaleway/model模型标识的用法、所需环境变量、底层 OpenAI 兼容适配器的实现原理以及 14 个可用模型的完整清单。读完本文你将能在一分钟内把 VoltAgent Agent 切换到 Scaleway 提供的开源模型如bge-multilingual-gemma2、gemma-3-27b-it、qwen3-coder-30b-a3b-instruct等并通过SCALEWAY_BASE_URL自定义端点。一、Scaleway Provider 概览Scaleway 是 VoltAgent 模型路由器内置支持的一个 Provider官方文档定义于 model-provider-registry.generated.ts注册表条目如下Provider IDscalewayProvider 名称Scalewaynpm 包ai-sdk/openai-compatible默认 API 地址https://api.scaleway.ai/v1必需环境变量SCALEWAY_API_KEY该注册表条目是 generate-model-docs.js 生成 scaleway.md 等 Provider 文档页的数据源。在 providers 概览页 的 Provider 目录表中Scaleway 对应的模型前缀为scaleway环境变量为SCALEWAY_API_KEY。二、快速开始使用scaleway/model模型标识VoltAgent 支持零导入的模型字符串路由方式你不需要手动安装 Provider 适配器或编写任何初始化代码只需在Agent构造函数中传入scaleway/model格式的模型标识模型路由器会自动解析 Provider 并完成底层调用。以下是最小可运行示例import { Agent } from voltagent/core; const agent new Agent({ name: scaleway-agent, instructions: You are a helpful assistant, model: scaleway/bge-multilingual-gemma2, });其中nameAgent 名称用于日志与链路标识instructions系统提示词定义 Agent 的角色与行为model模型标识格式为provider/model此处即 Scaleway 的bge-multilingual-gemma2模型。模型标识的解析逻辑位于 model-provider-registry.ts 的splitModelId函数它以/或:为分隔符将字符串切分为providerId与modelId两部分并对 Provider 名做trim().toLowerCase()归一化处理。若格式非法缺少 Provider 或缺少模型名会抛出Invalid model id .... Use provider/model.错误。类型安全的模型标识如果你希望在编译期获得模型标识的自动补全与类型校验可以使用ModelRouterModelId类型。该类型由 model-provider-registry.ts 中的buildTypesContent从注册表模型清单自动生成scaleway/前缀下的每个模型都会成为合法的字面量联合成员import type { ModelRouterModelId } from voltagent/core; const modelId: ModelRouterModelId scaleway/bge-multilingual-gemma2; // 合法可获得 IDE 自动补全 // const badId: ModelRouterModelId scaleway/not-exist; // 类型错误三、环境变量配置使用 Scaleway Provider 前需要配置以下环境变量环境变量说明是否必填SCALEWAY_API_KEYScaleway Generative APIs 的 API 密钥必填SCALEWAY_BASE_URL自定义 API 端点覆盖默认 base URL选填在运行时ModelProviderRegistry会通过requireApiKey见 model-provider-registry.ts检查SCALEWAY_API_KEY是否已设置该函数会过滤出环境变量名中匹配KEY|TOKEN|SECRET的条目并遍历取值忽略空白字符串。若缺失会抛出明确错误Missing API key for scaleway. Set process.env.SCALEWAY_API_KEY.这就是注册表驱动的环境变量映射VoltAgent 内置知道每个 Provider 需要哪些环境变量并在缺失时报告具体是哪一个此机制在 overview.md 的 Models 页面中也有说明。典型的.env配置示例SCALEWAY_API_KEYyour-scaleway-api-key四、Provider 包与 OpenAI 兼容适配器Scaleway Provider 底层使用ai-sdk/openai-compatible包即 OpenAI 兼容适配器。也就是说VoltAgent 通过createOpenAICompatible工厂函数将 Scaleway 的 API 端点包装为标准 AI SDK Provider。该过程实现在 model-provider-registry.ts 的buildOpenAICompatibleProvider适配器中const provider createFn({ name: config.id, baseURL, apiKey: apiKeyMatch.value, supportsStructuredOutputs: true, });关键点name设为scaleway用于标识该 Provider 实例baseURL默认取自注册表中的api字段https://api.scaleway.ai/v1可被SCALEWAY_BASE_URL覆盖见下一节apiKey取自SCALEWAY_API_KEYsupportsStructuredOutputs: true启用结构化输出支持意味着基于 Scaleway 的 Agent 可以配合 VoltAgent 的 structured output / tool calling 能力使用。适配器按 npm 包名注册在PACKAGE_ADAPTERS映射中model-provider-registry.tsai-sdk/openai-compatible统一走buildOpenAICompatibleProvider分支。当 Agent 首次使用scaleway/model时注册表会通过动态import(config.npm)按需加载该 npm 包若包未安装会抛出提示安装依赖的错误。五、默认 base URL 与自定义端点Scaleway Provider 的默认 API 端点为https://api.scaleway.ai/v1你可以通过设置SCALEWAY_BASE_URL环境变量来覆盖默认端点适合使用代理、网关或私有化部署场景。Base URL 的解析顺序实现在resolveBaseUrlmodel-provider-registry.ts首先查找注册表env列表中名称匹配ENDPOINT|BASE_URL|BASEURL的环境变量Scaleway 注册表中只有SCALEWAY_API_KEY不命中该分支其次查找约定俗成的${PROVIDER_ID}_BASE_URL环境变量——envKeyForProvider将 Provider ID 转换为大写并替换-为_因此对scaleway生成的就是SCALEWAY_BASE_URL最后回退到注册表api字段的默认值https://api.scaleway.ai/v1。SCALEWAY_API_KEYyour-scaleway-api-key SCALEWAY_BASE_URLhttps://your-gateway.example.com/v1 # 可选自定义端点需要说明的是该_BASE_URL覆盖约定对所有注册表 Provider 通用例如在 model-provider-registry-minimax.spec.ts 中就有MINIMAX_BASE_URL的对应测试用例验证了同一条解析链路。六、可用模型清单以下是当前注册表快照中记录的 Scaleway 模型清单来源model-provider-types.generated.ts与本文档页中的列表一致共 14 个模型类型从命名推断bge-multilingual-gemma2多语言嵌入模型bge 系列deepseek-r1-distill-llama-70b推理/蒸馏对话模型devstral-2-123b-instruct-2512开发者导向 instruct 模型gemma-3-27b-it对话模型Google Gemma 系列gpt-oss-120b开源对话模型llama-3.1-8b-instruct对话模型Llama 系列llama-3.3-70b-instruct对话模型Llama 系列mistral-nemo-instruct-2407对话模型Mistral 系列mistral-small-3.2-24b-instruct-2506对话模型Mistral 系列pixtral-12b-2409多模态视觉模型Mistral Pixtral 系列qwen3-235b-a22b-instruct-2507MoE 对话模型Qwen 系列qwen3-coder-30b-a3b-instruct代码模型Qwen Coder 系列voxtral-small-24b-2507多模态模型Mistral Voxtral 系列whisper-large-v3语音转文字模型Whisper 系列这些模型标识全部可以直接作为model: scaleway/模型名使用。注意嵌入模型如bge-multilingual-gemma2与语音模型如whisper-large-v3在 VoltAgent 中主要用于对应的嵌入检索与音频处理场景而非普通对话任务使用时请结合具体 API 能力。模型清单的自动刷新上述模型清单并非手写维护而是由注册表自动生成。ModelProviderRegistry支持从https://models.dev/api.json拉取最新数据并刷新 Provider 配置见 model-provider-registry.ts 的fetchModelsDevRegistry默认自动刷新间隔为 30 分钟DEFAULT_AUTO_REFRESH_INTERVAL_MSmodel-provider-registry.ts。刷新结果会缓存到用户主目录的.voltagent/model-registry/目录以及voltagent/core的dist/registries/下同时重新生成类型声明文件。这意味着模型列表会随上游数据更新而变化本文列举的 14 个模型以当前仓库快照为准。七、文档与进一步探索本 Provider 页website/models-docs/providers/scaleway.md由 generate-model-docs.js 自动生成勿手动编辑全部 Provider 目录website/models-docs/providers/overview.mdProvider 注册表条目packages/core/src/registries/model-provider-registry.generated.ts模型类型映射packages/core/src/registries/model-provider-types.generated.ts注册表运行时实现packages/core/src/registries/model-provider-registry.ts。关于 Scaleway Generative APIs 的官方模型目录与接口细节可查阅注册表条目中doc字段所指向的官方文档Scaleway Generative APIs 文档本仓库仅记录其链接不复制其内容。小结在 VoltAgent 中接入 Scaleway 只需三步设置SCALEWAY_API_KEY环境变量、在Agent的model字段填写scaleway/模型名、确保项目安装了ai-sdk/openai-compatible。模型路由器会在运行时自动完成 Provider 加载、API Key 校验、base URL 解析含SCALEWAY_BASE_URL覆盖与模型调用让你无需编写任何 Provider 专用胶水代码即可使用 Scaleway 托管的开源模型生态。赞分享人工智能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 集成 Upstage Solar 模型upstage/model 模型路由配置与使用指南VoltAgent 集成 Upstage Solar 模型upstage/model 模型路由配置与使用指南 本文是 VoltAgent基于 TypeSc人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音在 VoltAgent 中接入 Amazon Bedrock从凭证配置到多模型路由的完整实战指南在 VoltAgent 中接入 Amazon Bedrock从凭证配置到多模型路由的完整实战指南 本指南以 VoltAgent 官方示例 examples/w人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音在 VoltAgent 中使用 GitHub Copilot 模型github-copilot/model 模型路由接入指南在 VoltAgent 中使用 GitHub Copilot 模型github copilot/model 模型路由接入指南 本篇基于 VoltAgent人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音上一篇Portainer与Kubernetes集成轻松管理复杂容器编排下一篇如何快速部署Langchain-Chatchat5步搭建私有化AI问答系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考