A model version is the smallest deployable unit of a model asset, corresponding to a specific training artifact. DataBuddy model version management is organized in Catalog as catalog.schema.model_name/<version>, providing capabilities for version registration, viewing, copying, deletion, and complete metadata display.
Prerequisites
You already have the USE CATALOG and USE SCHEMA privileges on the target Catalog and Schema.
Registering a new model requires the CREATE MODEL privilege. Registering a new version for an existing model requires the CREATE MODEL VERSION privilege.
Registered models must include a Model signature: when using mlflow.<flavor>.log_model(), explicitly pass it through the signature= parameter; when fe.log_model() from the feature engineering SDK is used, it is automatically inferred from training_set.feature_spec. Do not rely on Autologging's automatic signature inference, as it does not guarantee signature generation for certain flavors (such as custom PyFunc) or training data containing the decimal type, which can cause registration to fail.
Deleting a version requires the DELETE privilege on the corresponding model.
Note:
If a model is registered without a signature, the registration will fail with an error. Additionally, a missing signature will cause automatic feature completion to fail for subsequent score_batch and online inference. Confirm that the signature has been written during the training or logging stage before registering the model.
Registering a New Version
Method 1: Registering via Feature Engineering SDK
If a model has feature tables joined through create_training_set during training, you must register it using fe.log_model() from the feature engineering SDK. It is the only method that writes feature_spec.yaml and supports the feature consumption pipeline, including automatic lookup by score_batch and automatic completion during online inference.
from wedata.feature_engineering.client import FeatureEngineeringClient
fe = FeatureEngineeringClient(spark)
fe.log_model(
model=model,
artifact_path="model",
flavor=mlflow.sklearn,
training_set=training_set, # Carries the feature source and writes it to feature_spec.yaml
registered_model_name="catalog.schema.model_name",
infer_input_example=True,
)
fe.log_model() completes version registration while logging the model, and automatically infers the model signature and input_example based on training_set.feature_spec. For complete usage, see Feature Engineering SDK.Method 2: Registering via UI
The registration entry is located on the experiment run details page:
1. Go to Data Science → Model Experiments, and open the details page of the target experiment Run.
2. In the upper-right corner, click Register Model.
3. In the dialog, select New Version of Existing Model, and then choose the target model from the dropdown list. The version number will automatically increment based on the current maximum version of that model.
4. Click Register Model to complete the registration.
To create a new model, select New Model in the dialog and enter a name following the catalog.schema.modelname convention. If the model name already exists, a message will appear stating, "The current model has already been registered. Please register a new version of this model."
Version Details
There are two ways to access the model details page:
In the Model List, click a model name to go to the model details page, and then click a specific version number in the version list.
In Data Catalog, navigate through the path catalog → schema → model → version.
1. Overview
You can edit the current version at the top of the Overview Tab:
Add Description: Supplement the version description to help the team identify the purpose of the version.
Add Owner: Assign an owner to the version.
Add Tag: Tag the version to facilitate search and lifecycle management. For details, see Model Tags and Lifecycle.
The Overview Tab displays the metrics and training parameters from the experiment run that produced this version. You can click Source Run to go to the corresponding run details. In Activity Log, key events such as registration, copying, and deletion of this version are recorded in reverse chronological order for audit and traceability. This will be extended to scenarios such as model deployment and automatic deployment jobs. You can also query model metrics, parameters, and version signatures.
2. Lineage
Lineage shows the relationships between model versions and upstream and downstream assets, with two views supported:
List mode: Displays a one-level list of upstream and downstream assets.
Upstream node types: data tables and feature tables (Table). Process types: Notebook and Studio.
Downstream node types: data tables and inference tables (Table). Process types: model services (Process).
Lineage graph mode: Displays the complete chain in graph form, with nodes that support click-through navigation:
Model nodes support switching between different versions.
The model service node displays the model name, creator, registration time, and version creation time. Click the service name to go to the model service details.
The inference table node information is consistent with that of a regular data table. Click to go to the table details.
Lineage data is provided by the unified Catalog query API. It is reported by each module during model registration and service deployment.
3. Model Artifacts
Artifacts are displayed in a tree structure, showing model-related files such as MLmodel, conda.yaml, python_env.yaml, and model weights:
Click a folder to expand its subitems.
Click a single file to display a preview of its content on the right.
Files can be downloaded locally.
4. Copying a Version
Cross-model version copying can be used to quickly distribute an existing version to a Catalog or Schema, making it suitable for multi-environment (development and production) or cross-project sharing scenarios.
1. In the upper-right corner of the version details page, click Copy This Version.
2. Select the target model in the dialog box. You can directly enter keywords to filter. The target model can be the source model itself (that is, a new version copied under the same model) or another model under the same Catalog / Schema.
3. Click Copy.
5. Deleting a Version
In the upper-right corner of the version details page, click Delete This Version, ** click Confirm Delete** to delete it.
Warning
Deleted versions cannot be recovered. If the version is referenced by an online inference service, remove the deployment relationship before deletion to avoid impacting the online service.
Managing Versions via Code
The DataBuddy model version management APIs are compatible with the MLflow standard API. Commonly used APIs:
API | Description |
mlflow.register_model(model_uri, name)
| Register a model or a new version. |
mlflow.search_model_versions(filter_string)
| Search versions by filter criteria. |
mlflow.search_registered_models(filter_string)
| Search registered models by filter criteria. |
MlflowClient.delete_model_version(name, version)
| Delete a model version. |
Note:
To delete a model version, you need to import MlflowClient.
When running in DataBuddy Notebook, the kernel automatically injects temporary credentials and completes the connection configuration for Tracking / Registry. You do not need to manually set the URI and can directly call the APIs mentioned above:
import mlflow
# The DataBuddy Notebook kernel has automatically configured Tracking / Registry, so you can use it directly.
mlflow.register_model(model_uri="runs:/<run_id>/model", name="catalog.schema.model_name")
Tip
To use it in an environment outside DataBuddy Notebook (such as a local environment), you need to manually configure the Tracking / Registry URI pointing to DataBuddy and the authentication information. For specific values, see the platform connection instructions.
Use Limits
Version numbers increment automatically within the same model, and manual specification of version numbers is not supported.
Cross-Catalog version copying is available only when the current user has read permission on the source version and CREATE MODEL VERSION permission on the target model.
Before deleting a version that is referenced by an existing deployment service, unbind the version on the model service side first to avoid runtime errors.
Artifact display and download rely on the underlying Catalog and COS capabilities. Loading delays may occur for oversized artifacts.
FAQs
Q: The version is registered successfully, but the Metrics Tab is empty?
A: Metrics come from the source experiment run (Source Run). Check whether the source run has recorded metrics. If model_uri comes from an external source when mlflow.register_model(model_uri=...) is used and is not associated with an experiment run, the metrics will be empty.
Q: Why can't I see downstream model services in the lineage graph?
A: Downstream lineage of model services needs to be reported by the deployment side. Confirm that this version has been deployed through Model Service, and refresh the lineage view. Q: Can I roll back to the source version after copying a version?
A: Yes. Copying does not modify the source version, and the source version is completely independent of the new version. If you need to roll back, you can change the deployment target back to the source version in the model service.
References
Model Tags and Lifecycle