角色型存取控制 (RBAC) 可讓你決定組織和各專案中的使用者能透過 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.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 金鑰發出請求時,系統會檢查指派給 API 金鑰的權限,並確認使用者至少有一個專案角色授予這些權限。例如,要向 /v1/models 發出請求,API 金鑰必須獲授 api.model.read 權限,使用者也必須擁有包含 api.model.read 權限的專案角色。
最佳做法
- 依組織架構建立群組:在 IdP 中依團隊建立群組,並以群組為單位指派角色,無須逐一指派給成員。
- 區分職責:將讀取模型、上傳檔案和管理金鑰分為不同職責。
- 劃分專案範圍:為實驗、預備環境和正式環境分別建立專案。
- 定期檢查:移除未使用的角色和金鑰,並定期輪替敏感金鑰。
- 以非擁有者身分測試:在全面推行前,確認存取權符合預期。