# 模型授权

来源: https://platform.lyrouter.com/ai_gateway/docs/authorization
更新日期: 2026-10-14

一把 API Key 能调用哪些模型由两层设置决定：Key 所属工作空间在 **模型广场** 中开通的模型是基线；安全围栏的「模型访问控制」策略再按部门、组织成员或 API Key 收窄，只能减少、不能增加。模型没有在工作空间开通时，调用返回 403 `model_not_available`；被模型策略拦下时返回 403 `guardrail_model`。

## 两层授权

| 层 | 在哪里设置 | 谁来设置 | 作用 |
| --- | --- | --- | --- |
| 模型广场开通 | 工作空间的 **模型广场**：模型卡片上的开关，或模型详情页中每个服务商的开关 | 当前账号管理员、该工作空间的管理员（个人版为账户本人） | 决定工作空间内所有 API Key 能调用哪些模型、经由哪些服务商 |
| 模型访问控制策略 | **安全围栏** 的「模型访问控制」 | 当前账号管理员，团队版起可用 | 对部门、组织成员或 API Key 进一步收窄 |

- 没有任何模型策略时，工作空间内的所有 Key 都能调用模型广场中已开通的模型。
- 模型策略不能放开模型广场没开通的模型：即使允许名单里写了它，调用仍返回 `model_not_available`。
- 开通、停用和策略的修改保存后几秒内同步到网关，不需要更换 API Key。
- 安全围栏页面只对账号管理员显示，普通成员遇到权限问题时，请把模型 ID、API Key 名称和报错原文发给账号管理员核对。

## 在模型广场开通模型

模型广场分三个区：「专属可用模型」是本工作空间已经开通、可以直接调用的模型；「可启用」是有可用来源但尚未开通的模型；「需接入」是还没有任何可用来源的模型，需要先[接入 BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok)。

- **按模型开关**：卡片上的开关作用于整个模型，打开时开通它所有可开通的来源，关闭时停用全部已开通的来源。
- **按服务商开关**：只想开通或停用某一个服务商时，打开模型详情页的「服务商与价格」，在对应服务商那一行操作。
- **停用最后一个来源**：会先弹出「确认停用最后一个服务来源」，确认后本工作空间的 API Key 不能再调用这个模型。
- **作用范围**：开通和停用只影响当前工作空间，不改变其他工作空间。

（截图：模型广场的「专属可用模型」列出本工作空间已开通的模型，管理员可用卡片右上角的开关开通或停用。）

## 成员申请开通

工作空间角色为查看者或编辑者的成员看不到开关，可以在模型广场或模型详情页向账号管理员提出申请：

| 按钮 | 出现位置 |
| --- | --- |
| 「申请开通」 | 模型在本工作空间没有可用来源时，出现在模型卡片或详情页顶部 |
| 「申请开通该服务商」 | 详情页中某个服务商的状态为「已禁用」或「成员访问受限」时，出现在该服务商那一行 |

- 点击后向当前账号管理员发送一条站内通知，按钮变为「已通知管理员」。同一成员 24 小时内对同一模型或服务商重复申请，不会再发新通知，页面提示「管理员已收到该通知」。
- 申请只发通知，不创建审批流程，也不改变任何权限。账号管理员或工作空间管理员需要在模型广场开通模型或服务商；限制来自模型策略时，由账号管理员在安全围栏中调整。
- 详情页的状态「成员访问受限」表示工作空间已经开通了这个服务商，限制来自模型访问控制策略，需要调整的是安全围栏而不是模型广场。

## 用模型访问控制策略收窄范围

当前账号管理员在 **安全围栏** 打开「模型访问控制」页签，点「新建模型访问控制策略」，按三步完成：

1. **生效对象**：选择「部门」「组织成员」或「API Key」。这类策略不能挂在整个工作空间上，要限制全空间请直接在模型广场停用。
2. **策略规则**：在「名单模式」中选「允许名单」（只允许名单内的模型）或「拒绝名单」（禁止名单内的模型）；在「允许调用的模型」或「禁止调用的模型」中选择具体模型，或在「模型通配符」中每行写一个 `*` 通配，例如 `qwen-*`、`deepseek/*`。执行动作固定为「阻断」。
3. **生效时间**：选择立即生效或定时生效，以及是否设置失效时间。

（截图：安全围栏按策略类型分页签；在「模型访问控制」页签查看各策略的生效对象、执行动作与状态。）

### 多条策略如何叠加

| 情况 | 结果 |
| --- | --- |
| 任意一条适用的拒绝名单命中 | 拒绝 |
| 同一对象上有多条允许名单 | 合并，模型出现在其中任意一条即可 |
| 不同对象上都有允许名单（例如部门一条、Key 一条） | 模型必须同时出现在每一个对象的允许名单里 |

所以 Key 上的允许名单不能放宽部门或成员的限制。生效对象的匹配方式：「部门」覆盖创建人主部门恰好是该部门的 Key，不含子部门；「组织成员」覆盖该成员创建的全部 Key；「API Key」只覆盖所选的 Key。

## 调用时的结果

| 情况 | 结果 |
| --- | --- |
| 模型已开通，没有策略限制 | 正常调用 |
| 模型未在工作空间开通 | 403 `Model is not available in the model plaza`，`error.code` 为 `model_not_available`。工作空间设置了默认模型时，对话类请求改由默认模型回答，见[通道选择与路由策略](https://platform.lyrouter.com/ai_gateway/docs/routing) |
| 模型被模型策略禁止 | 403 `Request blocked by guardrail policy`，`error.code` 为 `guardrail_model`，不会再尝试备用模型 |

- **按实际模型检查**：通过[虚拟模型](https://platform.lyrouter.com/ai_gateway/docs/presets)或 `lyrouter/auto` 调用时，网关按最终选中的模型 ID 检查策略。在模型策略里填写 `@vmodel/...` 或 `lyrouter/auto` 不起作用。
- **`GET /v1/models` 按 Key 列出**：返回工作空间已开通、且这把 Key 的模型策略允许的模型 ID，所以同一工作空间的不同 Key 可能得到不同的列表。`@vmodel/<名称>` 和 `lyrouter/auto` 总会列出，调用时再按实际模型检查。
- **日志中的标记**：在[请求日志](https://platform.lyrouter.com/ai_gateway/docs/logs)的「状态说明」列，模型策略拦截显示为「模型访问被拒绝」。各类 403 的处理方法见[401 / 403：鉴权与权限](https://platform.lyrouter.com/ai_gateway/docs/auth-errors)。

## 验证授权

用目标成员自己创建的 Key 调用 `GET /v1/models`，确认列表符合预期；再分别调用一个允许的模型和一个被禁止的模型，确认前者成功、后者返回 403 `guardrail_model`。环境变量的设置见[完成第一次模型调用](https://platform.lyrouter.com/ai_gateway/docs/quickstart)：

```bash
curl "$LYROUTER_BASE_URL/v1/models" \
  -H "Authorization: Bearer $LYROUTER_API_KEY"
```

## 常见问题

### 模型在模型广场能看到，为什么 Key 调用返回 403？

**答：** 先看 `error.code`。`model_not_available` 表示 Key 所属工作空间没有开通这个模型或服务商：确认模型在「专属可用模型」中，并确认 Key 属于这个工作空间。`guardrail_model` 表示模型策略禁止了这把 Key，请账号管理员在安全围栏的「模型访问控制」中检查对 Key、创建人及其主部门生效的策略。

### 修改客户端里的模型名称能绕过限制吗？

**答：** 不能。网关只认模型 ID，策略也按实际选中的模型检查。请把 `model` 写成模型广场卡片上复制的模型 ID，不要使用展示名称。

### 成员申请开通后多久能用？

**答：** 申请只是通知账号管理员。在模型广场开通模型或服务商、或调整模型策略并保存后，几秒内生效，成员无需更换 API Key，重新调用即可。