如何用 Terraform 配置 Microsoft Foundry 的 Content Understanding？
结论
可以通过 Terraform 完成，分为模型部署和默认模型配置两步：
- 使用
azurerm_cognitive_deployment，或通过 AzAPI 使用Microsoft.CognitiveServices/accounts/deploymentsARM 资源部署模型。 - 调用 Content Understanding 的
PATCH /contentunderstanding/defaults数据平面 API，将模型名称和分析器别名映射到实际部署名称。
Foundry 资源和模型部署已有 Terraform 支持。默认模型映射可以用 terraform_data 配合 local-exec 调用 REST API，放在同一次部署流程中完成。Foundry Terraform 文档、默认配置 API
为什么找不到对应的资源类型
Content Understanding 通过以下服务端点配置默认模型：
PATCH https://<foundry-endpoint>/contentunderstanding/defaults?api-version=2025-11-01这个接口属于数据平面。AzAPI 的 azapi_resource、azapi_update_resource 和 azapi_resource_action 面向 ARM 控制平面，不能直接调用这个服务端点。
AzAPI 提供的 azapi_data_plane_resource 只支持已登记的数据平面资源类型。当前公开支持列表中没有 Content Understanding defaults，因此自行拼写一个 type 也无法使用。AzAPI 数据平面说明、支持的资源类型
一、准备 Foundry 资源和执行权限
以下示例假设已有 Microsoft Foundry 资源，模型也部署在同一个资源下。执行前需要准备：
- Foundry 资源的 ARM ID。
- Content Understanding 使用的资源级服务端点，例如
https://<resource-name>.services.ai.azure.com。 - 能创建模型部署的 Terraform 执行身份。
- 已登录的 Azure CLI，以及 Bash、cURL。
示例通过 Microsoft Entra ID 调用 defaults API。运行 Azure CLI 的身份需要具备目标 Foundry 资源的数据平面权限。官方 SDK 示例要求授予 Cognitive Services User 角色，即使该身份已经是资源 Owner，也需要检查这项授权。local-exec 使用本机或 CI 中的 Azure CLI 登录状态，不会自动继承 Terraform provider 的认证配置。官方 SDK 配置示例
二、用 Terraform 部署模型
示例使用 gpt-4.1、gpt-4.1-mini 和 text-embedding-3-large。这三个模型都在官方支持列表中，实际能否部署还取决于区域、模型生命周期、订阅配额和部署类型。部署前应核对目标分析器支持的模型，这组示例并非所有场景的固定要求。Content Understanding 支持的模型
terraform {
required_version = ">= 1.4.0"
required_providers {
azurerm = {
source = "hashicorp/azurerm"
version = "~> 4.0"
}
}
}
variable "subscription_id" {
type = string
}
variable "foundry_account_id" {
type = string
}
variable "content_understanding_endpoint" {
type = string
}
provider "azurerm" {
features {}
subscription_id = var.subscription_id
}
locals {
models = {
"gpt-4.1" = {
deployment_name = "cu-gpt41"
version = "2025-04-14"
}
"gpt-4.1-mini" = {
deployment_name = "cu-gpt41-mini"
version = "2025-04-14"
}
"text-embedding-3-large" = {
deployment_name = "cu-embedding"
version = null
}
}
}
resource "azurerm_cognitive_deployment" "models" {
for_each = local.models
name = each.value.deployment_name
cognitive_account_id = var.foundry_account_id
model {
format = "OpenAI"
name = each.key
version = each.value.version
}
sku {
name = "GlobalStandard"
capacity = 1
}
}GlobalStandard 和 capacity = 1 是示例值，需要根据模型可用性和配额调整。version = null 表示不指定版本，由服务选择当时的默认版本。如果需要固定版本，应填写目标资源实际支持的版本。azurerm_cognitive_deployment 参数说明
如果 Foundry 资源由当前 Terraform 配置创建，将 var.foundry_account_id 换成相应资源的 .id 引用即可。
三、设置 Content Understanding 默认模型映射
模型部署完成后，需要配置 Content Understanding 使用的部署。映射中的键是模型名称或分析器别名，值是实际部署名称，例如：
{
"modelDeployments": {
"gpt-4.1": "cu-gpt41",
"gpt-4.1-mini": "cu-gpt41-mini",
"text-embedding-3-large": "cu-embedding",
"prebuilt-analyzer-completion": "cu-gpt41",
"prebuilt-analyzer-completion-mini": "cu-gpt41-mini",
"prebuilt-analyzer-embedding": "cu-embedding"
}
}预置分析器会引用 prebuilt-analyzer-* 别名，配置时应包含这些映射。模型名和部署名可以不同，例如 gpt-4.1 可以对应名为 cu-gpt41 的部署。模型映射规则
在前面的 Terraform 代码后追加以下配置：
locals {
cu_api_version = "2025-11-01"
cu_defaults = {
modelDeployments = merge(
{
for model_name, deployment in azurerm_cognitive_deployment.models :
model_name => deployment.name
},
{
"prebuilt-analyzer-completion" = (
azurerm_cognitive_deployment.models["gpt-4.1"].name
)
"prebuilt-analyzer-completion-mini" = (
azurerm_cognitive_deployment.models["gpt-4.1-mini"].name
)
"prebuilt-analyzer-embedding" = (
azurerm_cognitive_deployment.models["text-embedding-3-large"].name
)
}
)
}
cu_defaults_json = jsonencode(local.cu_defaults)
}
resource "terraform_data" "content_understanding_defaults" {
triggers_replace = [
var.foundry_account_id,
var.content_understanding_endpoint,
local.cu_api_version,
local.cu_defaults_json
]
depends_on = [azurerm_cognitive_deployment.models]
provisioner "local-exec" {
interpreter = ["/bin/bash", "-c"]
environment = {
CU_ENDPOINT = trimsuffix(var.content_understanding_endpoint, "/")
CU_API_VERSION = local.cu_api_version
CU_DEFAULTS = local.cu_defaults_json
}
command = <<-EOT
set -euo pipefail
cu_access_token="$(az account get-access-token \
--resource https://cognitiveservices.azure.com \
--query accessToken \
--output tsv)"
curl --fail-with-body --silent --show-error \
--request PATCH \
"$CU_ENDPOINT/contentunderstanding/defaults?api-version=$CU_API_VERSION" \
--header "Authorization: Bearer $cu_access_token" \
--header "Content-Type: application/merge-patch+json" \
--data-binary "$CU_DEFAULTS"
EOT
}
}示例使用 GA API 版本 2025-11-01。Content-Type 和令牌作用域均按 defaults API 定义设置，令牌面向 Cognitive Services，而非 ARM。Update Defaults API
端点、API 版本或映射变化时，triggers_replace 会触发重新配置；depends_on 确保调用在模型部署完成后执行。没有专用资源可用时，可以用 terraform_data 承载这类 provisioner 操作。terraform_data 文档
四、执行并验证
在 terraform.tfvars 中填写实际值：
subscription_id = "<subscription-id>"
foundry_account_id = "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<foundry-name>"
content_understanding_endpoint = "https://<foundry-name>.services.ai.azure.com"确认 Azure CLI 已登录目标租户，然后执行：
terraform init
terraform plan
terraform apply完成后读取默认配置，检查返回的部署名称：
CU_ENDPOINT="https://<foundry-name>.services.ai.azure.com"
az rest \
--method GET \
--resource https://cognitiveservices.azure.com \
--url "$CU_ENDPOINT/contentunderstanding/defaults?api-version=2025-11-01"读取接口为 GET /contentunderstanding/defaults。确认返回结果正确后，再用实际需要的分析器提交一次分析请求，验证模型兼容性和调用权限。Get Defaults API
注意事项
- 默认模型取决于分析器。可以通过
GET /contentunderstanding/analyzers/{analyzerId}?api-version=2025-11-01查看其models和supportedModels。调整模型时，应同时修改部署和映射。分析器模型选择说明 local-exec不具备专用 Terraform 资源的完整状态管理能力。它不会在每次plan时读取远端 defaults，因此控制台中的修改不会自动显示为漂移。删除这个terraform_data资源也不会清除远端映射。- defaults API 使用合并补丁。上述代码会更新提交的映射，但从 Terraform 配置中删掉一个键，不会删除服务端已有的键。迁移模型时，需要检查是否残留旧映射。Update Defaults API
- 新授予的角色可能需要等待生效。如果模型部署成功，但 defaults 调用失败，应先检查执行身份、令牌作用域和资源端点。端点应来自目标 Foundry 资源，避免误用带有项目路径的 URL。
- 如果 CI 不适合运行 provisioner，可以在
terraform apply成功后增加一个独立步骤，执行同样的 REST 请求。如果需要 Terraform 持续读取、比较并管理 defaults，应使用明确支持该 API 的 provider 实现。
备注：内容仅供参考。