next-ai-draw-io AI 提供商配置实战：从环境变量到服务端多模型的完整指南

next-ai-draw-io AI 提供商配置实战：从环境变量到服务端多模型的完整指南

【免费下载链接】next-ai-draw-ioA next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.项目地址: https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io

next-ai-draw-io 通过一套统一的环境变量与配置体系，接入 OpenAI、Anthropic、Google Gemini、DeepSeek、Ollama 等 20 余种 AI 提供商，让用户可以按自己的密钥来源、成本预算和隐私要求自由切换模型。本文基于官方文档 docs/cn/ai-providers.md 与仓库源码（lib/ai-providers.ts、lib/server-model-config.ts、env.example），系统讲解每个提供商的密钥与端点配置、自动检测机制的判定逻辑、服务端多模型配置的三种方式，以及推理模型的温度与 thinking 参数，读完即可独立完成任意提供商的接入与多模型部署。

快速开始

官方文档给出的四步上手流程：

1. 将.env.example复制为.env.local；
2. 设置所选提供商的 API 密钥；
3. 将AI_MODEL设置为所需的模型；
4. 运行npm run dev。

仓库根目录的 env.example 是全部环境变量的权威清单，每个提供商的密钥变量、可选 Base URL 以及推理相关参数都有注释。其中与 AI 提供商直接相关的核心变量为：

# AI_PROVIDER: 要使用的提供商 # 可选值：bedrock, openai, anthropic, google, vertexai, azure, ollama, openrouter, # aihubmix, deepseek, siliconflow, gateway, novita 等 AI_PROVIDER=bedrock # AI_MODEL: 所选提供商的模型 ID（必填） # 单提供商快速多模型：逗号分隔，第一个为默认模型 AI_MODEL=global.anthropic.claude-sonnet-4-5-20250929-v1:0

注意 env.example 中明确说明：如果只需要暴露同一 provider 下的多个模型，直接在AI_MODEL中用逗号分隔即可；如果要配置多个 provider 或自定义apiKeyEnv/baseUrlEnv，则应改用AI_MODELS_CONFIG/ai-models.json（见下文“服务端多模型配置”）。

支持的提供商与配置清单

国际主流提供商

Google Gemini

GOOGLE_GENERATIVE_AI_API_KEY=your_api_key AI_MODEL=gemini-2.0-flash

可选的自定义端点：

GOOGLE_BASE_URL=https://your-custom-endpoint

OpenAI

OPENAI_API_KEY=your_api_key AI_MODEL=gpt-4o

可选的自定义端点（用于 OpenAI 兼容服务）：

OPENAI_BASE_URL=https://your-custom-endpoint/v1

Anthropic：支持两种互斥的认证方式——ANTHROPIC_API_KEY会作为x-api-key头发送，而ANTHROPIC_AUTH_TOKEN会作为Authorization: Bearer <token>头发送（适合通过下发 OAuth 风格 token 的网关接入），两者只能设置其一：

ANTHROPIC_API_KEY=your_api_key AI_MODEL=claude-sonnet-4-5-20250514

或者使用 Bearer 认证令牌：

ANTHROPIC_AUTH_TOKEN=your_auth_token AI_MODEL=claude-sonnet-4-5-20250514

可选的自定义端点：

ANTHROPIC_BASE_URL=https://your-custom-endpoint

Azure OpenAI需要额外指定端点，两种写法二选一：

AZURE_API_KEY=your_api_key AZURE_RESOURCE_NAME=your-resource-name # 必填：您的 Azure 资源名称 AI_MODEL=your-deployment-name

或者使用自定义端点代替资源名称：

AZURE_API_KEY=your_api_key AZURE_BASE_URL=https://your-resource.openai.azure.com # AZURE_RESOURCE_NAME 的替代方案 AI_MODEL=your-deployment-name

可选的推理配置：

AZURE_REASONING_EFFORT=low # 可选：low, medium, high AZURE_REASONING_SUMMARY=detailed # 可选：none, brief, detailed

AWS Bedrock：

AWS_REGION=us-west-2 AWS_ACCESS_KEY_ID=your_access_key_id AWS_SECRET_ACCESS_KEY=your_secret_access_key AI_MODEL=anthropic.claude-sonnet-4-5-20250514-v1:0

在 AWS 环境（Lambda、带有 IAM 角色的 EC2）中，凭证会自动从 IAM 角色获取，无需显式配置密钥。

OpenRouter（单一密钥访问众多模型）：

OPENROUTER_API_KEY=your_api_key AI_MODEL=anthropic/claude-sonnet-4

可选的自定义端点：

OPENROUTER_BASE_URL=https://your-custom-endpoint

AIHubMix：通过单个 API Key 聚合 Claude、GPT、Gemini、DeepSeek 等模型：

AIHUBMIX_API_KEY=your_api_key AI_MODEL=claude-sonnet-4-5-20250929

可选的自定义端点：

AIHUBMIX_BASE_URL=https://aihubmix.com/v1

Vercel AI Gateway：通过单个 API 密钥提供对多个 AI 提供商的统一访问，模型格式使用provider/model语法：

• openai/gpt-4o— OpenAI GPT-4o
• anthropic/claude-sonnet-4-5— Anthropic Claude Sonnet 4.5
• google/gemini-2.0-flash— Google Gemini 2.0 Flash

基本用法（Vercel 托管网关）：

AI_GATEWAY_API_KEY=your_gateway_api_key AI_MODEL=openai/gpt-4o

自定义网关 URL（用于本地开发或自托管网关）：

AI_GATEWAY_API_KEY=your_custom_api_key AI_GATEWAY_BASE_URL=https://your-custom-gateway.com/v1/ai AI_MODEL=openai/gpt-4o

配置说明（来自官方文档）：

• 如果未设置AI_GATEWAY_BASE_URL，则使用默认的 Vercel Gateway URL（https://ai-gateway.vercel.sh/v1/ai）；
• 自定义基础 URL 适用于本地开发、自托管 AI Gateway 部署和企业代理配置；
• 当使用自定义基础 URL 时，必须同时提供AI_GATEWAY_API_KEY。

国内提供商

豆包（字节跳动火山引擎）：在火山引擎 ARK 平台注册可获得所有模型 50 万免费 Token。

DOUBAO_API_KEY=your_api_key AI_MODEL=doubao-seed-1-8-251215 # 或其他豆包模型

DeepSeek：

DEEPSEEK_API_KEY=your_api_key AI_MODEL=deepseek-chat

可选的自定义端点：

DEEPSEEK_BASE_URL=https://your-custom-endpoint

SiliconFlow（OpenAI 兼容）：

SILICONFLOW_API_KEY=your_api_key AI_MODEL=deepseek-ai/DeepSeek-V3 # 示例；使用任何 SiliconFlow 模型 ID

可选的自定义端点（默认为推荐域名）：

SILICONFLOW_BASE_URL=https://api.siliconflow.com/v1 # 或 https://api.siliconflow.cn/v1

ModelScope（魔搭社区）：

MODELSCOPE_API_KEY=your_api_key AI_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507

可选的自定义端点：

MODELSCOPE_BASE_URL=https://your-custom-endpoint

GLM（智谱 AI）：

GLM_API_KEY=your_api_key AI_MODEL=glm-4

Qwen（阿里云通义千问）：

QWEN_API_KEY=your_api_key AI_MODEL=qwen-turbo

Kimi（月之暗面 Moonshot AI）：

KIMI_API_KEY=your_api_key AI_MODEL=kimi-latest

以上国内提供商均可通过对应的GLM_BASE_URL、QWEN_BASE_URL、KIMI_BASE_URL覆盖端点。它们在源码中的默认端点定义在 lib/types/model-config.ts 的PROVIDER_INFO表中，例如 GLM 默认为https://open.bigmodel.cn/api/paas/v4、Qwen 默认为https://dashscope.aliyuncs.com/compatible-mode/v1、Kimi 默认为https://api.moonshot.cn/v1。

MiniMax：支持两种 API 格式——Anthropic 兼容（/anthropic端点，推荐，支持 interleaved thinking）和 OpenAI 兼容（/v1端点）：

MINIMAX_API_KEY=your_api_key AI_MODEL=MiniMax-M3

可选配置：

# 中国大陆版，Anthropic 兼容（默认） MINIMAX_BASE_URL=https://api.minimaxi.com/anthropic # 中国大陆版，OpenAI 兼容 MINIMAX_BASE_URL=https://api.minimaxi.com/v1 # 国际版，Anthropic 兼容 MINIMAX_BASE_URL=https://api.minimax.io/anthropic # 国际版，OpenAI 兼容 MINIMAX_BASE_URL=https://api.minimax.io/v1

Qiniu（七牛云）与MiMo（小米）：

QINIU_API_KEY=your_api_key AI_MODEL=your_model_id # 可选 QINIU_BASE_URL=https://your-custom-endpoint

MIMO_API_KEY=your_api_key AI_MODEL=mimo-v2.5-pro

MiMo 的 Token Plan 订阅用户请设置专属 Base URL：

MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

自建推理与本地部署

Ollama（本地/云）——唯一不需要任何密钥的提供商：

AI_PROVIDER=ollama AI_MODEL=llama3.2

可选的自定义 URL（[env.example](https://link.gitcode.com/i/dc72a5df07e927f08084e39a50a25834#L72-L75)中默认指向 Ollama Cloud，本地部署时指向本机）：

OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_API_KEY=your-ollama-cloud-api-key # 可选：Ollama Cloud 或需要认证的远程实例 OLLAMA_ENABLE_THINKING=true # 可选：为支持的模型（如 qwen3）启用思考模式

SGLang：

SGLANG_API_KEY=your_api_key AI_MODEL=your_model_id

可选的自定义端点（env.example 中给出的本地示例为http://127.0.0.1:8000/v1）：

SGLANG_BASE_URL=https://your-custom-endpoint/v1

环境变量的完整映射

源码中 lib/ai-providers.ts 的PROVIDER_ENV_VARS表给出了“提供商 → 必需环境变量”的权威映射，与上文的配置清单一一对应：

注意vertexai、novita、atlascloud、edgeone等值同样出现在 lib/types/model-config.ts 的ProviderName联合类型中，完整列表以源码为准。

提供商自动检测与凭证校验

官方文档对自动检测的规则是：只配置了一个提供商的 API 密钥时，系统自动检测并使用该提供商，无需设置AI_PROVIDER；配置了多个API 密钥时，必须显式设置AI_PROVIDER：

AI_PROVIDER=google # 或：openai, anthropic, aihubmix, deepseek, siliconflow, doubao, azure, bedrock, openrouter, ollama, gateway, sglang, modelscope, minimax, glm, qwen, kimi, qiniu, mimo

这一行为在 lib/ai-providers.ts 的detectProvider()中实现，几个值得注意的细节：

• Ollama 被跳过：因为它不需要凭证，不参与“唯一密钥”检测，本地 Ollama 必须显式AI_PROVIDER=ollama；
• Azure 需要额外条件：仅有AZURE_API_KEY不算“已配置”，还必须同时设置AZURE_BASE_URL或AZURE_RESOURCE_NAME才会被计入；
• Anthropic 双认证：ANTHROPIC_API_KEY与ANTHROPIC_AUTH_TOKEN任一存在即视为已配置。

当检测出多个提供商时，getAIModel 会抛出带明确指引的错误信息（列出已配置的提供商，提示设置AI_PROVIDER）；一个都没配置时，错误信息会列出所有可用密钥变量的示例，便于快速定位问题。

凭证校验逻辑在 validateProviderCredentials 中：缺少密钥时抛出形如OPENAI_API_KEY environment variable is required for openai provider. Please set it in your .env.local file.的错误；apiKeyEnv支持数组形式（多密钥负载均衡场景），数组中至少一个变量有值即可通过校验。

源码纵深：getAIModel 的解析链与安全设计

所有对话请求最终都经过 app/api/chat/route.ts 调用getAIModel()来构建模型实例，其解析优先级为：客户端覆盖（用户在设置面板填的 BYOK 密钥）>AI_PROVIDER显式配置 > 自动检测 > 报错。围绕这条主链，源码中有几个直接影响使用体验的设计。

自定义 Base URL 必须配 API Key（SSRF 防护）

getAIModel 开头 有一道安全闸门：如果请求携带自定义baseUrl但没有apiKey（Vertex AI 的 API Key、EdgeOne 例外），会直接抛出API key is required when using a custom base URL错误。其注释明确引用了 GHSA-9qf7-mprq-9qgm：防止攻击者把服务端的 API 密钥重定向到恶意端点。也就是说，“只改端点不给密钥”的组合会被拒绝，这是自托管反向代理场景需要理解的前提。

Base URL 的三级解析

resolveBaseURL 的解析顺序为：

1. 用户提供了自己的 API Key 时，只取“用户指定的 baseUrl 或官方默认端点”，不回退到服务端环境变量里的 baseUrl——避免用户密钥被发往服务器侧配置的代理；
2. 无用户密钥时，依次回退：用户 baseUrl → 服务端*_BASE_URL环境变量 → 提供商官方默认端点（来自PROVIDER_INFO）。

密钥解析 resolveApiKey 同理，优先级为：客户端密钥 →ai-models.json中的apiKeyEnv自定义变量（若是数组，则在有值的变量中随机选一个，日志会打印Selected ... from N available keys）→ 标准默认变量（如OPENAI_API_KEY）。

几个有代表性的提供商特殊实现

• MiniMax 双协议归一化：normalizeMiniMaxBaseURL 会根据 URL 是否包含/anthropic判断协议形态，自动补全/v1后缀；随后 MiniMax 分支 选择createAnthropic或createOpenAI来创建客户端。这解释了文档中“两种端点、四种域名组合”在底层如何落到具体的 SDK。
• SGLang 流修复：SGLang 的 SSE 流包含非标准字段，sglang 分支 注入了一个自定义fetch，用TransformStream逐条解析data:消息，剔除空的role与reasoning_content字段后重新序列化转发，解析失败则原样透传以保流不断。
• 豆包按模型名路由 SDK：doubao 分支 发现模型 ID 含deepseek或kimi时改用createDeepSeek（以获得推理内容支持），其余模型走 OpenAI 兼容的.chat()（多模态支持），默认端点为火山引擎https://ark.cn-beijing.volces.com/api/v3。
• Kimi / MiMo 借用 DeepSeek SDK：kimi 分支 与 mimo 分支 均使用createDeepSeek，原因是这些思考模型的 API 在多轮工具调用时必须把上一轮的reasoning_content回传，否则返回 400，而 DeepSeek SDK 正是按此约定实现的。这一结论也有单测印证：tests/unit/ai-providers.test.ts 断言了 Kimi 走createDeepSeek且默认端点为https://api.moonshot.cn/v1。
• AIHubMix 标准端点识别：aihubmix 分支 通过 isAihubmixStandardBaseURL 判断是否命中官方端点——命中则用官方@aihubmix/ai-sdk-provider（附带固定的appCode: "MSBS9675"），未命中则降级为通用 OpenAI 兼容客户端。
• Bedrock Claude 的 Prompt Caching：supportsPromptCaching 只对模型 ID 含claude/anthropic（含us./eu.区域前缀）的 Bedrock 模型启用缓存。

高级环境变量：推理（thinking）与采样参数

除了密钥与端点，buildProviderOptions（配合 env.example 的注释）为各提供商暴露了一组可选的推理/采样环境变量：

几个自动行为值得留意：o1/o3/o4/gpt-5 系列模型会自动启用reasoningSummary: "auto"（见 openai 分支）；Gemini 2.5/3 系列默认开启includeThoughts: true以回传思考内容。此外还有一个容易被忽略的变量：getValidationModel 表明图表校验可以使用独立的VALIDATION_MODEL环境变量，未设置时回退到AI_MODEL的第一个模型。

温度设置 (Temperature)

官方文档建议通过环境变量选择性配置温度：

TEMPERATURE=0 # 输出更具确定性（推荐用于图表）

该值在 app/api/chat/route.ts 中被解析后注入请求参数：process.env.TEMPERATURE !== undefined时才附加temperature字段。重要提示：对于不支持温度设置的模型（例如 GPT-5.1 和其他推理模型、某些专用模型），请勿设置TEMPERATURE；未设置时模型使用其默认行为。

服务端多模型配置

管理员可以配置多个服务端模型，让所有用户无需提供个人 API Key 即可使用。文档给出了三种配置方式，源码 lib/server-model-config.ts 按同样的优先级顺序加载。

方式一：环境变量（推荐用于云部署）

设置AI_MODELS_CONFIG为 JSON 字符串：

AI_MODELS_CONFIG='{"providers":[{"name":"OpenAI","provider":"openai","models":["gpt-4o"],"default":true}]}'

方式二：配置文件

在项目根目录创建ai-models.json文件，或通过AI_MODELS_CONFIG_PATH指定路径（getConfigPath 的实现：自定义路径优先，否则读./ai-models.json）。

方式三：AI_MODEL用逗号分隔（单 provider 快速配置）

如果只需要暴露同一 provider 下的多个模型，可以直接在AI_MODEL里用逗号分隔，第一个模型会作为默认值：

AI_PROVIDER=doubao AI_MODEL=doubao-seed-1-8-251215,doubao-seed-1-6-flash,doubao-seed-1-6-pro

这是等价ai-models.json的简写形式。如果需要配置多个 provider，或自定义apiKeyEnv/baseUrlEnv，请使用方式一或方式二。注意 configFromCommaSeparatedAiModel 要求AI_PROVIDER同时已设置且为已知提供商，否则仅打印警告并跳过该回退。

配置示例与字段说明

{ "providers": [ { "name": "OpenAI Production", "provider": "openai", "models": ["gpt-4o", "gpt-4o-mini"], "default": true }, { "name": "Custom DeepSeek", "provider": "deepseek", "models": ["deepseek-chat"], "apiKeyEnv": "MY_DEEPSEEK_KEY", "baseUrlEnv": "MY_DEEPSEEK_URL" } ] }

配置语义补充（结合 ServerProviderSchema 的 Zod 校验与源码实现）：

• 该配置会被 Zod schema 严格校验，provider值必须是PROVIDER_INFO中已知的提供商，models中每项不能为空字符串；
• apiKeyEnv除了字符串外还接受字符串数组，用于多密钥负载均衡——resolveApiKey 会在所有有值的变量中随机选取一个；
• name字段会被 slugify 后拼进模型 ID（格式server:<slug>:<modelId>，见 loadFlattenedServerModels），这正是“同一 provider 可以配置 OpenAI Production / OpenAI Staging 两组不同密钥”能共存的原因；
• 服务端模型配置与 管理面板 中配置的 provider 会自动合并（loadRawServerModelsConfig），且面板里设置的default会覆盖环境变量里的默认项；
• 如果上述配置都不存在，应用会回退到AI_PROVIDER/AI_MODEL环境变量配置。

该链路的加载与合并行为由 tests/unit/server-model-config.test.ts 与 tests/unit/ai-providers.test.ts 覆盖，后者还专门验证了 BYOK（用户自带密钥）与服务端密钥在 AIHubMix、Kimi、Atlas Cloud 等提供商上的优先级关系。

模型能力要求与选型建议

模型能力要求

此任务对模型能力要求极高，因为它涉及生成具有严格格式约束（draw.io XML）的长文本。官方文档的推荐是Claude Sonnet 4.5 / Opus 4.5。

关于 Ollama 的说明：虽然支持将 Ollama 作为提供商，但除非在本地运行像 DeepSeek R1 或 Qwen3-235B 这样的高性能模型，否则对于此用例通常不太实用。

推荐

• 最佳体验：使用支持视觉的模型（GPT-4o, Claude, Gemini）以获得图像转图表功能；
• 经济实惠：DeepSeek 提供具有竞争力的价格；
• 隐私保护：使用 Ollama 进行完全本地、离线的操作（需要强大的硬件支持）；
• 灵活性：OpenRouter 通过单一 API 提供对众多模型的访问。

小结

next-ai-draw-io 的 AI 提供商体系可以概括为三层：环境变量层（密钥 +AI_MODEL，覆盖绝大多数单提供商场景，并支持单 key 自动检测）、服务端多模型层（AI_MODELS_CONFIG/ai-models.json/ 逗号分隔AI_MODEL三种方式，支持apiKeyEnv多密钥负载均衡与name多组配置）、客户端 BYOK 层（用户在设置面板自带密钥，优先级最高并受 SSRF 防护约束）。所有提供商最终都汇入 getAIModel 这一入口，配合 buildProviderOptions 的推理参数与 app/api/chat/route.ts 的温度注入，构成了一套从选型到落地的完整闭环。配置完成后运行npm run dev，即可在界面中验证所选模型能否正确生成 draw.io XML。

【免费下载链接】next-ai-draw-ioA next.js web application that integrates AI capabilities with draw.io diagrams. This app allows you to create, modify, and enhance diagrams through natural language commands and AI-assisted visualization.项目地址: https://gitcode.com/GitHub_Trending/ne/next-ai-draw-io