ModelScope · 阿里达摩院 Model-as-a-Service 模型平台 · 本地环境与推理训练库部署全指南
项目仓库： https://github.com/modelscope/modelscope
开源协议：Apache License 2.0 · 语言：Python · 支持框架：PyTorch / TensorFlow / ONNX · 运行环境：Python 3.7+ · 官方镜像：阿里云 ACR（CPU / GPU）· 仓库分支：master
1 项目简介
ModelScope（魔搭社区）建立在 Model-as-a-Service（MaaS） 理念之上，目标是汇聚 AI 社区最先进的机器学习模型，并让在真实应用中调用 AI 模型的过程尽量简单。本仓库开源的 ModelScope 库提供统一的接口与实现，让开发者用极少的代码完成模型推理、训练与评测。
通过分层的 API 抽象，ModelScope 库为跨领域（CV、NLP、语音、多模态、科学计算）的 SOTA 模型提供一致的使用体验：模型贡献者通过分层 API 把模型接入 ModelScope 生态后，他人只需几行代码即可完成推理、微调与评测，同时保留各组件按需定制的灵活性。库本身还负责与 Model-Hub、Dataset-Hub 后端交互，在后台完成模型/数据集的查找、版本控制、缓存管理。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | ModelScope（魔搭） |
| 仓库地址 | github.com/modelscope/modelscope |
| 项目定位 | Model-as-a-Service 模型库，统一推理/训练/评测接口 |
| 开源协议 | Apache License 2.0 |
| 主要语言 | Python |
| 支持框架 | PyTorch 1.8+ / TensorFlow 1.15 / 2.0+ / ONNX |
| Python 要求 | 3.7+（部分音频模型仅支持 3.7 + TF1.15.4 Linux） |
| 官方站点 | modelscope.cn |
| 分发渠道 | PyPI modelscope + 阿里云 ACR Docker 镜像 |
| 仓库分支 | master |
1.2 适用场景
- 想在本地统一调用上百个开源模型（LLM、多模态、CV、语音、科学计算），而不必为每个模型单独搭环境。
- 需要通过
pip install modelscope[cv/nlp/audio/multi-modal/science]按领域装齐依赖，快速跑通推理或微调。 - 希望直接用官方 Docker 镜像跳过环境配置，开箱即用。
- 模型贡献者想把自己的模型按 ModelScope 接入流程上架到模型库。
1.3 能力边界（官方口径）
- 库本身是模型推理/训练/评测的接口与实现，模型权重与数据集托管在 modelscope.cn 后端，首次使用需联网拉取。
- 部分音频任务模型仅支持 Python 3.7 + TensorFlow 1.15.4 的 Linux 环境；其余大部分模型可在 Windows、Mac（x86）上安装使用。
- CV 部分模型需要 mmcv-full，需按官方指引单独安装。
2 功能特性
- 统一简洁接口：不同任务、不同模型抽象为统一 UI，推理最少 3 行、训练最少约 10 行代码。
- 以模型为中心：贯通训练、推理、导出、部署，便于在 ModelScope 生态上自建 MLOps。
- 模块化设计：推理与训练流程中提供丰富功能模块实现，可按需定制。
- 分布式训练策略：针对大模型提供数据并行、模型并行、混合并行等支持。
- 与模型/数据集后端交互：后台自动完成实体查找、版本控制、缓存管理。
- 官方镜像与多领域 extra 依赖：提供 CPU/GPU
官方镜像，以及
[cv]/[nlp]/[audio]/[multi-modal]/[science]等领域化安装包。
3 官方界面预览
文首为 ModelScope 官方品牌横幅；平台内的在线体验、Notebook
环境与模型详情页见官网 modelscope.cn，README
中另附推理演示动图（data/resource/inference.gif）。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | https://github.com/modelscope/modelscope | 源码、README、接入流程 |
| 模型平台 | https://www.modelscope.cn | 模型库、数据集、在线体验、Notebook |
| 中文 README | README_zh.md | 中文说明 |
| 环境安装文档 | 环境安装 | 官方详细安装指南 |
| 推理 Pipeline | 模型的推理 Pipeline | Pipeline 推理用法 |
| 微调训练 | 模型的训练 Train | 微调示例 |
| 许可证 | Apache-2.0 | Apache License 2.0 |
5 前置要求与服务器配置
5.1 软件前提
- Python 3.7+（建议 3.8）：用 anaconda 创建独立环境。
- PyTorch 或 TensorFlow：按所用模型要求自行安装，PyTorch 1.8+、TensorFlow 1.15 或 2.0+。
- Docker（容器方式）：需要 Docker 与（可选）NVIDIA Container Toolkit 才能使用 GPU 镜像。
- 联网：首次运行需从 modelscope.cn 拉取模型权重与数据集。
5.2 系统备注（官方 Notes）
- 部分音频任务模型仅支持 Python 3.7、TensorFlow 1.15.4 的 Linux 环境；其余大部分模型可在 Windows、Mac（x86）使用。
- 音频领域部分模型用 SoundFile 处理 wav，Linux 需手动安装
libsndfile（Ubuntu：sudo apt-get install libsndfile1）。 - 部分 CV 模型需要
mmcv-full：先pip uninstall mmcv，再pip install -U openmim、mim install mmcv-full。
6 方式一：官方 Docker 镜像（推荐，开箱即用）
官方为每个 release 提供 CPU 与 GPU 镜像，可跳过全部环境安装。
# CPU 镜像（py38）
docker pull registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-py38-torch2.0.1-tf2.13.0-1.9.5
# GPU 镜像（py38，CUDA 11.8）
docker pull registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-cuda11.8.0-py38-torch2.0.1-tf2.13.0-1.9.5
# 启动容器（GPU 需安装 NVIDIA Container Toolkit）
docker run --gpus all -it registry.cn-hangzhou.aliyuncs.com/modelscope-repo/modelscope:ubuntu20.04-cuda11.8.0-py38-torch2.0.1-tf2.13.0-1.9.5 /bin/bash官方另提供 py37 版本的 CPU/GPU 镜像（标签见 README）。
7 方式二：本地 Python 环境安装
# 1. 创建环境
conda create -n modelscope python=3.8
conda activate modelscope
# 2. 自行安装 PyTorch / TensorFlow（按模型要求）
# 见 https://pytorch.org/get-started/locally/
# 3. 核心库（仅体验框架或下载模型/数据集）
pip install modelscope
# 4. 按领域安装 extra 依赖
pip install modelscope[multi-modal]
pip install modelscope[nlp] -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html
pip install modelscope[cv] -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html
pip install modelscope[audio] -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html
pip install modelscope[science] -f https://modelscope.oss-cn-beijing.aliyuncs.com/releases/repo.html7.1 最小推理示例（官方 Pipeline 思路）
from modelscope.pipelines import pipeline
from modelscope.utils.constant import Tasks
# 以一个 CV/NLP/语音任务为例，具体模型 id 见模型卡片
# pipe = pipeline(task=Tasks.xxx, model='模型ID')
# result = pipe('输入')8 配置项说明
| 配置 | 位置 | 说明 |
|---|---|---|
| 领域 extra | pip install
modelscope[cv/nlp/audio/multi-modal/science] |
按任务领域安装额外依赖 |
| 模型缓存 | 默认本机缓存目录 | 首次拉取模型权重后缓存，路径以官方文档为准 |
| 镜像标签 | ACR 仓库标签 | 选择 py37/py38、torch/tf 版本、CPU/CUDA 组合 |
| mmcv-full | CV 模型按需 | 通过 openmim 安装 |
9 常用运维命令
# 查看已安装版本
pip show modelscope
# 升级到最新版
pip install -U modelscope
# 查看模型缓存（默认目录，按系统为准）
ls ~/.cache/modelscope
# 进入 GPU 容器
docker run --gpus all -it <镜像> /bin/bash10 常见故障排查
- 音频模型在 Windows/Mac 报错：官方说明部分音频模型仅支持 Python 3.7 + TF1.15.4 Linux，换用对应环境或改用 Docker 镜像。
- wav 读取失败：Linux 装
libsndfile1（sudo apt-get install libsndfile1）。 - CV 模型报 mmcv 相关错误：卸载旧 mmcv 后用
openmim安装mmcv-full。 - 模型下载慢或失败：官方托管在阿里云 OSS，国内网络通常更稳；失败可重试，或配置代理后重试。
- Python 版本不兼容：新建 3.8 专用 conda 环境，避免与系统 Python 混用。
11 风险与合规说明
- 许可证：ModelScope 库采用 Apache License 2.0，可自由使用与二次开发。
- 模型权重版权：各模型权重的许可证以模型卡片为准，商用前需逐一核对模型作者许可。
- 数据与隐私：在线体验与 Notebook 在云端，敏感数据请优先在本地环境处理。
- 非官方声明：本文为基于官方仓库 README 整理的部署指南，命令与标签以仓库最新版本为准。