# 配置大模型

接入大模型，配置模型组中的 Fast、Omni 和 Agent 角色，并测试连接。

AskTable 支持多种大模型。模型需要支持工具调用，以完成数据查询、Python 计算和图表生成。

## 开始前

- 权限：账号的「用户身份」是「系统管理员」。模型组是全局资源，不按项目隔离。
- 入口：左下角头像 →「系统设置」→ 左侧「模型组」。首次部署时初始化向导也会带你配一次。
- 准备一份接入信息：走 AskTable 托管算力只要「算力 API Key」；接自己的服务要 Base URL、API Key 和模型名。
- 私有部署要确认服务器能出网访问模型服务地址。

## 操作步骤

**首次部署：走初始化向导**

打开站点会进 `/setup`，顶部两个步骤：「创建管理员」「配置模型」。

「配置模型」页有三张卡：

| 卡片                   | 什么时候出现           | 要填什么                                                    |
| -------------------- | ---------------- | ------------------------------------------------------- |
| 「已检测到阿里云百炼配置」        | 服务器上配了阿里云百炼的环境变量 | 不用填，提示「将使用 qwen3-max 作为默认模型」                            |
| 「AskTable 官方 API 渠道」 | 一直有              | 「算力 API Key」，旁边是「没有API Key？点击免费获取」                      |
| 「自定义渠道」              | 一直有              | 「Base URL」「API Key」「模型名称」，模型名占位符「例如 gpt-4o, qwen-3-max」 |

点「完成配置」后进入项目列表。已经初始化过的站点不会再进这个向导。

**打开模型组管理**

左下角头像 →「系统设置」→ 左侧「模型组」。

标题「模型组管理」，副标题「管理系统中的 LLM 模型组配置」，右上角「新建模型组」。左栏是模型组列表，每项显示「显示名称」（留空时显示「唯一标识」）和 Base URL，徽标有「官方」「默认」，非 OpenAI 协议的显示协议名（例如「Anthropic」）。右栏没选中时显示「选择一个模型组查看详情」；一个组都没有时左栏显示「暂无数据」。

**新建模型组**

点「新建模型组」，第一步「选择模型组类型」，三张卡：

- 「AskTable 官方」——「使用 AskTable 算力服务，只需填写算力 API Key」。
- 「OpenAI 兼容」——「接入第三方 LLM 服务，自由配置」。
- 「Anthropic 兼容」——「接入 Anthropic 协议的第三方 LLM 服务」。

官方类型只填「算力 API Key」（占位符 `asktable-`）。自定义类型要填：

| 字段       | 说明                                |
| -------- | --------------------------------- |
| 「唯一标识」   | 必填，机器标识，不能和已有组重名                  |
| 「显示名称」   | 选填，占位符「留空则使用唯一标识」                 |
| 「API 协议」 | 「OpenAI」或「Anthropic」              |
| Base URL | 必填，例如 `https://api.openai.com/v1` |
| API Key  | 必填，占位符 `sk-...`                   |

点「创建」，按钮变成「创建中...」，成功提示「模型组创建成功」。官方类型会自动把 Base URL 写成 `https://aiproxy.asktable.com/v1`，并把三个角色预置成 `asktable-fast`、`asktable-omni`、`asktable-agent`。

**把模型加进可用列表**

选中一个组，右栏「可用模型」区块：

1. 手填：在「模型 ID（如 gpt-4o）」和「显示名称（可选）」两个框里填值，点「添加」；重名提示「模型已存在」。
2. 拉取：点「Fetch」调上游的模型列表接口，把没见过的模型补进来，新补进来的默认关闭。
3. 搜索与统计：搜索框提示「搜索模型...」，上方统计形如「共 N 个模型，M 个已启用（已启用排在前面）」。

每行右侧四个控件：齿轮是「模型选项」、垃圾桶是「移除模型」、闪电是「测试模型」、最右侧开关控制启用。移除一个模型时，引用它的角色路由会一起清空。

**逐个测通模型**

点行内的「测试模型」（闪电图标），成功提示「模型 X 测试通过」，失败提示「模型 X 测试失败」。

只把测通过的模型打开开关：「模型路由」的下拉里只列已启用的模型。

**给三个角色分模型**

「模型路由」区块有三行，角色名是 Fast、Omni、Agent，每行一个下拉。未选时显示「未指定」，可选值就是已启用的模型。

改动即时保存，不需要再点保存按钮。

**调模型选项**

点某个模型的齿轮打开「模型选项」弹窗，说明是「配置 X 的选项」：

| 项                              | 说明                                                        |
| ------------------------------ | --------------------------------------------------------- |
| 「上下文窗口」                        | 数字框，占位符 `128000`。留空时对话上下文压缩回退用 65536                      |
| 「供应商选项（JSON）」                  | 原样发给上游的参数，说明里的示例形如 `thinking.type = disabled`             |
| 「思考参数（快速 / 深度）」                | 选 provider 类型，再给「快速模式」「深度思考模式」各挑一个档位；档位会 merge 到「供应商选项」之上 |
| 「回传历史推理内容（reasoning\_content）」 | 开关，默认开                                                    |

「思考参数」的 provider 选项是「不启用（不覆盖）」「DeepSeek（思考开关）」「OpenAI（reasoning\_effort）」「通义千问 / DashScope（enable\_thinking）」「自定义（原始 JSON）」。选到具体 provider 时，快速模式默认取最省档位、深度思考模式默认取较强档位，可以再改；选「自定义（原始 JSON）」时两个模式各给一个 JSON 文本框，JSON 写错会标红且不保存。

「回传历史推理内容（reasoning\_content）」的说明是「DeepSeek V4 等接续推理模型需开启；asktable-fast 等不接受该字段的模型必须关闭。」

**设默认、克隆、删除**

右栏右上角「更多」菜单里有两个操作：

- 「设为默认」：成功提示「已设为默认模型组」。默认组全站只有一个，也是没指定时的兜底。
- 「克隆模型组」：复制出一个标识加 `-copy` 的组，凭证和模型配置一起带走。

「删除」按钮只在非默认组上出现，确认弹窗写「确定要删除模型组 "X" 吗？此操作无法撤销。」默认组不显示删除按钮。

**决定项目用哪个组**

默认情况下项目跟随系统默认组。要单独指定：左侧主导航 → 项目名右侧的「设置」→「通用」→「模型组」下拉，选项是「默认」「默认（组名）」或具体组名，占位提示「请选择模型组」。一个可用组都没有时提示「暂无可用模型组，请联系管理员配置模型。」

## 关键约束

| 项目            | 值或默认                                                                   | 在哪里改                    |
| ------------- | ---------------------------------------------------------------------- | ----------------------- |
| 模型组作用域        | 全局，不按项目隔离                                                              | 头像 →「系统设置」→「模型组」        |
| 默认模型组         | 必须有一个，且不能删除                                                            | 「模型组」→ 目标组 →「更多」→「设为默认」 |
| 官方渠道 Base URL | `https://aiproxy.asktable.com/v1`                                      | 新建官方类型时自动写入             |
| 官方渠道预置角色      | Fast 是 `asktable-fast`、Omni 是 `asktable-omni`、Agent 是 `asktable-agent` | 「模型组」→「模型路由」            |
| 模型角色          | Fast、Omni、Agent 三个                                                     | 「模型组」→「模型路由」            |
| 「API 协议」      | 「OpenAI」或「Anthropic」                                                   | 「模型组」→「连接配置」            |
| 「上下文窗口」       | 默认空；留空时上下文压缩回退用 65536                                                  | 模型选项                    |
| 「回传历史推理内容」    | 默认开                                                                    | 模型选项                    |
| 「思考参数」        | 默认「不启用（不覆盖）」                                                           | 模型选项                    |
| 「额外请求头」       | 默认空                                                                    | 「模型组」→「额外请求头」           |
| 官方组可见字段       | 默认只显示「显示名称」「算力 API Key」；其余在「高级配置」里                                     | 「模型组」→「高级配置」            |
| 项目使用的模型组      | 默认跟随系统默认                                                               | 项目设置 →「通用」→「模型组」        |
| 官方组的「充值」      | 只在私有部署出现                                                               | 「模型组」→ 官方组右栏            |

以上数值都是默认值，可在管理后台调整。

## 出问题怎么判断

| 现象                                  | 判定条件                       | 处理                                   |
| ----------------------------------- | -------------------------- | ------------------------------------ |
| 对话里报「模型组 X 认证失败，请检查该模型组的 API 密钥或余额」 | 错误码 `LLM_AUTH_ERROR`       | 到「模型组」重填 API Key，或给账户充值              |
| 对话里报「模型组 X 连接失败」                    | 错误码 `LLM_CONNECTION_ERROR` | 核对 Base URL；私有部署再确认服务器能出网到该地址        |
| 对话里报「模型组 X 服务异常，请稍后重试」              | 错误码 `LLM_ERROR`            | 上游服务本身异常，稍后重试或看上游状态                  |
| 对话里报「AI 服务返回了无效响应」                  | 错误码 `LLM_BAD_RESPONSE`     | 该模型对工具调用的支持不完整，换一个模型或调整「供应商选项」       |
| 对话里报「输入内容触发了内容安全审查，请修改后重试」          | 错误码 `LLM_CONTENT_FILTERED` | 换问法；这是上游的内容审查，不是 AskTable 拦的         |
| 报「此功能仅在配置官方 AI 代理通道时可用」             | 错误码 `ASKTABLE_LLM_ONLY`    | 该功能要「AskTable 官方」类型的组，新建一个官方组并「设为默认」 |
| 项目设置里提示「模型组"X"不存在，使用默认模型组」          | 项目选的组已被删除                  | 在「模型组」里重选一个，或把当前组「设为默认」              |
| 项目设置里提示「暂无可用模型组，请联系管理员配置模型。」        | 一个模型组都没有                   | 先建一个组                                |
| 「测试模型」失败                            | 点闪电图标后提示「模型 X 测试失败」        | 确认模型 ID 与上游一致，且该 Key 有调用这个模型的权限      |
| 「模型路由」下拉里没有想要的模型                    | 下拉只列已启用模型                  | 到「可用模型」把该模型开关打开                      |
| 删除按钮点不到                             | 该组是默认组                     | 先把别的组「设为默认」，再删这个                     |
| 「深度思考模式」没生效                         | 该模型没配「思考参数」的深度档位           | 模型选项 →「思考参数」→ 给「深度思考模式」选档位           |
| 「思考参数」保存不了                          | JSON 文本框标红，说明 JSON 不合法     | 改到合法 JSON 再保存                        |
| 模型列表里想删的模型删不掉引用                     | 移除模型时该模型还占着角色路由            | 移除后到「模型路由」重新给该角色选模型                  |

## 下一步

- 让每个项目用不同模型组：项目设置 →「通用」→「模型组」
- 解除私有部署的限制：[商业授权](https://docs.asktable.com/admin/license)
- 把数据接进来再开对话：[连接数据源](https://docs.asktable.com/data/connect)
- 部署参数与运行责任：[部署总览](https://docs.asktable.com/deploy/overview)