OpenAI Terraform 模型、工具与数据控制

本文将模型、托管工具和数据保留控制应用于已有项目。这些控制决定项目工作负载可以使用哪些能力，以及适用哪种已经批准的数据保留策略；它们不会授予用户或服务账户访问项目的权限。

完成主要流程后，你将得到一套可重复使用的配置，用于：

• 将项目限制为只能使用经过批准的一组模型。
• 为每种受支持的托管工具明确设置权限。
• 将组织的默认数据保留策略应用于项目。

开始之前

完成 Terraform 提供程序配置，并将管理 API 密钥导出为 OPENAI_ADMIN_KEY。此外还需要：

• 一个已有项目的 ID。
• 组织可用模型的 ID。
• 如果计划管理项目的数据保留设置，组织必须已启用数据保留控制。

评估此流程时使用测试项目。若要对单个项目禁用某项托管工具，组织级工具策略必须已经将该工具限制为仅允许选定项目使用。如果组织对所有项目启用了该工具，单个项目无法将它禁用。

限制模型访问

openai_project_model_permissions 为单个项目应用模型允许列表或拒绝列表。以下示例仅允许使用 gpt-5.4-mini：

来源示例 1（terraform）：

## [中文] 声明项目模型允许列表；示例仅列出gpt-5.4-mini，实际模型必须对组织可见，deny_list的含义不同。
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 都必须对组织可见，包括添加到策略中的微调模型快照。Terraform 会在下一次生成并应用计划时，使模式和模型列表与配置一致。

配置托管工具

openai_project_hosted_tool_permissions 管理五项项目级工具权限。应设置每个字段，让经过检查的配置完整描述策略：

来源示例 2（terraform）：

## [中文] 明确配置五种托管工具权限；false要求组织工具策略允许按选定项目控制，不能覆盖组织对全部项目启用的策略。
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 服务器和代码解释器（Code Interpreter）。组织的每项托管工具策略都有三种模式：允许所有项目、拒绝所有项目、允许选定项目。字段设置为 true 时，允许该项目使用相应工具，但仍须满足组织其他资格和数据保留要求。设置为 false 会将该项目从工具的选定项目策略中移除。如果组织当前允许所有项目使用该工具，设置为 false 会失败。因此，应先将组织的工具策略改为允许选定项目，再对单个项目禁用工具。

Terraform 会从 OpenAI 刷新全部五个值，并在下一次计划中将控制台变更报告为漂移。

配置数据保留

openai_project_data_retention 为单个项目应用经过批准的数据保留类型。除非项目获得了覆盖组织策略的批准，否则应继承组织当前策略：

来源示例 3（terraform）：

## [中文] 声明项目继承组织默认数据保留策略；不代表组织自动获得任何数据保留计划资格。
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：

来源示例 4（terraform）：

## [中文] 声明组织已有的零数据保留设置由Terraform管理；这会修改组织设置，不是申请开通零数据保留。
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 之外的变更

生成计划，刷新远程状态并与已经检查过的配置比较：

来源示例 5（bash）：

## [中文] 只生成刷新后的差异计划；先调查控制台或其他自动化造成的漂移，再决定是否应用。
terraform plan -detailed-exitcode

退出码 0 表示没有变更，2 表示计划包含变更，1 表示 Terraform 遇到错误。应用前调查意外变更，不要在尚未理解紧急管理变更用途时自动将其覆盖。

运行完整示例

以下示例同时管理三类项目控制。创建 main.tf：

来源示例 6（terraform）：

## [中文] 完整声明模型列表、五种托管工具及项目数据保留控制；变量校验限制策略枚举，输出项用于核对生效对象与模式。
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、托管工具策略和经过批准的数据保留类型：

来源示例 7（terraform）：

## [中文] 填写已有项目、模型与三类控制输入；示例将所有工具设为true，修改为false前须检查对应组织策略。
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，然后检查并应用保存的计划：

来源示例 8（bash）：

## [中文] 初始化、格式化和检查配置，保存并显示计划，最后应用该计划；最后一步会写入远程项目设置。
terraform init
terraform fmt
terraform validate
terraform plan -out=tfplan
terraform show tfplan
terraform apply tfplan

第一个计划应包含三个待新增资源。对于托管工具和数据保留控制，“新增”表示 Terraform 开始管理项目已有的单例设置，并不创建独立的远程对象。模型权限则会创建或更新项目的模型权限配置。

再次运行 terraform plan，确认配置不会产生后续变更。如果出现漂移，应先确认其他管理员或自动化流程是否修改了项目控制，再应用下一次更新。