fix(container): start on CPU when device=auto and align run commands

Resolve SENSEVOICE_DEVICE=auto for CPU Docker hosts

Keeps the local-build path documented while public registry pulls remain private.

Signed-off-by: LauraGPT <18321252+LauraGPT@users.noreply.github.com>

Author: modelpath-dev

.github/workflows/sensevoice-container.yml

@@ -4,23 +4,37 @@ on:
   pull_request:
     paths:
       - Dockerfile
+      - docker-compose.yaml
       - requirements.txt
       - api.py
       - model.py
+      - utils/device_env.py
+      - README.md
+      - README_zh.md
+      - README_ja.md
+      - CONTRIBUTING.md
       - .github/workflows/sensevoice-container.yml
       - tests/test_container_contract.py
+      - tests/test_device_env.py
   push:
     branches:
       - main
     tags:
       - "v*"
     paths:
       - Dockerfile
+      - docker-compose.yaml
       - requirements.txt
       - api.py
       - model.py
+      - utils/device_env.py
+      - README.md
+      - README_zh.md
+      - README_ja.md
+      - CONTRIBUTING.md
       - .github/workflows/sensevoice-container.yml
       - tests/test_container_contract.py
+      - tests/test_device_env.py
   workflow_dispatch:
 
 permissions:
@@ -37,7 +51,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Validate container contract
-        run: python -m unittest tests.test_container_contract
+        run: python -m unittest tests.test_container_contract tests.test_device_env
 
   build:
     needs: contract

CONTRIBUTING.md

@@ -145,12 +145,14 @@ You can also run SenseVoice using Docker:
 docker build -t sensevoice .
 
 # Run with GPU
-docker run --gpus all -p 50000:50000 sensevoice
+docker run --rm --gpus all -p 50000:50000 -v sensevoice-models:/models sensevoice
 
 # Run on CPU
-docker run -e SENSEVOICE_DEVICE=cpu -p 50000:50000 sensevoice
+docker run --rm -e SENSEVOICE_DEVICE=cpu -p 50000:50000 -v sensevoice-models:/models sensevoice
 ```
 
+Do not advertise `docker pull` for `ghcr.io/qwenaudio/sensevoice` or the old Aliyun registry while those paths return HTTP 401 for anonymous clients. Port is 50000, not 60001.
+
 ## Questions?
 
 - Open an issue using the [Questions template](https://github.com/QwenAudio/SenseVoice/issues/new?template=ask_questions.md).

README.md

@@ -339,18 +339,22 @@ docker build -t sensevoice .
 
 ### Run (GPU – default)
 ```bash
-docker run --gpus all -p 50000:50000 sensevoice
+docker run --rm --gpus all -p 50000:50000 -v sensevoice-models:/models sensevoice
 ```
 ### Run (CPU-only)
 ```bash
 docker run --rm -e SENSEVOICE_DEVICE=cpu -p 50000:50000 -v sensevoice-models:/models sensevoice
 ```
+
+The container listens on port 50000. After it is healthy, open `http://127.0.0.1:50000/docs`.
+
 ### Docker Compose
-Docker Compose provides an easier way to run SenseVoice with persistent model caching, networking etc. 
+Docker Compose builds the same image and keeps the model cache on the `sensevoice-models` volume. The default compose file does not request GPUs, so it starts on CPU hosts. For GPU, use the `docker run --gpus all` command above.
 
 ### Start Stack
 ```bash
 docker compose up --build
+# CPU is the default. Equivalent: SENSEVOICE_DEVICE=cpu docker compose up --build
 ```
 ### Data prepare
 

api.py

@@ -1,7 +1,7 @@
 # Set the device with environment, default is cuda:0
 # export SENSEVOICE_DEVICE=cuda:1
 
-import os, re
+import re
 from fastapi import FastAPI, File, Form, UploadFile
 from fastapi.responses import HTMLResponse
 from typing_extensions import Annotated
@@ -11,6 +11,7 @@
 from model import SenseVoiceSmall
 from funasr.utils.postprocess_utils import rich_transcription_postprocess
 from io import BytesIO
+from utils.device_env import resolve_sensevoice_device
 
 TARGET_FS = 16000
 
@@ -26,7 +27,9 @@ class Language(str, Enum):
 
 
 model_dir = "iic/SenseVoiceSmall"
-m, kwargs = SenseVoiceSmall.from_pretrained(model=model_dir, device=os.getenv("SENSEVOICE_DEVICE", "cuda:0"))
+m, kwargs = SenseVoiceSmall.from_pretrained(
+    model=model_dir, device=resolve_sensevoice_device()
+)
 m.eval()
 
 regex = r"<\|.*\|>"

docker-compose.yaml

@@ -18,7 +18,9 @@ services:
       options:
         max-size: "5m"
         max-file: "3"
-    gpus: all
+    # No GPU reservation. A default one makes `docker compose up` fail on
+    # hosts without the NVIDIA runtime, which is the CPU path from issue 339.
+    # GPU users should use `docker run --gpus all`.
 
 volumes:
   sensevoice-models:

tests/__init__.py

@@ -43,11 +43,43 @@ def test_readme_uses_real_service_port_and_no_retired_registry(self):
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
 
         self.assertIn("-p 50000:50000", readme)
+        self.assertNotIn("60001", readme)
         self.assertNotIn(
             "registry.cn-hangzhou.aliyuncs.com/funasr/sensevoice",
             readme,
         )
 
+    def test_verified_docker_run_is_identical_across_docs(self):
+        gpu = (
+            "docker run --rm --gpus all -p 50000:50000 "
+            "-v sensevoice-models:/models sensevoice"
+        )
+        cpu = (
+            "docker run --rm -e SENSEVOICE_DEVICE=cpu -p 50000:50000 "
+            "-v sensevoice-models:/models sensevoice"
+        )
+        for name in ("README.md", "README_zh.md", "README_ja.md", "CONTRIBUTING.md"):
+            text = (ROOT / name).read_text(encoding="utf-8")
+            self.assertIn(gpu, text, msg=name)
+            if name != "README_ja.md":
+                self.assertIn(cpu, text, msg=name)
+
+    def test_default_compose_starts_without_a_gpu_reservation(self):
+        compose = (ROOT / "docker-compose.yaml").read_text(encoding="utf-8")
+
+        self.assertIn("50000:50000", compose)
+        self.assertIn("sensevoice-models:/models", compose)
+        self.assertNotIn("gpus:", compose)
+
+    def test_api_uses_resolved_device_not_raw_auto(self):
+        api = (ROOT / "api.py").read_text(encoding="utf-8")
+
+        self.assertIn("resolve_sensevoice_device()", api)
+        self.assertNotIn(
+            'SenseVoiceSmall.from_pretrained(model=model_dir, device=os.getenv("SENSEVOICE_DEVICE", "cuda:0"))',
+            api,
+        )
+
     def test_readmes_do_not_offer_private_ghcr_image_as_anonymous_pull(self):
         for name in ("README.md", "README_zh.md", "README_ja.md"):
             readme = (ROOT / name).read_text(encoding="utf-8").lower()

tests/test_container_contract.py

@@ -0,0 +1,27 @@
+import unittest
+
+from utils.device_env import resolve_sensevoice_device
+
+
+class ResolveSensevoiceDeviceTest(unittest.TestCase):
+    def test_explicit_cpu(self):
+        self.assertEqual(resolve_sensevoice_device("cpu", cuda_available=True), "cpu")
+
+    def test_explicit_cuda(self):
+        self.assertEqual(
+            resolve_sensevoice_device("cuda:1", cuda_available=False), "cuda:1"
+        )
+
+    def test_auto_prefers_cuda_when_present(self):
+        self.assertEqual(
+            resolve_sensevoice_device("auto", cuda_available=True), "cuda:0"
+        )
+
+    def test_auto_falls_back_to_cpu(self):
+        self.assertEqual(
+            resolve_sensevoice_device("auto", cuda_available=False), "cpu"
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_device_env.py

@@ -0,0 +1,19 @@
+import os
+
+
+def resolve_sensevoice_device(requested=None, cuda_available=None):
+    """Map SENSEVOICE_DEVICE to a FunASR device string.
+
+    The image defaults to ``auto``. FunASR/torch want ``cuda:0`` or ``cpu``.
+    Passing ``auto`` through would fail on hosts without a GPU, which is the
+    path the original Docker issue was hitting.
+    """
+    if requested is None:
+        requested = os.getenv("SENSEVOICE_DEVICE", "cuda:0")
+    if requested != "auto":
+        return requested
+    if cuda_available is None:
+        import torch
+
+        cuda_available = torch.cuda.is_available()
+    return "cuda:0" if cuda_available else "cpu"