Merge pull request #311 from runpod-workers/t3code/cd56c69d

fix: serve original model name when HF cache dir is lowercased (#310)

.github/workflows/CI-readme_version_sync.yml

@@ -0,0 +1,71 @@
+name: CI | Sync vLLM version in READMEs
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "Dockerfile"
+
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync_version:
+    runs-on: ubuntu-latest
+    name: Check README version matches Dockerfile and update if needed
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Extract vLLM version from Dockerfile and sync READMEs
+        run: |
+          echo "Extracting vLLM version from Dockerfile..."
+          dockerfile_version=$(grep -oP 'vllm(?:\[[\w,]+\])?==\K[\d.]+' Dockerfile | head -1)
+
+          if [ -z "$dockerfile_version" ]; then
+            echo "ERROR: Could not extract vLLM version from Dockerfile."
+            exit 1
+          fi
+          echo "Dockerfile vLLM version: $dockerfile_version"
+          echo "VLLM_VERSION=$dockerfile_version" >> $GITHUB_ENV
+
+          updated=0
+          for readme in README.md .runpod/README.md; do
+            if [ ! -f "$readme" ]; then
+              echo "Skipping $readme (not found)"
+              continue
+            fi
+
+            readme_version=$(grep -oP 'Current vLLM version: \[\K[\d.]+' "$readme" || echo "")
+            echo "$readme current version: ${readme_version:-not found}"
+
+            if [ "$readme_version" = "$dockerfile_version" ]; then
+              echo "$readme is already up to date."
+              continue
+            fi
+
+            echo "Updating $readme from $readme_version to $dockerfile_version..."
+            sed -i "s|Current vLLM version: \[${readme_version}\](https://github.com/vllm-project/vllm/releases/tag/v${readme_version})|Current vLLM version: [${dockerfile_version}](https://github.com/vllm-project/vllm/releases/tag/v${dockerfile_version})|g" "$readme"
+            updated=1
+          done
+
+          echo "UPDATED=$updated" >> $GITHUB_ENV
+
+      - name: Create Pull Request
+        if: env.UPDATED == '1'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "docs: sync vLLM version to ${{ env.VLLM_VERSION }} in READMEs"
+          title: "docs: sync vLLM version to ${{ env.VLLM_VERSION }} in READMEs"
+          body: |
+            The vLLM version in the Dockerfile has been updated to `${{ env.VLLM_VERSION }}`.
+
+            This PR syncs the version badge/link in:
+            - `README.md`
+            - `.runpod/README.md`
+          branch: docs/sync-vllm-version-${{ env.VLLM_VERSION }}
+          labels: documentation

.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Tests
+
+on:
+  pull_request:
+    branches:
+      - "**"
+  push:
+    branches:
+      - "main"
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r tests/requirements.txt
+
+      - name: Run unit tests
+        run: python -m pytest tests -v

.runpod/README.md

@@ -33,6 +33,17 @@ All behaviour is controlled through environment variables:
 
 **Pass any vLLM engine arg** not listed above by setting an env var with the **UPPERCASED** field name (e.g. `MAX_MODEL_LEN=4096`, `ENABLE_CHUNKED_PREFILL=true`). The worker auto-discovers all `AsyncEngineArgs` fields from env. See the [vLLM engine args docs](https://docs.vllm.ai/en/latest/configuration/engine_args) for all available options.
 
+**Configuration file:** You can also supply a `config.yaml` instead of (or alongside) env vars. Mount it at `/vllm_config.yaml` in the container, or set `VLLM_CONFIG_FILE` to a custom path. Use the same key names as `vllm serve` — hyphens and underscores both work:
+
+```yaml
+model: meta-llama/Llama-3.1-8B-Instruct
+max-model-len: 8192
+gpu-memory-utilization: 0.90
+quantization: awq
+```
+
+Environment variables always override config file values.
+
 For complete configuration options, see the [full configuration documentation](https://github.com/runpod-workers/worker-vllm/blob/main/docs/configuration.md).
 
 ### Specify Transformers Version

.runpod/tests.json

@@ -5,7 +5,7 @@
       "input": {
         "prompt": "Write a short poem about artificial intelligence."
       },
-      "timeout": 30000
+      "timeout": 300000
     },
     {
       "name": "openai_messages_test",
@@ -26,11 +26,11 @@
           "temperature": 0.1
         }
       },
-      "timeout": 30000
+      "timeout": 300000
     }
   ],
   "config": {
-    "gpuTypeId": "NVIDIA GeForce RTX 4090",
+    "gpuTypeId": "NVIDIA L40",
     "gpuCount": 1,
     "env": [
       {
@@ -38,6 +38,6 @@
         "value": "HuggingFaceTB/SmolLM2-135M-Instruct"
       }
     ],
-    "allowedCudaVersions": ["12.9", "12.8", "12.7", "12.6", "12.5"]
+    "allowedCudaVersions": ["13.0"]
   }
 }

README.md

@@ -78,6 +78,20 @@ Configure worker-vllm using environment variables:
 
 Any env var whose name matches a valid `AsyncEngineArgs` field (uppercased) is applied automatically. Backward-compat aliases: `MODEL_NAME`, `TOKENIZER_NAME`, `MAX_CONTEXT_LEN_TO_CAPTURE`. This lets you configure any vLLM option without waiting for explicit worker support.
 
+### Configuration File (config.yaml)
+
+As an alternative to environment variables, you can supply a `config.yaml` file using the same key names as `vllm serve` (hyphens or underscores both work):
+
+```yaml
+model: meta-llama/Llama-3.1-8B-Instruct
+max-model-len: 8192
+gpu-memory-utilization: 0.90
+quantization: awq
+tensor-parallel-size: 2
+```
+
+Mount the file into the container at `/vllm_config.yaml`, or point to a custom path with the `VLLM_CONFIG_FILE` env var. Environment variables always take precedence over config file values.
+
 For the complete list of all available environment variables, examples, and detailed descriptions: **[Configuration](docs/configuration.md)**
 
 ### Specify Transformers Version

builder/requirements.txt

@@ -1,7 +1,7 @@
 ray
 pandas
 pyarrow
-runpod==1.9.0
+runpod~=1.10.0
 huggingface-hub
 lmcache==0.4.5
 packaging>=24.2
@@ -11,5 +11,5 @@ pydantic-settings
 hf-transfer
 transformers>=5
 bitsandbytes>=0.45.0
-kernels
+kernels<0.15
 torch-c-dlpack-ext

configs/gemma/gemma4_31b_it.yaml

@@ -0,0 +1,11 @@
+model: google/gemma-4-31b-it
+gpu-memory-utilization: 0.95
+max-model-len: 8192
+dtype: auto
+trust-remote-code: true
+quantization: fp8
+kv-cache-dtype: fp8
+enforce-eager: false
+enable-prefix-caching: true
+enable-chunked-prefill: true
+speculative-config: '{"model":"RedHatAI/gemma-4-31B-it-speculator.eagle3","method":"eagle3","num_speculative_tokens":3}'

configs/gpt-oss/gpt_oss_120b.yaml

@@ -0,0 +1,9 @@
+model: openai/gpt-oss-120b
+gpu-memory-utilization: 0.95
+max-model-len: 8192
+dtype: auto
+trust-remote-code: true
+enforce-eager: false
+enable-prefix-caching: true
+enable-chunked-prefill: true
+speculative-config: '{"model":"RedHatAI/gpt-oss-120b-speculator.eagle3","method":"eagle3","num_speculative_tokens":3}'

configs/llama/llama3.1_8b_instruct.yaml

@@ -0,0 +1,10 @@
+model: meta-llama/Llama-3.1-8B-Instruct
+gpu-memory-utilization: 0.95
+max-model-len: 8192
+dtype: auto
+trust-remote-code: true
+quantization: fp8
+kv-cache-dtype: fp8
+enforce-eager: false
+enable-prefix-caching: true
+speculative-config: '{"model":"RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3","method":"eagle3","num_speculative_tokens":3}'

configs/qwen/qwen3_8b.yaml

@@ -0,0 +1,10 @@
+model: Qwen/Qwen3-8B
+gpu-memory-utilization: 0.95
+max-model-len: 8192
+dtype: auto
+trust-remote-code: true
+quantization: fp8
+kv-cache-dtype: fp8
+enforce-eager: false
+enable-prefix-caching: true
+speculative-config: '{"model":"RedHatAI/Qwen3-8B-speculator.eagle3","method":"eagle3","num_speculative_tokens":3}'

src/engine_args.py

@@ -404,6 +404,23 @@ def _resolve_cached_model_path(model_name: str) -> str:
     return resolved
 
 
+def _get_args_from_config_file() -> dict:
+    """Load engine args from a vLLM-style config.yaml.
+
+    Checks VLLM_CONFIG_FILE env var, then falls back to /vllm_config.yaml.
+    Keys use the same long-form names as vllm serve (hyphens converted to underscores).
+    """
+    import yaml
+    path = os.getenv("VLLM_CONFIG_FILE", "/vllm_config.yaml")
+    if not os.path.exists(path):
+        return {}
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+    normalized = {k.replace("-", "_"): v for k, v in raw.items()}
+    logging.info("Loaded engine args from config file %s: %s", path, list(normalized.keys()))
+    return normalized
+
+
 def get_local_args():
     """
     Retrieve local arguments from a JSON file.
@@ -429,6 +446,9 @@ def get_engine_args():
     # Start with worker custom defaults (only where we differ from vLLM)
     args = dict(DEFAULT_ARGS)
 
+    # Config file values sit above defaults but below env vars
+    args.update(_get_args_from_config_file())
+
     # Auto-discover: every AsyncEngineArgs field from env UPPERCASED (e.g. MAX_MODEL_LEN)
     args.update(_get_args_from_env_auto_discover())
 
@@ -581,6 +601,13 @@ def get_engine_args():
 
     # Resolve lowercase HF cache paths (FDE-174)
     if args.get("model"):
-        args["model"] = _resolve_cached_model_path(args["model"])
+        original_model = args["model"]
+        args["model"] = _resolve_cached_model_path(original_model)
+        # When the model was rewritten to an on-disk snapshot path, keep serving
+        # under the original repo id so the OpenAI API model name does not become
+        # a filesystem path (issue #310). An explicit served_model_name (or the
+        # OPENAI_SERVED_MODEL_NAME_OVERRIDE handled downstream) still wins.
+        if args["model"] != original_model and not args.get("served_model_name"):
+            args["served_model_name"] = original_model
 
     return AsyncEngineArgs(**args)

tests/conftest.py

@@ -0,0 +1,105 @@
+"""Shared test fixtures.
+
+``src/engine_args.py`` hard-imports ``vllm`` (and a tensorizer submodule) and
+``torch.cuda``. Both are only installed inside the GPU Docker image, so when the
+tests run on a machine without them we install lightweight stubs. When the real
+packages *are* available (e.g. CI inside the worker image) the stubs are skipped
+and the real ones are used instead.
+"""
+
+import sys
+import types
+from dataclasses import dataclass
+from typing import Optional, Union, List
+
+
+def _install_torch_stub():
+    try:
+        import torch  # noqa: F401
+        return  # real torch present, nothing to stub
+    except Exception:
+        pass
+
+    torch = types.ModuleType("torch")
+    cuda = types.ModuleType("torch.cuda")
+    # No GPU in the test environment -> 0 devices (skips tensor-parallel setup).
+    cuda.device_count = lambda: 0
+    torch.cuda = cuda
+    sys.modules["torch"] = torch
+    sys.modules["torch.cuda"] = cuda
+
+
+def _install_vllm_stub():
+    try:
+        import vllm  # noqa: F401
+        return  # real vLLM present, nothing to stub
+    except Exception:
+        pass
+
+    vllm = types.ModuleType("vllm")
+
+    @dataclass
+    class AsyncEngineArgs:
+        # Only the fields the worker actually sets/reads need to exist here;
+        # get_engine_args() filters args down to AsyncEngineArgs.__dataclass_fields__
+        # before construction, so unknown keys are dropped rather than passed.
+        model: Optional[str] = None
+        served_model_name: Optional[Union[str, List[str]]] = None
+        revision: Optional[str] = None
+        tokenizer: Optional[str] = None
+        trust_remote_code: bool = False
+        max_model_len: Optional[int] = None
+        max_num_batched_tokens: Optional[int] = None
+        disable_log_stats: bool = False
+        gpu_memory_utilization: float = 0.9
+        tensor_parallel_size: int = 1
+        max_parallel_loading_workers: Optional[int] = None
+        kv_cache_dtype: Optional[str] = None
+
+    class _Stub:  # pragma: no cover - placeholder for vllm symbols
+        def __init__(self, *args, **kwargs):
+            pass
+
+    vllm.AsyncEngineArgs = AsyncEngineArgs
+    vllm.SamplingParams = _Stub
+    sys.modules["vllm"] = vllm
+
+    # src.utils imports these at module load and uses ErrorResponse as a return
+    # annotation, which Python evaluates eagerly on <3.14 -> must be defined.
+    vllm_utils = types.ModuleType("vllm.utils")
+    vllm_utils.random_uuid = lambda: "stub-uuid"
+    vllm.utils = vllm_utils
+    sys.modules["vllm.utils"] = vllm_utils
+
+    protocol = types.ModuleType("vllm.entrypoints.openai.engine.protocol")
+    protocol.ErrorResponse = _Stub
+    protocol.ErrorInfo = _Stub
+    protocol.RequestResponseMetadata = _Stub
+    for name in (
+        "vllm.entrypoints",
+        "vllm.entrypoints.openai",
+        "vllm.entrypoints.openai.engine",
+    ):
+        sys.modules.setdefault(name, types.ModuleType(name))
+    sys.modules["vllm.entrypoints.openai.engine.protocol"] = protocol
+
+    # vllm.model_executor.model_loader.tensorizer.TensorizerConfig
+    model_executor = types.ModuleType("vllm.model_executor")
+    model_loader = types.ModuleType("vllm.model_executor.model_loader")
+    tensorizer = types.ModuleType("vllm.model_executor.model_loader.tensorizer")
+
+    class TensorizerConfig:  # pragma: no cover - placeholder
+        def __init__(self, *args, **kwargs):
+            pass
+
+    tensorizer.TensorizerConfig = TensorizerConfig
+    model_loader.tensorizer = tensorizer
+    model_executor.model_loader = model_loader
+    vllm.model_executor = model_executor
+    sys.modules["vllm.model_executor"] = model_executor
+    sys.modules["vllm.model_executor.model_loader"] = model_loader
+    sys.modules["vllm.model_executor.model_loader.tensorizer"] = tensorizer
+
+
+_install_torch_stub()
+_install_vllm_stub()

tests/requirements.txt

@@ -0,0 +1,6 @@
+# Test-only dependencies. vllm/torch are stubbed in conftest.py when absent,
+# so the unit tests run on a plain CPU runner without the GPU image.
+pytest>=8,<10
+# get_engine_args() reads a vLLM-style config via PyYAML (a transitive vllm dep
+# at runtime); install it explicitly here since vllm itself is stubbed.
+pyyaml

tests/test_engine_args.py

@@ -0,0 +1,126 @@
+"""Tests for HF cache path resolution and served-model-name decoupling.
+
+Regression coverage for issue #310: when MODEL_NAME is served from a lowercased
+HF cache dir, the cache resolver rewrites engine_args.model to a snapshot path.
+The served model name must stay the original repo id, not the path.
+"""
+
+import os
+
+import pytest
+
+from src import engine_args
+from src.engine_args import _resolve_cached_model_path, get_engine_args
+
+
+MODEL = "Qwen/Qwen3.6-27B-FP8"
+SNAPSHOT_HASH = "e89b16ebf1988b3d6befa7de50abc2d76f26eb09"
+
+
+def _make_cache(root, folder_name, snapshot=SNAPSHOT_HASH):
+    """Create a HF-style ``models--…/snapshots/<hash>/`` dir and return its path."""
+    snap_dir = os.path.join(root, folder_name, "snapshots", snapshot)
+    os.makedirs(snap_dir)
+    return snap_dir
+
+
+def _is_case_sensitive_fs(path):
+    """The lowercase-cache resolution only matters on case-sensitive filesystems.
+
+    On macOS (APFS, case-insensitive by default) ``models--Qwen--…`` and
+    ``models--qwen--…`` collide, so the resolver always sees the exact-case dir
+    as present. Production runs on Linux (case-sensitive), which is what these
+    tests exercise.
+    """
+    probe = os.path.join(path, "CaseProbe")
+    open(probe, "w").close()
+    try:
+        return not os.path.exists(os.path.join(path, "caseprobe"))
+    finally:
+        os.remove(probe)
+
+
+requires_case_sensitive_fs = pytest.mark.skipif(
+    not _is_case_sensitive_fs(os.environ.get("TMPDIR", "/tmp")),
+    reason="lowercase HF cache resolution only applies on case-sensitive filesystems",
+)
+
+
+@pytest.fixture
+def hf_cache(tmp_path, monkeypatch):
+    cache = tmp_path / "hub"
+    cache.mkdir()
+    monkeypatch.setenv("HUGGINGFACE_HUB_CACHE", str(cache))
+    # Make sure HF_HOME does not shadow the explicit cache dir during the test.
+    monkeypatch.delenv("HF_HOME", raising=False)
+    return cache
+
+
+class TestResolveCachedModelPath:
+    def test_exact_case_dir_returns_repo_id(self, hf_cache):
+        _make_cache(str(hf_cache), "models--Qwen--Qwen3.6-27B-FP8")
+        assert _resolve_cached_model_path(MODEL) == MODEL
+
+    def test_no_cache_returns_repo_id(self, hf_cache):
+        assert _resolve_cached_model_path(MODEL) == MODEL
+
+    def test_absolute_path_passthrough(self, hf_cache):
+        path = "/runpod-volume/some/local/model"
+        assert _resolve_cached_model_path(path) == path
+
+    @requires_case_sensitive_fs
+    def test_lowercase_dir_returns_snapshot_path(self, hf_cache):
+        snap = _make_cache(str(hf_cache), "models--qwen--qwen3.6-27b-fp8")
+        assert _resolve_cached_model_path(MODEL) == snap
+
+    def test_lowercase_dir_without_snapshots_returns_repo_id(self, hf_cache):
+        # Dir exists but has no snapshots subdir -> nothing to resolve to.
+        os.makedirs(os.path.join(str(hf_cache), "models--qwen--qwen3.6-27b-fp8"))
+        assert _resolve_cached_model_path(MODEL) == MODEL
+
+    @requires_case_sensitive_fs
+    def test_lowercase_dir_picks_latest_snapshot(self, hf_cache):
+        folder = "models--qwen--qwen3.6-27b-fp8"
+        _make_cache(str(hf_cache), folder, snapshot="aaaa")
+        latest = _make_cache(str(hf_cache), folder, snapshot="zzzz")
+        assert _resolve_cached_model_path(MODEL) == latest
+
+
+class TestGetEngineArgsServedName:
+    """Issue #310: served name must be decoupled from the resolved on-disk path."""
+
+    @pytest.fixture(autouse=True)
+    def base_env(self, monkeypatch):
+        # Avoid the network branch in _resolve_max_model_len.
+        monkeypatch.setenv("MAX_NUM_BATCHED_TOKENS", "2048")
+        monkeypatch.delenv("SERVED_MODEL_NAME", raising=False)
+        # Don't pick up a stray vLLM config file from the environment.
+        monkeypatch.setenv("VLLM_CONFIG_FILE", "/nonexistent-vllm-config.yaml")
+
+    @requires_case_sensitive_fs
+    def test_served_name_is_repo_id_when_path_rewritten(self, hf_cache, monkeypatch):
+        snap = _make_cache(str(hf_cache), "models--qwen--qwen3.6-27b-fp8")
+        monkeypatch.setenv("MODEL_NAME", MODEL)
+
+        result = get_engine_args()
+
+        assert result.model == snap  # weights load from the lowercase cache
+        assert result.served_model_name == MODEL  # API still serves the repo id
+
+    def test_served_name_untouched_when_no_rewrite(self, hf_cache, monkeypatch):
+        _make_cache(str(hf_cache), "models--Qwen--Qwen3.6-27B-FP8")
+        monkeypatch.setenv("MODEL_NAME", MODEL)
+
+        result = get_engine_args()
+
+        assert result.model == MODEL
+        assert result.served_model_name is None
+
+    def test_explicit_served_name_not_overridden(self, hf_cache, monkeypatch):
+        _make_cache(str(hf_cache), "models--qwen--qwen3.6-27b-fp8")
+        monkeypatch.setenv("MODEL_NAME", MODEL)
+        monkeypatch.setenv("SERVED_MODEL_NAME", "custom-name")
+
+        result = get_engine_args()
+
+        assert result.served_model_name == "custom-name"