如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

使用 Terraform 管理模型、工具與資料保留設定

設定專案的模型存取權、託管工具權限與資料保留政策。

本指南說明如何為現有專案設定模型權限、託管工具權限與資料保留政策。這些設定決定專案中的工作負載可以使用哪些模型與工具,以及專案適用哪一項已核准的保留政策。這些設定不會授予使用者或服務帳戶專案存取權。

完成主要流程後,你就能重複使用同一份組態來達成下列目的:

  • 限制專案只能使用已核准的模型。
  • 明確設定每項受支援託管工具的權限。
  • 將組織的預設資料保留政策套用至專案。

開始之前

完成 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,確認組態不會產生其他變更。如果計畫顯示組態漂移,請先查明是否有其他管理員或自動化程序變更了專案設定,再套用下一次更新。