[Feat] helm: use downloader image and add global.imageRegistry support

deploy/helm/README.md

@@ -48,6 +48,8 @@ helm install semantic-router ./deploy/helm/semantic-router \
   --create-namespace
 ```
 
+> Need a registry mirror/proxy (e.g., in China)? Append `--set global.imageRegistry=<your-registry>` to any Helm install/upgrade command.
+
 ### Verify Installation
 
 ```bash

deploy/helm/semantic-router/README.md

@@ -228,6 +228,7 @@ kubectl apply -f deploy/helm/semantic-router/crds/
 | env[0].value | string | `"/app/lib"` |  |
 | fullnameOverride | string | `""` | Override the full name of the chart |
 | global.namespace | string | `""` | Namespace for all resources (if not specified, uses Release.Namespace) |
+| global.imageRegistry | string | `""` | Optional registry prefix applied to all images (e.g., mirror registry in China) |
 | image.pullPolicy | string | `"IfNotPresent"` | Image pull policy |
 | image.repository | string | `"ghcr.io/vllm-project/semantic-router/extproc"` | Image repository |
 | image.tag | string | `"latest"` | Image tag (overrides the image tag whose default is the chart appVersion) |
@@ -238,7 +239,7 @@ kubectl apply -f deploy/helm/semantic-router/crds/
 | ingress.hosts | list | `[{"host":"semantic-router.local","paths":[{"path":"/","pathType":"Prefix","servicePort":8080}]}]` | Ingress hosts configuration |
 | ingress.tls | list | `[]` | Ingress TLS configuration |
 | initContainer.enabled | bool | `true` | Enable init container |
-| initContainer.image | string | `"python:3.11-slim"` | Init container image |
+| initContainer.image | object | `{ "repository": "ghcr.io/vllm-project/semantic-router/model-downloader", "tag": "" (defaults to chart appVersion), "pullPolicy": "IfNotPresent" }` | Init container image |
 | initContainer.models | list | `[{"name":"all-MiniLM-L12-v2","repo":"sentence-transformers/all-MiniLM-L12-v2"},{"name":"category_classifier_modernbert-base_model","repo":"LLM-Semantic-Router/category_classifier_modernbert-base_model"},{"name":"pii_classifier_modernbert-base_model","repo":"LLM-Semantic-Router/pii_classifier_modernbert-base_model"},{"name":"jailbreak_classifier_modernbert-base_model","repo":"LLM-Semantic-Router/jailbreak_classifier_modernbert-base_model"},{"name":"pii_classifier_modernbert-base_presidio_token_model","repo":"LLM-Semantic-Router/pii_classifier_modernbert-base_presidio_token_model"}]` | Models to download |
 | initContainer.resources | object | `{"limits":{"cpu":"1000m","memory":"2Gi"},"requests":{"cpu":"500m","memory":"1Gi"}}` | Resource limits for init container |
 | livenessProbe.enabled | bool | `true` | Enable liveness probe |

deploy/helm/semantic-router/templates/deployment.yaml

@@ -26,22 +26,23 @@ spec:
       imagePullSecrets:
         {{- toYaml . | nindent 8 }}
       {{- end }}
+      {{- $registry := trimSuffix "/" (default "" .Values.global.imageRegistry) }}
+      {{- $prefix := ternary "" (printf "%s/" $registry) (eq $registry "") }}
       serviceAccountName: {{ include "semantic-router.serviceAccountName" . }}
       securityContext:
         {{- toYaml .Values.podSecurityContext | nindent 8 }}
       {{- if .Values.initContainer.enabled }}
       initContainers:
       - name: model-downloader
-        image: {{ .Values.initContainer.image }}
+        {{- $initImage := .Values.initContainer.image }}
+        image: "{{ $prefix }}{{ $initImage.repository }}:{{ $initImage.tag | default .Chart.AppVersion }}"
+        imagePullPolicy: {{ $initImage.pullPolicy | default "IfNotPresent" }}
         securityContext:
           {{- toYaml .Values.securityContext | nindent 10 }}
         command: ["/bin/bash", "-c"]
         args:
         - |
           set -e
-          echo "Installing Hugging Face Hub..."
-          pip install -U --no-cache-dir "huggingface_hub>=0.19.0"
-
           echo "Downloading models to persistent volume..."
           cd /app/models
 
@@ -79,7 +80,7 @@ spec:
       {{- end }}
       containers:
       - name: {{ .Chart.Name }}
-        image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
+        image: "{{ $prefix }}{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
         imagePullPolicy: {{ .Values.image.pullPolicy }}
         {{- with .Values.args }}
         args:

deploy/helm/semantic-router/values.yaml

@@ -3,9 +3,11 @@
 # Declare variables to be passed into your templates.
 
 # Global settings
 global:
   # -- Namespace for all resources (if not specified, uses Release.Namespace)
   namespace: ""
+  # -- Optional registry prefix applied to all images (e.g., mirror in China such as registry.cn-hangzhou.aliyuncs.com)
+  imageRegistry: ""
 
 # -- Number of replicas for the deployment
 replicaCount: 1
@@ -47,7 +49,7 @@
 
 # Pod security context
 podSecurityContext: {}
   # fsGroup: 2000
 
 # Container security context
 securityContext:
@@ -100,7 +102,7 @@
   className: ""
   # -- Ingress annotations
   annotations: {}
     # kubernetes.io/ingress.class: nginx
     # kubernetes.io/tls-acme: "true"
   # -- Ingress hosts configuration
   hosts:
@@ -131,7 +133,11 @@
   # -- Enable init container
   enabled: true
   # -- Init container image
-  image: python:3.11-slim
+  image:
+    repository: ghcr.io/vllm-project/semantic-router/model-downloader
+    # Leave empty to default to the chart AppVersion; override with a pinned tag if desired
+    tag: ""
+    pullPolicy: IfNotPresent
   # -- Resource limits for init container
   resources:
     limits:
@@ -166,7 +172,7 @@
     - name: jailbreak_classifier_modernbert-base_model
       repo: LLM-Semantic-Router/jailbreak_classifier_modernbert-base_model
     - name: pii_classifier_modernbert-base_presidio_token_model
       repo: LLM-Semantic-Router/pii_classifier_modernbert-base_presidio_token_model
     # LoRA PII detector (for auto-detection feature)
     - name: lora_pii_detector_bert-base-uncased_model
       repo: LLM-Semantic-Router/lora_pii_detector_bert-base-uncased_model
@@ -232,7 +238,7 @@
   size: 10Gi
   # -- Annotations for PVC
   annotations: {}
   # -- Existing claim name (if provided, will use existing PVC instead of creating new one)
   existingClaim: ""
 
 # Application configuration
@@ -267,7 +273,7 @@
     model_id: "models/jailbreak_classifier_modernbert-base_model"
     threshold: 0.7
     use_cpu: true
     jailbreak_mapping_path: "models/jailbreak_classifier_modernbert-base_model/jailbreak_type_mapping.json"
 
   # Classifier configuration
   classifier:
@@ -276,13 +282,13 @@
       use_modernbert: true
       threshold: 0.6
       use_cpu: true
       category_mapping_path: "models/category_classifier_modernbert-base_model/category_mapping.json"
     pii_model:
       model_id: "models/pii_classifier_modernbert-base_presidio_token_model"
       use_modernbert: true
       threshold: 0.7
       use_cpu: true
       pii_mapping_path: "models/pii_classifier_modernbert-base_presidio_token_model/pii_type_mapping.json"
 
   # Reasoning families
   reasoning_families:
@@ -313,7 +319,7 @@
         detailed_goroutine_tracking: true
         high_resolution_timing: false
         sample_rate: 1.0
         duration_buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30]
         size_buckets: [1, 2, 5, 10, 20, 50, 100, 200]
 
   # Observability configuration
@@ -351,7 +357,7 @@
               enum: ["celsius", "fahrenheit"]
               description: "Temperature unit"
           required: ["location"]
     description: "Get current weather information, temperature, conditions, forecast for any location, city, or place. Check weather today, now, current conditions, temperature, rain, sun, cloudy, hot, cold, storm, snow"
     category: "weather"
     tags: ["weather", "temperature", "forecast", "climate"]
   - tool:
@@ -370,7 +376,7 @@
               description: "Number of results to return"
               default: 5
           required: ["query"]
     description: "Search the internet, web search, find information online, browse web content, lookup, research, google, find answers, discover, investigate"
     category: "search"
     tags: ["search", "web", "internet", "information", "browse"]
   - tool:

website/docs/installation/k8s/ai-gateway.md

@@ -103,6 +103,7 @@ Deploy the semantic router service with all required components using Helm:
 
 ```bash
 # Install with custom values from GHCR OCI registry
+# (Optional) If you use a registry mirror/proxy, append: --set global.imageRegistry=<your-registry>
 helm install semantic-router oci://ghcr.io/vllm-project/charts/semantic-router \
   --version v0.0.0-latest \
   --namespace vllm-semantic-router-system \

website/docs/installation/k8s/aibrix.md

@@ -56,6 +56,7 @@ Deploy the semantic router service with all required components using Helm:
 
 ```bash
 # Install with custom values from GHCR OCI registry
+# (Optional) If you use a registry mirror/proxy, append: --set global.imageRegistry=<your-registry>
 helm install semantic-router oci://ghcr.io/vllm-project/charts/semantic-router \
   --version v0.0.0-latest \
   --namespace vllm-semantic-router-system \

website/docs/installation/k8s/production-stack.md

@@ -99,6 +99,7 @@ Deploy using Helm with custom values:
 
 ```bash
    # Deploy vLLM Semantic Router with custom values from GHCR OCI registry
+   # (Optional) If you use a registry mirror/proxy, append: --set global.imageRegistry=<your-registry>
    helm install semantic-router oci://ghcr.io/vllm-project/charts/semantic-router \
      --version v0.0.0-latest \
      --namespace vllm-semantic-router-system \