next-ai-draw-io/docs/cn/ai-providers.md

# 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` 可选值清单同样要改。