# AI 供应商与模型

AiCode 自身不提供模型，需先接入一个模型服务。入口在「设置 → AI 供应商」。

## 添加一个供应商

点右上角 + 从底部弹出添加面板：

- 第一项是**自定义供应商**（从空白手动配置）。
- 下面是内置官方预设，选中后自动填入名称、上游格式与 Base URL，进编辑页补上 API Key 即可使用，各项也可手动修改。

预设列表随版本更新，以实际显示为准。

自定义时填以下四项：

- **名称**：易识别的别名，例如「我的中转」。列表按名称自动匹配品牌图标。
- **上游格式**：`OpenAI` / `Anthropic` / `Gemini` 三选一，决定请求协议。第三方中转站一般选 `OpenAI`。
- **API Key**：密钥，形如 `sk-xxx`。粘贴时多带的空格或换行会在保存时自动清理。
- **Base URL**：API 根地址。留空会按上游格式自动填官方地址；用第三方中转时填中转服务的地址，带不带 `/v1` 都可以。

配好后切到「模型」标签拉取模型，即可回主页开始对话。

## 管理供应商列表

列表每行显示名称、上游格式、模型数量和启用状态。

- 点一行进入编辑页。修改后点左上角返回箭头或按系统返回键，配置会自动保存；未修改时直接返回，不重复保存。
- **左滑一行**露出红色删除按钮。
- **长按名称或上游格式区域拖动**调整顺序，重启后保持。

## 多 Key 模式

::: tip 版本说明
多 Key 模式从 1.11.0 起提供。
:::

如果持有同一服务的多个密钥，可在编辑页的「选项」里打开**多 Key 模式**：密钥不可用时自动切到下一个并**重发本次请求**。打开后单 Key 输入框隐藏，密钥统一在「多 Key 管理」页维护（原本填的那个会成为列表第一项）。

管理页分三块：

**Key 列表**：每条 Key 是一张可折叠卡片，折叠时显示序号与掩码预览，点击展开后可编辑该条 Key 并设置**调度权重**（默认 `1`，最大 `1,000,000`；`≤ 0` 表示保留但不参与调度）。左滑删除，长按卡片头部拖动排序（重启后保持），眼睛图标切换明文/掩码。权重只影响**轮询**策略——数值越大，新会话分到该 Key 的比例越高（按权重平滑分配，如 `1:3` 约为 1 比 3）。

**取用策略**：

- `顺序`：始终用靠前的 Key，失败达到阈值才切下一个。
- `轮询`：新会话按权重比例轮流起步，用于均衡多个 Key 的额度消耗。

为保住服务端 Prompt 缓存，**单会话内默认保持同一个 Key**，只在当前 Key 不可用时才切。

**失败切换**：

- `自动切换状态码`：命中这些 HTTP 状态码时立即切换并重发，默认 `401,402,403,429`；留空使用默认值，也可按需增删（逗号分隔）。
- `冷却时长`：被切走的 Key 隔多久重新参与候选，默认 5 分钟，也可设为不冷却。

一次请求依次尝试列表里的 Key，全部失败才报错（提示「N 个 Key 均失败」）。流式回复若已开始输出则不再重发（避免重复输出），只切换后续请求用的 Key；触发切换时聊天区出现「已切换到第 N/M 个 Key」提示。

鉴权失败、权限不足、限流、余额或额度用尽视为「密钥不可用」，会触发切换；服务器 5xx、超时、网络不可达换 Key 也无法解决，仍走原有网络重试。若所有 Key 都在冷却中，会直接报错提示稍后重试。

App 重启后回到第一个 Key，冷却记录清空。

## 选项

编辑页的「选项」分组里还有：

- **完整 URL**：开启后 Base URL 即完整请求地址，不再自动拼接默认路径。
- **新版协议端点**：上游格式为 OpenAI 时可开启「Response API (新版)」，Gemini 时可开启「Interactions API (新版)」。默认关闭，确认服务支持对应新协议时再开。

### 自定义请求头

给该供应商的所有请求追加 Header，完全覆盖同名默认头（如填 `User-Agent` 就替换掉默认 UA）。仅少数中转网关需要。值里可用的占位符：

::: v-pre
| 占位符 | 说明 |
| :--- | :--- |
| `{{SESSION_ID}}` | 当前会话 id |
| `{{API_KEY}}` | 本次实际取用的 Key |
:::

### 自定义面板脚本

让供应商在输入框上方显示余额或用量卡片。脚本放在 `~/.aicode/scripts/` 下，支持 Python、Bash、Node，可在编辑页点「运行测试」看输出。

脚本参数以 `AICODE_KEY_<KEY>` 环境变量注入（KEY 转大写，仅保留字母、数字与下划线）。值里可用的占位符：

::: v-pre
| 占位符 | 说明 |
| :--- | :--- |
| `{{PROVIDER_API_KEY}}` | 当前生效的 API Key |
| `{{PROVIDER_ID}}` | 供应商记录 ID |
| `{{PROVIDER_NAME}}` | 供应商名称 |
| `{{PROVIDER_TYPE}}` | 上游格式（OPENAI / ANTHROPIC / GEMINI） |
| `{{BASE_URL}}` | 供应商 Base URL |
| `{{DEFAULT_MODEL}}` | 默认模型 |
| `{{SELECTED_MODEL}}` | 当前选中的模型 |
| `{{MODEL}}` | 实际生效的模型（优先选中，其次默认） |
:::

脚本能读到的环境变量（Token、会话状态、工作区、供应商等）与卡片 JSON 结构，见[自定义面板](https://aicode.murk.top/md/advanced/dashboard-cards.md)。

## 模型管理

切到编辑页的「模型」标签页。

**拉取模型**：点「拉取模型」从服务端同步可用列表，结果按品牌分组、可搜索。每个模型旁有 `Image`（支持图片输入）、`Tools`（支持工具调用）标签，`↑` 后是上下文长度、`↓` 后是最大输出。弹窗右上角「全部添加」可一键把新模型批量加入当前供应商。

拉取成功后会自动对齐本地列表：远端已不存在的模型会从列表移除（拉取失败或返回空列表时不动本地列表），手动添加但不在远端结果里的模型也会被移除。不希望如此可在[偏好设置](https://aicode.murk.top/md/guide/general.md)里关掉「拉取模型后自动移除无效模型」。

**批量操作与多选**：模型列表非空时，编辑页顶栏右侧出现多选按钮，点击进入批量选择模式：
- **全选 / 取消全选**：一键勾选全部模型或清空。
- **批量测试**：对选中模型依次发起连通性测试。
- **批量删除**：二次确认后批量删除。
- 点左上角返回箭头或按返回键退出。

**手动添加**：中转站模型名有时拉不全，可点 + 手动输入。编辑弹窗里可自定义该模型：

- **总上下文窗口**：输入与输出合计的容量，影响何时触发上下文自动压缩。
- **输入窗口**：模型可接收的最大输入长度，与总上下文窗口独立设置。
- **输出窗口**：单次回复的最大长度。
- **价格**：输入 / 输出 / 缓存读取 / 缓存写入四档，单位是美元每百万 token，用于费用统计。
- **能力开关**：图片输入、图片输出、工具调用、推理能力。

窗口值需填写有效的正整数，也可留空使用自动识别值；填写 0、负数、小数或超出范围的整数时会显示提示，且无法保存。编辑已有模型时，只改价格不会改变原有的总上下文、输入和输出窗口。

手动填的值优先；未填的会回退到自动识别结果，自定义设置始终对应当前供应商下的原模型名。自动识别优先匹配完整名称，再尝试忽略大小写；仍未找到时尝试去掉 `-thinking`、`-preview`、`-high` 这类常见后缀，并尝试去掉供应商品牌前缀。上述尝试均失败后，才去掉最后一个 `-` 及其后面的部分匹配一次，不会反复截短名称。

**测试**：每个模型行有「测试」按钮，发一次真实请求验证连通性，结果显示在行下方。

**排序**：长按模型名称区域拖动调整顺序，保存后立即生效（模型选择弹窗与默认模型列表都按此顺序），重启后保持。

**删除**：模型行左滑删除。若删掉的模型正在被使用（当前选中模型、新会话默认模型、识图 / 生图 / 压缩 / 标题总结等专用模型，或某历史会话绑定的模型），相关选择自动回退到默认模型。

## 思考强度

聊天输入框上的思考强度按钮决定模型的推理档位。能识别模型支持的档位时只列出这几档；识别不出（模型无档位信息，或中转站改了模型名）则列出全部档位——`关闭` / `极低` / `低` / `中` / `高` / `极高` / `最高`，由你判断。选择会记住，下次新会话使用该模型时沿用。