本指南說明如何為現有專案設定模型權限、託管工具權限與資料保留政策。這些設定決定專案中的工作負載可以使用哪些模型與工具,以及專案適用哪一項已核准的保留政策。這些設定不會授予使用者或服務帳戶專案存取權。
完成主要流程後,你就能重複使用同一份組態來達成下列目的:
- 限制專案只能使用已核准的模型。
- 明確設定每項受支援託管工具的權限。
- 將組織的預設資料保留政策套用至專案。
開始之前
完成 Terraform 提供者設定,並將 Admin API 金鑰匯出為環境變數 OPENAI_ADMIN_KEY。你還需要:
- 現有專案的 ID。
- 組織可用的模型 ID。
- 如果打算管理專案的資料保留設定,組織必須已啟用資料保留控制功能。
請使用測試專案評估此流程。若要為單一專案停用某項託管工具,組織層級的工具政策必須已將該工具的使用範圍限於指定專案。如果組織已為所有專案啟用該工具,個別專案就無法停用它。
限制模型存取權
openai_project_model_permissions 可為單一專案設定模型允許清單或拒絕清單。以下範例只允許使用 gpt-5.4-mini:
resource "openai_project_model_permissions" "application" {
project_id = "proj_123"
mode = "allow_list"
model_ids = ["gpt-5.4-mini"]
}
將 mode 設為下列其中一個值:
allow_list:只允許使用model_ids列出的模型。deny_list:允許使用所有可用模型,但排除model_ids列出的模型。
組織必須能看見清單中的每個模型 ID,包括你加入政策的任何微調模型快照 ID。下次產生計畫時,Terraform 會列出模式與模型清單的變更,並在套用計畫時更新設定。
設定託管工具
openai_project_hosted_tool_permissions 可管理五項專案層級的工具權限。請設定所有欄位,讓審查組態的人能看到完整政策:
resource "openai_project_hosted_tool_permissions" "application" {
project_id = "proj_123"
file_search_enabled = true
web_search_enabled = false
image_generation_enabled = false
mcp_enabled = false
code_interpreter_enabled = true
}
這些欄位分別控制檔案搜尋、網頁搜尋、圖像生成、遠端 MCP 伺服器與程式碼解譯器。組織的託管工具政策有三種模式:允許所有專案使用、禁止所有專案使用,或僅允許指定專案使用。將欄位設為 true 即可允許該專案使用對應的工具,但專案仍須符合組織的其他資格與資料保留要求。將欄位設為 false 會將該專案從工具政策允許的指定專案清單中移除。如果組織目前允許所有專案使用該工具,將欄位設為 false 就會失敗。若要為個別專案停用工具,請先將組織的工具政策改為僅允許指定專案使用。
下次產生計畫時,Terraform 會從 OpenAI 重新讀取這五個欄位的值,並將透過儀表板所做的變更列為組態漂移。
設定資料保留政策
openai_project_data_retention 可將已核准的資料保留類型套用至單一專案。除非專案已獲准覆寫組織政策,否則請讓專案繼承組織目前的政策:
resource "openai_project_data_retention" "application" {
project_id = "proj_123"
type = "organization_default"
}
提供者也接受 none、zero_data_retention、modified_abuse_monitoring、enhanced_zero_data_retention 和 enhanced_modified_abuse_monitoring。可用的模式以及模式之間允許的切換方式,取決於組織的設定與專案的資料駐留區域。
選擇專案層級的覆寫設定前,請先閱讀你的資料以及組織與 OpenAI 簽訂的協議。
管理組織的預設政策
只有在現有的組織層級設定由 Terraform 管理時,才使用 openai_organization_data_retention:
resource "openai_organization_data_retention" "default" {
type = "zero_data_retention"
}
這項資源可變更組織現有的設定,無法用來申請加入資料保留方案。部分保留層級之間的切換需要支援團隊協助,另有一些層級之間無法切換。
從組態中移除 openai_project_hosted_tool_permissions 或 openai_project_data_retention 時,Terraform 只會從狀態中移除該資源,遠端設定會維持原樣。移除 openai_project_model_permissions 則會刪除專案的模型權限設定。審查銷毀計畫時,請留意這些差異。
偵測在 Terraform 以外所做的變更
執行下列指令產生計畫,以重新讀取遠端狀態,並與已審查的組態比較:
terraform plan -detailed-exitcode
結束代碼 0 表示沒有變更,2 表示計畫包含變更,1 表示 Terraform 遇到錯誤。若發現非預期的變更,請先查明原因再套用計畫。如果管理員因應緊急情況調整了設定,請勿在釐清用途前自動覆寫這項變更。
執行完整範例
以下範例會一併管理上述三類專案設定。建立 main.tf:
terraform {
required_version = ">= 1.0"
required_providers {
openai = {
source = "openai/openai"
version = ">= 1.0.0"
}
}
}
provider "openai" {}
variable "project_id" {
type = string
description = "ID of the existing OpenAI project."
}
variable "model_permission_mode" {
type = string
description = "Whether model_ids is an allowlist or denylist."
default = "allow_list"
validation {
condition = contains(["allow_list", "deny_list"], var.model_permission_mode)
error_message = "The model permission mode must be allow_list or deny_list."
}
}
variable "model_ids" {
type = list(string)
description = "Model IDs included in the project model policy."
}
variable "hosted_tools" {
type = object({
file_search = bool
web_search = bool
image_generation = bool
mcp = bool
code_interpreter = bool
})
description = "Hosted tools enabled for the project."
}
variable "project_data_retention_type" {
type = string
description = "Approved data-retention type for the project."
validation {
condition = contains([
"organization_default",
"none",
"zero_data_retention",
"modified_abuse_monitoring",
"enhanced_zero_data_retention",
"enhanced_modified_abuse_monitoring",
], var.project_data_retention_type)
error_message = "Provide a supported project data-retention type."
}
}
resource "openai_project_model_permissions" "application" {
project_id = var.project_id
mode = var.model_permission_mode
model_ids = var.model_ids
}
resource "openai_project_hosted_tool_permissions" "application" {
project_id = var.project_id
file_search_enabled = var.hosted_tools.file_search
web_search_enabled = var.hosted_tools.web_search
image_generation_enabled = var.hosted_tools.image_generation
mcp_enabled = var.hosted_tools.mcp
code_interpreter_enabled = var.hosted_tools.code_interpreter
}
resource "openai_project_data_retention" "application" {
project_id = var.project_id
type = var.project_data_retention_type
}
output "controlled_project_id" {
value = var.project_id
}
output "model_permission_mode" {
value = openai_project_model_permissions.application.mode
}
output "project_data_retention_type" {
value = openai_project_data_retention.application.type
}
建立 terraform.tfvars,填入現有專案的 ID、組織可見的模型 ID、託管工具政策,以及已核准的資料保留類型:
project_id = "proj_123"
model_permission_mode = "allow_list"
model_ids = ["gpt-5.4-mini"]
hosted_tools = {
file_search = true
web_search = true
image_generation = true
mcp = true
code_interpreter = true
}
project_data_retention_type = "organization_default"
這個範例會啟用所有託管工具,因此即使組織政策已為所有專案啟用這些工具,也能執行範例。只有在對應的組織層級政策已改為僅允許指定專案使用該工具後,才可將欄位值改為 false。套用計畫前,請確認組織可以使用指定的模型 ID 與資料保留類型。
初始化 Terraform,然後審查並套用已儲存的計畫:
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan
第一次產生的計畫應會列出三項待新增的資源。託管工具權限與資料保留政策在每個專案中各有一份設定。對這兩項資源而言,新增表示 Terraform 開始管理專案現有的設定,不會另外建立遠端物件。模型權限資源則會建立或更新專案的模型權限設定。
再次執行 terraform plan,確認組態不會產生其他變更。如果計畫顯示組態漂移,請先查明是否有其他管理員或自動化程序變更了專案設定,再套用下一次更新。