AWS SageMaker创建HyperparameterTuner作业代入角色ARN校验失败

开发者阿泽

2026-9-1

问题描述

在SageMaker中创建HyperparameterTuner超参数调优作业时，当前环境仅支持使用assumed role（代入角色），所用角色的ARN格式如下：
arn:aws:sts::123456789012:assumed-role/ROLE_NAME/email@company.com

参照官方教程流程创建作业时触发校验报错，复现代码如下：

# 非完整代码片段
>>> tuner = HyperparameterTuner(
    xgb, objective_metric_name, hyperparameter_ranges, max_jobs=20, max_parallel_jobs=3
)
>>> tuner.fit()

报错信息如下：

ClientError: An error occurred (ValidationException) when calling the CreateHyperParameterTuningJob 
operation: 1 validation error detected: Value 
'arn:aws:sts::123456789012:assumed-role/ROLE_NAME/email@company.com' at 
'trainingJobDefinition.roleArn' failed to satisfy constraint: Member must satisfy regular expression 
pattern: ^arn:aws[a-z\-]*:iam::\d{12}:role/?[a-zA-Z_0-9+=,.@\-_/]+$

报错提示trainingJobDefinition.roleArn字段取值必须满足指定正则规则，即使用iam::12位账号ID:role/前缀的IAM角色ARN，但当前使用的代入角色ARN为sts::12位账号ID:assumed-role/前缀格式，无法通过校验，需要确认是否可通过格式调整让HyperparameterTuner正常识别代入角色，或是SageMaker服务本身不兼容代入角色的使用。

问题原因

这不是SageMaker不支持代入角色，是传参时用错了ARN类型，靠硬改字符串凑正则是没用的，两类ARN的本质用途完全不同：

你拿到的arn:aws:sts::xxx:assumed-role/ROLE_NAME/xxx是STS签发的临时角色会话凭证标识，只代表你当前操作时用的临时身份，本身不是可被服务引用的IAM角色实体
SageMaker调优、训练、部署这类作业要求传入的roleArn，是IAM中存在的实体角色ARN，固定为arn:aws:iam::账号ID:role/角色名格式。SageMaker拿到这个实体角色ARN后，会自己向STS申请该角色的临时权限来运行作业，不接受直接传入已经生成好的临时会话ARN。

解决方法

不用做特殊适配，只要从你当前的临时会话ARN里提取出底层的实体角色ARN，显式传给SageMaker即可，转换规则非常固定：

把ARN开头的arn:aws:sts::替换为arn:aws:iam::
把路径段的assumed-role/替换为role/
删掉最后一段的会话名称后缀（也就是示例里的/email@company.com部分）

以给出的ARN为例，转换后可用的实体角色ARN为：
arn:aws:iam::123456789012:role/ROLE_NAME

不要直接用SageMaker SDK的sagemaker.get_execution_role()自动获取角色——这个方法在使用assumed role的环境里，经常会直接把当前临时会话的STS ARN读出来，就会触发你遇到的格式校验错误。手动把转换好的实体角色ARN传给Estimator即可，示例代码如下：

import sagemaker
from sagemaker.tuner import HyperparameterTuner

# 显式指定转换后的实体角色ARN
valid_role = "arn:aws:iam::123456789012:role/ROLE_NAME"

# 初始化XGBoost训练容器时传入正确角色
xgb = sagemaker.estimator.Estimator(
    image_uri=sagemaker.image_uris.retrieve("xgboost", sagemaker.Session().boto_region_name, "1.5-1"),
    role=valid_role,
    instance_count=1,
    instance_type="ml.m5.xlarge",
    output_path="s3://your-bucket/path/to/output"
)

# 后续调优作业初始化、启动流程和官方教程完全一致
tuner = HyperparameterTuner(
    xgb, objective_metric_name, hyperparameter_ranges, max_jobs=20, max_parallel_jobs=3
)
tuner.fit()

注意：确保你当前使用的临时角色会话拥有iam:PassRole权限，有权将上述实体角色传递给SageMaker服务，否则格式校验通过后仍会触发权限报错。

内容的提问来源于stack exchange，提问作者Desi Pilla