mirror of
https://github.com/DayuanJiang/next-ai-draw-io.git
synced 2026-10-12 20:49:53 +08:00
dayuan.jiang
75ffc32a49
Five reviewers (Fable 5.1, Opus 5.5, Sonnet 5.5, Codex GPT-6 Astra, Codex GPT-6.1 Sol) found no behavior or security regression; this commit applies what they asked for. Settings dialog: the automatic model list fetch only fills the list, which waits behind 'Browse models'; it no longer opens the picker (the modal picker took the focus from whatever the user was typing) and shows no error of its own. One list request per provider at a time, so a click during the automatic fetch sends nothing twice; the baseline that detects freshly entered credentials is taken on every visit of a provider page; SGLang's prefilled local example URL triggers no fetch. Entries saved with Azure's old placeholder URL still count as having no URL. The base URL field of Azure and of the custom preset is labelled required (new dictionary key baseUrlRequired). Smaller code: the PROVIDER_INFO alias is gone (three files and the tests import PROVIDERS), as are three logo values no code read, two unused type re-exports, three unused exports and SINGLE_SYSTEM_PROVIDERS (the chat route reads the record). Renamed for clarity: REQUIRED_KEY_VARS, requiredKeyEnv, configuredUrl, LocalizedText. Seven stale comments rewritten; the custom preset's note shortened. Tests: the matrix gains six override shapes (a Vertex key alone, AWS keys with a session token, headers with a URL, a trusted URL with a key, a key with a server model's URL variable, '/' alone), 5843 rows; the new rows were regenerated on the pre-refactor code and match it. The matrix and the server credential tests clear every variable they read; the admin variable table covers every provider; a test that derived its expectation from the function under test is gone; the singleSystem, listNeedsNoKey, sdkKnowsEndpoint and auto-detection sets are spelled out. Docs: the READMEs say 25 providers and name the OpenAI-compatible preset; the AI_PROVIDER lists are complete; the Azure example URL has its /openai suffix; 'Adding a Provider' names the tests to update.
470 lines
13 KiB
Markdown
470 lines
13 KiB
Markdown
# AI 提供商配置
|
||
|
||
本指南介绍如何为 next-ai-draw-io 配置不同的 AI 模型提供商。
|
||
|
||
## 快速开始
|
||
|
||
1. 将 `.env.example` 复制为 `.env.local`
|
||
2. 设置所选提供商的 API 密钥
|
||
3. 将 `AI_MODEL` 设置为所需的模型
|
||
4. 运行 `npm run dev`
|
||
|
||
## 支持的提供商
|
||
|
||
### 豆包 (字节跳动火山引擎)
|
||
|
||
```bash
|
||
DOUBAO_API_KEY=your_api_key
|
||
AI_MODEL=doubao-seed-1-8-251215 # 或其他豆包模型
|
||
```
|
||
|
||
### Google Gemini
|
||
|
||
```bash
|
||
GOOGLE_GENERATIVE_AI_API_KEY=your_api_key
|
||
AI_MODEL=gemini-2.0-flash
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
GOOGLE_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
### OpenAI
|
||
|
||
```bash
|
||
OPENAI_API_KEY=your_api_key
|
||
AI_MODEL=gpt-4o
|
||
```
|
||
|
||
可选的自定义端点（用于 OpenAI 兼容服务）：
|
||
|
||
```bash
|
||
OPENAI_BASE_URL=https://your-custom-endpoint/v1
|
||
```
|
||
|
||
LM Studio 等本地 OpenAI 兼容服务也用同样的方式：把 base URL 设为 `http://localhost:1234/v1`（LM Studio 的默认端口），API 密钥填任意非空值即可，例如 `lm-studio`。在上面的环境变量或模型设置里配置都可以。
|
||
|
||
### AIHubMix
|
||
|
||
AIHubMix 通过单个 API Key 聚合 Claude、GPT、Gemini、DeepSeek 等模型。
|
||
|
||
```bash
|
||
AIHUBMIX_API_KEY=your_api_key
|
||
AI_MODEL=claude-sonnet-4-5-20250929
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
AIHUBMIX_BASE_URL=https://aihubmix.com/v1
|
||
```
|
||
|
||
### Anthropic
|
||
|
||
```bash
|
||
ANTHROPIC_API_KEY=your_api_key
|
||
AI_MODEL=claude-sonnet-4-5-20250514
|
||
```
|
||
|
||
或者使用 Bearer 认证令牌（例如通过会下发 OAuth 风格 token 的网关时）。`ANTHROPIC_AUTH_TOKEN` 会作为 `Authorization: Bearer <token>` 头发送，而 `ANTHROPIC_API_KEY` 会作为 `x-api-key` 头发送。两者互斥，只能设置其中之一：
|
||
|
||
```bash
|
||
ANTHROPIC_AUTH_TOKEN=your_auth_token
|
||
AI_MODEL=claude-sonnet-4-5-20250514
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
ANTHROPIC_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
### DeepSeek
|
||
|
||
```bash
|
||
DEEPSEEK_API_KEY=your_api_key
|
||
AI_MODEL=deepseek-chat
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
DEEPSEEK_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
### SiliconFlow (OpenAI 兼容)
|
||
|
||
```bash
|
||
SILICONFLOW_API_KEY=your_api_key
|
||
AI_MODEL=deepseek-ai/DeepSeek-V3 # 示例；使用任何 SiliconFlow 模型 ID
|
||
```
|
||
|
||
可选的自定义端点（默认为推荐域名）：
|
||
|
||
```bash
|
||
SILICONFLOW_BASE_URL=https://api.siliconflow.com/v1 # 或 https://api.siliconflow.cn/v1
|
||
```
|
||
|
||
### SGLang
|
||
|
||
```bash
|
||
SGLANG_API_KEY=your_api_key
|
||
AI_MODEL=your_model_id
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
SGLANG_BASE_URL=https://your-custom-endpoint/v1
|
||
```
|
||
|
||
### Azure OpenAI
|
||
|
||
```bash
|
||
AZURE_API_KEY=your_api_key
|
||
AZURE_RESOURCE_NAME=your-resource-name # 必填：您的 Azure 资源名称
|
||
AI_MODEL=your-deployment-name
|
||
```
|
||
|
||
或者使用自定义端点代替资源名称：
|
||
|
||
```bash
|
||
AZURE_API_KEY=your_api_key
|
||
AZURE_BASE_URL=https://your-resource.openai.azure.com/openai # AZURE_RESOURCE_NAME 的替代方案
|
||
AI_MODEL=your-deployment-name
|
||
```
|
||
|
||
可选的推理配置：
|
||
|
||
```bash
|
||
AZURE_REASONING_EFFORT=low # 可选：low, medium, high
|
||
AZURE_REASONING_SUMMARY=detailed # 可选：none, brief, detailed
|
||
```
|
||
|
||
### AWS Bedrock
|
||
|
||
```bash
|
||
AWS_REGION=us-west-2
|
||
AWS_ACCESS_KEY_ID=your_access_key_id
|
||
AWS_SECRET_ACCESS_KEY=your_secret_access_key
|
||
AI_MODEL=global.anthropic.claude-sonnet-5-5
|
||
```
|
||
|
||
较新的 Claude 模型只能通过推理配置文件（inference profile）的 ID 调用，这种 ID 以地区前缀开头，例如 `global.` 或 `us.`。直接用 `anthropic.claude-sonnet-5-5` 这样的 ID 会报错 “on-demand throughput isn't supported”。
|
||
|
||
注意：在 AWS 环境（Lambda、带有 IAM 角色的 EC2）中，凭证会自动从 IAM 角色获取。
|
||
|
||
### OpenRouter
|
||
|
||
```bash
|
||
OPENROUTER_API_KEY=your_api_key
|
||
AI_MODEL=anthropic/claude-sonnet-4
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
OPENROUTER_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
### Ollama (本地)
|
||
|
||
```bash
|
||
AI_PROVIDER=ollama
|
||
AI_MODEL=llama3.2
|
||
```
|
||
|
||
### ModelScope
|
||
|
||
```bash
|
||
MODELSCOPE_API_KEY=your_api_key
|
||
AI_MODEL=Qwen/Qwen3-235B-A22B-Instruct-2507
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
MODELSCOPE_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
可选的自定义 URL：
|
||
|
||
```bash
|
||
OLLAMA_BASE_URL=http://localhost:11434/api
|
||
```
|
||
|
||
### Vercel AI Gateway
|
||
|
||
Vercel AI Gateway 通过单个 API 密钥提供对多个 AI 提供商的统一访问。这简化了身份验证，让您无需管理多个 API 密钥即可在不同提供商之间切换。
|
||
|
||
**基本用法（Vercel 托管网关）：**
|
||
|
||
```bash
|
||
AI_GATEWAY_API_KEY=your_gateway_api_key
|
||
AI_MODEL=openai/gpt-4o
|
||
```
|
||
|
||
**自定义网关 URL（用于本地开发或自托管网关）：**
|
||
|
||
```bash
|
||
AI_GATEWAY_API_KEY=your_custom_api_key
|
||
AI_GATEWAY_BASE_URL=https://your-custom-gateway.com/v1/ai
|
||
AI_MODEL=openai/gpt-4o
|
||
```
|
||
|
||
模型格式使用 `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
|
||
|
||
**配置说明：**
|
||
|
||
- 如果未设置 `AI_GATEWAY_BASE_URL`，则使用默认的 Vercel Gateway URL (`https://ai-gateway.vercel.sh/v1/ai`)
|
||
- 自定义基础 URL 适用于：
|
||
- 使用自定义网关实例进行本地开发
|
||
- 自托管 AI Gateway 部署
|
||
- 企业代理配置
|
||
- 当使用自定义基础 URL 时，必须同时提供 `AI_GATEWAY_API_KEY`
|
||
|
||
从 [Vercel AI Gateway 仪表板](https://vercel.com/ai-gateway) 获取您的 API 密钥。
|
||
|
||
### MiniMax
|
||
|
||
MiniMax 支持两种 API 格式：
|
||
- **Anthropic 兼容**（`/anthropic` 端点）— 推荐，支持 interleaved thinking
|
||
- **OpenAI 兼容**（`/v1` 端点）— 标准 OpenAI 聊天补全格式
|
||
|
||
```bash
|
||
MINIMAX_API_KEY=your_api_key
|
||
AI_MODEL=MiniMax-M3
|
||
```
|
||
|
||
可选配置：
|
||
|
||
```bash
|
||
# 中国大陆版，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
|
||
```
|
||
|
||
### GLM (智谱 AI)
|
||
|
||
```bash
|
||
GLM_API_KEY=your_api_key
|
||
AI_MODEL=glm-4
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
GLM_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
### Qwen (阿里云通义千问)
|
||
|
||
```bash
|
||
QWEN_API_KEY=your_api_key
|
||
AI_MODEL=qwen-turbo
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
QWEN_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
### Kimi (月之暗面 Moonshot AI)
|
||
|
||
```bash
|
||
KIMI_API_KEY=your_api_key
|
||
AI_MODEL=kimi-latest
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
KIMI_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
### Qiniu (七牛云)
|
||
|
||
```bash
|
||
QINIU_API_KEY=your_api_key
|
||
AI_MODEL=your_model_id
|
||
```
|
||
|
||
可选的自定义端点：
|
||
|
||
```bash
|
||
QINIU_BASE_URL=https://your-custom-endpoint
|
||
```
|
||
|
||
### MiMo (小米)
|
||
|
||
```bash
|
||
MIMO_API_KEY=your_api_key
|
||
AI_MODEL=mimo-v2.5-pro
|
||
```
|
||
|
||
可选的自定义端点（Token Plan 订阅用户请设置专属 Base URL）：
|
||
|
||
```bash
|
||
MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
|
||
```
|
||
|
||
### 任何 OpenAI 兼容接口（custom）
|
||
|
||
上面没有列出的服务（vLLM、LM Studio、LiteLLM、API 网关），在设置里选择 **OpenAI-compatible**，填入它的地址和 Key；服务端不校验 key 时填任意非空内容即可。多条 system 消息会合并成一条（开源模型的对话模板通常要求这样），`<think>` 里的推理内容会从回复里分离出来。
|
||
|
||
```bash
|
||
CUSTOM_API_KEY=your_api_key
|
||
CUSTOM_BASE_URL=http://127.0.0.1:8000/v1
|
||
AI_MODEL=your_model_id
|
||
```
|
||
|
||
---
|
||
|
||
## 自动检测
|
||
|
||
如果您只配置了**一个**提供商的 API 密钥，系统将自动检测并使用该提供商。无需设置 `AI_PROVIDER`。
|
||
|
||
如果您配置了**多个** API 密钥，则必须显式设置 `AI_PROVIDER`：
|
||
|
||
```bash
|
||
AI_PROVIDER=google # 或：openai, anthropic, google, vertexai, azure, bedrock, ollama, openrouter, aihubmix, deepseek, siliconflow, sglang, gateway, edgeone, doubao, modelscope, glm, qwen, qiniu, kimi, minimax, novita, mimo, atlascloud, custom
|
||
```
|
||
|
||
## 服务端多模型配置
|
||
|
||
管理员可以配置多个服务端模型，让所有用户无需提供个人 API Key 即可使用。
|
||
|
||
### 配置方式
|
||
|
||
**方式一：环境变量**（推荐用于云部署）
|
||
|
||
设置 `AI_MODELS_CONFIG` 为 JSON 字符串：
|
||
|
||
```bash
|
||
AI_MODELS_CONFIG='{"providers":[{"name":"OpenAI","provider":"openai","models":["gpt-4o"],"default":true}]}'
|
||
```
|
||
|
||
**方式二：配置文件**
|
||
|
||
在项目根目录创建 `ai-models.json` 文件（或通过 `AI_MODELS_CONFIG_PATH` 指定路径）。
|
||
|
||
**方式三：`AI_MODEL` 用逗号分隔**（单 provider 的快速配置）
|
||
|
||
如果只需要暴露同一 provider 下的多个模型，可以直接在 `AI_MODEL` 里用逗号分隔。第一个模型会作为默认值。
|
||
|
||
```bash
|
||
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`，请使用方式一或方式二。
|
||
|
||
### 配置示例
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|------|------|------|
|
||
| `name` | 是 | 显示名称（支持同一提供商多个配置） |
|
||
| `provider` | 是 | 提供商类型（`openai`, `anthropic`, `google`, `bedrock` 等） |
|
||
| `models` | 是 | 模型 ID 列表 |
|
||
| `default` | 否 | 设为 `true` 表示默认选中该提供商的第一个模型 |
|
||
| `apiKeyEnv` | 否 | 自定义 API Key 环境变量名（默认使用提供商标准变量如 `OPENAI_API_KEY`）。也可以写成环境变量名数组，每次请求从有值的变量中随机选一个，把负载分摊到多个 Key 上 |
|
||
| `baseUrlEnv` | 否 | 自定义 Base URL 环境变量名 |
|
||
|
||
### 说明
|
||
|
||
- API Key 和凭证通过环境变量提供。默认使用标准变量名（如 `OPENAI_API_KEY`），也可通过 `apiKeyEnv` 指定自定义变量名。
|
||
- `name` 字段允许同一提供商多个配置（例如 "OpenAI Production" 和 "OpenAI Staging" 都使用 `provider: "openai"` 但 `apiKeyEnv` 不同）。
|
||
- 如果配置不存在，应用会回退到 `AI_PROVIDER`/`AI_MODEL` 环境变量配置。
|
||
|
||
## 模型能力要求
|
||
|
||
此任务对模型能力要求极高，因为它涉及生成具有严格格式约束（draw.io XML）的长文本。
|
||
|
||
**推荐模型**：
|
||
|
||
- Claude Sonnet 4.5 / Opus 4.5
|
||
|
||
**关于 Ollama 的说明**：虽然支持将 Ollama 作为提供商，但除非您在本地运行像 DeepSeek R1 或 Qwen3-235B 这样的高性能模型，否则对于此用例通常不太实用。
|
||
|
||
## 温度设置 (Temperature)
|
||
|
||
您可以通过环境变量选择性地配置温度：
|
||
|
||
```bash
|
||
TEMPERATURE=0 # 输出更具确定性（推荐用于图表）
|
||
```
|
||
|
||
**重要提示**：对于不支持温度设置的模型（例如以下模型），请勿设置 `TEMPERATURE`：
|
||
- GPT-5.1 和其他推理模型
|
||
- 某些专用模型
|
||
|
||
未设置时，模型将使用其默认行为。
|
||
|
||
## 推荐
|
||
|
||
- **最佳体验**：使用支持视觉的模型（GPT-4o, Claude, Gemini）以获得图像转图表功能
|
||
- **经济实惠**：DeepSeek 提供具有竞争力的价格
|
||
- **隐私保护**：使用 Ollama 进行完全本地、离线的操作（需要强大的硬件支持）
|
||
- **灵活性**：OpenRouter 通过单一 API 提供对众多模型的访问
|
||
|
||
## 新增一个服务商
|
||
|
||
一个服务商的全部事实都在 `lib/providers.ts` 的一条记录里：用哪个 AI SDK（`sdk`）、用什么凭据登录（`credential`）、环境变量 `<PREFIX>_API_KEY` / `<PREFIX>_BASE_URL` 的前缀（`envPrefix`）、官方地址、选择器里的分组，以及可选的提示文案。设置界面、连接测试、聊天路由和管理面板都读这条记录，所以新增一个 OpenAI 兼容服务商只需：
|
||
|
||
1. 在 `lib/providers.ts` 里加一条记录，例如：
|
||
|
||
```ts
|
||
acme: {
|
||
label: "Acme AI",
|
||
sdk: "openai-compatible",
|
||
credential: "apiKey",
|
||
group: "aggregators",
|
||
envPrefix: "ACME",
|
||
defaultBaseUrl: "https://api.acme.example/v1",
|
||
apiKeyUrl: "https://acme.example/keys",
|
||
modelList: "openai",
|
||
},
|
||
```
|
||
|
||
需要在地址输入框下方显示提示，或在选择器里显示说明的服务商，在记录里加 `baseUrlHint` 或 `note` 对象，四种界面语言（`en`、`zh`、`ja`、`zh-Hant`）都要写。不能在线列出模型的服务商不写 `modelList`，改写一个短的 `models` 列表。
|
||
2. 在 `env.example` 里加上 `ACME_API_KEY` 和 `ACME_BASE_URL`（有一个单元测试检查每条记录的变量名都出现在里面）。
|
||
3. 在 `docs/en`、`docs/cn`、`docs/ja` 的本文档里各加一节说明。
|
||
4. 把它加进 `tests/unit/provider-matrix.test.ts` 开头的两个清单（`MATRIX_PROVIDERS` 和 `MATRIX_MODEL_IDS`），用 `npx vitest run tests/unit/provider-matrix.test.ts -u` 重新生成行为快照；新增的行都属于这家服务商，已有的行不能变。`tests/unit/providers.test.ts` 写明了选择器的分组和会改变服务端行为的服务商集合（自动检测、只接受一条 system 消息），也要加进去。三份 README 里的服务商数量和本文档的 `AI_PROVIDER` 可选值清单同样要改。
|