通过基于角色的访问控制 (RBAC),您可以决定哪些用户能通过 API 或控制台在组织和项目中执行哪些操作。API 和控制台使用同一套权限:如果用户可以调用某个端点(例如 /v1/chat/completions),就可以使用控制台中对应的页面。如果用户缺少所需权限,相应的界面控件(例如 Playground 中的上传按钮)就会被禁用。使用 RBAC,您可以:
- 对用户分组并批量分配权限
- 创建自定义角色,按需精确配置权限
- 在组织或项目级别限定访问范围
- 在控制台和 API 中实施一致的权限控制
核心概念
- 组织:您的顶级账号。组织角色可以授予对组织内所有项目的访问权限。
- 项目:存放密钥、文件和其他资源的工作空间。项目角色授予的权限仅在该项目内有效。
- 群组:由用户组成,您可以为整个群组分配角色。您可以通过 SCIM 从身份提供商同步群组,让成员名单自动保持最新。
- 角色:一组权限,例如向模型发起请求或写入文件。您可以在组织设置中创建组织角色,也可以在特定项目的设置中创建项目角色。创建后,您可以将组织角色或项目角色分配给用户或群组。用户可以拥有多个角色,其访问权限是这些角色所授予权限的并集。
- 权限:角色允许执行的具体操作,例如向模型发起请求、读取文件、写入文件或管理密钥。
权限
下表列出了可用权限、各预设角色包含的权限,以及哪些权限可用于自定义角色。
| 权限类别 | 允许的操作 | 组织所有者权限 | 组织读取者权限 | 项目所有者权限 | 项目成员权限 | 项目查看者权限 | 可用于自定义角色 |
|---|---|---|---|---|---|---|---|
| 列出模型 | 列出组织可访问的模型 | Read |
Read |
Read |
Read |
Read |
✓ |
| 群组 | 查看和管理群组 | Read、Write |
Read |
Read、Write |
Read、Write |
Read |
|
| 角色 | 查看和管理角色 | Read、Write |
Read |
Read、Write |
Read、Write |
Read |
|
| 组织管理 | 管理组织的用户、项目、邀请、管理员 API 密钥和速率限制 | Read、Write |
|||||
| 用量 | 查看用量面板并导出用量数据 | Read |
✓ | ||||
| 外部密钥 | 查看和管理企业密钥管理功能使用的密钥 | Read、Write |
|||||
| IP 允许列表 | 查看和管理 IP 允许列表 | Read、Write |
|||||
| mTLS | 查看和管理双向 TLS 设置 | Read、Write |
|||||
| OIDC | 查看和管理 OIDC 配置 | Read、Write |
|||||
| 模型能力 | 向聊天补全、音频、嵌入和图像端点发起请求 | Request |
Request |
Request |
Request |
✓ | |
| 助手 | 创建和检索助手 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
✓ |
| 线程 | 创建和检索线程、消息及运行记录 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
✓ |
| 评测 | 创建、检索和删除评测 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
✓ |
| 微调 | 创建和检索微调任务 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
✓ |
| 文件 | 创建和检索文件 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
✓ |
| 向量存储 | 创建和检索向量存储 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
✓ | |
| Responses API | 创建响应 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
✓ | |
| 提示词 | 创建和检索提示词,供 Responses API 和 Realtime API 用作上下文 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
✓ |
| Webhook | 在项目中创建和查看 Webhook | Read、Write |
Read |
Read、Write |
Read、Write |
Read |
✓ |
| 数据集 | 创建和检索数据集 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
✓ |
| 应用 | 在控制台中创建和管理应用,并提交应用供审核 | Read、Write |
✓ | ||||
| 隧道 | 检查、使用和管理组织级隧道 | Read、Use、Manage |
✓ | ||||
| 项目 API 密钥 | 允许用户管理自己的 API 密钥 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
✓ |
| 项目管理 | 通过管理 API 管理项目用户、服务账号、API 密钥和速率限制 | Read、Write |
Read、Write |
||||
| 批处理 | 创建和管理批处理任务 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
|
| 服务账号 | 查看和管理项目的服务账号 | Read、Write |
Read、Write |
||||
| 音色 | 创建和检索音色 | Read、Write |
Read、Write |
Read、Write |
Read、Write |
Read |
|
| Agent Builder | 在 Agent Builder 中创建和管理智能体及工作流 | Read、Write |
Read |
Read、Write |
Read、Write |
Read |
✓ |
批处理权限包含的额外访问权限
批处理权限包含准备批处理输入文件、执行请求和检索结果所需的访问权限。批处理任务中可以请求哪些端点,则取决于批处理 API 支持的端点范围。有关这些端点的列表,请参阅批处理 API 指南。
| 批处理权限 | 额外授予的访问权限 |
|---|---|
读取(api.batch.read) |
文件读取权限(api.files.read),适用于 /v1/files |
写入(api.batch.write) |
批处理读取权限 列出模型的权限( api.model.read 和 model.read),适用于 /v1/models文件读取和写入权限( api.files.read 和 api.files.write),适用于 /v1/files模型能力请求权限( api.model.request 和 model.request),适用于 /v1/audio、/v1/chat/completions、/v1/embeddings、/v1/images、/v1/moderations、/v1/realtime 和 /v1/responses |
配置 RBAC
角色变更和群组同步最多需要 30 分钟才能完全生效。
-
创建群组 为各团队创建群组,例如数据科学和支持。如果您使用身份提供商(IdP),请启用 SCIM 同步,以便及时更新群组成员名单。
-
创建自定义角色 从角色所需的最小权限开始。例如:
- 模型测试人员:模型读取、模型能力请求、评测
- 模型工程师:模型能力请求、文件读写、微调
- 应用发布人员:应用读取、应用写入
-
分配角色
- 组织级角色适用于整个组织,包括组织内的所有项目。
- 项目级角色仅适用于相应项目。 您可以将角色分配给用户和群组。用户可以拥有多个角色,实际访问权限是各角色所授予权限的并集。
-
验证 使用非所有者账号检查 API 和控制台中的访问权限是否符合预期。如果用户可以看到超出其需要的内容,请调整角色权限。
遵循最小权限原则。先授予完成任务所需的最少权限,再根据实际需要增加权限。
访问权限配置示例
小型团队
- 为核心团队分配组织级角色,授予模型能力请求和文件读写权限。
- 为每个应用创建一个项目。只将承包商加入其参与的项目,并为其分配项目级角色。
较大型组织
- 从 IdP 同步群组,例如研究、支持和财务。
- 根据职能创建自定义角色,并在组织级别分配。如果某个项目需要更严格的控制,则只授予该项目专属的角色。
承包商和供应商
- 创建“承包商”群组,不为该群组分配组织级角色。
- 将群组成员加入特定项目,并分配权限范围较小的项目角色,例如仅授予只读权限。
如何确定用户的访问权限
控制台会合并以下角色:
- 来自组织的角色(直接分配或通过群组获得)
- 来自项目的角色(直接分配或通过群组获得)
用户的实际权限是分配给该用户的所有角色所授予权限的并集。
当用户在项目内使用 API 密钥发起请求时,系统会检查分配给该密钥的权限,并确认用户至少有一个项目角色授予这些权限。例如,请求 /v1/models 时,API 密钥必须具有 api.model.read 权限,用户也必须拥有授予 api.model.read 权限的项目角色。
最佳实践
- 按组织结构划分群组:在 IdP 中按团队建立群组,并按群组统一分配角色,避免逐人分配。
- 分离职责:将读取模型、上传文件和管理密钥划分为不同职责。
- 划清项目边界:为实验、预发布和生产环境分别设立项目。
- 定期审查:移除不再使用的角色和密钥,并轮换敏感密钥。
- 使用非所有者账号测试:在大范围推行前,验证访问权限是否符合预期。