# 模型网关

Raise 的所有大语言模型调用（包含租户自带密钥）都统一经过平台网关 Bifrost。平台运营方在运营台中配置「模型供应商」，租户管理员在「模型与额度」中选择平台模型或「自带密钥（BYO）」，并统一管理模型额度、调用限速与数据驻留规则。

## 谁能用

使用与配置模型网关涉及以下角色与权限要求：

| 角色 / 身份 | 权限标识 | 权限说明 |
|---|---|---|
| 部署运维方 | 系统运维命令行 | 执行安装脚本。仅当附加 `--llm` 或 `--shell` 参数时才会拉起模型网关容器。未部署网关时，运营台提示「没有部署模型网关」，并说明安装时加 `--llm` 或 `--shell` 才有网关，供应商可先配置。 |
| 平台运营管理员 | `platform.ops` | 拥有运营台「模型供应商」的可写权限，负责添加供应商、维护模型及触发同步。 |
| 平台运营支持人员 | `platform.support` | 拥有运营台「模型供应商」的只读权限，不能添加或修改供应商配置。 |
| 租户管理员 | `admin.write` | 拥有租户「模型与额度」的修改权限，可切换模型来源、设定可用模型与额度策略。 |
| 租户只读成员与审计员 | `admin.read` / 审计员 | 拥有租户「模型与额度」的只读权限，界面标注「只读」并提示「审计员只能查看。」 |

> **注意**
>
> 模型网关是系统所有模型调用的唯一出口。若网关服务异常或未启动，所有模型调用均会失败；租户管理员保存模型策略时也会返回 502 错误且配置不会写入数据库。系统监控会触发 `KworkModelGatewayDown` 或 `KworkModelCallsFailing` 告警。

## 怎么打开

根据不同的管理与使用需求，你可以通过以下地址访问模型网关及相关控制台：

| 访问入口 | 地址 / 路径 | 说明 |
|---|---|---|
| 运营台「模型供应商」 | `https://ops.{base}:8443` → 点击导航「模型供应商」 | 平台运营人员配置模型供应商与模型定价的主控制台。 |
| 网关管理界面（只读） | `https://llm.ops.{base}:8443` | 网关只读管理控制台，支持运营 SSO 登录。供应商配置、租户密钥与管理策略一律以运营台为准。 |
| Grafana「LLM 网关」 | `https://grafana.ops.{base}:8443` | 模型网关监控仪表盘（安装时需附加 `--obs` 参数）。 |
| Langfuse 可观测平台 | `https://langfuse.ops.{base}:8443` | 大模型调用链路追踪控制台（安装时需附加 `--obs-llm` 参数）。 |
| 租户模型管理 | 登录[工作台](/guide/workspace) → 进入「我的组织」→ 点击助手「模型与额度」 | 租户管理员配置组织模型来源、可用模型、限速额度与合规策略的入口。 |
| 主服务调用网关 | 容器内网络默认地址：<br>• 推理接口：`KWORK_LLM_BASE_URL=http://bifrost:8080/v1`<br>• 管理接口：`KWORK_LLM_ADMIN_URL=http://bifrost:8080` | Raise 主服务连接模型网关的内部接口地址。 |

> **提示**
>
> 在 Helm 部署中，通过 `llm.baseUrl` 指定网关地址。Temporal 与模型网关仅在开启 `agent.enabled` 时才需要部署。

## 界面一览

### 运营台「模型供应商」

运营人员通过该界面统一维护平台级的大模型服务商与模型清单：

| 区域 / 组件 | 界面元素 | 说明 |
|---|---|---|
| 顶部操作按钮 | 「重新同步」「添加供应商」 | 点击「添加供应商」可打开新建对话框；当配置与网关不一致时，点击「重新同步」重新下发。 |
| 导航标签 | 「供应商」「用量与租户」「账单」「对账」 | 分别用于管理供应商列表、查看各租户使用量、查看账单明细以及核对 Token 用量与账单。 |
| 概览卡片 | 「网关」「供应商」「可用模型」 | 展示当前网关状态（正常、异常、未部署）、供应商数量（启用数 / 全部数）以及平台当前可用模型总数。 |
| 一致性状态 | 「与网关的一致性」 | 显示数据库配置与网关运行配置的一致性状态。若状态未对齐可点击「重新同步」。 |
| 空列表提示 | 「还没有模型供应商」 | 尚未添加任何供应商时展示，并提示「添加供应商后租户才能用平台模型。」 |
| 供应商列表列 | 「供应商」「接口地址」「区域」「模型」「状态」 | 展示供应商名称、接入 URL、数据区域、包含模型数量，以及当前同步状态（展示「同步于 …」或同步失败错误信息）。 |
| 「添加模型供应商」对话框 | 类型、标识、接口与模型表 | 支持配置供应商类型（「OpenAI 兼容」「Anthropic」「Google Gemini」）、ID、名称、接口地址、区域、API 密钥与模型单价表格。 |

### 租户「模型与额度」

租户管理员在[工作台](/guide/workspace)「我的组织」中对本组织的大模型使用进行精细化管控：

| 区域 / 标签 | 界面元素 | 说明 |
|---|---|---|
| 标签页 | 「用量」「成员管控」「账单」「策略」 | 切换查看组织使用量、单人使用限制、费用账单与模型配置策略。在「策略」页底部提供「还原」与「保存」按钮。 |
| 「模型来源」 | 单选项：「平台模型」与「自带密钥（BYO）」 | 切换使用运营方统一提供的平台模型，或使用租户自己的模型 API Key。 |
| 自带密钥字段 | 「供应商」「接口地址」「API Key」「自带密钥可用的模型」 | 选「自带密钥（BYO）」时显示。输入供应商标识（必填，如 deepseek）、接口地址（可留空）、API Key 以及每行一个模型 ID 的可用模型文本框。 |
| 「可用模型」 | 「范围」「显示名称（别名）」 | 选「平台模型」时显示。「范围」可设为「全部可用模型」或「只允许选中的」；可为勾选的模型设置不超过 40 个字符的别名。 |
| 「默认模型」 | 下拉选项，含「自动（第一个可用的）」 | 设定组织成员进行日常助手对话时默认使用的模型。 |
| 「后台模型」 | 下拉选项，含「平台默认（未单独指定时用默认模型）」 | 设定用于生成会话标题、推荐问题、压缩长对话的专用模型。这些系统调用不受个人可用模型限制，但计入组织总额度。 |
| 「额度与限速」 | 「每月 token 额度」「每分钟请求数」 | 设定全组织每月消耗的 Token 总上限与每分钟最大请求次数，输入 0 表示不限制。 |
| 「按人与角色」 | 「每人每月 token 上限」「按角色限定模型」 | 设定每名成员每月默认可消耗的 Token 上限，并可按角色指定允许调用的模型。个人的特殊例外需在「成员管控」标签中配置。 |
| 「数据与合规」 | 「数据驻留」「记录提示词与回复内容」 | 「数据驻留」可选择「不限制」「中国境内」「欧盟」或「美国」；「记录提示词与回复内容」开关关闭时系统仅统计 Token 消耗量。 |
| 空目录提示 | 「没有可用的模型，请联系运营方添加。」 | 当平台尚未配置任何可用模型且组织未自带密钥时显示。 |

## 常用操作

### 部署模型网关服务

1. 在服务器终端中，执行包含 `--llm` 或 `--shell` 参数的安装脚本：
   ```bash
   ./deploy/install.sh --pack onprem --llm
   ```
   脚本执行完成后，系统自动拉起 Bifrost 容器，并向环境配置文件写入推理地址 `KWORK_LLM_BASE_URL`（默认 `http://bifrost:8080/v1`）与管理地址 `KWORK_LLM_ADMIN_URL`（默认 `http://bifrost:8080`）。
2. 在服务器终端中，打开网关配置文件 `deploy/compose/config/bifrost/config.json`，核对默认运行参数。网关使用 SQLite 存储配置与日志，出厂默认配置包含：`disable_content_logging: true`（不记录请求正文）、`log_retention_days: 30`（日志保留 30 天）、`enforce_auth_on_inference: false`、`allow_direct_keys: false`。模型的策略控制与虚拟密钥由 Raise 主服务在发起调用前强制执行。
3. 若网关需要连接到私有网络或使用 HTTP 协议的上游模型服务，在系统环境中添加 `KWORK_LLM_ALLOW_PRIVATE=true` 并重新加载配置。
4. 若系统需要为知识库等功能启用语义检索，在系统环境中配置 `KWORK_EMBED_MODEL` 指定嵌入模型 ID（具体配置说明参见 [存储](/deploy/storage)）。

### 添加模型供应商

1. 在浏览器中打开运营台（`https://ops.{base}:8443`），在左侧导航点击「模型供应商」，进入供应商管理页面。
2. 在页面顶部，点击「添加供应商」，打开「添加模型供应商」对话框。
3. 在对话框中，填写供应商各项基础信息：
   | 字段 | 必填 | 说明 |
   |---|---|---|
   | 类型 | 是 | 选择「OpenAI 兼容」「Anthropic」或「Google Gemini」。 |
   | ID | 是 | 填写供应商唯一英文标识，创建后不可修改。不能与网关内置标准供应商名称（如 `openrouter`、`openai`、`anthropic`、`gemini` 等）同名，建议使用如 `openrouter-main`。以 `byo-` 开头的标识保留给租户自带密钥。 |
   | 「名称」 | 是 | 填写供应商的显示名称。 |
   | 「接口地址」 | 是 | 填写上游服务的接口基础地址：不带 `/v1`（网关会补）；供应商的接口根地址本身以版本号结尾的（如 `…/api/v3`、`…/api/paas/v4`）原样填写。 |
   | 「数据所在区域」 | 是 | 选择「不限」「中国境内」「欧盟」或「美国」。 |
   | API 密钥 | 是 | 填写供应商分配的 API 凭证，保存后界面将不再显示明文。 |
4. 在模型配置表格中，配置要开放的模型。若添加的是已保存的「OpenAI 兼容」类型供应商，可点击「从供应商读取」，系统会自动列出上游支持的模型；勾选「启用」，并填入「模型 ID」、「租户 入」「租户 出」「成本 入」「成本 出」价格。
5. 在表格下方，点击「测试连接」。系统会向首个已启用的模型发送短消息测试连通性，等待界面提示「通了：…」或「没通：…」。
6. 测试成功后，在对话框右下角点击「保存并同步」，保存供应商数据并向网关同步。若同步失败，可在列表状态列查看错误信息，或点击页面顶部的「重新同步」。

> **提示**
>
> 通过「从供应商读取」获取聚合服务模型列表时，上游可能一次性返回数百个模型，你只需勾选实际计划向租户提供的模型即可。

> **注意**
>
> 若在运营台中停用或关闭某个模型，该模型会立即从所有租户的可用模型列表中消失；正在使用该模型的会话在下一轮对话时会自动回落到组织设置的默认模型。

### 配置租户平台模型策略

1. 在浏览器中登录[工作台](/guide/workspace)，进入「我的组织」应用，在左侧导航点击助手「模型与额度」。
2. 在页面上方，点击「策略」标签页，进入模型规则配置面板。
3. 在「模型来源」区域，选中「平台模型」。
4. 配置组织使用的模型与额度规则：
   | 设置项 | 字段 / 选项 | 说明 |
   |---|---|---|
   | 「可用模型」 | 「范围」 | 选择「全部可用模型」或「只允许选中的」。若选择特定模型，在列表中勾选允许成员使用的模型，并在「显示名称（别名）」输入框中填写别名（长度不超过 40 个字符）。未勾选任何模型时表示允许使用全部平台模型。 |
   | 「默认模型」 | 下拉菜单 | 选择成员新建对话时的首选模型，或选择「自动（第一个可用的）」。 |
   | 「后台模型」 | 下拉菜单 | 选择用于生成会话标题、推荐问题与长对话压缩的专用模型，或选择「平台默认（未单独指定时用默认模型）」。后台调用不受成员可用模型限制，但计入组织总额度。 |
   | 「额度与限速」 | 「每月 token 额度」/「每分钟请求数」 | 输入组织每月的 Token 消耗上限与每分钟最大请求次数，输入 0 表示不限制。 |
   | 「按人与角色」 | 「每人每月 token 上限」/「按角色限定模型」 | 设定每位成员的每月 Token 消耗上限，并可按角色指定允许调用的模型。个人的特殊例外设置可在「成员管控」标签中配置。 |
   | 「数据与合规」 | 「数据驻留」 | 选择「不限制」「中国境内」「欧盟」或「美国」。系统将严格限制只调用该地理区域内的模型。 |
   | 「数据与合规」 | 「记录提示词与回复内容」 | 开关选项。关闭时系统仅统计 Token 消耗量，不保存具体提示词与回复正文。 |
5. 在页面底部，点击「保存」，应用策略设置。保存成功后界面弹出提示「模型策略已保存」。若要放弃未保存的修改，点击「还原」。

> **提示**
>
> 若平台运营方后续停用了组织此前已勾选的某些模型，策略页面会提示「有 N 个允许的模型现在用不了」。

### 配置租户自带密钥（BYO）

1. 在[工作台](/guide/workspace)中，进入「我的组织」→「模型与额度」，点击「策略」标签页。
2. 在「模型来源」区域，选中「自带密钥（BYO）」。
3. 在自带密钥表单中，填写供应商连接信息：
   | 字段 | 必填 | 说明 |
   |---|---|---|
   | 「供应商」 | 是 | 填写供应商标识（例如 deepseek）。 |
   | 「接口地址」 | 否 | 填写自定义模型接口服务地址。接口地址必须通过系统的安全检查，使用 HTTPS 协议（除非部署方显式开启了私网允许）。若使用官方默认地址可留空。 |
   | 「API Key」 | 是 | 填写你在该供应商处申请的 API 凭证。密钥将安全加密存储在 OpenBao 中，数据库中仅保留密钥引用。 |
   | 「自带密钥可用的模型」 | 是 | 在多行文本输入框中逐行填入允许使用的模型标识，每行填写一个模型 ID。 |
4. 在下方区域，根据需要设置「默认模型」、「后台模型」、「额度与限速」以及「数据驻留」规则。
5. 在页面底部，点击「保存」，提交配置。系统会对接口地址进行安全检查并将供应商凭证注册到网关中。

> **注意**
>
> 租户随时可以在「模型来源」中切回「平台模型」。一旦切换回平台模型并保存，原先注册的自带密钥（BYO）配置与凭证将立即从网关中注销并移除。

### 临时开启网关内容日志排查

系统出厂默认严格保护数据隐私，租户侧「记录提示词与回复内容」默认处于关闭状态，Bifrost 网关配置中的 `disable_content_logging` 默认也为 `true`。若在运维排查过程中需要临时记录请求正文：

1. 在服务器终端中，打开网关配置文件 `deploy/compose/config/bifrost/config.json`。
2. 在文件中，将 `disable_content_logging` 的值从 `true` 修改为 `false`。
3. 在服务器终端中，执行以下命令强制重建并重启网关容器：
   ```bash
   docker compose up -d --force-recreate bifrost
   ```
4. 故障排查完成后，请务必重新将 `disable_content_logging` 改为 `true`，并再次执行上述命令重启网关，以确保符合数据隐私要求。

## 状态说明

系统在运营台与租户端提供以下运行状态指示与流转机制：

### 网关与供应商状态

| 状态类型 | 状态显示 | 状态说明 |
|---|---|---|
| 网关运行状态 | 正常 / 异常 / 未部署 | 正常表示 Bifrost 运行良好；异常表示无法连接；未部署表示安装时未附加 `--llm` 或 `--shell` 参数，界面提示「没有部署模型网关」，并说明安装时加 `--llm` 或 `--shell` 才有网关，供应商可先配置。 |
| 数据一致性状态 | 「与网关的一致性」 | 显示运营台数据库中的配置与网关内存配置的一致状态。若状态异常或未对齐，可点击「重新同步」按钮重新下发。 |
| 供应商同步状态 | 「同步于 …」 / 同步错误 | 正常时展示最近一次成功同步的时间戳；同步失败时展示具体的错误信息。 |

### 租户使用与额度状态

| 状态场景 | 界面提示或表现 | 处理方法 |
|---|---|---|
| 暂无可用模型 | 「没有可用的模型，请联系运营方添加。」 | 平台尚未配置任何可用模型，需联系平台运营人员添加供应商与模型，或切换为自带密钥。 |
| 模型被运营方停用 | 「有 N 个允许的模型现在用不了」 | 组织此前配置允许的模型已被运营方下架，对话会自动回落到默认模型，管理员可重新调整允许列表。 |
| 成员模型权限被暂停 | 「你的账号被管理员暂停了模型使用。」 | 该成员的模型使用权限已被租户管理员暂停，需管理员在「成员管控」标签中解除限制。 |
| 成员每月额度耗尽 | 「你本月的模型额度已用完，请联系管理员。」 | 该成员已达到本月设定的 Token 上限，额度将在次月 1 日重置，或由管理员在「成员管控」中调整个人上限。 |
| 请求频率超限 | 「请求太频繁」 | 模型触发 429 速率限制（常见于免费聚合模型）。429 限制仅计入错误次数，系统不会扣除 Token 额度，也不计费。 |

## 让助手帮你做

租户管理员可以通过自然语言让助手协助管理模型与额度策略。这些操作属于组织高风险管理操作，助手会先起草变更草稿，必须由管理员在审阅页人工确认后才会执行生效。涉及 API Key 的操作，密钥只能由管理员在审阅页手动输入。

你可以对助手说：

> 把月额度改成 1 亿 token
> 改成自带 DeepSeek 密钥
> 暂停张三的模型

助手支持起草以下管理任务：
- 「修改模型与额度」：调整组织的每月 Token 额度或请求频率限制。
- 「设置模型来源（自带密钥）」：切换至自带密钥模式并设定模型列表（API Key 需在审阅界面由你亲自填写）。
- 「设置成员的模型使用」：为指定成员设置个人每月 Token 上限或暂停其使用权限。

> **注意**
>
> 助手只能协助起草租户内部的模型策略，助手不能执行以下操作：
> - 修改运营台中的模型供应商配置。
> - 查看系统中已存储的 API 密钥明文。
> - 绕过网关直接连接上游模型服务。
> - 在模型网关不可用时保存模型策略。

## 设置

模型网关涉及的环境变量与系统配置项如下：

| 配置项 | 作用 | 默认值 | 配置角色 |
|---|---|---|---|
| `KWORK_LLM_BASE_URL` | OpenAI 兼容格式的模型推理接口地址 | `http://bifrost:8080/v1`（安装 `--llm` 时写入） | 部署运维方 |
| `KWORK_LLM_ADMIN_URL` | 模型网关管理接口地址 | `http://bifrost:8080` | 部署运维方 |
| `KWORK_LLM_API_KEY` | Raise 主服务调用网关管理接口的认证密钥 | 空 | 部署运维方 |
| `KWORK_LLM_ALLOW_PRIVATE` | 是否允许网关连接私有网络或 HTTP 协议的上游模型地址 | 未设置（不允许） | 部署运维方 |
| `KWORK_EMBED_MODEL` | 语义检索所使用的嵌入模型 ID（未配置时仅支持关键词检索） | 空 | 部署运维方 |
| 「数据驻留」 | 限制租户仅调用指定地理区域的模型（可选「不限制」「中国境内」「欧盟」「美国」） | 「不限制」 | 租户管理员 |
| 「记录提示词与回复内容」 | 是否在数据库中记录提示词与模型回复的正文内容（关闭时仅记录 Token 消耗量） | 关闭 | 租户管理员 |
| Bifrost `disable_content_logging` | 网关日志是否包含请求与回复正文 | `true`（不记录） | 部署运维方 |
| Bifrost `log_retention_days` | 网关日志在 SQLite 中的保留天数 | `30` | 部署运维方 |
| Bifrost `enforce_auth_on_inference` | 网关推断接口本身是否强制身份认证 | `false` | 部署运维方 |
| Bifrost `allow_direct_keys` | 网关是否允许客户端直接传递上游密钥 | `false` | 部署运维方 |

## 注意事项

- **网关唯一出口**：系统中的日常助手对话、后台命名与压缩、知识库嵌入向量化以及分析洞察等所有大模型调用，均统一经过主服务路由器与 Bifrost 网关。网关不可用时，所有模型调用均会失败，且租户保存模型策略也会返回 502 错误并且不会落库。
- **供应商 ID 限制**：运营台添加供应商时，供应商 ID 不能与网关内置标准供应商名称（如 `openrouter`、`openai`、`anthropic`、`gemini` 等）同名，否则网关会拒绝并报错 `Custom provider cannot be same as a standard provider`。此外，以 `byo-` 开头的 ID 专门保留给租户自带密钥。
- **命名与列表上限**：在租户配置中，模型的「显示名称（别名）」长度不能超过 40 个字符；通过助手操作配置允许的模型列表时，模型数量上限（`maxItems`）为 100。
- **额度重置周期**：成员的个人每月 Token 额度上限统一按 **UTC 自然月** 进行重置。
- **密钥安全与解密**：租户自带的 API Key 加密保存在 OpenBao 中。若 OpenBao 服务处于封存（sealed）状态，密钥解密将失败，Raise 主服务的 `/readyz` 健康检查将返回 503 错误。
- **数据驻留与嵌入约束**：当租户设置了「数据驻留」时，系统仅调用该区域内的模型；知识库所用的嵌入模型同样受到数据驻留区域与组织 Token 额度的严格约束。
- **可观测追踪与脱敏**：在 Langfuse 可观测平台中，生成的调用记录包含模型标识、Token 用量与租户标识（`tenant_id`），但**绝不包含消息正文**（日志收集器会自动过滤 Bifrost 链路追踪数据中的消息内容）。
- **计费与对账**：系统所有模型调用的计费币种统一为 USD。平台运营方修改模型价格仅对后续调用生效，不会更改历史账单。运营台在对账偏差（drift）超过 `max(5%, 200 token)` 时会进行提示。

## 目前不支持

- **预置上游供应商**：系统出厂时不预置任何上游模型供应商与 API 凭证，部署后必须由平台运营人员在运营台中手动添加。
- **绕过网关直连**：系统不支持租户或成员绕过平台网关直接连接上游模型服务。

## 常见问题

### 运营台提示「没有部署模型网关」是怎么回事？
在执行主机安装或服务部署脚本时，未附加 `--llm` 或 `--shell` 参数。此时网关容器未启动。平台运营人员可以先在运营台中预先配置模型供应商，但租户无法进行模型调用，也无法保存模型策略。若需启用网关，请使用 `install.sh --llm` 重新执行部署。

### 为什么租户管理员在保存模型策略时提示 502 错误？
Bifrost 模型网关是策略保存链路上的必经组件。若网关容器未部署、未启动或运行异常，租户保存模型策略时会直接返回 502 错误，并且策略配置不会写入数据库。请检查网关容器的运行状态与网络连通性。

### 用户调用模型时提示「请求太频繁」，会扣除 Token 额度或产生账单吗？
不会。该提示通常是由于上游模型供应商（尤其是免费聚合模型）返回了 429 速率限制错误。429 错误在系统中仅计入调用失败次数，不扣除租户或成员的 Token 额度，也不会计入计费账单。

### 成员提示「你本月的模型额度已用完，请联系管理员」，额度何时恢复？
成员的个人每月 Token 上限按照 **UTC 自然月** 进行重置，在每月 1 日 00:00 (UTC) 会自动恢复额度。如果成员急需使用，租户管理员可进入「我的组织」→「模型与额度」→「成员管控」标签，为该成员调整个人例外上限。

### 添加供应商时报错 Custom provider cannot be same as a standard provider 该如何处理？
Bifrost 网关内置了常见标准供应商的保留标识（如 `openrouter`、`openai`、`anthropic`、`gemini` 等）。在运营台填写供应商 ID 时，不能直接使用这些保留标识，需改用自定义名称（例如 `openrouter-main`）。