Skip to main content
Version: 0.6.6

swcli model

Overview​

swcli [GLOBAL OPTIONS] model [OPTIONS] <SUBCOMMAND> [ARGS]...

The model command includes the following subcommands:

  • build
  • copy(cp)
  • diff
  • extract
  • history
  • info
  • list(ls)
  • recover
  • remove(rm)
  • run
  • serve
  • tag

swcli model build​

swcli [GLOBAL OPTIONS] model build [OPTIONS] <WORKDIR>

model build will put the whole WORKDIR into the model, except files that match patterns defined in .swignore.

model build will import modules specified by --module to generate the required configurations to run the model. If your module depends on third-party libraries, we strongly recommend you use the --runtime option; otherwise, you need to ensure that the python environment used by swcli has these libraries installed.

OptionRequiredTypeDefaultsDescription
--project or -pNStringthe default projectthe project URI
--model-yaml or -fNString${workdir}/model.yamlmodel yaml path, default use ${workdir}/model.yaml file. model.yaml is optional for model build.
--module or -mNStringPython modules to be imported during the build process. Starwhale will export model handlers from these modules to the model package. This option supports set multiple times.
--runtime or -rNStringthe URI of the Starwhale Runtime to use when running this command. If this option is used, this command will run in an independent python environment specified by the Starwhale Runtime; otherwise, it will run directly in the swcli's current python environment.
--name or -nNStringmodel package name
--desc or -dNStringmodel package description
--package-runtime 或 --no-package-runtimeNBooleanTrueWhen using the --runtime parameter, by default, the corresponding Starwhale runtime will become the built-in runtime for the Starwhale model. This feature can be disabled with the --no-package-runtime parameter.
--add-allNBooleanFalseAdd all files in the working directory to the model package(excludes python cache files and virtual environment files when disabled).The .swignore file still takes effect.
-t or --tagNGlobalString

Examples for model build​

# build by the model.yaml in current directory and model package will package all the files from the current directory.
swcli model build .
# search model run decorators from mnist.evaluate, mnist.train and mnist.predict modules, then package all the files from the current directory to model package.
swcli model build . --module mnist.evaluate --module mnist.train --module mnist.predict
# build model package in the Starwhale Runtime environment.
swcli model build . --module mnist.evaluate --runtime pytorch/version/v1
# forbid to package Starwhale Runtime into the model.
swcli model build . --module mnist.evaluate --runtime pytorch/version/v1 --no-package-runtime
# build model package with tags.
swcli model build . --tag tag1 --tag tag2

swcli model copy​

swcli [GLOBAL OPTIONS] model copy [OPTIONS] <SRC> <DEST>

model copy copies from SRC to DEST for Starwhale Model sharing.

SRC and DEST are both model URIs.

When copying Starwhale Model, all custom user-defined labels will be copied by default. You can use the --ignore-tag parameter to ignore certain labels. In addition, the latest and ^v\d+$ labels are Starwhale built-in labels that are only used within the instance itself and will not be copied to other instances.

OptionRequiredTypeDefaultsDescription
--force or -fNBooleanFalseIf true, DEST will be overwritten if it exists. In addition, if the labels carried during duplication have already been used by other versions, this parameter can be used to forcibly update the labels to this version.
-i or --ignore-tagNStringIgnore tags to copy. The option can be used multiple times.

Examples for model copy​

#- copy cloud instance(pre-k8s) mnist project's mnist-cloud model to local project(myproject) with a new model name 'mnist-local'
swcli model cp cloud://pre-k8s/project/mnist/mnist-cloud/version/ge3tkylgha2tenrtmftdgyjzni3dayq local/project/myproject/mnist-local

#- copy cloud instance(pre-k8s) mnist project's mnist-cloud model to local default project(self) with the cloud instance model name 'mnist-cloud'
swcli model cp cloud://pre-k8s/project/model/mnist/mnist-cloud/version/ge3tkylgha2tenrtmftdgyjzni3dayq .

#- copy cloud instance(pre-k8s) mnist project's mnist-cloud model to local project(myproject) with the cloud instance model name 'mnist-cloud'
swcli model cp cloud://pre-k8s/project/mnist/mnist-cloud/version/ge3tkylgha2tenrtmftdgyjzni3dayq . -dlp myproject

#- copy cloud instance(pre-k8s) mnist project's mnist-cloud model to local default project(self) with a model name 'mnist-local'
swcli model cp cloud://pre-k8s/project/model/mnist/mnist-cloud/version/ge3tkylgha2tenrtmftdgyjzni3dayq mnist-local

#- copy cloud instance(pre-k8s) mnist project's mnist-cloud model to local project(myproject) with a model name 'mnist-local'
swcli model cp cloud://pre-k8s/project/mnist/mnist-cloud/version/ge3tkylgha2tenrtmftdgyjzni3dayq mnist-local -dlp myproject

#- copy standalone instance(local) default project(self)'s mnist-local model to cloud instance(pre-k8s) mnist project with a new model name 'mnist-cloud'
swcli model cp mnist-local/version/latest cloud://pre-k8s/project/mnist/mnist-cloud

#- copy standalone instance(local) default project(self)'s mnist-local model to cloud instance(pre-k8s) mnist project with standalone instance model name 'mnist-local'
swcli model cp mnist-local/version/latest cloud://pre-k8s/project/mnist

#- copy standalone instance(local) default project(self)'s mnist-local model to cloud instance(pre-k8s) mnist project without 'cloud://' prefix
swcli model cp mnist-local/version/latest pre-k8s/project/mnist

#- copy standalone instance(local) project(myproject)'s mnist-local model to cloud instance(pre-k8s) mnist project with standalone instance model name 'mnist-local'
swcli model cp local/project/myproject/model/mnist-local/version/latest cloud://pre-k8s/project/mnist

#- copy without some tags
swcli model cp mnist cloud://cloud.starwhale.cn/project/starwhale:public --ignore-tag t1

swcli model diff​

swcli [GLOBAL OPTIONS] model diff [OPTIONS] <MODEL VERSION> <MODEL VERSION>

model diff compares the difference between two versions of the same model.

MODEL VERSION is a model URI.

OptionRequiredTypeDefaultsDescription
--show-detailsNBooleanFalseIf true, outputs the detail information.

swcli model extract​

swcli [GLOBAL OPTIONS] model extract [OPTIONS] <MODEL> <TARGET_DIR>

The model extract command can extract a Starwhale model to a specified directory for further customization.

MODEL is a model URI.

OptionRequiredTypeDefaultDescription
--force or -fNBooleanFalseIf this option is used, it will forcibly overwrite existing extracted model files in the target directory.

Examples for model extract​

#- extract mnist model package to current directory
swcli model extract mnist/version/xxxx .

#- extract mnist model package to current directory and force to overwrite the files
swcli model extract mnist/version/xxxx . -f

swcli model history​

swcli [GLOBAL OPTIONS] model history [OPTIONS] <MODEL>

model history outputs all history versions of the specified Starwhale Model.

MODEL is a model URI.

OptionRequiredTypeDefaultsDescription
--fullnameNBooleanFalseShow the full version name. Only the first 12 characters are shown if this option is false.

swcli model info​

swcli [GLOBAL OPTIONS] model info [OPTIONS] <MODEL>

model info outputs detailed information about the specified Starwhale Model version.

MODEL is a model URI.

OptionRequiredTypeDefaultsDescription
--output-filter or -ofNChoice of [basic/model_yaml/manifest/files/handlers/all]basicFilter the output content. Only standalone instance supports this option.

Examples for model info​

swcli model info mnist # show basic info from the latest version of model
swcli model info mnist/version/v0 # show basic info from the v0 version of model
swcli model info mnist/version/latest --output-filter=all # show all info
swcli model info mnist -of basic # show basic info
swcli model info mnist -of model_yaml # show model.yaml
swcli model info mnist -of handlers # show model runnable handlers info
swcli model info mnist -of files # show model package files tree
swcli -o json model info mnist -of all # show all info in json format

swcli model list​

swcli [GLOBAL OPTIONS] model list [OPTIONS]

model list shows all Starwhale Models.

OptionRequiredTypeDefaultsDescription
--projectNStringThe URI of the project to list. Use the default project if not specified.
--fullnameNBooleanFalseShow the full version name. Only the first 12 characters are shown if this option is false.
--show-removedNBooleanFalseIf true, include packages that are removed but not garbage collected.
--pageNInteger1The starting page number. Server and cloud instances only.
--sizeNInteger20The number of items in one page. Server and cloud instances only.
--filter or -flNStringShow only Starwhale Models that match specified filters. This option can be used multiple times in one command.
FilterTypeDescriptionExample
nameKey-ValueThe name prefix of models--filter name=mnist
ownerKey-ValueThe model owner name--filter owner=starwhale
latestFlagIf specified, it shows only the latest version.--filter latest

swcli model recover​

swcli [GLOBAL OPTIONS] model recover [OPTIONS] <MODEL>

model recover recovers previously removed Starwhale Models or versions.

MODEL is a model URI. If the version part of the URI is omitted, all removed versions are recovered.

Garbage-collected Starwhale Models or versions can not be recovered, as well as those are removed with the --force option.

OptionRequiredTypeDefaultsDescription
--force or -fNBooleanFalseIf true, overwrite the Starwhale Model or version with the same name or version id.

swcli model remove​

swcli [GLOBAL OPTIONS] model remove [OPTIONS] <MODEL>

model remove removes the specified Starwhale Model or version.

MODEL is a model URI. If the version part of the URI is omitted, all versions are removed.

Removed Starwhale Models or versions can be recovered by swcli model recover before garbage collection. Use the --force option to persistently remove a Starwhale Model or version.

Removed Starwhale Models or versions can be listed by swcli model list --show-removed.

OptionRequiredTypeDefaultsDescription
--force or -fNBooleanFalseIf true, persistently delete the Starwhale Model or version. It can not be recovered.

swcli model run​

swcli [GLOBAL OPTIONS] model run [OPTIONS]

model run executes a model handler. Model run supports two modes to run: model URI and local development. Model URI mode needs a pre-built Starwhale Model Package. Local development model only needs the model src dir.

OptionRequiredTypeDefaultsDescription
--workdir or -wNStringFor local development mode, the path of model src dir.
--uri or -uNStringFor model URI mode, the string of model uri.
--handler or -hNStringRunnable handler index or name, default is None, will use the first handler
--module or -mNStringThe name of the Python module to import. This parameter can be set multiple times.
--runtime or -rNStringthe Starwhale Runtime URI to use when running this command. If this option is used, this command will run in an independent python environment specified by the Starwhale Runtime; otherwise, it will run directly in the swcli's current python environment.
--model-yaml or -fNString${MODEL_DIR}/model.yamlThe path to the model.yaml. model.yaml is optional for model run.
--run-project or -pNStringDefault projectProject URI, indicates the model run results will be stored in the corresponding project.
--dataset or -dNStringDataset URI, the Starwhale dataset required for model running. This parameter can be set multiple times.
--dataset-head or -dhNInteger0[ONLY STANDALONE]For debugging purpose, every prediction task will, at most, consume the first n rows from every dataset.When the value is less than or equal to 0, all samples will be used.
--in-containerNBooleanFalseUse docker container to run the model. This option is only available for standalone instances. For server and cloud instances, a docker image is always used. If the runtime is a docker image, this option is always implied.
--forbid-snapshot or -fsNBooleanFalseIn model URI mode, each model run uses a new snapshot directory. Setting this parameter will directly use the model's workdir as the run directory. In local dev mode, this parameter does not take effect, each run is in the --workdir specified directory.
-- --user-arbitrary-argsNStringSpecify the args you defined in your handlers.

Examples for model run​

# --> run by model uri
# run the first handler from model uri
swcli model run -u mnist/version/latest
# run index id(1) handler from model uri
swcli model run --uri mnist/version/latest --handler 1
# run index fullname(mnist.evaluator:MNISTInference.cmp) handler from model uri
swcli model run --uri mnist/version/latest --handler mnist.evaluator:MNISTInference.cmp

# --> run by the working directory, which does not build model package yet. Make local debug happy.
# run the first handler from the working directory, use the model.yaml in the working directory
swcli model run -w .
# run index id(1) handler from the working directory, search mnist.evaluator module and model.yaml handlers(if existed) to get runnable handlers
swcli model run --workdir . --module mnist.evaluator --handler 1
# run index fullname(mnist.evaluator:MNISTInference.cmp) handler from the working directory, search mnist.evaluator module to get runnable handlers
swcli model run --workdir . --module mnist.evaluator --handler mnist.evaluator:MNISTInference.cmp
# run the f handler in th.py from the working directory with the args defined in th:f
# @handler()
# def f(
# x=ListInput(IntInput()),
# y=2,
# mi=MyInput(),
# ds=DatasetInput(required=True),
# ctx=ContextInput(),
# )
swcli model run -w . -m th --handler th:f -- -x 2 -x=1 --mi=blab-la --ds mnist

# --> run with dataset of head 10
swcli model run --uri mnist --dataset-head 10 --dataset mnist

swcli model serve​

Here is the English translation:

swcli [GLOBAL OPTIONS] model serve [OPTIONS]

The model serve command can run the model as a web server, and provide a simple web interaction interface.

OptionRequiredTypeDefaultsDescription
--workdir or -wNStringIn local dev mode, specify the directory of the model code.
--uri or -uNStringIn model URI mode, specify the model URI.
--runtime or -rNStringThe URI of the Starwhale runtime to use when running this command. If specified, the command will run in the isolated Python environment defined in the Starwhale runtime. Otherwise it will run directly in the current Python environment of swcli.
--model-yaml or -fNString${MODEL_DIR}/model.yamlThe path to the model.yaml. model.yaml is optional for model serve.
--module or -mNStringName of the Python module to import. This parameter can be set multiple times.
--hostNString127.0.0.1The address for the service to listen on.
--portNInteger8080The port for the service to listen on.

Examples for model serve​

swcli model serve -u mnist
swcli model serve --uri mnist/version/latest --runtime pytorch/version/latest

swcli model serve --workdir . --runtime pytorch/version/v0
swcli model serve --workdir . --runtime pytorch/version/v1 --host 0.0.0.0 --port 8080
swcli model serve --workdir . --runtime pytorch --module mnist.evaluator

swcli model tag​

swcli [GLOBAL OPTIONS] model tag [OPTIONS] <MODEL> [TAGS]...

model tag attaches a tag to a specified Starwhale Model version. At the same time, tag command also supports list and remove tags. The tag can be used in a model URI instead of the version id.

MODEL is a model URI.

Each model version can have any number of tags, but duplicated tag names are not allowed in the same model.

model tag only works for the Standalone Instance.

OptionRequiredTypeDefaultsDescription
--remove or -rNBooleanFalseremove the tag if true
--quiet or -qNBooleanFalseignore errors, for example, removing tags that do not exist.
--force-add or -fNBooleanFalseWhen adding labels to server/cloud instances, if the label is already used by another model version, an error will be prompted. In this case, you can force an update using the --force-add parameter.

Examples for model tag​

#- list tags of the mnist model
swcli model tag mnist

#- add tags for the mnist model
swcli model tag mnist t1 t2
swcli model tag cloud://cloud.starwhale.cn/project/public:starwhale/model/mnist/version/latest t1 --force-add
swcli model tag mnist t1 --quiet

#- remove tags for the mnist model
swcli model tag mnist -r t1 t2
swcli model tag cloud://cloud.starwhale.cn/project/public:starwhale/model/mnist --remove t1