Merge pull request #131 from solidDoWant/feat/qwen3-asr-language-key-1

Support OpenAI-standard `language` key for Qwen3-ASR models

Author: SearchSavior

src/engine/openvino/qwen3_asr/qwen3_asr.py

@@ -30,8 +30,8 @@
     MAX_ASR_INPUT_SECONDS,
     merge_languages,
     normalize_audios,
-    normalize_language_name,
     parse_asr_output,
+    resolve_language_name,
     split_audio_into_chunks,
     validate_language,
 )
@@ -377,7 +377,7 @@ async def transcribe(self, gen_config: OV_Qwen3ASRGenConfig) -> AsyncIterator[Un
         audio_array = (await asyncio.to_thread(normalize_audios, audio_input))[0]
         language: Optional[str] = None
         if gen_config.language:
-            language = normalize_language_name(gen_config.language)
+            language = resolve_language_name(gen_config.language)
             validate_language(language)
 
         audio_seconds = len(audio_array) / SAMPLE_RATE

src/engine/openvino/qwen3_asr/qwen3_asr_utils.py

@@ -66,6 +66,42 @@
     "Hungarian",
     "Macedonian"
 ]
+# ISO-639-1 codes (with a few ISO-639-2/3 codes for languages that lack a
+# 639-1 code) mapped to the canonical full names Qwen3-ASR expects. Used to
+# accept Whisper-style language codes (e.g. "en") in addition to full names.
+LANGUAGE_CODE_TO_NAME: dict = {
+    "zh": "Chinese",
+    "en": "English",
+    "yue": "Cantonese",   # no ISO-639-1 code exists for Cantonese
+    "ar": "Arabic",
+    "de": "German",
+    "fr": "French",
+    "es": "Spanish",
+    "pt": "Portuguese",
+    "id": "Indonesian",
+    "it": "Italian",
+    "ko": "Korean",
+    "ru": "Russian",
+    "th": "Thai",
+    "vi": "Vietnamese",
+    "ja": "Japanese",
+    "tr": "Turkish",
+    "hi": "Hindi",
+    "ms": "Malay",
+    "nl": "Dutch",
+    "sv": "Swedish",
+    "da": "Danish",
+    "fi": "Finnish",
+    "pl": "Polish",
+    "cs": "Czech",
+    "tl": "Filipino",     # Tagalog; Filipino has no distinct ISO-639-1 code
+    "fil": "Filipino",
+    "fa": "Persian",
+    "el": "Greek",
+    "ro": "Romanian",
+    "hu": "Hungarian",
+    "mk": "Macedonian",
+}
 _ASR_TEXT_TAG = "<asr_text>"
 _LANG_PREFIX = "language "
 
@@ -92,6 +128,35 @@ def normalize_language_name(language: str) -> str:
     return s[:1].upper() + s[1:].lower()
 
 
+def resolve_language_name(language: str) -> str:
+    """
+    Resolve a user-provided language to the canonical full name used by
+    Qwen3-ASR, accepting either an ISO-639-1 code (e.g. 'en', 'zh') or a full
+    name (e.g. 'English', 'Chinese').
+
+    Codes are matched case-insensitively against LANGUAGE_CODE_TO_NAME; anything
+    else falls back to normalize_language_name.
+
+    Args:
+        language (str): ISO-639-1 code or language name.
+
+    Returns:
+        str: Canonical language name.
+
+    Raises:
+        ValueError: If language is empty.
+    """
+    if language is None:
+        raise ValueError("language is None")
+    s = str(language).strip()
+    if not s:
+        raise ValueError("language is empty")
+    mapped = LANGUAGE_CODE_TO_NAME.get(s.lower())
+    if mapped is not None:
+        return mapped
+    return normalize_language_name(s)
+
+
 def validate_language(language: str) -> None:
     """
     Validate the language is supported.

src/server/routes/openai.py

@@ -487,6 +487,14 @@ async def event_stream() -> AsyncIterator[bytes]:
 async def openai_audio_transcriptions(
     file: UploadFile = File(..., description="The audio file to transcribe"),
     model: str = Form(..., description="ID of the model to use"),
+    language: Optional[str] = Form(
+        None,
+        description=(
+            "Language of the input audio as an ISO-639-1 code (e.g. 'en') or "
+            "full name (e.g. 'English'). When set, overrides "
+            "openarc_asr.qwen3_asr.language; when unset, that value is used."
+        ),
+    ),
     response_format: Optional[str] = Form("json", description="Format of output"),
     openarc_asr: Optional[str] = Form(
         None, description="JSON: OpenArcASRConfig with qwen3_asr params"
@@ -516,7 +524,12 @@ async def openai_audio_transcriptions(
                 payload["qwen3_asr"] = {}
 
             cfg = OpenArcASRConfig.model_validate(payload)
-            gen_config = cfg.qwen3_asr.model_copy(update={"audio_base64": audio_base64})
+            update = {"audio_base64": audio_base64}
+            if language:
+                # Whisper-style top-level `language` takes precedence; otherwise
+                # fall back to openarc_asr.qwen3_asr.language (current behavior).
+                update["language"] = language
+            gen_config = cfg.qwen3_asr.model_copy(update=update)
             result = await _workers.transcribe_qwen3_asr(model, gen_config)
         else:
             gen_config = OVGenAI_WhisperGenConfig(audio_base64=audio_base64)

src/tests/test_qwen3_asr_unit.py

@@ -0,0 +1,44 @@
+import pytest  # type: ignore[import]
+
+from src.engine.openvino.qwen3_asr.qwen3_asr_utils import (
+    LANGUAGE_CODE_TO_NAME,
+    SUPPORTED_LANGUAGES,
+    resolve_language_name,
+    validate_language,
+)
+
+
+def test_resolve_language_name_maps_iso_639_1_code() -> None:
+    assert resolve_language_name("en") == "English"
+    assert resolve_language_name("zh") == "Chinese"
+
+
+def test_resolve_language_name_code_is_case_insensitive_and_trimmed() -> None:
+    assert resolve_language_name("ZH") == "Chinese"
+    assert resolve_language_name(" ja ") == "Japanese"
+
+
+def test_resolve_language_name_passes_through_full_names() -> None:
+    assert resolve_language_name("english") == "English"
+    assert resolve_language_name("cHINese") == "Chinese"
+
+
+def test_resolve_language_name_handles_non_iso_639_1_special_cases() -> None:
+    # Cantonese has no ISO-639-1 code; Filipino accepts both 639-1 (tl) and 639-3 (fil).
+    assert resolve_language_name("yue") == "Cantonese"
+    assert resolve_language_name("tl") == "Filipino"
+    assert resolve_language_name("fil") == "Filipino"
+
+
+@pytest.mark.parametrize("value", [None, "", "   "])
+def test_resolve_language_name_rejects_empty(value) -> None:
+    with pytest.raises(ValueError):
+        resolve_language_name(value)
+
+
+def test_every_mapped_code_resolves_to_a_supported_language() -> None:
+    # Guards against drift if SUPPORTED_LANGUAGES is edited without updating the map.
+    for code, name in LANGUAGE_CODE_TO_NAME.items():
+        assert name in SUPPORTED_LANGUAGES, f"{code} -> {name} not in SUPPORTED_LANGUAGES"
+        # Resolved canonical names must pass validation.
+        validate_language(resolve_language_name(code))