[Feat][Helm] Add vllmConfig.revision for HuggingFace model version pinning (#961)

* [Feat][Helm] Add vllmConfig.revision for HuggingFace model version pinning

Add a `revision` field to `vllmConfig` that maps to vLLM's `--revision`
flag, allowing operators to pin deployed models to a specific HuggingFace
Hub branch, tag, or commit hash. Without this, vLLM always pulls the
latest commit on the default branch, which can silently change model
behaviour across re-deploys.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Roberto Barreda <roberto.barreda@midokura.com>

* [Feat][Helm] fix pre-commit checks

Signed-off-by: Roberto Barreda <roberto.barreda@midokura.com>

* feat(helm): promote modelRevision to top-level model spec field

Move revision pinning from vllmConfig.revision to modelRevision at the
model spec level, making it a first-class field on each model entry.

- Add modelRevision to modelSpec defaults and schema
- Update deployment-vllm-multi and ray-cluster templates to read
  $modelSpec.modelRevision
- Update tests to use modelRevision instead of vllmConfig.revision
- Update docs to reference modelRevision
- Add llama3 example entry to values-01 with pinned revision

modelRevision for meta-llama/Llama-3.1-8B-Instruct obtained via:
  curl -s https://huggingface.co/api/models/meta-llama/Llama-3.1-8B-Instruct | yq -p json '.sha'

Signed-off-by: Roberto Barreda <roberto.barreda@midokura.com>

---------

Signed-off-by: Roberto Barreda <roberto.barreda@midokura.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Rui Zhang <51696593+ruizhang0101@users.noreply.github.com>

Author: 3 people

docs/source/deployment/helm.rst

@@ -45,6 +45,7 @@ Explanation of Key Items in ``values-02-basic-config.yaml``
   - ``maxModelLen``: The maximum sequence length the model can handle.
   - ``dtype``: Data type for computations, e.g., ``bfloat16`` for faster performance on modern GPUs.
   - ``extraArgs``: Additional arguments passed to the vLLM engine for fine-tuning behavior.
+  - ``modelRevision``: Hugging Face model revision (branch, tag, or commit hash) to pin the exact model version downloaded at deployment time.
 
 - **hf_token**: The Hugging Face token for authenticating with the Hugging Face model hub.
 - **env**: Extra environment variables to pass to the model-serving engine.

helm/templates/deployment-vllm-multi.yaml

@@ -197,6 +197,10 @@ spec:
           {{-     end }}
           {{-   end }}
           {{- end }}
+          {{- if $modelSpec.modelRevision }}
+          - "--revision"
+          - {{ $modelSpec.modelRevision | quote }}
+          {{- end }}
           {{- if $modelSpec.lmcacheConfig }}
           {{-   if $modelSpec.lmcacheConfig.enabled }}
           {{-     if hasKey $modelSpec.lmcacheConfig "enablePD" }}

helm/templates/ray-cluster.yaml

@@ -635,6 +635,9 @@ data:
     ARGS+=({{ . | quote }})
       {{- end }}
     {{- end }}
+    {{- if $modelSpec.modelRevision }}
+    ARGS+=("--revision" {{ $modelSpec.modelRevision | quote }})
+    {{- end }}
 
     {{- if $modelSpec.lmcacheConfig }}
       {{- if $modelSpec.lmcacheConfig.enabled }}

helm/tests/deployment-vllm-multi_test.yaml

@@ -363,3 +363,53 @@ tests:
             value: "localhost"
           - name: LMCACHE_P2P_INIT_PORTS
             value: "30081"
+
+  - it: should pass --revision flag when modelRevision is set
+    release:
+      name: vllm
+    set:
+      servingEngineSpec:
+        enableEngine: true
+        modelSpec:
+        - name: "opt125m"
+          repository: "lmcache/vllm-openai"
+          tag: "latest"
+          modelURL: "facebook/opt-125m"
+          replicaCount: 1
+          requestCPU: 6
+          requestMemory: "16Gi"
+          requestGPU: 1
+          pvcStorage: "50Gi"
+          modelRevision: "abc123def"
+    asserts:
+    - documentIndex: 0
+      contains:
+        path: spec.template.spec.containers[0].command
+        content: "--revision"
+    - documentIndex: 0
+      contains:
+        path: spec.template.spec.containers[0].command
+        content: "abc123def"
+
+  - it: should not pass --revision flag when modelRevision is empty
+    release:
+      name: vllm
+    set:
+      servingEngineSpec:
+        enableEngine: true
+        modelSpec:
+        - name: "opt125m"
+          repository: "lmcache/vllm-openai"
+          tag: "latest"
+          modelURL: "facebook/opt-125m"
+          replicaCount: 1
+          requestCPU: 6
+          requestMemory: "16Gi"
+          requestGPU: 1
+          pvcStorage: "50Gi"
+          modelRevision: ""
+    asserts:
+    - documentIndex: 0
+      notContains:
+        path: spec.template.spec.containers[0].command
+        content: "--revision"

helm/tests/ray-cluster_test.yaml

@@ -603,3 +603,63 @@ tests:
     - documentIndex: 0
       isNull:
         path: spec.workerGroupSpecs[0].template.spec.serviceAccountName
+
+  - it: should pass --revision flag in the start script when modelRevision is set
+    release:
+      name: vllm
+    set:
+      servingEngineSpec:
+        enableEngine: true
+        modelSpec:
+          - name: "test-model"
+            repository: "vllm/vllm-openai"
+            tag: "latest"
+            modelURL: "facebook/opt-125m"
+            replicaCount: 1
+            requestCPU: 1
+            requestMemory: "1Gi"
+            requestGPU: 1
+            raySpec:
+              enabled: true
+              headNode:
+                requestCPU: 1
+                requestMemory: "1Gi"
+                requestGPU: 1
+            modelRevision: "abc123def"
+    asserts:
+    - documentSelector:
+        path: metadata.name
+        value: "test-model-vllm-start-script"
+      matchRegex:
+        path: data["vllm-entrypoint.sh"]
+        pattern: "--revision.*abc123def"
+
+  - it: should not pass --revision flag in the start script when modelRevision is empty
+    release:
+      name: vllm
+    set:
+      servingEngineSpec:
+        enableEngine: true
+        modelSpec:
+          - name: "test-model"
+            repository: "vllm/vllm-openai"
+            tag: "latest"
+            modelURL: "facebook/opt-125m"
+            replicaCount: 1
+            requestCPU: 1
+            requestMemory: "1Gi"
+            requestGPU: 1
+            raySpec:
+              enabled: true
+              headNode:
+                requestCPU: 1
+                requestMemory: "1Gi"
+                requestGPU: 1
+            modelRevision: ""
+    asserts:
+    - documentSelector:
+        path: metadata.name
+        value: "test-model-vllm-start-script"
+      notMatchRegex:
+        path: data["vllm-entrypoint.sh"]
+        pattern: "--revision"

helm/values.schema.json

@@ -1377,6 +1377,10 @@
                                     }
                                 }
                             },
+                            "modelRevision": {
+                                "description": "Hugging Face model revision (branch, tag, or commit hash) to pin the model version",
+                                "type": "string"
+                            },
                             "modelURL": {
                                 "description": "The URL of the model",
                                 "type": "string"

helm/values.yaml

@@ -49,6 +49,8 @@ servingEngineSpec:
     imagePullSecret: ""
     # -- The URL of the model
     modelURL: "mistralai/Mistral-7B-Instruct-v0.2"
+    # -- Hugging Face model revision (branch, tag, or commit hash) to pin the model version
+    modelRevision: ""
     # -- Chat template (Jinga2) specifying tokenizer configuration
     # chatTemplate: "{% for message in messages %}\n{% if message['role'] == 'user' %}\n{{ 'Question:\n' + message['content'] + '\n\n' }}{% elif message['role'] == 'system' %}\n{{ 'System:\n' + message['content'] + '\n\n' }}{% elif message['role'] == 'assistant' %}{{ 'Answer:\n'  + message['content'] + '\n\n' }}{% endif %}\n{% if loop.last and add_generation_prompt %}\n{{ 'Answer:\n' }}{% endif %}{% endfor %}"
     # -- The number of replicas for the model