GPUStack Operator

Model Delivery

ModelArtifact gives model weights a stable identity. Delivery uses an engine, node cache, PersistentVolumeClaim or image. A workload can reference the artifact instead of repeating its source.

Contents

Overview

Model delivery and node cache flow

Model Artifact defines the sources and delivery choices. Remote Weight Delivery describes loading from a prepared source node.

Configuration

Use the annotated artifact example to select a source and filters. Model Image Source defines image-backed weights. Model Prefetch defines cache grants and warm-up requests.

For a complete example, follow the Model Prefetch Walkthrough .

Operations

Step 1: Configure cache

Follow Model Store Operations to configure node delivery. Node Model Store defines node cache state and the plugin.

Step 2: Inspect delivery

Inspect the artifact and node stores:

bash
kubectl -n <namespace> get modelartifact <artifact-name> -o yaml
kubectl get nodemodelstores

Verification: Check the artifact’s Resolved condition and the node cache status. See Model Artifact Status and Node Model Store . The Model Artifact API describes progress views. Node-to-Node Sync describes peer status and metrics.

Troubleshooting

If weights do not reach a deployment, inspect the artifact and deployment conditions:

bash
kubectl -n <namespace> describe modelartifact <artifact-name>
kubectl -n <namespace> get modeldeployment <deployment-name> -o yaml

If a serving Pod exists, inspect its events with kubectl -n <namespace> describe pod <pod-name>.

Condition Reason Resolution
WeightsReady=False NodeDeliveryUnavailable Check modelManager.enabled and the model.csi.gpustack.ai CSIDriver.
WeightsReady=False FilterNeedsNodeDelivery Check the delivery setting and artifact patterns.

Use Model Store Troubleshooting for more symptoms and recovery checks. For remote loading failures, see Remote Weight Delivery .