人工智能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 是一个基于 TypeScript 的开源 AI Agent 工程平台其内置的模型路由器Model Router支持通过alibaba/model形式直接引用阿里云百炼DashScope系列模型。本文围绕 website/models-docs/providers/alibaba.md 文档完整讲解 alibaba 提供商的接入步骤、环境变量、默认端点、底层适配机制与全部 39 个可用模型并给出可复制的实战示例。读完本文你将掌握在 VoltAgent 中配置 DashScope API Key、切换模型、覆盖 Base URL 的完整方法并能理解 OpenAI 兼容适配器在底层是如何工作的。一、快速开始一行模型 ID 接入百炼在 VoltAgent 中接入阿里云百炼不需要安装额外的 VoltAgent 插件只需在创建Agent时将model字段设置为alibaba/model格式即可。模型 ID 中的alibaba前缀由 VoltAgent 的模型路由器解析model部分对应百炼平台上的具体模型名称import { Agent } from voltagent/core; const agent new Agent({ name: alibaba-agent, instructions: You are a helpful assistant, model: alibaba/qvq-max, });上述代码创建了一个名为alibaba-agent的 Agent使用qvq-max作为默认语言模型。instructions用于设定 Agent 的系统提示词model则是模型路由器的入口参数——运行时 VoltAgent 会自动完成解析提供商 → 加载适配器 → 注入 API Key 与端点 → 返回语言模型实例的完整链路。二、环境变量DASHSCOPE_API_KEYalibaba 提供商需要配置以下环境变量DASHSCOPE_API_KEY阿里云百炼DashScope平台的 API Key必填。在运行 Agent 前请先在环境中导出该变量export DASHSCOPE_API_KEYsk-xxxxxxxxxxxxxxxx如果未设置该变量VoltAgent 的模型路由器在加载提供商时会抛出类似Missing API key for alibaba. Set process.env.DASHSCOPE_API_KEY.的错误。该错误信息来自 model-provider-registry.ts 中的requireApiKey函数——它从提供商注册项读取env列表按顺序查找首个非空的环境变量找不到就明确报错。从底层实现看这个校验逻辑位于ModelProviderRegistry的懒加载链路中只有当你真正引用alibaba/xxx模型时对应提供商才会被动态加载密钥校验也在此时发生因此未使用就报错的情况不会出现。三、提供商适配器与默认 Base URL3.1 使用 OpenAI 兼容适配器alibaba 提供商对应的 npm 包是ai-sdk/openai-compatible也就是说百炼平台走的是 OpenAI 兼容Chat Completions 风格协议VoltAgent 通过ai-sdk/openai-compatible提供的createOpenAICompatible工厂函数完成适配。在 model-provider-registry.ts 中buildOpenAICompatibleProvider适配器的实现要点如下const provider createFn({ name: config.id, baseURL, apiKey: apiKeyMatch.value, supportsStructuredOutputs: true, });适配器会自动注入三个关键参数提供商 IDalibaba、解析后的 Base URL、以及从DASHSCOPE_API_KEY读取到的密钥并开启supportsStructuredOutputs: true这意味着你可以在 Agent 中直接使用结构化输出JSON Schema能力。3.2 默认 Base URL 与覆盖方式alibaba 提供商的默认 Base URL 为https://dashscope-intl.aliyuncs.com/compatible-mode/v1该默认值来自 model-provider-registry.generated.ts 中alibaba注册项的api字段。你可以在 Agent 中通过设置ALIBABA_BASE_URL环境变量覆盖默认端点export ALIBABA_BASE_URLhttps://your-gateway.example.com/v1从源码看Base URL 的解析顺序见 model-provider-registry.ts 的resolveBaseUrl是优先读取提供商env列表中名称匹配ENDPOINT|BASE_URL|BASEURL的环境变量其次读取${PROVIDER_ID}_BASE_URL约定命名即ALIBABA_BASE_URL兜底使用注册项中的api默认值。因此ALIBABA_BASE_URL的设置方式是官方约定命名优先级高于默认端点适合通过企业网关、代理或自建兼容端点接入的场景。3.3 中国区端点alibaba-cn值得留意的是当前仓库的提供商注册表中还包含一个alibaba-cn条目见 model-provider-registry.generated.ts其默认端点为中国区https://dashscope.aliyuncs.com/compatible-mode/v1它同样使用ai-sdk/openai-compatible适配器和DASHSCOPE_API_KEY环境变量。如果你使用中国内地网络的百炼服务可以通过alibaba-cn/model形式引用模型例如alibaba-cn/qwen-max。国际版与国内版端点不同但环境变量与模型名基本一致。四、可用模型清单39 个以下是 alibaba 提供商当前可用的全部模型 ID来自 model-provider-types.generated.ts 的alibaba类型定义与文档列表一致模型 ID典型定位qvq-max视觉-语言问答旗舰模型qwen-flash高速低成本模型qwen-max通义千问旗舰qwen-mt-plus机器翻译增强qwen-mt-turbo机器翻译高速版qwen-omni-turbo多模态全能qwen-omni-turbo-realtime多模态实时交互qwen-plus综合能力均衡qwen-plus-character-ja日文字符优化qwen-turbo高速推理qwen-vl-max视觉理解旗舰qwen-vl-ocrOCR 识别qwen-vl-plus视觉理解均衡qwen2-5-14b-instruct/qwen2-5-32b-instruct/qwen2-5-72b-instruct/qwen2-5-7b-instructQwen2.5 开源系列Instructqwen2-5-omni-7bQwen2.5 多模态开源qwen2-5-vl-72b-instruct/qwen2-5-vl-7b-instructQwen2.5-VL 视觉开源qwen3-14b/qwen3-32b/qwen3-8bQwen3 开源系列qwen3-235b-a22bQwen3 MoE 超大模型qwen3-asr-flash语音识别qwen3-coder-30b-a3b-instruct/qwen3-coder-480b-a35b-instruct/qwen3-coder-flash/qwen3-coder-plus代码生成系列qwen3-livetranslate-flash-realtime实时翻译qwen3-maxQwen3 旗舰qwen3-next-80b-a3b-instruct/qwen3-next-80b-a3b-thinking新一代 80B MoE推理版qwen3-omni-flash/qwen3-omni-flash-realtimeQwen3 多模态qwen3-vl-235b-a22b/qwen3-vl-30b-a3b/qwen3-vl-plusQwen3 视觉理解qwq-plus推理增强思考型注模型可用性以百炼平台实际开通情况为准部分开源型号如qwen2-5-*、qwen3-*b系列可能需要相应服务开通或配额。模型的官方说明可在阿里云 Model Studio 文档中查询。五、模型路由器的底层工作方式了解底层机制有助于排查接入问题。VoltAgent 的模型路由器由 model-provider-registry.ts 中的ModelProviderRegistry类实现其核心流程为ID 解析splitModelId将alibaba/qwen-max拆分为提供商alibaba与模型qwen-max也兼容provider:model冒号写法详见 model-provider-registry.ts懒加载提供商getProviderEntry首次访问时调用注册的 loader动态import(ai-sdk/openai-compatible)并执行buildOpenAICompatibleProvider适配器model-provider-registry.ts缓存复用加载完成的语言模型工厂会被缓存后续请求直接复用不会重复初始化注册表自动刷新在非生产环境下注册表默认每 30 分钟从 models.dev 拉取一次提供商与模型清单model-provider-registry.ts因此模型列表可能随时间更新——仓库内的生成文件仅代表生成时的快照。因此模型 ID 无效类问题通常有两个原因一是环境变量未设置报错会明确提示Missing API key二是ai-sdk/openai-compatible包未安装报错会提示Failed to load provider alibaba from ai-sdk/openai-compatible. Install the package and try again.。确保依赖可用即可正常解析。六、完整实战配置多模型 Agent结合前面所有配置项一个完整的接入示例import { Agent } from voltagent/core; // 运行时环境需包含DASHSCOPE_API_KEY // 可选覆盖ALIBABA_BASE_URL默认 https://dashscope-intl.aliyuncs.com/compatible-mode/v1 const qwenAgent new Agent({ name: qwen-assistant, instructions: You are a helpful assistant powered by Qwen. Answer in the users language., model: alibaba/qwen-max, // 也可换为 alibaba/qvq-max、alibaba/qwen3-max 等 }); const result await qwenAgent.run(介绍一下 VoltAgent 的模型路由器); console.log(result);如果你想在不同场景间切换模型只需修改model字段无需改动其余 Agent 配置。对于多模态任务可选用alibaba/qvq-max、alibaba/qwen-vl-max或alibaba/qwen3-omni-flash对于代码生成任务可选用alibaba/qwen3-coder-plus等模型。中国区用户则可将前缀替换为alibaba-cn/使用国内端点。七、常见问题与排查清单现象排查方向报错Missing API key for alibaba确认DASHSCOPE_API_KEY已导出且非空空字符串会被getEnvValue视为未设置见 model-provider-registry.ts报错Failed to load provider alibaba确认项目中安装了ai-sdk/openai-compatible依赖请求 404 / 401确认使用的是百炼国际版端点国内环境改用alibaba-cn/model或设置ALIBABA_BASE_URL指向https://dashscope.aliyuncs.com/compatible-mode/v1提示模型不可用在百炼控制台确认该模型已开通模型清单以平台实际开放为准相关参考文件提供商文档website/models-docs/providers/alibaba.md提供商注册表含 alibaba / alibaba-cn 条目packages/core/src/registries/model-provider-registry.generated.ts模型类型定义39 个模型 IDpackages/core/src/registries/model-provider-types.generated.ts模型路由器核心实现packages/core/src/registries/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点击查看免费下载相关推荐Dragonfly实体系统从怪物AI到自定义实体的完整实现Dragonfly实体系统从怪物AI到自定义实体的完整实现 探索Dragonfly实体系统的强大功能了解如何从基础怪物AI到高级自定义实体的完整实现流程。D人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音阿里百炼DashScope接入 TradingAgents-CNOpenAI 兼容适配器配置与实战指南阿里百炼DashScope接入 TradingAgents CNOpenAI 兼容适配器配置与实战指南 导读 本文是 TradingAgents CN 中人工智能大模型AI Agent多智能体金融科技后端前端LangBot项目中阿里云百炼模型stream模式配置指南LangBot项目中阿里云百炼模型stream模式配置指南 概述 LangBot是一个功能强大的多平台AI聊天机器人框架支持阿里云百炼Bailian模型的人工智能大模型AI Agent即时通讯RAG后端MCP 服务本地部署上一篇用 Swift 实现 Quickhull 凸包算法swift-algorithm-club 中的计算几何实战下一篇如何快速上手Dantotsu3分钟完成Anilist账号绑定与个性化设置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考