如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

使用 Terraform 管理模型、工具和数据保留设置

配置项目的模型访问权限、托管工具权限和数据保留设置。

按照本指南,您可以为现有项目配置模型权限、托管工具权限和数据保留设置。这些设置决定项目中的工作负载可以使用哪些模型和工具,以及项目适用哪项已获批准的数据保留政策。它们不会授予用户或服务账号访问项目的权限。

完成主要步骤后,您将得到一份可重复使用的配置,用于:

  • 将项目可使用的模型限制在已获批准的范围内。
  • 为每个受支持的托管工具明确设置权限。
  • 将组织的默认数据保留政策应用于项目。

开始之前

完成 Terraform 提供程序设置,并将管理员 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 刷新这五个字段的值。如果有人在控制面板中更改了设置,Terraform 会在下次生成计划时将这些差异报告为配置漂移。

配置数据保留设置

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,确认配置不会产生进一步的更改。如果计划显示配置漂移,请先查明是否有其他管理员或自动化流程更改了项目设置,再应用下一次更新。