MLflow SageMaker 部署指南使用 mlflow.sagemaker 模块将模型部署到 AWS SageMaker【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowmlflow.sagemaker是 MLflow 提供的官方 AWS SageMaker 部署模块负责把已记录logged的 MLflow 模型一键部署为 SageMaker 实时推理端点Endpoint或批量转换任务Batch Transform Job。读完本文你将掌握容器镜像构建推送、三种部署模式create/add/replace的选择、完整参数配置、统一部署客户端SageMakerDeploymentClient与 CLI 用法以及本地模拟服务等实战技能。模块定位与能力总览该模块的完整说明位于 mlflow.sagemaker.rst其核心实现集中在 mlflow/sagemaker/init.py约 3000 行与 mlflow/sagemaker/cli.py另附 Docker 辅助脚本 mlflow/sagemaker/push_image_to_ecr.sh。从源码结构看模块提供以下几类能力能力类别公开 API / CLI 命令说明容器镜像构建与推送mlflow sagemaker build-and-push-container、push_image_to_ecr()将本地 Docker 镜像推送到 AWS ECR实时端点部署deploy()内部_deploy创建/更新 SageMaker 端点统一部署客户端SageMakerDeploymentClient通过mlflow.deployments.get_deploy_client使用支持create/update/delete/list/get/predict/run_local批量推理deploy_transform_job()、terminate_transform_job()mlflow sagemaker deploy-transform-job创建/终止批量转换任务本地模拟服务run_local()在本地以 SageMaker 兼容容器方式服务模型仅推送模型push_model_to_sagemaker()、mlflow sagemaker push-model只创建 SageMaker Model不建端点该模块的部署流程可以概括为下载模型 → 上传 S3 → 创建 SageMaker Model引用 ECR 镜像 S3 模型数据→ 创建 EndpointConfig → 创建/更新 Endpoint每一步都由源码中的私有函数串联下文会逐一展开。前提条件根据源码中的实际调用使用本模块前需要准备AWS 凭证当前活跃 AWS 账户需具备 SageMaker、S3、ECR、IAM、STS 相关权限。部署函数注释明确要求当前活跃的 AWS 账户必须已配置正确的权限见 mlflow/sagemaker/init.py。Python 依赖boto3在函数体内惰性导入、docker命令可用run_local与镜像推送均调用dockerCLI。已记录的 MLflow 模型model_uri支持多种形式本地路径/Users/me/path/to/local/model、relative/path/to/local/model、s3://my_bucket/path/to/model、runs:/run_id/run-relative/path/to/model、models:/model_name/model_version、models:/model_name/stage。可部署的 flavor模型必须包含受支持的部署 flavor。_get_preferred_deployment_flavor()会优先选择python_functionpyfuncflavor若模型中没有任何受支持 flavor 则抛出RESOURCE_DOES_NOT_EXIST异常若显式指定的 flavor 不受支持_validate_deployment_flavor()则抛出INVALID_PARAMETER_VALUE异常。三种部署模式Deployment Modes_deploy()的mode参数决定部署行为源码在 mlflow/sagemaker/init.py 中定义如下三个常量DEPLOYMENT_MODE_CREATE create创建指定名称的新应用。若同名应用已存在则直接失败源码中通过_find_endpoint查重并抛出异常。DEPLOYMENT_MODE_REPLACE replace若同名应用存在用新模型替换其模型若不存在则创建。新模型初始权重为 1旧模型及其配置在archiveFalse时被清理。DEPLOYMENT_MODE_ADD add若同名应用存在将新模型追加到现有端点初始权重为0不承接流量若不存在则创建。之后需要通过 AWS 控制台或 SageMaker 的UpdateEndpointWeightsAndCapacitiesAPI 手动调整流量权重。需要注意_deploy内部还会校验mode必须是上述三者之一否则抛出INVALID_PARAMETER_VALUE另外archiveFalse与synchronousFalse不能同时使用——非同步模式下资源必须被归档保留否则抛出异常提示Either setsynchronousTrueorarchiveTrue。构建并推送服务容器镜像SageMaker 推理需要一个承载 MLflow 模型的 Docker 镜像流程分两步先构建镜像再推送到 ECR。CLI 入口在 mlflow/sagemaker/cli.py# 构建默认镜像mlflow-pyfunc并推送到 ECR mlflow sagemaker build-and-push-container # 自定义镜像名与容器构建网络例如在 SageMaker JupyterLab 中构建时 mlflow sagemaker build-and-push-container --image-name my-image \ --container --network sagemaker底层由push_image_to_ecr(imageDEFAULT_IMAGE_NAME)mlflow/sagemaker/init.py执行其内部逻辑通过 STSget_caller_identity()获取当前账户 IDboto3.session.Session().region_name获取区域缺省us-west-2拼出完整 ECR 地址{account}.dkr.ecr.{region}.amazonaws.com/{image}:{version}version为mlflow.version.VERSION检查 ECR 仓库是否存在不存在则create_repository创建依次执行aws ecr get-login-password→docker login --username AWS --password-stdin registry→docker tag→docker push任一子命令失败即抛出MlflowException。之后_get_default_image_url()会通过 ECRdescribe_repositories自动解析该镜像的 repository URI 并拼接版本号也可以直接用环境变量MLFLOW_SAGEMAKER_DEPLOY_IMG_URL指定镜像 URL见 mlflow/environment_variables.py。部署实时推理端点deploy核心函数是_deploy()完整签名如下源码 mlflow/sagemaker/init.py_deploy( app_name, model_uri, execution_role_arnNone, assume_role_arnNone, bucketNone, image_urlNone, region_nameus-west-2, modeDEPLOYMENT_MODE_CREATE, archiveFalse, instance_typeDEFAULT_SAGEMAKER_INSTANCE_TYPE, # ml.m4.xlarge instance_countDEFAULT_SAGEMAKER_INSTANCE_COUNT, # 1 vpc_configNone, flavorNone, synchronousTrue, timeout_seconds1200, data_capture_configNone, variant_nameNone, async_inference_configNone, serverless_configNone, envNone, tagsNone, )关键参数详解参数默认值说明app_name必填应用/端点名称SageMaker 对名称长度有 63 字符限制超长会被中间截断_truncate_namemodel_uri必填MLflow 模型位置支持 runs:/、models:/、s3:// 等execution_role_arn当前角色授予 SageMaker 服务访问镜像与 S3 模型产物的 IAM 角色作为CreateModel的ExecutionRoleArn参数仅在该调用中使用assume_role_arnNone跨账户部署时假设的 IAM 角色通过 STSassume_role会话名mlflow-sagemakerbucketmlflow-sagemaker-region-account模型产物存储桶默认桶不存在时自动创建非us-east-1区域会附带LocationConstraintimage_urlECR 自动解析或MLFLOW_SAGEMAKER_DEPLOY_IMG_URL承载模型的 Docker 镜像地址region_nameus-west-2部署的 AWS 区域modecreatecreate / add / replacearchiveFalseTrue 时保留被替换产生的旧模型与旧端点配置instance_typeml.m4.xlarge推理实例类型instance_count1实例数量vpc_configNone字典取值与 boto3create_model的VpcConfig一致{SecurityGroupIds: [...], Subnets: [...]}data_capture_configNone数据捕获配置如{EnableCapture: True, InitialSamplingPercentage: 100, DestinationS3Uri: s3://..., CaptureOptions: [{CaptureMode: Output}]}variant_nameNone缺省用模型名生产变体Production Variant名称async_inference_configNone异步推理配置如{AsyncInferenceConfig: {ClientConfig: {MaxConcurrentInvocationsPerInstance: 4}, OutputConfig: {S3OutputPath: s3://..., NotificationConfig: {}}}}serverless_configNoneServerless 配置如{ServerlessConfig: {MemorySizeInMB: 2048, MaxConcurrency: 20}}提供后实例类型/数量被忽略envNone传给模型的额外环境变量会合并进容器 Environment同时自动附加MLFLOW_DEPLOYMENT_FLAVOR_NAME、SERVING_ENVIRONMENTSageMaker及本机代理变量tagsNone应用到端点的标签字典app_name标签由系统自动写入用户标签不允许与之重名synchronousTrueTrue 时阻塞至部署完成或不可恢复失败False 时立即返回由调用方通过 AWS 控制台/API 监控timeout_seconds1200同步模式下等待上限超时返回状态为timed_out任务仍可能在进行中flavorNone自动选择 pyfunc指定部署 flavor必须是SUPPORTED_DEPLOYMENT_FLAVORS之一且模型中存在部署内部流程源码级_deploy的执行链路为_download_artifact_from_uri(model_uri)下载模型校验根目录存在MLmodel配置文件缺失抛INVALID_PARAMETER_VALUE解析模型 flavors确定部署 flavor_assume_role_and_get_credentials()处理跨账户角色创建 S3 / SageMaker boto3 client_find_endpoint()探测端点是否存在——存在且modecreate直接报错_get_sagemaker_model_name(app_name)生成唯一模型名app_name-model-20位uuid且总长度 ≤ 63_upload_s3()将本地模型目录打包为model.tar.gz上传到s3://bucket/model_name/model.tar.gz并打上SageMakertrue标签若端点不存在走_create_sagemaker_endpoint()create_modelPrimaryContainer含Image/ModelDataUrl/Environment→create_endpoint_config→create_endpoint最终轮询至InService状态若端点存在走_update_sagemaker_endpoint()为replace/add模式创建新模型与新端点配置再update_endpoint切换配置。源码对更新操作有回滚检测若 20 秒内端点回到InService但EndpointConfigName不是新配置视为失败replace模式成功后清理旧模型与旧配置。同步等待由_SageMakerOperation.await_completion()实现每 5 秒调用一次status_check_fn约每 20 秒打印一次进度日志超时返回timed_out状态成功后若archiveFalse则执行clean_up()清理资源。使用统一部署客户端SageMakerDeploymentClientSageMakerDeploymentClient继承自BaseDeploymentClient是官方推荐的方式设计上用于取代部分零散的mlflow.sagemaker实时服务 API且必须通过mlflow.deployments模块使用get_deploy_client与mlflow deploymentsCLI。target_uri 格式初始化客户端时target_uri决定默认区域与假设角色解析逻辑见_get_values_from_target_urisagemaker区域默认us-west-2无假设角色sagemaker:/region_name如sagemaker:/us-east-1设置默认区域sagemaker:/region_name/assumed_role_arn如sagemaker:/us-east-1/arn:aws:1234:role/assumed_role同时设置区域与假设角色若提供了 role ARN 而未提供区域名如sagemaker:/arn:aws:...会抛出MlflowException提示必须遵循sagemaker:/region_name/assumed_role_arn格式。Python 示例创建部署from mlflow.deployments import get_deploy_client vpc_config { SecurityGroupIds: [sg-123456abc], Subnets: [subnet-123456abc], } config dict( assume_role_arnarn:aws:123:role/assumed_role, execution_role_arnarn:aws:456:role/execution_role, bucket_namemy-s3-bucket, image_url1234.dkr.ecr.us-east-1.amazonaws.com/mlflow-test:1.23.1, region_nameus-east-1, archiveFalse, instance_typeml.m5.4xlarge, instance_count1, synchronousTrue, timeout_seconds300, vpc_configvpc_config, variant_nameprod-variant-1, env{DISABLE_NGINX: true, GUNICORN_CMD_ARGS: --timeout 60}, tags{training_timestamp: 2022-11-01T05:12:26}, ) client get_deploy_client(sagemaker) client.create_deployment( my-deployment, model_uri/mlruns/0/abc/model, flavorpython_function, configconfig, )自定义配置由_apply_custom_config()归一化instance_count/timeout_seconds强制转 intsynchronous/archive按字符串True判定为 boolvpc_config/data_capture_config/tags/env/async_inference_config/serverless_config若为字符串则按 JSON 解析不在白名单的键被忽略。未显式传入的键使用_default_deployment_config()中的默认值instance_typeml.m4.xlarge、instance_count1、timeout_seconds1200等。CLI 示例创建部署mlflow deployments create --target sagemaker:/us-east-1/arn:aws:123:role/assumed_role \ --name my-deployment \ --model-uri /mlruns/0/abc/model \ --flavor python_function \ -C execution_role_arnarn:aws:456:role/execution_role \ -C bucket_namemy-s3-bucket \ -C image_url1234.dkr.ecr.us-east-1.amazonaws.com/mlflow-test:1.23.1 \ -C region_nameus-east-1 \ -C archiveFalse \ -C instance_typeml.m5.4xlarge \ -C instance_count1 \ -C synchronousTrue \ -C timeout_seconds300 \ -C variant_nameprod-variant-1 \ -C vpc_config{SecurityGroupIds: [sg-123456abc], Subnets: [subnet-123456abc]} \ -C data_capture_config{EnableCapture: true, InitialSamplingPercentage: 100, DestinationS3Uri: s3://my-bucket/path, CaptureOptions: [{CaptureMode: Output}]} \ -C env{DISABLE_NGINX: true, GUNICORN_CMD_ARGS: \--timeout 60\} \ -C tags{training_timestamp: 2022-11-01T05:12:26}更新部署updateupdate_deployment默认以replace模式替换模型也可显式传modeadd追加新模型权重 0。其余配置项与 create 基本一致另支持async_inference_config。注意更新时model_uri必填否则抛INVALID_PARAMETER_VALUEmode仅允许add/replace传create会报错。CLI 对应为mlflow deployments update ...用法与 create 相同以-C modereplace指定模式。查询与推理list_deployments()调用 SageMakerlist_endpoints返回端点列表区域/角色通过 target_uri 指定例如client get_deploy_client(sagemaker:/us-east-1/arn:aws:123:role/assumed_role)。get_deployment(name)describe_endpoint返回端点描述字典出错包装为MlflowException。predict(deployment_name, inputs, paramsNone)调用sagemaker-runtime的invoke_endpoint请求体经dump_input_data(inputs, inputs_keyinstances, paramsparams)序列化为 JSONContentType: application/json响应通过PredictionsResponse.from_json解析返回类型与 MLflow PyFunc 推理接口一致DataFrame / Series / NumPy 数组等。CLI 可用mlflow deployments predict --name my-deployment --input-path ./input.json。import pandas as pd from mlflow.deployments import get_deploy_client df pd.DataFrame(data[[1, 2, 3]], columns[feat1, feat2, feat3]) client get_deploy_client(sagemaker:/us-east-1/arn:aws:123:role/assumed_role) client.predict(my-deployment, df)本地模拟服务run_localrun_local()允许在本地用 SageMaker 兼容的 Docker 容器先行验证模型注意本地部署的模型不能被其他部署 API 管理如update_deployment/delete_deployment。其配置仅支持两个键image默认mlflow-pyfunc与port默认5000。实现上会先下载模型再用docker run -v model_path:/opt/ml/model/ -p port:8080挂载模型目录并注入 flavor 相关环境变量收到 SIGTERM 时向容器转发 SIGINT 后等待退出。from mlflow.deployments import get_deploy_client client get_deploy_client(sagemaker) client.run_local( namemy-local-deployment, model_uri/mlruns/0/abc/model, flavorpython_function, config{port: 5000, image: mlflow-pyfunc}, )对应的 CLI 方式mlflow models build-docker --name mlflow-pyfunc mlflow deployments run-local --target sagemaker \ --name my-local-deployment \ --model-uri /mlruns/0/abc/model \ --flavor python_function \ -C port5000 \ -C imagemlflow-pyfunc批量转换任务deploy_transform_job 与终止批量推理适用于离线、大文件量场景入口为deploy_transform_job()Python API与mlflow sagemaker deploy-transform-jobCLI。它先创建 SageMaker Model再调用create_transform_job提交任务。批量任务的输入输出参数与 SageMaker Transform API 一一对应参数CLI 选项默认值说明job_name--job-name/-n必填批量转换任务名重名会报错model_uri--model-uri必填MLflow 模型 URIs3_input_data_type--input-data-type必填输入数据类型s3_input_uri--input-uri/-u必填输入数据 S3 前缀或 manifestcontent_type--content-type必填输入 MIME 类型s3_output_path--output-path/-o必填输出结果 S3 路径compression_type--compression-typeNone输入压缩类型split_type--split-type/-sLine数据切分方式accept--accept/-atext/csv输出 MIME 类型assemble_with--assemble-withLine结果合并方式input_filter/output_filter--input-filter/--output-filter$JSONPath 表达式选择输入/输出数据片段join_resource--join-resource/-jNone与转换结果 join 的数据来源instance_type/instance_count--instance-type/-t/--instance-count/-cml.m4.xlarge/1转换实例配置vpc_config--vpc-config/-vJSON 文件路径None模型 VPC 配置archive--archiveFalseTrue 时保留任务结束后的模型与 S3 产物synchronous--asyncTrueFalse 时立即返回不等待任务完成源码中_create_sagemaker_transform_job会依次构造TransformInputS3DataSourceContentType/CompressionType/SplitType、TransformOutputS3OutputPath/Accept/AssembleWith、TransformResources实例配置与DataProcessing输入/输出过滤器与 JoinSource并以model_name作为任务标签提交。状态轮询以TransformJobStatus为准InProgress→Completed为成功其余含FailureReason视为失败。终止任务使用terminate_transform_job()/mlflow sagemaker terminate-transform-job --job-name name调用stop_transform_job后轮询Stopping→Stopped完成后按archive决定是否删除关联模型与 S3 模型产物。删除与清理_delete()Python API 或client.delete_deployment删除指定端点先delete_endpoint成功后轮询确认端点消失再依次删除关联的 EndpointConfig 与 ProductionVariants 对应的 SageMaker Model_delete_sagemaker_model会解析ModelDataUrl的 S3 位置并删除model.tar.gz对象。archiveTrue时保留这些资源archiveFalse时同步删除。同样地archiveFalse要求synchronousTrue。CLI 示例mlflow deployments delete --target sagemaker \ --name my-deployment \ -C assume_role_arnarn:aws:123:role/assumed_role \ -C region_nameus-east-1 \ -C archiveFalse \ -C synchronousTrue \ -C timeout_seconds300只推送模型push_model_to_sagemaker若只想在 SageMaker 中创建 Model例如供其他服务复用可用push_model_to_sagemaker()或mlflow sagemaker push-model --model-name name --model-uri uri。该函数只执行上传 S3 create_model两步不创建端点与端点配置模型重名时报错。env与tags在该路径下固定为空字典vpc_config可选传入。底层实现细节与可复用经验资源命名规则SageMaker 限制模型/配置名称 ≤ 63 字符。_truncate_name()采用中间截断保留头尾中间以---连接_get_unique_name()追加 20 位 uuid 后缀如-model-uuid、-config-uuid保证资源名全局唯一。默认 S3 桶命名规则为mlflow-sagemaker-region-account_id不存在时自动创建除us-east-1外的区域创建时需带CreateBucketConfiguration.LocationConstraint源码注释明确说明该约束不能用于 us-east-1。部署 flavor 注入容器环境变量由_get_deployment_config()生成固定包含MLFLOW_DEPLOYMENT_FLAVOR_NAMEflavor与SERVING_ENVIRONMENTSageMaker并透传本机的http_proxy/https_proxy/no_proxy若已设置。操作状态机所有异步操作创建/更新/删除/批量任务统一封装为_SageMakerOperation_SageMakerOperationStatussucceeded/failed/in progress/timed_out同步模式下每 5 秒轮询一次超时给出timed_out状态并提示通过 AWS 控制台查看后续。可测试性仓库在 tests/sagemaker 下提供了覆盖上述流程的单元测试可作为理解各函数参数行为与边界条件的补充参考。总结mlflow.sagemaker将模型注册 → 容器镜像 → SageMaker 端点/批量任务的整条链路收敛为一组声明式 API 与 CLI实时服务优先走SageMakerDeploymentClientmlflow deployments批量推理走deploy_transform_job本地预演用run_local并结合 create/add/replace 三种模式实现灰度与替换。实践时建议重点确认 IAM 权限执行角色与假设角色、实例类型成本、archive/synchronous的组合约束以及 SageMaker 63 字符命名上限即可稳定完成生产级模型上线。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MLflow SageMaker 部署指南：使用 mlflow.sagemaker 模块将模型部署到 AWS SageMaker
MLflow SageMaker 部署指南使用 mlflow.sagemaker 模块将模型部署到 AWS SageMaker【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflowmlflow.sagemaker是 MLflow 提供的官方 AWS SageMaker 部署模块负责把已记录logged的 MLflow 模型一键部署为 SageMaker 实时推理端点Endpoint或批量转换任务Batch Transform Job。读完本文你将掌握容器镜像构建推送、三种部署模式create/add/replace的选择、完整参数配置、统一部署客户端SageMakerDeploymentClient与 CLI 用法以及本地模拟服务等实战技能。模块定位与能力总览该模块的完整说明位于 mlflow.sagemaker.rst其核心实现集中在 mlflow/sagemaker/init.py约 3000 行与 mlflow/sagemaker/cli.py另附 Docker 辅助脚本 mlflow/sagemaker/push_image_to_ecr.sh。从源码结构看模块提供以下几类能力能力类别公开 API / CLI 命令说明容器镜像构建与推送mlflow sagemaker build-and-push-container、push_image_to_ecr()将本地 Docker 镜像推送到 AWS ECR实时端点部署deploy()内部_deploy创建/更新 SageMaker 端点统一部署客户端SageMakerDeploymentClient通过mlflow.deployments.get_deploy_client使用支持create/update/delete/list/get/predict/run_local批量推理deploy_transform_job()、terminate_transform_job()mlflow sagemaker deploy-transform-job创建/终止批量转换任务本地模拟服务run_local()在本地以 SageMaker 兼容容器方式服务模型仅推送模型push_model_to_sagemaker()、mlflow sagemaker push-model只创建 SageMaker Model不建端点该模块的部署流程可以概括为下载模型 → 上传 S3 → 创建 SageMaker Model引用 ECR 镜像 S3 模型数据→ 创建 EndpointConfig → 创建/更新 Endpoint每一步都由源码中的私有函数串联下文会逐一展开。前提条件根据源码中的实际调用使用本模块前需要准备AWS 凭证当前活跃 AWS 账户需具备 SageMaker、S3、ECR、IAM、STS 相关权限。部署函数注释明确要求当前活跃的 AWS 账户必须已配置正确的权限见 mlflow/sagemaker/init.py。Python 依赖boto3在函数体内惰性导入、docker命令可用run_local与镜像推送均调用dockerCLI。已记录的 MLflow 模型model_uri支持多种形式本地路径/Users/me/path/to/local/model、relative/path/to/local/model、s3://my_bucket/path/to/model、runs:/run_id/run-relative/path/to/model、models:/model_name/model_version、models:/model_name/stage。可部署的 flavor模型必须包含受支持的部署 flavor。_get_preferred_deployment_flavor()会优先选择python_functionpyfuncflavor若模型中没有任何受支持 flavor 则抛出RESOURCE_DOES_NOT_EXIST异常若显式指定的 flavor 不受支持_validate_deployment_flavor()则抛出INVALID_PARAMETER_VALUE异常。三种部署模式Deployment Modes_deploy()的mode参数决定部署行为源码在 mlflow/sagemaker/init.py 中定义如下三个常量DEPLOYMENT_MODE_CREATE create创建指定名称的新应用。若同名应用已存在则直接失败源码中通过_find_endpoint查重并抛出异常。DEPLOYMENT_MODE_REPLACE replace若同名应用存在用新模型替换其模型若不存在则创建。新模型初始权重为 1旧模型及其配置在archiveFalse时被清理。DEPLOYMENT_MODE_ADD add若同名应用存在将新模型追加到现有端点初始权重为0不承接流量若不存在则创建。之后需要通过 AWS 控制台或 SageMaker 的UpdateEndpointWeightsAndCapacitiesAPI 手动调整流量权重。需要注意_deploy内部还会校验mode必须是上述三者之一否则抛出INVALID_PARAMETER_VALUE另外archiveFalse与synchronousFalse不能同时使用——非同步模式下资源必须被归档保留否则抛出异常提示Either setsynchronousTrueorarchiveTrue。构建并推送服务容器镜像SageMaker 推理需要一个承载 MLflow 模型的 Docker 镜像流程分两步先构建镜像再推送到 ECR。CLI 入口在 mlflow/sagemaker/cli.py# 构建默认镜像mlflow-pyfunc并推送到 ECR mlflow sagemaker build-and-push-container # 自定义镜像名与容器构建网络例如在 SageMaker JupyterLab 中构建时 mlflow sagemaker build-and-push-container --image-name my-image \ --container --network sagemaker底层由push_image_to_ecr(imageDEFAULT_IMAGE_NAME)mlflow/sagemaker/init.py执行其内部逻辑通过 STSget_caller_identity()获取当前账户 IDboto3.session.Session().region_name获取区域缺省us-west-2拼出完整 ECR 地址{account}.dkr.ecr.{region}.amazonaws.com/{image}:{version}version为mlflow.version.VERSION检查 ECR 仓库是否存在不存在则create_repository创建依次执行aws ecr get-login-password→docker login --username AWS --password-stdin registry→docker tag→docker push任一子命令失败即抛出MlflowException。之后_get_default_image_url()会通过 ECRdescribe_repositories自动解析该镜像的 repository URI 并拼接版本号也可以直接用环境变量MLFLOW_SAGEMAKER_DEPLOY_IMG_URL指定镜像 URL见 mlflow/environment_variables.py。部署实时推理端点deploy核心函数是_deploy()完整签名如下源码 mlflow/sagemaker/init.py_deploy( app_name, model_uri, execution_role_arnNone, assume_role_arnNone, bucketNone, image_urlNone, region_nameus-west-2, modeDEPLOYMENT_MODE_CREATE, archiveFalse, instance_typeDEFAULT_SAGEMAKER_INSTANCE_TYPE, # ml.m4.xlarge instance_countDEFAULT_SAGEMAKER_INSTANCE_COUNT, # 1 vpc_configNone, flavorNone, synchronousTrue, timeout_seconds1200, data_capture_configNone, variant_nameNone, async_inference_configNone, serverless_configNone, envNone, tagsNone, )关键参数详解参数默认值说明app_name必填应用/端点名称SageMaker 对名称长度有 63 字符限制超长会被中间截断_truncate_namemodel_uri必填MLflow 模型位置支持 runs:/、models:/、s3:// 等execution_role_arn当前角色授予 SageMaker 服务访问镜像与 S3 模型产物的 IAM 角色作为CreateModel的ExecutionRoleArn参数仅在该调用中使用assume_role_arnNone跨账户部署时假设的 IAM 角色通过 STSassume_role会话名mlflow-sagemakerbucketmlflow-sagemaker-region-account模型产物存储桶默认桶不存在时自动创建非us-east-1区域会附带LocationConstraintimage_urlECR 自动解析或MLFLOW_SAGEMAKER_DEPLOY_IMG_URL承载模型的 Docker 镜像地址region_nameus-west-2部署的 AWS 区域modecreatecreate / add / replacearchiveFalseTrue 时保留被替换产生的旧模型与旧端点配置instance_typeml.m4.xlarge推理实例类型instance_count1实例数量vpc_configNone字典取值与 boto3create_model的VpcConfig一致{SecurityGroupIds: [...], Subnets: [...]}data_capture_configNone数据捕获配置如{EnableCapture: True, InitialSamplingPercentage: 100, DestinationS3Uri: s3://..., CaptureOptions: [{CaptureMode: Output}]}variant_nameNone缺省用模型名生产变体Production Variant名称async_inference_configNone异步推理配置如{AsyncInferenceConfig: {ClientConfig: {MaxConcurrentInvocationsPerInstance: 4}, OutputConfig: {S3OutputPath: s3://..., NotificationConfig: {}}}}serverless_configNoneServerless 配置如{ServerlessConfig: {MemorySizeInMB: 2048, MaxConcurrency: 20}}提供后实例类型/数量被忽略envNone传给模型的额外环境变量会合并进容器 Environment同时自动附加MLFLOW_DEPLOYMENT_FLAVOR_NAME、SERVING_ENVIRONMENTSageMaker及本机代理变量tagsNone应用到端点的标签字典app_name标签由系统自动写入用户标签不允许与之重名synchronousTrueTrue 时阻塞至部署完成或不可恢复失败False 时立即返回由调用方通过 AWS 控制台/API 监控timeout_seconds1200同步模式下等待上限超时返回状态为timed_out任务仍可能在进行中flavorNone自动选择 pyfunc指定部署 flavor必须是SUPPORTED_DEPLOYMENT_FLAVORS之一且模型中存在部署内部流程源码级_deploy的执行链路为_download_artifact_from_uri(model_uri)下载模型校验根目录存在MLmodel配置文件缺失抛INVALID_PARAMETER_VALUE解析模型 flavors确定部署 flavor_assume_role_and_get_credentials()处理跨账户角色创建 S3 / SageMaker boto3 client_find_endpoint()探测端点是否存在——存在且modecreate直接报错_get_sagemaker_model_name(app_name)生成唯一模型名app_name-model-20位uuid且总长度 ≤ 63_upload_s3()将本地模型目录打包为model.tar.gz上传到s3://bucket/model_name/model.tar.gz并打上SageMakertrue标签若端点不存在走_create_sagemaker_endpoint()create_modelPrimaryContainer含Image/ModelDataUrl/Environment→create_endpoint_config→create_endpoint最终轮询至InService状态若端点存在走_update_sagemaker_endpoint()为replace/add模式创建新模型与新端点配置再update_endpoint切换配置。源码对更新操作有回滚检测若 20 秒内端点回到InService但EndpointConfigName不是新配置视为失败replace模式成功后清理旧模型与旧配置。同步等待由_SageMakerOperation.await_completion()实现每 5 秒调用一次status_check_fn约每 20 秒打印一次进度日志超时返回timed_out状态成功后若archiveFalse则执行clean_up()清理资源。使用统一部署客户端SageMakerDeploymentClientSageMakerDeploymentClient继承自BaseDeploymentClient是官方推荐的方式设计上用于取代部分零散的mlflow.sagemaker实时服务 API且必须通过mlflow.deployments模块使用get_deploy_client与mlflow deploymentsCLI。target_uri 格式初始化客户端时target_uri决定默认区域与假设角色解析逻辑见_get_values_from_target_urisagemaker区域默认us-west-2无假设角色sagemaker:/region_name如sagemaker:/us-east-1设置默认区域sagemaker:/region_name/assumed_role_arn如sagemaker:/us-east-1/arn:aws:1234:role/assumed_role同时设置区域与假设角色若提供了 role ARN 而未提供区域名如sagemaker:/arn:aws:...会抛出MlflowException提示必须遵循sagemaker:/region_name/assumed_role_arn格式。Python 示例创建部署from mlflow.deployments import get_deploy_client vpc_config { SecurityGroupIds: [sg-123456abc], Subnets: [subnet-123456abc], } config dict( assume_role_arnarn:aws:123:role/assumed_role, execution_role_arnarn:aws:456:role/execution_role, bucket_namemy-s3-bucket, image_url1234.dkr.ecr.us-east-1.amazonaws.com/mlflow-test:1.23.1, region_nameus-east-1, archiveFalse, instance_typeml.m5.4xlarge, instance_count1, synchronousTrue, timeout_seconds300, vpc_configvpc_config, variant_nameprod-variant-1, env{DISABLE_NGINX: true, GUNICORN_CMD_ARGS: --timeout 60}, tags{training_timestamp: 2022-11-01T05:12:26}, ) client get_deploy_client(sagemaker) client.create_deployment( my-deployment, model_uri/mlruns/0/abc/model, flavorpython_function, configconfig, )自定义配置由_apply_custom_config()归一化instance_count/timeout_seconds强制转 intsynchronous/archive按字符串True判定为 boolvpc_config/data_capture_config/tags/env/async_inference_config/serverless_config若为字符串则按 JSON 解析不在白名单的键被忽略。未显式传入的键使用_default_deployment_config()中的默认值instance_typeml.m4.xlarge、instance_count1、timeout_seconds1200等。CLI 示例创建部署mlflow deployments create --target sagemaker:/us-east-1/arn:aws:123:role/assumed_role \ --name my-deployment \ --model-uri /mlruns/0/abc/model \ --flavor python_function \ -C execution_role_arnarn:aws:456:role/execution_role \ -C bucket_namemy-s3-bucket \ -C image_url1234.dkr.ecr.us-east-1.amazonaws.com/mlflow-test:1.23.1 \ -C region_nameus-east-1 \ -C archiveFalse \ -C instance_typeml.m5.4xlarge \ -C instance_count1 \ -C synchronousTrue \ -C timeout_seconds300 \ -C variant_nameprod-variant-1 \ -C vpc_config{SecurityGroupIds: [sg-123456abc], Subnets: [subnet-123456abc]} \ -C data_capture_config{EnableCapture: true, InitialSamplingPercentage: 100, DestinationS3Uri: s3://my-bucket/path, CaptureOptions: [{CaptureMode: Output}]} \ -C env{DISABLE_NGINX: true, GUNICORN_CMD_ARGS: \--timeout 60\} \ -C tags{training_timestamp: 2022-11-01T05:12:26}更新部署updateupdate_deployment默认以replace模式替换模型也可显式传modeadd追加新模型权重 0。其余配置项与 create 基本一致另支持async_inference_config。注意更新时model_uri必填否则抛INVALID_PARAMETER_VALUEmode仅允许add/replace传create会报错。CLI 对应为mlflow deployments update ...用法与 create 相同以-C modereplace指定模式。查询与推理list_deployments()调用 SageMakerlist_endpoints返回端点列表区域/角色通过 target_uri 指定例如client get_deploy_client(sagemaker:/us-east-1/arn:aws:123:role/assumed_role)。get_deployment(name)describe_endpoint返回端点描述字典出错包装为MlflowException。predict(deployment_name, inputs, paramsNone)调用sagemaker-runtime的invoke_endpoint请求体经dump_input_data(inputs, inputs_keyinstances, paramsparams)序列化为 JSONContentType: application/json响应通过PredictionsResponse.from_json解析返回类型与 MLflow PyFunc 推理接口一致DataFrame / Series / NumPy 数组等。CLI 可用mlflow deployments predict --name my-deployment --input-path ./input.json。import pandas as pd from mlflow.deployments import get_deploy_client df pd.DataFrame(data[[1, 2, 3]], columns[feat1, feat2, feat3]) client get_deploy_client(sagemaker:/us-east-1/arn:aws:123:role/assumed_role) client.predict(my-deployment, df)本地模拟服务run_localrun_local()允许在本地用 SageMaker 兼容的 Docker 容器先行验证模型注意本地部署的模型不能被其他部署 API 管理如update_deployment/delete_deployment。其配置仅支持两个键image默认mlflow-pyfunc与port默认5000。实现上会先下载模型再用docker run -v model_path:/opt/ml/model/ -p port:8080挂载模型目录并注入 flavor 相关环境变量收到 SIGTERM 时向容器转发 SIGINT 后等待退出。from mlflow.deployments import get_deploy_client client get_deploy_client(sagemaker) client.run_local( namemy-local-deployment, model_uri/mlruns/0/abc/model, flavorpython_function, config{port: 5000, image: mlflow-pyfunc}, )对应的 CLI 方式mlflow models build-docker --name mlflow-pyfunc mlflow deployments run-local --target sagemaker \ --name my-local-deployment \ --model-uri /mlruns/0/abc/model \ --flavor python_function \ -C port5000 \ -C imagemlflow-pyfunc批量转换任务deploy_transform_job 与终止批量推理适用于离线、大文件量场景入口为deploy_transform_job()Python API与mlflow sagemaker deploy-transform-jobCLI。它先创建 SageMaker Model再调用create_transform_job提交任务。批量任务的输入输出参数与 SageMaker Transform API 一一对应参数CLI 选项默认值说明job_name--job-name/-n必填批量转换任务名重名会报错model_uri--model-uri必填MLflow 模型 URIs3_input_data_type--input-data-type必填输入数据类型s3_input_uri--input-uri/-u必填输入数据 S3 前缀或 manifestcontent_type--content-type必填输入 MIME 类型s3_output_path--output-path/-o必填输出结果 S3 路径compression_type--compression-typeNone输入压缩类型split_type--split-type/-sLine数据切分方式accept--accept/-atext/csv输出 MIME 类型assemble_with--assemble-withLine结果合并方式input_filter/output_filter--input-filter/--output-filter$JSONPath 表达式选择输入/输出数据片段join_resource--join-resource/-jNone与转换结果 join 的数据来源instance_type/instance_count--instance-type/-t/--instance-count/-cml.m4.xlarge/1转换实例配置vpc_config--vpc-config/-vJSON 文件路径None模型 VPC 配置archive--archiveFalseTrue 时保留任务结束后的模型与 S3 产物synchronous--asyncTrueFalse 时立即返回不等待任务完成源码中_create_sagemaker_transform_job会依次构造TransformInputS3DataSourceContentType/CompressionType/SplitType、TransformOutputS3OutputPath/Accept/AssembleWith、TransformResources实例配置与DataProcessing输入/输出过滤器与 JoinSource并以model_name作为任务标签提交。状态轮询以TransformJobStatus为准InProgress→Completed为成功其余含FailureReason视为失败。终止任务使用terminate_transform_job()/mlflow sagemaker terminate-transform-job --job-name name调用stop_transform_job后轮询Stopping→Stopped完成后按archive决定是否删除关联模型与 S3 模型产物。删除与清理_delete()Python API 或client.delete_deployment删除指定端点先delete_endpoint成功后轮询确认端点消失再依次删除关联的 EndpointConfig 与 ProductionVariants 对应的 SageMaker Model_delete_sagemaker_model会解析ModelDataUrl的 S3 位置并删除model.tar.gz对象。archiveTrue时保留这些资源archiveFalse时同步删除。同样地archiveFalse要求synchronousTrue。CLI 示例mlflow deployments delete --target sagemaker \ --name my-deployment \ -C assume_role_arnarn:aws:123:role/assumed_role \ -C region_nameus-east-1 \ -C archiveFalse \ -C synchronousTrue \ -C timeout_seconds300只推送模型push_model_to_sagemaker若只想在 SageMaker 中创建 Model例如供其他服务复用可用push_model_to_sagemaker()或mlflow sagemaker push-model --model-name name --model-uri uri。该函数只执行上传 S3 create_model两步不创建端点与端点配置模型重名时报错。env与tags在该路径下固定为空字典vpc_config可选传入。底层实现细节与可复用经验资源命名规则SageMaker 限制模型/配置名称 ≤ 63 字符。_truncate_name()采用中间截断保留头尾中间以---连接_get_unique_name()追加 20 位 uuid 后缀如-model-uuid、-config-uuid保证资源名全局唯一。默认 S3 桶命名规则为mlflow-sagemaker-region-account_id不存在时自动创建除us-east-1外的区域创建时需带CreateBucketConfiguration.LocationConstraint源码注释明确说明该约束不能用于 us-east-1。部署 flavor 注入容器环境变量由_get_deployment_config()生成固定包含MLFLOW_DEPLOYMENT_FLAVOR_NAMEflavor与SERVING_ENVIRONMENTSageMaker并透传本机的http_proxy/https_proxy/no_proxy若已设置。操作状态机所有异步操作创建/更新/删除/批量任务统一封装为_SageMakerOperation_SageMakerOperationStatussucceeded/failed/in progress/timed_out同步模式下每 5 秒轮询一次超时给出timed_out状态并提示通过 AWS 控制台查看后续。可测试性仓库在 tests/sagemaker 下提供了覆盖上述流程的单元测试可作为理解各函数参数行为与边界条件的补充参考。总结mlflow.sagemaker将模型注册 → 容器镜像 → SageMaker 端点/批量任务的整条链路收敛为一组声明式 API 与 CLI实时服务优先走SageMakerDeploymentClientmlflow deployments批量推理走deploy_transform_job本地预演用run_local并结合 create/add/replace 三种模式实现灰度与替换。实践时建议重点确认 IAM 权限执行角色与假设角色、实例类型成本、archive/synchronous的组合约束以及 SageMaker 63 字符命名上限即可稳定完成生产级模型上线。【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考