ModelArts SDK是华为云ModelArts服务提供的Python开发工具包用于在本地环境中管理数据集、创建训练作业、部署模型等。但本地安装过程并非一帆风顺Python版本不匹配、pip版本冲突、依赖包缺失等问题层出不穷。本文基于官方文档及常见问题整理一份完整的踩坑与避坑指南。一、环境准备版本选对事半功倍1. Python版本——第一大坑ModelArts SDK对Python版本有严格限制要求大于3.7.x且小于3.10.x。⚠️ 特别注意Python 3.10及以上版本不被支持。如果在Windows上使用过高版本安装会直接报错。建议推荐使用Python 3.7.x或3.9.x版本。检查当前Python版本bashpython --version2. pip版本——第二个坑pip版本需小于24.0。如果pip版本≥24.1安装包名称校验会触发如下错误textERROR: Invalid requirement: modelartslatest: Expected end or semicolon (after name and no valid version specifier) modelartslatest解决方案降级pip版本pip install pip23.3.2或重命名whl文件将modelarts-latest-py2.py3-none-any.whl改为modelarts-1.0.0-py2.py3-none-any.whl实际SDK版本不受影响3. 环境变量配置——Windows用户必看Windows下若提示pip或python“不是内部或外部命令”需将Python和pip的安装路径添加到系统环境变量Path中WinR→ 输入sysdm.cpl→ 确定切换到“高级”页签 → 点击“环境变量”在用户变量中找到Path→ 双击 → 新增Python和pip的安装路径pip的安装路径一般为Python所在目录的Scripts文件夹例如c:\python\python39\Scripts二、安装步骤踩坑点逐个击破步骤1获取SDK软件包ModelArts SDK安装包为modelarts-latest-py2.py3-none-any.whl。获取方式华为云帮助中心下载最新版本企业用户登录华为企业业务网站搜索安装包名称可选校验可使用OpenSSL验证软件包一致性bashopenssl cms -verify -binary -in D:\modelarts-latest-py2.py3-none-any.whl.cms -inform DER -content D:\modelarts-latest-py2.py3-none-any.whl -noverify ./test步骤2配置pip源推荐配置国内pip源可大幅提升依赖包下载速度以华为云镜像源为例在%APPDATA%路径下创建pip文件夹新建pip.ini文件内容如下ini[global] index-url https://mirrors.huaweicloud.com/repository/pypi/simple trusted-host mirrors.huaweicloud.com disable-pip-version-check true timeout 120 [install] ignore-installed true no-dependencies yes 查看APPDATA路径启动cmd输入set命令找到APPDATA对应的路径。步骤3执行安装bashpip install C:\Users\xxx\Downloads\modelarts-latest-py2.py3-none-any.whl安装成功时显示textSuccessfully installed Pillow-*.*.0 ... modelarts-*.*.* ...步骤4依赖包缺失——第三个坑如果在安装过程中报错提示缺少依赖包需要手动安装bashpip install xxxx # xxxx为缺失的依赖包名称常见问题futures依赖包缺失报错如下图解决方案先单独安装3.1.1版本的futuresbashpip install futures3.1.1然后再重新安装SDK。三、安装后操作鉴权与配置1. Session鉴权——本地使用的必要步骤本地安装SDK后必须完成Session鉴权才能使用。方式一AK/SK认证推荐pythonfrom modelarts.session import Session import os _AK os.environ[HUAWEICLOUD_SDK_AK] _SK os.environ[HUAWEICLOUD_SDK_SK] session Session(access_key_AK, secret_key_SK, project_id***, region_name***)⚠️ AK/SK硬编码到代码中有安全风险建议通过环境变量配置。方式二用户名密码认证pythonfrom modelarts.session import Session session Session(username***, password***, region_name***, project_id***) 如果华为云账号已升级为华为账号账号认证方式不可用需使用IAM用户认证。2. PyCharm工程配置可选将安装好的ModelArts包复制到PyCharm工程目录下bashpip show modelarts找到Location路径下的modelarts和modelarts-*.dist-info两个文件复制到PyCharm工程的External Libraries Lib site-packages目录下。3. 私有云环境hosts配置HCS场景如果是华为云StackHCS私有云环境还需配置hosts域名映射hosts文件路径C:\Windows\System32\drivers\etc\hosts添加映射textModelArts IP modelarts.region-id.domain_name OBS IP obsv3_name_prefix.region-id.domain_name IAM IP iam-apigateway-proxy.region-id.domain_name四、功能限制本地SDK不支持什么本地ModelArts SDK有以下功能限制不支持❌ 训练作业调测❌ 模型调试❌ 在开发环境中部署本地服务进行调试 以上调试功能仅支持在ModelArts开发环境Notebook中进行。本地SDK支持的操作✅ OBS桶管理创建、上传、下载、删除✅ 创建ModelArts训练作业✅ 创建AI应用并部署为在线服务五、踩坑总结速查表坑位问题现象解决方案Python版本过高安装报错使用3.7.x~3.9.x版本需3.10pip版本过高Invalid requirement: modelartslatest降级pip至24.0或重命名whl文件futures缺失特定报错见官方文档图pip install futures3.1.1环境变量未配置提示“不是内部或外部命令”将Python和pip路径加入Path依赖包缺失提示缺少某个包pip install xxxx手动安装鉴权失败调用SDK报错检查AK/SK、project_id、region_name六、注意事项区域限制本地安装的SDK仅支持在特定区域使用包括华北-北京四、华东-上海一等[6]使用场景SDK目前只提供Python语言版本不支持在ModelArts的训练作业和推理在线服务中使用安全提醒密码、AK/SK等信息建议通过环境变量配置避免硬编码明文存储