tessl/pypi-modelscope
ModelScope brings the notion of Model-as-a-Service to life with unified interfaces for state-of-the-art machine learning models.
—
Pending
hub.mddocs/
Hub Operations
ModelScope Hub integration provides seamless access to the ModelScope ecosystem for downloading, uploading, and managing models and datasets. The Hub API enables model discovery, version control, and collaborative development workflows.
Capabilities
Model Download
Download complete model repositories or individual files from ModelScope Hub.
def snapshot_download(
model_id: str = None,
revision: Optional[str] = None,
cache_dir: Union[str, Path, None] = None,
user_agent: Optional[Union[Dict, str]] = None,
local_files_only: Optional[bool] = False,
cookies: Optional[CookieJar] = None,
ignore_file_pattern: Optional[Union[str, List[str]]] = None,
allow_file_pattern: Optional[Union[str, List[str]]] = None,
local_dir: Optional[str] = None,
allow_patterns: Optional[Union[List[str], str]] = None,
ignore_patterns: Optional[Union[List[str], str]] = None,
max_workers: int = 8,
repo_id: str = None,
repo_type: Optional[str] = REPO_TYPE_MODEL,
enable_file_lock: Optional[bool] = None,
progress_callbacks: List[Type[ProgressCallback]] = None,
) -> str:
"""
Download a complete model repository from ModelScope Hub.
Parameters:
- model_id: ModelScope model identifier (e.g., 'damo/nlp_structbert_sentence-similarity_chinese')
- revision: Model version/revision to download (default: latest)
- cache_dir: Local cache directory path (Union[str, Path, None])
- user_agent: User agent for HTTP requests (dict or string)
- local_files_only: Only use local cached files
- cookies: HTTP cookies for authenticated requests
- ignore_file_pattern: File patterns to ignore during download
- allow_file_pattern: File patterns to allow during download
- local_dir: Local directory to download files to
- allow_patterns: List of file patterns to include (Union[List[str], str])
- ignore_patterns: List of file patterns to exclude (Union[List[str], str])
- max_workers: Maximum number of concurrent download workers
- repo_id: Repository identifier
- repo_type: Type of repository (REPO_TYPE_MODEL by default)
- enable_file_lock: Enable file locking during download
- progress_callbacks: List of progress callback functions
Returns:
Local path to downloaded model directory
"""
def model_file_download(
model_id: str,
file_path: str,
cache_dir: str = None,
local_files_only: bool = False,
**kwargs
) -> str:
"""
Download a single file from a model repository.
Parameters:
- model_id: ModelScope model identifier
- file_path: Path to file within the model repository
- cache_dir: Local cache directory path
- local_files_only: Only use local cached files
Returns:
Local path to downloaded file
"""Dataset Download
Download datasets from ModelScope Dataset Hub.
def dataset_snapshot_download(
dataset_id: str,
revision: str = None,
cache_dir: str = None,
local_files_only: bool = False,
**kwargs
) -> str:
"""
Download a complete dataset repository from ModelScope Hub.
Parameters:
- dataset_id: ModelScope dataset identifier
- revision: Dataset version/revision to download
- cache_dir: Local cache directory path
- local_files_only: Only use local cached files
Returns:
Local path to downloaded dataset directory
"""
def dataset_file_download(
dataset_id: str,
file_path: str,
cache_dir: str = None,
**kwargs
) -> str:
"""
Download a single file from a dataset repository.
Parameters:
- dataset_id: ModelScope dataset identifier
- file_path: Path to file within the dataset repository
- cache_dir: Local cache directory path
Returns:
Local path to downloaded file
"""Model Upload
Upload models and datasets to ModelScope Hub.
def push_to_hub(
repo_name: str,
output_dir: str,
token: str = None,
private: bool = True,
retry: int = 3,
commit_message: str = '',
tag: str = None,
source_repo: str = '',
ignore_file_pattern: list = None,
revision: str = DEFAULT_REPOSITORY_REVISION
):
"""
Upload a model or dataset to ModelScope Hub.
Parameters:
- repo_name: Repository name on ModelScope Hub
- output_dir: Local directory containing files to upload
- token: Authentication token (optional)
- private: Whether to create a private repository (default: True)
- retry: Number of retry attempts on failure (default: 3)
- commit_message: Commit message for the upload (default: empty string)
- tag: Git tag for the upload (optional)
- source_repo: Source repository URL (default: empty string)
- ignore_file_pattern: List of file patterns to ignore during upload
- revision: Repository revision (default: DEFAULT_REPOSITORY_REVISION)
"""
def push_to_hub_async(
repo_name: str,
output_dir: str,
**kwargs
):
"""
Asynchronously upload a model or dataset to ModelScope Hub.
Parameters:
- repo_name: Repository name on ModelScope Hub
- output_dir: Local directory containing files to upload
"""Hub API
Comprehensive API interface for advanced Hub operations.
class HubApi:
"""
Main API interface for ModelScope Hub operations.
"""
def __init__(
self,
endpoint: Optional[str] = None,
timeout = API_HTTP_CLIENT_TIMEOUT,
max_retries = API_HTTP_CLIENT_MAX_RETRIES
):
"""
Initialize Hub API client.
Parameters:
- endpoint: ModelScope Hub endpoint URL (optional)
- timeout: HTTP client timeout duration
- max_retries: Maximum number of HTTP request retries
"""
def login(
self,
access_token: Optional[str] = None,
endpoint: Optional[str] = None
):
"""
Authenticate with ModelScope Hub.
Parameters:
- access_token: Authentication access token (optional)
- endpoint: Hub endpoint URL (optional)
"""
def get_cookies(
self,
access_token: str,
cookies_required: Optional[bool] = False
):
"""
Get authentication cookies from access token.
Parameters:
- access_token: Authentication access token
- cookies_required: Whether cookies are required for the operation
"""
def logout(self):
"""
Log out from ModelScope Hub.
"""
def create_model(
self,
model_name: str,
visibility: int = 1,
license: str = None,
**kwargs
):
"""
Create a new model repository.
Parameters:
- model_name: Name of the model repository
- visibility: Repository visibility (1=public, 0=private)
- license: License type for the model
"""
def create_dataset(
self,
dataset_name: str,
visibility: int = 1,
**kwargs
):
"""
Create a new dataset repository.
Parameters:
- dataset_name: Name of the dataset repository
- visibility: Repository visibility (1=public, 0=private)
"""
def push_model(
self,
model_id: str,
model_dir: str,
**kwargs
):
"""
Push model files to repository.
Parameters:
- model_id: Target model repository identifier
- model_dir: Local directory containing model files
"""
def list_models(
self,
owner: str = None,
page_number: int = 1,
page_size: int = 10,
**kwargs
) -> list:
"""
List models from ModelScope Hub.
Parameters:
- owner: Filter by model owner
- page_number: Page number for pagination
- page_size: Number of models per page
Returns:
List of model information dictionaries
"""
def get_model_info(self, model_id: str) -> dict:
"""
Get detailed information about a model.
Parameters:
- model_id: ModelScope model identifier
Returns:
Dictionary containing model metadata
"""Model Validation
Utilities for validating model identifiers and checking model status.
def check_model_is_id(model_id: str, token: str = None) -> bool:
"""
Validate if a string is a valid ModelScope model identifier.
Parameters:
- model_id: String to validate as model identifier
- token: Authentication token (optional)
Returns:
True if valid model ID, False otherwise
"""
def check_local_model_is_latest(
local_path: str,
model_id: str,
token: str = None
) -> bool:
"""
Check if local model version matches the latest version on Hub.
Parameters:
- local_path: Path to local model directory
- model_id: ModelScope model identifier
- token: Authentication token (optional)
Returns:
True if local model is up to date, False otherwise
"""Configuration and Repository Management
Classes for configuration management and repository operations.
class ModelScopeConfig:
"""
Configuration management for ModelScope Hub operations.
"""
def __init__(self):
"""Initialize configuration manager."""
def get_token(self) -> str:
"""Get authentication token."""
def save_token(self, token: str):
"""Save authentication token."""
class Repository:
"""
Git repository management for ModelScope repositories.
"""
def __init__(self, local_dir: str, clone_from: str = None):
"""
Initialize repository manager.
Parameters:
- local_dir: Local directory for the repository
- clone_from: Remote repository URL to clone from
"""
def git_add(self, pattern: str = None):
"""Add files to git staging area."""
def git_commit(self, message: str):
"""Commit changes to repository."""
def git_push(self):
"""Push changes to remote repository."""
class DatasetRepository(Repository):
"""
Dataset-specific repository operations.
"""
passConstants and Enums
class ModelVisibility:
PUBLIC = 5
ORGANIZATION = 3
PRIVATE = 1
class DatasetVisibility:
PUBLIC = 5
ORGANIZATION = 3
PRIVATE = 1
class Licenses:
APACHE_2_0 = "Apache License 2.0"
MIT = "MIT"
GPL_3_0 = "GPL-3.0"
# Additional license constants availableUsage Examples
Basic Model Download
from modelscope import snapshot_download
# Download a text classification model
model_dir = snapshot_download('damo/nlp_structbert_sentence-similarity_chinese')
print(f"Model downloaded to: {model_dir}")
# Download specific version
model_dir = snapshot_download(
'damo/nlp_structbert_sentence-similarity_chinese',
revision='v1.0.0'
)Upload Custom Model
from modelscope import HubApi, push_to_hub
# Initialize Hub API and login
api = HubApi()
api.login('your_token_here')
# Create model repository
api.create_model('my-awesome-model', visibility=1)
# Upload model files
push_to_hub(
repo_name='my-awesome-model',
output_dir='./my_model_directory',
commit_message='Initial model upload'
)Check Model Status
from modelscope import check_model_is_id, check_local_model_is_latest
# Validate model ID
is_valid = check_model_is_id('damo/nlp_structbert_sentence-similarity_chinese')
# Check if local model is up to date
is_latest = check_local_model_is_latest(
'./local_model_dir',
'damo/nlp_structbert_sentence-similarity_chinese'
)Install with Tessl CLI
npx tessl i tessl/pypi-modelscope