Deploy a Custom Harmonizer Checkpoint

Use Bring Your Own Checkpoint (BYOC) to deploy a fine-tuned Harmonizer checkpoint instead of the release-approved default.

Prerequisites

The checkpoint must be a Harmonizer source .pkl artifact compatible with the packaged runtime. These are torch.save state-dict files (containing state_dict_unet and state_dict_vae) for the same Pix2Pix_Turbo / Harmonizer model architecture as the default checkpoint, served in bfloat16 (BF16) precision.

Single-file training deltas and adapter-only artifacts are not supported until they are merged into a full Harmonizer checkpoint.

For Docker, complete the registry login and environment setup in Quickstart for Harmonizer NIM. Export IMG_NAME, LOCAL_NIM_CACHE, and NGC_API_KEY in the terminal where you start the container.

For Helm, prepare the chart and common values in Deploy Harmonizer NIM with Helm.

Deploy the Checkpoint with Docker

Complete these steps to mount a local checkpoint read-only and start the NIM:

Prepare the checkpoint directory and verify its default file name.

Mount the checkpoint directory and point NIM_FT_CHECKPOINT at it. The runtime loads diffusion_harmonizer.pkl from the BYOC root by default:
```
export HARMONIZER_BYOC_PATH=/path/to/harmonizer-checkpoint
test -f "$HARMONIZER_BYOC_PATH/diffusion_harmonizer.pkl"
chmod -R a+rX "$HARMONIZER_BYOC_PATH"
```
Optional: Set a different checkpoint file path in the Docker command.

With BYOC set, the mounted checkpoint defaults to /byoc/diffusion_harmonizer.pkl. If the file has a different name or location, set HARMONIZER_PKL_MODEL_PATH to its full in-container path. Add the variable before the image name in the Docker command:
```
-e NIM_FT_CHECKPOINT=/byoc \
-e HARMONIZER_PKL_MODEL_PATH=/byoc/my_harmonizer.pkl
```
Both processing modes (non-temporal V=1 and temporal V=5) use the single BYOC checkpoint. The runtime applies the same fixed-shape optimization path as the default deployment. Measure quality and performance with your deployed checkpoint.
Start the NIM with the checkpoint mounted read-only.

The container runs as UID 1000. Every directory inside the mounted checkpoint tree must be traversable and the checkpoint file must be readable by that user. The a+rX mode grants read and directory-traversal access without making the checkpoint writable. Keep the model mount read-only and keep the NIM cache as a separate writable mount.
```
docker run -it --rm --name harmonizer-byoc \
   --runtime=nvidia \
   --gpus all \
   --shm-size=8g \
   --ulimit memlock=-1 \
   --ulimit stack=67108864 \
   -e NGC_API_KEY \
   -e NIM_FT_CHECKPOINT=/byoc \
   -v "$HARMONIZER_BYOC_PATH:/byoc:ro" \
   -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
   -p 8000:8000 \
   $IMG_NAME
```

Deploy the Checkpoint with Helm

Complete these steps to mount an existing checkpoint persistent volume claim (PVC) and install the chart:

Create a checkpoint PVC and write byoc-values.yaml.

Create a PVC that contains diffusion_harmonizer.pkl and make the claim available in the namespace where you install the NIM. Keep this checkpoint claim separate from the writable NIM cache. For example, add the following byoc-values.yaml override to the common values in Deploy Harmonizer NIM with Helm:

imagePullSecrets:
  - name: ngc-secret
model:
  ngcAPISecret: ""
  nimCache: /model-store
persistence:
  enabled: true
  size: 60Gi
extraVolumes:
  harmonizer-byoc:
    persistentVolumeClaim:
      claimName: harmonizer-byoc
extraVolumeMounts:
  harmonizer-byoc:
    mountPath: /opt/nim/byoc
    readOnly: true
env:
  - name: NIM_FT_CHECKPOINT
    value: /opt/nim/byoc

Give container UID 1000 read access to the checkpoint and write access to the separate cache.

The harmonizer-byoc claim must already exist and contain the checkpoint. The chart mounts it read-only at /opt/nim/byoc. Setting NIM_FT_CHECKPOINT makes the runtime use the BYOC checkpoint instead of downloading the release checkpoint, so model.ngcAPISecret can be empty. Keep imagePullSecrets configured because pulling the NIM container from a private NGC registry still requires registry credentials.

Provision the checkpoint volume so UID 1000 can traverse its directories and read the checkpoint file. The checkpoint claim does not need to be writable. Configure the separate cache volume so UID 1000 can write to it.
Optionally set a nondefault checkpoint file path in byoc-values.yaml.

The persistent volume configured by persistence is a separate, writable cache. The chart mounts that volume at model.nimCache and sets NIM_CACHE_PATH to the same path. The NIM can therefore retain downloaded dependencies and compiled artifacts without writing to the checkpoint PVC. Do not set NIM_CACHE_PATH again through env.

If the checkpoint file has a different name or a nested location on the PVC, add its full mounted path to the same override:
```
env:
  - name: NIM_FT_CHECKPOINT
    value: /opt/nim/byoc
  - name: HARMONIZER_PKL_MODEL_PATH
    value: /opt/nim/byoc/my_harmonizer.pkl
```
Install the chart with the common values and BYOC override.

Install the chart with the common values first and the BYOC override second:
```
helm install harmonizer-nim nim-wfm-1.3.0.tgz \
   -f custom-values.yaml \
   -f byoc-values.yaml
```

Verify the Deployment

For Helm deployments, forward the HTTP service port before running the checks:

kubectl port-forward service/harmonizer-nim-nim-wfm 8000:http-api

Keep port forwarding running in that terminal. Run the checks from a second terminal on the same host. Docker deployments already publish port 8000. Ensure that a previous deployment does not occupy this port.

Check readiness, then send one image to confirm that the checkpoint produces output:

Check the NIM readiness endpoint after startup.
```
curl http://localhost:8000/v1/health/ready
```
Send a sample request as shown in Quickstart for Harmonizer NIM.

A valid output image confirms that the checkpoint loaded and produces output.