按照本指南,您可以为现有项目配置模型权限、托管工具权限和数据保留设置。这些设置决定项目中的工作负载可以使用哪些模型和工具,以及项目适用哪项已获批准的数据保留政策。它们不会授予用户或服务账号访问项目的权限。
完成主要步骤后,您将得到一份可重复使用的配置,用于:
- 将项目可使用的模型限制在已获批准的范围内。
- 为每个受支持的托管工具明确设置权限。
- 将组织的默认数据保留政策应用于项目。
开始之前
完成 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,确认配置不会产生进一步的更改。如果计划显示配置漂移,请先查明是否有其他管理员或自动化流程更改了项目设置,再应用下一次更新。