Managing models

Managing models

After creating a model registry, you can manage models in it using different methods depending on the registry type.

• Hugging Face model registry: Models are stored on the Hugging Face platform. Refer to the Hugging Face official documentation to manage models.

• File system model registry: Models are stored locally. Use the Neutree CLI tool to push, list, or delete models as described in this section. You can also download models from Hugging Face and push them to a file system model registry.

Prerequisites

Before managing models in a file system model registry, complete the following:

1. Download version 1.1.0 of the Neutree CLI tool for your server’s CPU architecture.

   Note

   Neutree CLI tool communicates with Neutree via HTTP API. Ensure network connectivity between the CLI tool and Neutree.

2. Grant executable permission to the CLI tool.

   chmod +x neutree-cli-<arch>

   You can view the help information for the tool with the following command:

   neutree-cli-<arch> model -h

3. Create an API key and save it securely.

Pushing a model

Use the Neutree CLI tool to push a local model to a file system model registry:

neutree-cli-<arch> model push <local_model_dir> \
  -n <model_name> \
  -d [model_description] \
  -v [model_version] \
  -r <model_registry> \
  -w [workspace] \
  --api-key <api_key> \
  --server-url <server_url>

Parameter descriptions:

Parameter	Description
<local_model_dir>	The local directory where the model is stored.
<model_name>	The name under which the model is stored in the model registry. The name must consist of lowercase letters, digits, _, -, or ., be no longer than 63 characters, and must start and end with a letter or digit. If you use a model catalog when creating an endpoint, ensure the model name set here matches the model name in the model catalog.
[model_description]	Optional. A description of the model.
[model_version]	Optional. The version of the model. If left blank, the system generates one automatically. Multiple versions of a model with the same name can exist in a model registry.
<model_registry>	The name of the target model registry.
[workspace]	Optional. The name of the workspace. Defaults to the default workspace if left blank.
<api_key>	The API key created in the prerequisites.
<server_url>	The address of the control plane, for example http://localhost:3000.

If the target model registry is a file system model registry that starts with nfs://, and the node where the model is located can directly access the NFS storage, the transfer speed is faster than routing through the Neutree control plane. You can mount the target NFS path on that node and run the following command to import the model directly:

neutree-cli-<arch> model push <local_model_dir> \
  -n <model_name> \
  -v [model_version] \
  -r <model_registry> \
  -w [workspace] \
  --local-nfs-path <local_nfs_path> \
  [--skip-local-nfs-mount-check] \
  --api-key <api_key> \
  --server-url <server_url>

Parameter descriptions:

Parameter	Description
<local_nfs_path>	The local mount directory of the NFS source corresponding to the target model registry. The user running the command must have write permission on this directory.
--skip-local-nfs-mount-check	Optional. If configured, the NFS mount source check is skipped. You can configure this parameter when the command is run on the NFS server and <local_nfs_path> points to the export root directory of the model registry instead of a local mount point. Make sure that <local_nfs_path> corresponds to the export root directory of the model registry. Otherwise, endpoints may fail to read the model.

Viewing models

Use the following command to view models in a file system model registry:

neutree-cli-<arch> model list -r <model_registry> \
  -w [workspace] \
  --api-key <api_key> \
  --server-url <server_url>

Parameter descriptions:

Parameter	Description
<model_registry>	The name of the target model registry.
[workspace]	Optional. The name of the workspace. Defaults to the default workspace if left blank.
<api_key>	The API key created in the prerequisites.
<server_url>	The address of the control plane, for example http://localhost:3000.

Deleting a model

Prerequisites

• Check Viewing models to retrieve the version of the model to delete.
• Confirm that no endpoints are currently using the model version to be deleted.
• Confirm that no endpoints are using the latest version or have no version specified when using this model.

Procedure

Use the following command to delete a model from a file system model registry:

neutree-cli-<arch> model delete <model_name>:<model_version> \
  -r <model_registry> \
  -w [workspace] \
  --api-key <api_key> \
  --server-url <server_url>

Parameter descriptions:

Parameter	Description
<model_name>	The name of the model in the model registry.
<model_version>	The version of the model.
<model_registry>	The name of the target model registry.
[workspace]	Optional. The name of the workspace. Defaults to the default workspace if left blank.
<api_key>	The API key created in the prerequisites.
<server_url>	The address of the control plane, for example http://localhost:3000.

Downloading a model from Hugging Face

Skip this section for file system model registries.

1. Install the Hugging Face CLI tool. Refer to the Hugging Face official documentation.

2. Log in to Hugging Face:

   hf auth login

3. Use the hf download command to download a model to a local directory. The following examples cover common scenarios:

   • Downloading a complete model

     Downloads the complete model from Hugging Face to a local directory, for example, downloading the Qwen/Qwen3-0.6B model to ./test-model:

     hf download Qwen/Qwen3-0.6B --local-dir ./test-model

   • Selectively downloading specific files

     For large model repositories, use --include and --exclude to control what is downloaded:

     • Download only a specific precision variant. For example, download only the Q8.0 GGUF model:

       hf download microsoft/Phi-3-mini-4k-instruct-gguf \
         --include "*q8_0.gguf" \
         --local-dir ./phi3-q8

     • Download multiple types of key files. For example, download the Q8.0 model along with configuration files:

       hf download microsoft/Phi-3-mini-4k-instruct-gguf \
         --include "*q8_0.gguf" \
         --include "*.json" \
         --include "*.txt" \
         --local-dir ./phi3-q8

     • Exclude unnecessary large files. For example, download Qwen/Qwen3-0.6B but exclude large weight files:

       hf download Qwen/Qwen3-0.6B \
         --exclude "*.safetensors" \
         --exclude "pytorch_model.bin" \
         --local-dir ./qwen3-lightweight

After downloading the model to a local directory and completing the prerequisites, you can push, view, or delete models as needed.