0
# ModelScope
1

2
ModelScope is a comprehensive Python library that implements Model-as-a-Service (MaaS) architecture, providing unified interfaces for exploring, using, and integrating state-of-the-art machine learning models across multiple domains including Computer Vision, Natural Language Processing, Speech, Multi-Modality, and Scientific Computing.
3

4
## Package Information
5

6
- **Package Name**: modelscope
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install modelscope`
10

11
## Core Imports
12

13
```python
14
import modelscope
15
from modelscope import pipeline, Model, snapshot_download
16
```
17

18
Common patterns for specific functionality:
19

20
```python
21
# Hub operations
22
from modelscope import HubApi, snapshot_download, push_to_hub
23

24
# Pipeline usage (recommended approach)
25
from modelscope import pipeline
26

27
# Model and training
28
from modelscope import Model, EpochBasedTrainer, TrainingArgs
29

30
# Preprocessors and metrics
31
from modelscope import Preprocessor, Metric
32

33
# Dataset operations
34
from modelscope import MsDataset
35
```
36

37
## Basic Usage
38

39
### Simple Pipeline Usage (Recommended)
40

41
```python
42
from modelscope import pipeline
43

44
# Create a pipeline for a specific task
45
pipe = pipeline('text-classification', model='nlp_structbert_sentence-similarity_chinese')
46

47
# Use the pipeline
48
result = pipe('这是一个测试文本')
49
print(result)
50

51
# Computer vision example
52
cv_pipe = pipeline('image-classification', model='damo/cv_resnet50_image-classification_imagenet')
53
result = cv_pipe('path/to/image.jpg')
54
```
55

56
### Model Download and Usage
57

58
```python
59
from modelscope import snapshot_download, Model
60

61
# Download a model
62
model_dir = snapshot_download('nlp_structbert_sentence-similarity_chinese')
63

64
# Load the model
65
model = Model.from_pretrained(model_dir)
66

67
# Use the model
68
output = model(input_data)
69
```
70

71
### Training a Model
72

73
```python
74
from modelscope import EpochBasedTrainer, TrainingArgs
75
from modelscope import build_dataset_from_file
76

77
# Prepare dataset
78
dataset = build_dataset_from_file('path/to/train.json')
79

80
# Configure training
81
training_args = TrainingArgs(
82
    output_dir='./output',
83
    max_epochs=10,
84
    eval_strategy='epoch'
85
)
86

87
# Create trainer
88
trainer = EpochBasedTrainer(
89
    model=model,
90
    args=training_args,
91
    train_dataset=dataset
92
)
93

94
# Start training
95
trainer.train()
96
```
97

98
## Architecture
99

100
ModelScope is built on a layered architecture that provides multiple levels of abstraction:
101

102
- **Pipeline Layer**: High-level task-oriented interfaces that handle preprocessing, inference, and postprocessing automatically
103
- **Model Layer**: Direct model interfaces for custom workflows and fine-grained control
104
- **Component Layer**: Individual components (preprocessors, models, postprocessors) for maximum customization
105
- **Hub Layer**: Integration with ModelScope backend services for model and dataset management
106

107
The library seamlessly integrates with ModelScope Hub for model discovery, version control, and collaborative development, while also supporting local model development and custom implementations.
108

109
## Capabilities
110

111
### Hub Operations
112

113
ModelScope Hub integration for downloading, uploading, and managing models and datasets from the ModelScope ecosystem.
114

115
```python { .api }
116
def snapshot_download(model_id: str, revision: str = None, cache_dir: str = None, **kwargs) -> str: ...
117
def push_to_hub(repo_name: str, output_dir: str, **kwargs): ...
118
def model_file_download(model_id: str, file_path: str, **kwargs) -> str: ...
119

120
class HubApi:
121
    def login(self, token: str): ...
122
    def create_model(self, model_name: str, **kwargs): ...
123
    def list_models(self, **kwargs): ...
124
```
125

126
[Hub Operations](./hub.md)
127

128
### Pipeline Interface
129

130
High-level task-oriented pipeline interface that provides the easiest way to use pre-trained models for inference across different domains.
131

132
```python { .api }
133
def pipeline(task: str, model: str = None, preprocessor=None, **kwargs) -> Pipeline: ...
134

135
class Pipeline:
136
    def __call__(self, inputs, **kwargs): ...
137
    def preprocess(self, inputs): ...
138
    def forward(self, inputs): ...
139
    def postprocess(self, inputs): ...
140
```
141

142
[Pipeline Interface](./pipelines.md)
143

144
### Model Interface
145

146
Direct model interfaces for loading, using, and customizing pre-trained models with fine-grained control over the inference process.
147

148
```python { .api }
149
class Model:
150
    @classmethod
151
    def from_pretrained(cls, model_name_or_path: str, **kwargs): ...
152
    def forward(self, inputs): ...
153
    def __call__(self, inputs): ...
154

155
class TorchModel(Model):
156
    # PyTorch-specific model implementation
157
    pass
158
```
159

160
[Model Interface](./models.md)
161

162
### Training Framework
163

164
Comprehensive training framework supporting epoch-based training with hooks, metrics, and evaluation capabilities.
165

166
```python { .api }
167
class EpochBasedTrainer:
168
    def __init__(self, model, args: TrainingArgs, **kwargs): ...
169
    def train(self): ...
170
    def evaluate(self): ...
171
    def save_checkpoint(self, checkpoint_dir: str): ...
172

173
class TrainingArgs:
174
    def __init__(self, output_dir: str, max_epochs: int = 1, **kwargs): ...
175

176
def build_dataset_from_file(data_files, **kwargs): ...
177
```
178

179
[Training Framework](./training.md)
180

181
### Metrics and Evaluation
182

183
Comprehensive metrics framework for evaluating model performance across different tasks and domains.
184

185
```python { .api }
186
class Metric:
187
    def add(self, outputs, inputs): ...
188
    def evaluate(self): ...
189
    def merge(self, other): ...
190

191
def task_default_metrics(task: str) -> list: ...
192

193
# Specialized metrics
194
class AccuracyMetric(Metric): ...
195
class BleuMetric(Metric): ...
196
class ImageQualityAssessmentMetric(Metric): ...
197
```
198

199
[Metrics and Evaluation](./metrics.md)
200

201
### Preprocessors
202

203
Data preprocessing components for different modalities and tasks, providing consistent data preparation pipelines.
204

205
```python { .api }
206
class Preprocessor:
207
    def __call__(self, data): ...
208
    def forward(self, data): ...
209

210
# Common preprocessors
211
class Compose(Preprocessor): ...
212
class ToTensor(Preprocessor): ...
213
class LoadImage(Preprocessor): ...
214
```
215

216
[Preprocessors](./preprocessors.md)
217

218
### Datasets
219

220
Dataset handling and manipulation utilities for working with ModelScope datasets and local data.
221

222
```python { .api }
223
class MsDataset:
224
    @classmethod
225
    def load(cls, dataset_name: str, subset_name: str = None, **kwargs): ...
226
    def to_hf_dataset(self): ...
227
    def map(self, function): ...
228
    def filter(self, function): ...
229
    def split(self, test_size: float): ...
230
```
231

232
[Datasets](./datasets.md)
233

234
### Model Export
235

236
Model export capabilities for deploying models to different formats and target platforms.
237

238
```python { .api }
239
class Exporter:
240
    def export(self, model, output_dir: str): ...
241

242
class TorchModelExporter(Exporter): ...
243
class TfModelExporter(Exporter): ...
244
```
245

246
[Model Export](./export.md)
247

248
### Utilities and Constants
249

250
Core utilities, logging, configuration management, and task constants used throughout the ModelScope ecosystem.
251

252
```python { .api }
253
class Tasks:
254
    # Task constants for different domains
255
    pass
256

257
def get_logger(log_file: str = None, log_level=INFO) -> Logger: ...
258
def read_config(path: str) -> dict: ...
259
```
260

261
[Utilities](./utilities.md)