sagemaker-mlflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Connect to SageMaker MLflow

连接至SageMaker MLflow

Establishes the connection to SageMaker Managed MLflow (the

sagemaker-mlflow

plugin + an ARN tracking URI + AWS credentials), then hands off to the requested MLflow skill (instrumenting-with-mlflow-tracing, agent-evaluation, retrieving-mlflow-traces, querying-mlflow-metrics, etc.), which inherit the connection via

MLFLOW_TRACKING_URI

Requires Python >= 3.10 (mlflow >= 3.8). Validate and report the fix — never auto-install the plugin or acquire credentials (mirrors the repo's Databricks pattern).

建立与SageMaker托管式MLflow的连接（通过

sagemaker-mlflow

插件 + ARN追踪URI + AWS凭证），然后切换至请求的MLflow技能（如instrumenting-with-mlflow-tracing、agent-evaluation、retrieving-mlflow-traces、querying-mlflow-metrics等），这些技能将通过

MLFLOW_TRACKING_URI

继承该连接。

要求Python >= 3.10（对应mlflow >= 3.8）。需验证并告知修复方案——切勿自动安装插件或获取凭证（遵循仓库的Databricks模式）。

Step 1: Preconditions

步骤1：前置条件

```
python --version
```
-> must be 3.10+. If older, STOP and tell the user.
Confirm AWS credentials resolve (env vars,
```
aws configure
```
/ SSO, or an IAM role). If they error (ExpiredToken / no creds), STOP and ask the user to configure them. (
```
scripts/verify_connection.py
```
also checks this, via boto3.)

```
python --version
```
-> 版本必须为3.10+。若版本过低，需停止操作并告知用户。
确认AWS凭证可正常解析（通过环境变量、
```
aws configure
```
/SSO或IAM角色）。若出现错误（如ExpiredToken/无凭证），需停止操作并要求用户配置凭证。（
```
scripts/verify_connection.py
```
也会通过boto3检查此项。）

Step 2: Install the plugin

步骤2：安装插件

bash

pip install sagemaker-mlflow

Required even if

MLFLOW_TRACKING_URI

is already an ARN — without it,

mlflow.set_tracking_uri()

fails with

UnsupportedModelRegistryStoreURIException

bash

pip install sagemaker-mlflow

即使

MLFLOW_TRACKING_URI

已设置为ARN，仍需安装该插件——否则

mlflow.set_tracking_uri()

会抛出

UnsupportedModelRegistryStoreURIException

错误。

Step 3: Select the resource ARN

步骤3：选择资源ARN

If the user already provided an ARN (or
```
MLFLOW_TRACKING_URI
```
is set to
```
arn:aws:sagemaker:...
```
), use it as-is.
Otherwise, discover it in the user's region:
bash
```
python scripts/discover_arns.py
```
If exactly one is returned, use it; if several, list name/status/ARN and ask the user which to use. Both
```
mlflow-app
```
and
```
mlflow-tracking-server
```
ARNs work; the ARN is also shown on the resource's detail page in the SageMaker Studio console.

Then export it (the ARN is region-bound — a cross-region ARN will not authenticate):

bash

export MLFLOW_TRACKING_URI="<arn>"    # mlflow-app/<id> or mlflow-tracking-server/<name>
export AWS_DEFAULT_REGION="<region>"  # AWS credentials resolved via the default chain (SigV4)

若用户已提供ARN（或
```
MLFLOW_TRACKING_URI
```
已设置为
```
arn:aws:sagemaker:...
```
），直接使用该ARN。
否则，在用户所在区域发现ARN：
bash
```
python scripts/discover_arns.py
```
若仅返回一个ARN，则直接使用；若返回多个，则列出名称/状态/ARN并询问用户选择哪一个。
```
mlflow-app
```
和
```
mlflow-tracking-server
```
类型的ARN均可使用；ARN也可在SageMaker Studio控制台的资源详情页中查看。

随后导出相关变量（ARN与区域绑定——跨区域ARN无法通过身份验证）：

bash

export MLFLOW_TRACKING_URI="<arn>"    # mlflow-app/<id> 或 mlflow-tracking-server/<name>
export AWS_DEFAULT_REGION="<region>"  # AWS凭证通过默认链解析（SigV4）

Step 4: Verify

步骤4：验证连接

bash

python scripts/verify_connection.py "$MLFLOW_TRACKING_URI"

Checks all three prerequisites (plugin / credentials / ARN connectivity) and exits non-zero with a remediation hint on the first failure. Do not proceed until it passes.

After the connection verifies, hand off to the requested MLflow skill — it inherits the connected environment via

MLFLOW_TRACKING_URI

bash

python scripts/verify_connection.py "$MLFLOW_TRACKING_URI"

检查所有三项前置条件（插件/凭证/ARN连通性），若首次检查失败则返回非零状态码并给出修复提示。需等待验证通过后再继续操作。

连接验证通过后，切换至请求的MLflow技能——该技能将通过

MLFLOW_TRACKING_URI

继承已连接的环境。

Troubleshooting

故障排除

UnsupportedModelRegistryStoreURIException

— the

sagemaker-mlflow

plugin is not installed;

pip install sagemaker-mlflow

, then re-run

scripts/verify_connection.py

```
AccessDenied
```
/
```
403
```
— credentials are missing/expired, or the principal lacks MLflow permissions on the ARN. Check that credentials resolve, grant
```
sagemaker-mlflow
```
/
```
sagemaker
```
permissions, and confirm the ARN region matches
```
AWS_DEFAULT_REGION
```
.

UnsupportedModelRegistryStoreURIException

：未安装

sagemaker-mlflow

插件；执行

pip install sagemaker-mlflow

，然后重新运行

scripts/verify_connection.py

。

```
AccessDenied
```
/
```
403
```
：凭证缺失/过期，或主体缺少该ARN对应的MLflow权限。检查凭证是否可正常解析，授予
```
sagemaker-mlflow
```
/
```
sagemaker
```
权限，并确认ARN区域与
```
AWS_DEFAULT_REGION
```
匹配。