Sync master portability fixes from f07947a

tangwang
1 parent 778c299a
Showing 14 changed files with 832 additions and 183 deletions Show diff stats
api/translator_app.py
config/loader.py
frontend/static/js/app.js
requirements_translator_service.txt
scripts/download_translation_models.py
scripts/frontend/frontend_server.py
scripts/setup_translator_venv.sh
scripts/translation/download_translation_models.py
tests/test_translation_converter_resolution.py
tests/test_translation_local_backends.py
tests/test_translator_failure_semantics.py
translation/backends/local_ctranslate2.py
translation/ct2_conversion.py
translation/service.py
@@ -271,16 +271,20 @@ async def lifespan(_: FastAPI):
     """Initialize all enabled translation backends on process startup."""
     logger.info("Starting Translation Service API")
     service = get_translation_service()
+    failed_models = list(getattr(service, "failed_models", []))
+    backend_errors = dict(getattr(service, "backend_errors", {}))
     logger.info(
-        "Translation service ready | default_model=%s default_scene=%s available_models=%s loaded_models=%s",
+        "Translation service ready | default_model=%s default_scene=%s available_models=%s loaded_models=%s failed_models=%s",
         service.config["default_model"],
         service.config["default_scene"],
         service.available_models,
         service.loaded_models,
+        failed_models,
     )
     logger.info(
-        "Translation backends initialized on startup | models=%s",
+        "Translation backends initialized on startup | loaded=%s failed=%s",
         service.loaded_models,
+        backend_errors,
     )
     verbose_logger.info(
         "Translation startup detail | capabilities=%s cache_ttl_seconds=%s cache_sliding_expiration=%s",
@@ -316,11 +320,14 @@ async def health_check():
     """Health check endpoint."""
     try:
         service = get_translation_service()
+        failed_models = list(getattr(service, "failed_models", []))
+        backend_errors = dict(getattr(service, "backend_errors", {}))
         logger.info(
-            "Health check | default_model=%s default_scene=%s loaded_models=%s",
+            "Health check | default_model=%s default_scene=%s loaded_models=%s failed_models=%s",
             service.config["default_model"],
             service.config["default_scene"],
             service.loaded_models,
+            failed_models,
         )
         return {
             "status": "healthy",
@@ -330,6 +337,8 @@ async def health_check():
             "available_models": service.available_models,
             "enabled_capabilities": get_enabled_translation_models(service.config),
             "loaded_models": service.loaded_models,
+            "failed_models": failed_models,
+            "backend_errors": backend_errors,
         }
     except Exception as e:
         logger.error(f"Health check failed: {e}")
@@ -463,6 +472,10 @@ async def translate(request: TranslationRequest, http_request: Request):
         latency_ms = (time.perf_counter() - request_started) * 1000
         logger.warning("Translation validation error | error=%s latency_ms=%.2f", e, latency_ms)
         raise HTTPException(status_code=400, detail=str(e)) from e
+    except RuntimeError as e:
+        latency_ms = (time.perf_counter() - request_started) * 1000
+        logger.warning("Translation backend unavailable | error=%s latency_ms=%.2f", e, latency_ms)
+        raise HTTPException(status_code=503, detail=str(e)) from e
     except Exception as e:
         latency_ms = (time.perf_counter() - request_started) * 1000
         logger.error("Translation error | error=%s latency_ms=%.2f", e, latency_ms, exc_info=True)
@@ -655,6 +655,14 @@ class AppConfigLoader:
         translation_raw = raw.get("translation") if isinstance(raw.get("translation"), dict) else {}
         normalized_translation = build_translation_config(translation_raw)
+        local_translation_backends = {"local_nllb", "local_marian"}
+        for capability_name, capability_cfg in normalized_translation["capabilities"].items():
+            backend_name = str(capability_cfg.get("backend") or "").strip().lower()
+            if backend_name not in local_translation_backends:
+                continue
+            for path_key in ("model_dir", "ct2_model_dir"):
+                if capability_cfg.get(path_key) not in (None, ""):
+                    capability_cfg[path_key] = str(self._resolve_project_path_value(capability_cfg[path_key]).resolve())
         translation_config = TranslationServiceConfig(
             endpoint=str(normalized_translation["service_url"]).rstrip("/"),
             timeout_sec=float(normalized_translation["timeout_sec"]),
@@ -749,7 +757,7 @@ class AppConfigLoader:
                 port=port,
                 backend=backend_name,
                 runtime_dir=(
-                    str(v)
+                    str(self._resolve_project_path_value(v).resolve())
                     if (v := instance_raw.get("runtime_dir")) not in (None, "")
                     else None
                 ),
@@ -787,6 +795,12 @@ class AppConfigLoader:
             rerank=rerank_config,
         )
+    def _resolve_project_path_value(self, value: Any) -> Path:
+        candidate = Path(str(value)).expanduser()
+        if candidate.is_absolute():
+            return candidate
+        return self.project_root / candidate
+
     def _build_tenants_config(self, raw: Dict[str, Any]) -> TenantCatalogConfig:
         if not isinstance(raw, dict):
             raise ConfigurationError("tenant_config must be a mapping")
@@ -822,13 +836,6 @@ class AppConfigLoader:
     def _build_infrastructure_config(self, environment: str) -> InfrastructureConfig:
         del environment
-        _redis_db_raw = os.getenv("REDIS_DB") or os.getenv("REDIS_SNAPSHOT_DB")
-        _redis_db = 0
-        if _redis_db_raw is not None and str(_redis_db_raw).strip() != "":
-            try:
-                _redis_db = int(str(_redis_db_raw).strip())
-            except ValueError:
-                _redis_db = 0
         return InfrastructureConfig(
             elasticsearch=ElasticsearchSettings(
                 host=os.getenv("ES_HOST", "http://localhost:9200"),
@@ -838,7 +845,7 @@ class AppConfigLoader:
             redis=RedisSettings(
                 host=os.getenv("REDIS_HOST", "localhost"),
                 port=int(os.getenv("REDIS_PORT", 6479)),
-                snapshot_db=_redis_db,
+                snapshot_db=int(os.getenv("REDIS_SNAPSHOT_DB", 0)),
                 password=os.getenv("REDIS_PASSWORD"),
                 socket_timeout=int(os.getenv("REDIS_SOCKET_TIMEOUT", 1)),
                 socket_connect_timeout=int(os.getenv("REDIS_SOCKET_CONNECT_TIMEOUT", 1)),
@@ -316,7 +316,10 @@ async function performSearch(page = 1) {
     document.getElementById('productGrid').innerHTML = '';
     try {
-        const response = await fetch(`${API_BASE_URL}/search/`, {
+        const searchUrl = new URL(`${API_BASE_URL}/search/`, window.location.origin);
+        searchUrl.searchParams.set('tenant_id', tenantId);
+
+        const response = await fetch(searchUrl.toString(), {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -13,7 +13,8 @@ httpx&gt;=0.24.0
 tqdm>=4.65.0
 torch>=2.0.0
-transformers>=4.30.0
+# Keep translator conversions on the last verified NLLB-compatible release line.
+transformers>=4.51.0,<4.52.0
 ctranslate2>=4.7.0
 sentencepiece>=0.2.0
 sacremoses>=0.1.1
 #!/usr/bin/env python3
-"""Download local translation models declared in services.translation.capabilities."""
+"""Backward-compatible entrypoint for translation model downloads."""
 from __future__ import annotations
-import argparse
-import os
+import runpy
 from pathlib import Path
-import shutil
-import subprocess
-import sys
-from typing import Iterable
-
-from huggingface_hub import snapshot_download
-
-PROJECT_ROOT = Path(__file__).resolve().parent.parent
-if str(PROJECT_ROOT) not in sys.path:
-    sys.path.insert(0, str(PROJECT_ROOT))
-os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
-
-from config.services_config import get_translation_config
-
-
-LOCAL_BACKENDS = {"local_nllb", "local_marian"}
-
-
-def iter_local_capabilities(selected: set[str] | None = None) -> Iterable[tuple[str, dict]]:
-    cfg = get_translation_config()
-    capabilities = cfg.get("capabilities", {}) if isinstance(cfg, dict) else {}
-    for name, capability in capabilities.items():
-        backend = str(capability.get("backend") or "").strip().lower()
-        if backend not in LOCAL_BACKENDS:
-            continue
-        if selected and name not in selected:
-            continue
-        yield name, capability
-
-
-def _compute_ct2_output_dir(capability: dict) -> Path:
-    custom = str(capability.get("ct2_model_dir") or "").strip()
-    if custom:
-        return Path(custom).expanduser()
-    model_dir = Path(str(capability.get("model_dir") or "")).expanduser()
-    compute_type = str(capability.get("ct2_compute_type") or capability.get("torch_dtype") or "default").strip().lower()
-    normalized = compute_type.replace("_", "-")
-    return model_dir / f"ctranslate2-{normalized}"
-
-
-def _resolve_converter_binary() -> str:
-    candidate = shutil.which("ct2-transformers-converter")
-    if candidate:
-        return candidate
-    venv_candidate = Path(sys.executable).absolute().parent / "ct2-transformers-converter"
-    if venv_candidate.exists():
-        return str(venv_candidate)
-    raise RuntimeError(
-        "ct2-transformers-converter was not found. "
-        "Install ctranslate2 in the active Python environment first."
-    )
-
-
-def convert_to_ctranslate2(name: str, capability: dict) -> None:
-    model_id = str(capability.get("model_id") or "").strip()
-    model_dir = Path(str(capability.get("model_dir") or "")).expanduser()
-    model_source = str(model_dir if model_dir.exists() else model_id)
-    output_dir = _compute_ct2_output_dir(capability)
-    if (output_dir / "model.bin").exists():
-        print(f"[skip-convert] {name} -> {output_dir}")
-        return
-    quantization = str(
-        capability.get("ct2_conversion_quantization")
-        or capability.get("ct2_compute_type")
-        or capability.get("torch_dtype")
-        or "default"
-    ).strip()
-    output_dir.parent.mkdir(parents=True, exist_ok=True)
-    print(f"[convert] {name} -> {output_dir} ({quantization})")
-    subprocess.run(
-        [
-            _resolve_converter_binary(),
-            "--model",
-            model_source,
-            "--output_dir",
-            str(output_dir),
-            "--quantization",
-            quantization,
-        ],
-        check=True,
-    )
-    print(f"[converted] {name}")
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Download local translation models")
-    parser.add_argument("--all-local", action="store_true", help="Download all configured local translation models")
-    parser.add_argument("--models", nargs="*", default=[], help="Specific capability names to download")
-    parser.add_argument(
-        "--convert-ctranslate2",
-        action="store_true",
-        help="Also convert the downloaded Hugging Face models into CTranslate2 format",
-    )
-    args = parser.parse_args()
-
-    selected = {item.strip().lower() for item in args.models if item.strip()} or None
-    if not args.all_local and not selected:
-        parser.error("pass --all-local or --models <name> ...")
-
-    for name, capability in iter_local_capabilities(selected):
-        model_id = str(capability.get("model_id") or "").strip()
-        model_dir = Path(str(capability.get("model_dir") or "")).expanduser()
-        if not model_id or not model_dir:
-            raise ValueError(f"Capability '{name}' must define model_id and model_dir")
-        model_dir.parent.mkdir(parents=True, exist_ok=True)
-        print(f"[download] {name} -> {model_dir} ({model_id})")
-        snapshot_download(
-            repo_id=model_id,
-            local_dir=str(model_dir),
-        )
-        print(f"[done] {name}")
-        if args.convert_ctranslate2:
-            convert_to_ctranslate2(name, capability)
 if __name__ == "__main__":
-    main()
+    target = Path(__file__).resolve().parent / "translation" / "download_translation_models.py"
+    runpy.run_path(str(target), run_name="__main__")
@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""
+Simple HTTP server for saas-search frontend.
+"""
+
+import http.server
+import socketserver
+import os
+import sys
+import logging
+import time
+import urllib.request
+import urllib.error
+from collections import defaultdict, deque
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load .env file
+project_root = Path(__file__).resolve().parents[2]
+load_dotenv(project_root / '.env')
+
+# Get API_BASE_URL from environment（默认不注入，避免被旧 .env 覆盖同源策略）
+# 仅当显式设置 FRONTEND_INJECT_API_BASE_URL=1 时才注入 window.API_BASE_URL。
+API_BASE_URL = os.getenv('API_BASE_URL') or None
+INJECT_API_BASE_URL = os.getenv('FRONTEND_INJECT_API_BASE_URL', '0') == '1'
+# Backend proxy target for same-origin API forwarding
+BACKEND_PROXY_URL = os.getenv('BACKEND_PROXY_URL', 'http://127.0.0.1:6002').rstrip('/')
+
+# Change to frontend directory
+frontend_dir = os.path.join(project_root, 'frontend')
+os.chdir(frontend_dir)
+
+# FRONTEND_PORT is the canonical config; keep PORT as a secondary fallback.
+PORT = int(os.getenv('FRONTEND_PORT', os.getenv('PORT', 6003)))
+
+# Configure logging to suppress scanner noise
+logging.basicConfig(level=logging.ERROR, format='%(asctime)s - %(levelname)s - %(message)s')
+
+class RateLimitingMixin:
+    """Mixin for rate limiting requests by IP address."""
+    request_counts = defaultdict(deque)
+    rate_limit = 100  # requests per minute
+    window = 60  # seconds
+
+    @classmethod
+    def is_rate_limited(cls, ip):
+        now = time.time()
+
+        # Clean old requests
+        while cls.request_counts[ip] and cls.request_counts[ip][0] < now - cls.window:
+            cls.request_counts[ip].popleft()
+
+        # Check rate limit
+        if len(cls.request_counts[ip]) > cls.rate_limit:
+            return True
+
+        cls.request_counts[ip].append(now)
+        return False
+
+class MyHTTPRequestHandler(http.server.SimpleHTTPRequestHandler, RateLimitingMixin):
+    """Custom request handler with CORS support and robust error handling."""
+
+    _ALLOWED_CORS_HEADERS = "Content-Type, X-Tenant-ID, X-Request-ID, Referer"
+
+    def _is_proxy_path(self, path: str) -> bool:
+        """Return True for API paths that should be forwarded to backend service."""
+        return path.startswith('/search/') or path.startswith('/admin/') or path.startswith('/indexer/')
+
+    def _proxy_to_backend(self):
+        """Proxy current request to backend service on the GPU server."""
+        target_url = f"{BACKEND_PROXY_URL}{self.path}"
+        method = self.command.upper()
+
+        try:
+            content_length = int(self.headers.get('Content-Length', '0'))
+        except ValueError:
+            content_length = 0
+        body = self.rfile.read(content_length) if content_length > 0 else None
+
+        forward_headers = {}
+        for key, value in self.headers.items():
+            lk = key.lower()
+            if lk in ('host', 'content-length', 'connection'):
+                continue
+            forward_headers[key] = value
+
+        req = urllib.request.Request(
+            target_url,
+            data=body,
+            headers=forward_headers,
+            method=method,
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                resp_body = resp.read()
+                self.send_response(resp.getcode())
+                for header, value in resp.getheaders():
+                    lh = header.lower()
+                    if lh in ('transfer-encoding', 'connection', 'content-length'):
+                        continue
+                    self.send_header(header, value)
+                self.end_headers()
+                self.wfile.write(resp_body)
+        except urllib.error.HTTPError as e:
+            err_body = e.read() if hasattr(e, 'read') else b''
+            self.send_response(e.code)
+            if e.headers:
+                for header, value in e.headers.items():
+                    lh = header.lower()
+                    if lh in ('transfer-encoding', 'connection', 'content-length'):
+                        continue
+                    self.send_header(header, value)
+            self.end_headers()
+            if err_body:
+                self.wfile.write(err_body)
+        except Exception as e:
+            logging.error(f"Backend proxy error for {method} {self.path}: {e}")
+            self.send_response(502)
+            self.send_header('Content-Type', 'application/json; charset=utf-8')
+            self.end_headers()
+            self.wfile.write(b'{"error":"Bad Gateway: backend proxy failed"}')
+
+    def do_GET(self):
+        """Handle GET requests with API config injection."""
+        path = self.path.split('?')[0]
+
+        # Proxy API paths to backend first
+        if self._is_proxy_path(path):
+            self._proxy_to_backend()
+            return
+        
+        # Route / to index.html
+        if path == '/' or path == '':
+            self.path = '/index.html' + (self.path.split('?', 1)[1] if '?' in self.path else '')
+        
+        # Inject API config for HTML files
+        if self.path.endswith('.html'):
+            self._serve_html_with_config()
+        else:
+            super().do_GET()
+    
+    def _serve_html_with_config(self):
+        """Serve HTML with optional API_BASE_URL injected."""
+        try:
+            file_path = self.path.lstrip('/')
+            if not os.path.exists(file_path):
+                self.send_error(404)
+                return
+            
+            with open(file_path, 'r', encoding='utf-8') as f:
+                html = f.read()
+
+            # 默认不注入 API_BASE_URL，避免历史 .env（如 http://xx:6002）覆盖同源调用。
+            # 仅当 FRONTEND_INJECT_API_BASE_URL=1 且 API_BASE_URL 有值时才注入。
+            if INJECT_API_BASE_URL and API_BASE_URL:
+                config_script = f'<script>window.API_BASE_URL="{API_BASE_URL}";</script>\n    '
+                html = html.replace('<script src="/static/js/app.js', config_script + '<script src="/static/js/app.js', 1)
+            
+            self.send_response(200)
+            self.send_header('Content-Type', 'text/html; charset=utf-8')
+            self.end_headers()
+            self.wfile.write(html.encode('utf-8'))
+        except Exception as e:
+            logging.error(f"Error serving HTML: {e}")
+            self.send_error(500)
+
+    def do_POST(self):
+        """Handle POST requests. Proxy API requests to backend."""
+        path = self.path.split('?')[0]
+        if self._is_proxy_path(path):
+            self._proxy_to_backend()
+            return
+        self.send_error(405, "Method Not Allowed")
+
+    def setup(self):
+        """Setup with error handling."""
+        try:
+            super().setup()
+        except Exception:
+            pass  # Silently handle setup errors from scanners
+
+    def handle_one_request(self):
+        """Handle single request with error catching."""
+        try:
+            # Check rate limiting
+            client_ip = self.client_address[0]
+            if self.is_rate_limited(client_ip):
+                logging.warning(f"Rate limiting IP: {client_ip}")
+                self.send_error(429, "Too Many Requests")
+                return
+
+            super().handle_one_request()
+        except (ConnectionResetError, BrokenPipeError):
+            # Client disconnected prematurely - common with scanners
+            pass
+        except UnicodeDecodeError:
+            # Binary data received - not HTTP
+            pass
+        except Exception as e:
+            # Log unexpected errors but don't crash
+            logging.debug(f"Request handling error: {e}")
+
+    def log_message(self, format, *args):
+        """Suppress logging for malformed requests from scanners."""
+        message = format % args
+        # Filter out scanner noise
+        noise_patterns = [
+            "code 400",
+            "Bad request",
+            "Bad request version",
+            "Bad HTTP/0.9 request type",
+            "Bad request syntax"
+        ]
+        if any(pattern in message for pattern in noise_patterns):
+            return
+        # Only log legitimate requests
+        if message and not message.startswith(" ") and len(message) > 10:
+            super().log_message(format, *args)
+
+    def end_headers(self):
+        # Add CORS headers
+        self.send_header('Access-Control-Allow-Origin', '*')
+        self.send_header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
+        self.send_header('Access-Control-Allow-Headers', self._ALLOWED_CORS_HEADERS)
+        # Add security headers
+        self.send_header('X-Content-Type-Options', 'nosniff')
+        self.send_header('X-Frame-Options', 'DENY')
+        self.send_header('X-XSS-Protection', '1; mode=block')
+        super().end_headers()
+
+    def do_OPTIONS(self):
+        """Handle OPTIONS requests."""
+        try:
+            path = self.path.split('?')[0]
+            if self._is_proxy_path(path):
+                self.send_response(204)
+                self.end_headers()
+                return
+            self.send_response(200)
+            self.end_headers()
+        except Exception:
+            pass
+
+class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
+    """Threaded TCP server with better error handling."""
+    allow_reuse_address = True
+    daemon_threads = True
+
+if __name__ == '__main__':
+    # Check if port is already in use
+    import socket
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.bind(("", PORT))
+        sock.close()
+    except OSError:
+        print(f"ERROR: Port {PORT} is already in use.")
+        print(f"Please stop the existing server or use a different port.")
+        print(f"To stop existing server: kill $(lsof -t -i:{PORT})")
+        sys.exit(1)
+    
+    # Create threaded server for better concurrency
+    with ThreadedTCPServer(("", PORT), MyHTTPRequestHandler) as httpd:
+        print(f"Frontend server started at http://localhost:{PORT}")
+        print(f"Serving files from: {os.getcwd()}")
+        print("\nPress Ctrl+C to stop the server")
+
+        try:
+            httpd.serve_forever()
+        except KeyboardInterrupt:
+            print("\nShutting down server...")
+            httpd.shutdown()
+            print("Server stopped")
+            sys.exit(0)
+        except Exception as e:
+            print(f"Server error: {e}")
+            sys.exit(1)
@@ -8,8 +8,47 @@ PROJECT_ROOT=&quot;$(cd &quot;$(dirname &quot;$0&quot;)/..&quot; &amp;&amp; pwd)&quot;
 cd "${PROJECT_ROOT}"
 VENV_DIR="${PROJECT_ROOT}/.venv-translator"
-PYTHON_BIN="${PYTHON_BIN:-python3}"
 TMP_DIR="${TRANSLATOR_PIP_TMPDIR:-${PROJECT_ROOT}/.tmp/translator-pip}"
+MIN_PYTHON_MAJOR=3
+MIN_PYTHON_MINOR=10
+
+python_meets_minimum() {
+  local bin="$1"
+  "${bin}" - <<'PY' "${MIN_PYTHON_MAJOR}" "${MIN_PYTHON_MINOR}"
+import sys
+
+required = tuple(int(value) for value in sys.argv[1:])
+sys.exit(0 if sys.version_info[:2] >= required else 1)
+PY
+}
+
+discover_python_bin() {
+  local candidates=()
+
+  if [[ -n "${PYTHON_BIN:-}" ]]; then
+    candidates+=("${PYTHON_BIN}")
+  fi
+  candidates+=("python3.12" "python3.11" "python3.10" "python3")
+
+  local candidate
+  for candidate in "${candidates[@]}"; do
+    if ! command -v "${candidate}" >/dev/null 2>&1; then
+      continue
+    fi
+    if python_meets_minimum "${candidate}"; then
+      echo "${candidate}"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+if ! PYTHON_BIN="$(discover_python_bin)"; then
+  echo "ERROR: unable to find Python >= ${MIN_PYTHON_MAJOR}.${MIN_PYTHON_MINOR}." >&2
+  echo "Set PYTHON_BIN to a compatible interpreter and rerun." >&2
+  exit 1
+fi
 if ! command -v "${PYTHON_BIN}" >/dev/null 2>&1; then
   echo "ERROR: python not found: ${PYTHON_BIN}" >&2
@@ -32,6 +71,7 @@ mkdir -p &quot;${TMP_DIR}&quot;
 export TMPDIR="${TMP_DIR}"
 PIP_ARGS=(--no-cache-dir)
+echo "Using Python=${PYTHON_BIN}"
 echo "Using TMPDIR=${TMPDIR}"
 "${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" --upgrade pip wheel
 "${VENV_DIR}/bin/python" -m pip install "${PIP_ARGS[@]}" -r requirements_translator_service.txt
@@ -39,5 +79,5 @@ echo &quot;Using TMPDIR=${TMPDIR}&quot;
 echo
 echo "Done."
 echo "Translator venv: ${VENV_DIR}"
-echo "Download local models: ./.venv-translator/bin/python scripts/download_translation_models.py --all-local"
+echo "Download local models: ./.venv-translator/bin/python scripts/translation/download_translation_models.py --all-local"
 echo "Start service: ./scripts/start_translator.sh"
@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Download local translation models declared in services.translation.capabilities."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+import sys
+from typing import Iterable
+
+from huggingface_hub import snapshot_download
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+os.environ.setdefault("HF_HUB_DISABLE_XET", "1")
+
+from config.services_config import get_translation_config
+from translation.ct2_conversion import convert_transformers_model
+
+
+LOCAL_BACKENDS = {"local_nllb", "local_marian"}
+
+
+def iter_local_capabilities(selected: set[str] | None = None) -> Iterable[tuple[str, dict]]:
+    cfg = get_translation_config()
+    capabilities = cfg.get("capabilities", {}) if isinstance(cfg, dict) else {}
+    for name, capability in capabilities.items():
+        backend = str(capability.get("backend") or "").strip().lower()
+        if backend not in LOCAL_BACKENDS:
+            continue
+        if selected and name not in selected:
+            continue
+        yield name, capability
+
+
+def _compute_ct2_output_dir(capability: dict) -> Path:
+    custom = str(capability.get("ct2_model_dir") or "").strip()
+    if custom:
+        return Path(custom).expanduser()
+    model_dir = Path(str(capability.get("model_dir") or "")).expanduser()
+    compute_type = str(capability.get("ct2_compute_type") or capability.get("torch_dtype") or "default").strip().lower()
+    normalized = compute_type.replace("_", "-")
+    return model_dir / f"ctranslate2-{normalized}"
+
+
+def convert_to_ctranslate2(name: str, capability: dict) -> None:
+    model_id = str(capability.get("model_id") or "").strip()
+    model_dir = Path(str(capability.get("model_dir") or "")).expanduser()
+    model_source = str(model_dir if model_dir.exists() else model_id)
+    output_dir = _compute_ct2_output_dir(capability)
+    if (output_dir / "model.bin").exists():
+        print(f"[skip-convert] {name} -> {output_dir}")
+        return
+    quantization = str(
+        capability.get("ct2_conversion_quantization")
+        or capability.get("ct2_compute_type")
+        or capability.get("torch_dtype")
+        or "default"
+    ).strip()
+    output_dir.parent.mkdir(parents=True, exist_ok=True)
+    print(f"[convert] {name} -> {output_dir} ({quantization})")
+    convert_transformers_model(model_source, str(output_dir), quantization)
+    print(f"[converted] {name}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Download local translation models")
+    parser.add_argument("--all-local", action="store_true", help="Download all configured local translation models")
+    parser.add_argument("--models", nargs="*", default=[], help="Specific capability names to download")
+    parser.add_argument(
+        "--convert-ctranslate2",
+        action="store_true",
+        help="Also convert the downloaded Hugging Face models into CTranslate2 format",
+    )
+    args = parser.parse_args()
+
+    selected = {item.strip().lower() for item in args.models if item.strip()} or None
+    if not args.all_local and not selected:
+        parser.error("pass --all-local or --models <name> ...")
+
+    for name, capability in iter_local_capabilities(selected):
+        model_id = str(capability.get("model_id") or "").strip()
+        model_dir = Path(str(capability.get("model_dir") or "")).expanduser()
+        if not model_id or not model_dir:
+            raise ValueError(f"Capability '{name}' must define model_id and model_dir")
+        model_dir.parent.mkdir(parents=True, exist_ok=True)
+        print(f"[download] {name} -> {model_dir} ({model_id})")
+        snapshot_download(
+            repo_id=model_id,
+            local_dir=str(model_dir),
+        )
+        print(f"[done] {name}")
+        if args.convert_ctranslate2:
+            convert_to_ctranslate2(name, capability)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import sys
+import types
+
+import pytest
+
+import translation.ct2_conversion as ct2_conversion
+
+
+class _FakeTransformersConverter:
+    def __init__(self, model_name_or_path):
+        self.model_name_or_path = model_name_or_path
+        self.load_calls = []
+
+    def load_model(self, model_class, resolved_model_name_or_path, **kwargs):
+        self.load_calls.append(
+            {
+                "model_class": model_class,
+                "resolved_model_name_or_path": resolved_model_name_or_path,
+                "kwargs": dict(kwargs),
+            }
+        )
+        if "dtype" in kwargs or "torch_dtype" in kwargs:
+            raise TypeError("M2M100ForConditionalGeneration.__init__() got an unexpected keyword argument 'dtype'")
+        return {"loaded": True, "path": resolved_model_name_or_path}
+
+    def convert(self, output_dir, quantization=None, force=False):
+        loaded = self.load_model("FakeModel", self.model_name_or_path, dtype="float32")
+        return {
+            "loaded": loaded,
+            "output_dir": output_dir,
+            "quantization": quantization,
+            "force": force,
+            "load_calls": list(self.load_calls),
+        }
+
+
+def _install_fake_ctranslate2(monkeypatch, base_converter):
+    converters_module = types.ModuleType("ctranslate2.converters")
+    converters_module.TransformersConverter = base_converter
+    ctranslate2_module = types.ModuleType("ctranslate2")
+    ctranslate2_module.converters = converters_module
+
+    monkeypatch.setitem(sys.modules, "ctranslate2", ctranslate2_module)
+    monkeypatch.setitem(sys.modules, "ctranslate2.converters", converters_module)
+
+
+def test_convert_transformers_model_retries_without_torch_dtype(monkeypatch):
+    _install_fake_ctranslate2(monkeypatch, _FakeTransformersConverter)
+    fake_transformers = types.ModuleType("transformers")
+    fake_transformers.AutoConfig = types.SimpleNamespace(
+        from_pretrained=lambda path: types.SimpleNamespace(torch_dtype="float32", path=path)
+    )
+    monkeypatch.setitem(sys.modules, "transformers", fake_transformers)
+
+    result = ct2_conversion.convert_transformers_model("fake-model", "/tmp/out", "float16")
+
+    assert result["loaded"] == {"loaded": True, "path": "fake-model"}
+    assert result["output_dir"] == "/tmp/out"
+    assert result["quantization"] == "float16"
+    assert result["force"] is False
+    assert len(result["load_calls"]) == 2
+    assert result["load_calls"][0] == {
+        "model_class": "FakeModel",
+        "resolved_model_name_or_path": "fake-model",
+        "kwargs": {"dtype": "float32"},
+    }
+    assert result["load_calls"][1]["model_class"] == "FakeModel"
+    assert result["load_calls"][1]["resolved_model_name_or_path"] == "fake-model"
+    assert getattr(result["load_calls"][1]["kwargs"]["config"], "torch_dtype", "missing") is None
+
+
+def test_convert_transformers_model_preserves_unrelated_type_errors(monkeypatch):
+    class _AlwaysFailingConverter(_FakeTransformersConverter):
+        def load_model(self, model_class, resolved_model_name_or_path, **kwargs):
+            raise TypeError("different constructor error")
+
+    _install_fake_ctranslate2(monkeypatch, _AlwaysFailingConverter)
+    fake_transformers = types.ModuleType("transformers")
+    fake_transformers.AutoConfig = types.SimpleNamespace(from_pretrained=lambda path: types.SimpleNamespace(path=path))
+    monkeypatch.setitem(sys.modules, "transformers", fake_transformers)
+
+    with pytest.raises(TypeError, match="different constructor error"):
+        ct2_conversion.convert_transformers_model("fake-model", "/tmp/out", "float16")
@@ -201,6 +201,51 @@ def test_nllb_ctranslate2_accepts_finnish_short_code(monkeypatch):
     assert backend.translator.last_translate_batch_kwargs["target_prefix"] == [["zho_Hans"]]
+def test_nllb_ctranslate2_falls_back_to_model_id_when_local_dir_is_wrong_type(tmp_path, monkeypatch):
+    wrong_dir = tmp_path / "wrong-nllb"
+    wrong_dir.mkdir()
+    (wrong_dir / "config.json").write_text('{"model_type":"led"}', encoding="utf-8")
+
+    monkeypatch.setattr(NLLBCTranslate2TranslationBackend, "_load_runtime", _stub_load_ct2_runtime)
+
+    backend = NLLBCTranslate2TranslationBackend(
+        name="nllb-200-distilled-600m",
+        model_id="facebook/nllb-200-distilled-600M",
+        model_dir=str(wrong_dir),
+        device="cpu",
+        torch_dtype="float32",
+        batch_size=1,
+        max_input_length=16,
+        max_new_tokens=16,
+        num_beams=1,
+    )
+
+    assert backend._model_source() == "facebook/nllb-200-distilled-600M"
+    assert backend._tokenizer_source() == "facebook/nllb-200-distilled-600M"
+
+
+def test_nllb_ctranslate2_falls_back_to_model_id_when_local_dir_is_incomplete(tmp_path, monkeypatch):
+    incomplete_dir = tmp_path / "incomplete-nllb"
+    incomplete_dir.mkdir()
+    (incomplete_dir / "ctranslate2-float16").mkdir()
+
+    monkeypatch.setattr(NLLBCTranslate2TranslationBackend, "_load_runtime", _stub_load_ct2_runtime)
+
+    backend = NLLBCTranslate2TranslationBackend(
+        name="nllb-200-distilled-600m",
+        model_id="facebook/nllb-200-distilled-600M",
+        model_dir=str(incomplete_dir),
+        device="cpu",
+        torch_dtype="float32",
+        batch_size=1,
+        max_input_length=16,
+        max_new_tokens=16,
+        num_beams=1,
+    )
+
+    assert backend._model_source() == "facebook/nllb-200-distilled-600M"
+
+
 def test_nllb_resolves_flores_short_tags_and_iso_no():
     cat = build_nllb_language_catalog(None)
     assert resolve_nllb_language_code("ca", cat) == "cat_Latn"
@@ -197,6 +197,73 @@ def test_translation_route_log_focuses_on_routing_decision(monkeypatch, caplog):
     ]
+def test_service_skips_failed_backend_but_keeps_healthy_capabilities(monkeypatch):
+    monkeypatch.setattr(TranslationCache, "_init_redis_client", staticmethod(lambda: None))
+
+    def _fake_create_backend(self, *, name, backend_type, cfg):
+        del self, backend_type, cfg
+        if name == "broken-nllb":
+            raise RuntimeError("broken model dir")
+
+        class _Backend:
+            model = name
+
+            @property
+            def supports_batch(self):
+                return True
+
+            def translate(self, text, target_lang, source_lang=None, scene=None):
+                del target_lang, source_lang, scene
+                return text
+
+        return _Backend()
+
+    monkeypatch.setattr(TranslationService, "_create_backend", _fake_create_backend)
+    service = TranslationService(
+        {
+            "service_url": "http://127.0.0.1:6006",
+            "timeout_sec": 10.0,
+            "default_model": "llm",
+            "default_scene": "general",
+            "capabilities": {
+                "llm": {
+                    "enabled": True,
+                    "backend": "llm",
+                    "model": "dummy-llm",
+                    "base_url": "https://example.com",
+                    "timeout_sec": 10.0,
+                    "use_cache": True,
+                },
+                "broken-nllb": {
+                    "enabled": True,
+                    "backend": "local_nllb",
+                    "model_id": "dummy",
+                    "model_dir": "dummy",
+                    "device": "cpu",
+                    "torch_dtype": "float32",
+                    "batch_size": 8,
+                    "max_input_length": 16,
+                    "max_new_tokens": 16,
+                    "num_beams": 1,
+                    "use_cache": True,
+                },
+            },
+            "cache": {
+                "ttl_seconds": 60,
+                "sliding_expiration": True,
+            },
+        }
+    )
+
+    assert service.available_models == ["llm", "broken-nllb"]
+    assert service.loaded_models == ["llm"]
+    assert service.failed_models == ["broken-nllb"]
+    assert service.backend_errors["broken-nllb"] == "broken model dir"
+
+    with pytest.raises(RuntimeError, match="failed to initialize"):
+        service.get_backend("broken-nllb")
+
+
 def test_translation_cache_probe_models_order():
     cfg = {"cache": {"model_quality_tiers": {"low": 10, "high": 50, "mid": 30}}}
     assert translation_cache_probe_models(cfg, "low") == ["high", "mid", "low"]
@@ -4,9 +4,7 @@ from __future__ import annotations
 import logging
 import os
-import shutil
-import subprocess
-import sys
+import json
 import threading
 from pathlib import Path
 from typing import Dict, List, Optional, Sequence, Union
@@ -24,6 +22,7 @@ from translation.text_splitter import (
     join_translated_segments,
     split_text_for_translation,
 )
+from translation.ct2_conversion import convert_transformers_model
 logger = logging.getLogger(__name__)
@@ -76,17 +75,18 @@ def _derive_ct2_model_dir(model_dir: str, compute_type: str) -&gt; str:
     return str(Path(model_dir).expanduser() / f"ctranslate2-{normalized}")
-def _resolve_converter_binary() -> str:
-    candidate = shutil.which("ct2-transformers-converter")
-    if candidate:
-        return candidate
-    venv_candidate = Path(sys.executable).absolute().parent / "ct2-transformers-converter"
-    if venv_candidate.exists():
-        return str(venv_candidate)
-    raise RuntimeError(
-        "ct2-transformers-converter was not found. "
-        "Ensure ctranslate2 is installed in the active translator environment."
-    )
+def _detect_local_model_type(model_dir: str) -> Optional[str]:
+    config_path = Path(model_dir).expanduser() / "config.json"
+    if not config_path.exists():
+        return None
+    try:
+        with open(config_path, "r", encoding="utf-8") as handle:
+            payload = json.load(handle) or {}
+    except Exception as exc:
+        logger.warning("Failed to inspect local translation config %s: %s", config_path, exc)
+        return None
+    model_type = str(payload.get("model_type") or "").strip().lower()
+    return model_type or None
 class LocalCTranslate2TranslationBackend:
@@ -144,6 +144,7 @@ class LocalCTranslate2TranslationBackend:
         self.ct2_decoding_length_extra = int(ct2_decoding_length_extra)
         self.ct2_decoding_length_min = max(1, int(ct2_decoding_length_min))
         self._tokenizer_lock = threading.Lock()
+        self._local_model_source = self._resolve_local_model_source()
         self._load_runtime()
     @property
@@ -151,10 +152,44 @@ class LocalCTranslate2TranslationBackend:
         return True
     def _tokenizer_source(self) -> str:
-        return self.model_dir if os.path.exists(self.model_dir) else self.model_id
+        return self._local_model_source or self.model_id
     def _model_source(self) -> str:
-        return self.model_dir if os.path.exists(self.model_dir) else self.model_id
+        return self._local_model_source or self.model_id
+
+    def _expected_local_model_types(self) -> Optional[set[str]]:
+        return None
+
+    def _resolve_local_model_source(self) -> Optional[str]:
+        model_path = Path(self.model_dir).expanduser()
+        if not model_path.exists():
+            return None
+        if not (model_path / "config.json").exists():
+            logger.warning(
+                "Local translation model_dir is incomplete | model=%s model_dir=%s missing=config.json fallback=model_id",
+                self.model,
+                model_path,
+            )
+            return None
+
+        expected_types = self._expected_local_model_types()
+        if not expected_types:
+            return str(model_path)
+
+        detected_type = _detect_local_model_type(str(model_path))
+        if detected_type is None:
+            return str(model_path)
+        if detected_type in expected_types:
+            return str(model_path)
+
+        logger.warning(
+            "Local translation model_dir has unexpected model_type | model=%s model_dir=%s detected=%s expected=%s fallback=model_id",
+            self.model,
+            model_path,
+            detected_type,
+            sorted(expected_types),
+        )
+        return None
     def _tokenizer_kwargs(self) -> Dict[str, object]:
         return {}
@@ -204,7 +239,6 @@ class LocalCTranslate2TranslationBackend:
             )
         ct2_path.parent.mkdir(parents=True, exist_ok=True)
-        converter = _resolve_converter_binary()
         logger.info(
             "Converting translation model to CTranslate2 | name=%s source=%s output=%s quantization=%s",
             self.model,
@@ -213,25 +247,14 @@ class LocalCTranslate2TranslationBackend:
             self.ct2_conversion_quantization,
         )
         try:
-            subprocess.run(
-                [
-                    converter,
-                    "--model",
-                    model_source,
-                    "--output_dir",
-                    str(ct2_path),
-                    "--quantization",
-                    self.ct2_conversion_quantization,
-                ],
-                check=True,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                text=True,
+            convert_transformers_model(
+                model_source,
+                str(ct2_path),
+                self.ct2_conversion_quantization,
             )
-        except subprocess.CalledProcessError as exc:
-            stderr = exc.stderr.strip()
+        except Exception as exc:
             raise RuntimeError(
-                f"Failed to convert model '{self.model}' to CTranslate2: {stderr or exc}"
+                f"Failed to convert model '{self.model}' to CTranslate2: {exc}"
             ) from exc
     def _normalize_texts(self, text: Union[str, Sequence[str]]) -> List[str]:
@@ -557,6 +580,9 @@ class MarianCTranslate2TranslationBackend(LocalCTranslate2TranslationBackend):
                 f"Model '{self.model}' only supports target languages: {sorted(self.target_langs)}"
             )
+    def _expected_local_model_types(self) -> Optional[set[str]]:
+        return {"marian"}
+
 class NLLBCTranslate2TranslationBackend(LocalCTranslate2TranslationBackend):
     """Local backend for NLLB models on CTranslate2."""
@@ -619,6 +645,9 @@ class NLLBCTranslate2TranslationBackend(LocalCTranslate2TranslationBackend):
         if resolve_nllb_language_code(target_lang, self.language_codes) is None:
             raise ValueError(f"Unsupported NLLB target language: {target_lang}")
+    def _expected_local_model_types(self) -> Optional[set[str]]:
+        return {"m2m_100", "nllb_moe"}
+
     def _get_tokenizer_for_source(self, source_lang: str):
         src_code = resolve_nllb_language_code(source_lang, self.language_codes)
         if src_code is None:
@@ -0,0 +1,52 @@
+"""Helpers for converting Hugging Face translation models to CTranslate2."""
+
+from __future__ import annotations
+
+import copy
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def convert_transformers_model(
+    model_name_or_path: str,
+    output_dir: str,
+    quantization: str,
+    *,
+    force: bool = False,
+) -> str:
+    from ctranslate2.converters import TransformersConverter
+    from transformers import AutoConfig
+
+    class _CompatibleTransformersConverter(TransformersConverter):
+        def load_model(self, model_class, resolved_model_name_or_path, **kwargs):
+            try:
+                return super().load_model(model_class, resolved_model_name_or_path, **kwargs)
+            except TypeError as exc:
+                if "unexpected keyword argument 'dtype'" not in str(exc):
+                    raise
+                if kwargs.get("dtype") is None and kwargs.get("torch_dtype") is None:
+                    raise
+
+                logger.warning(
+                    "Retrying CTranslate2 model load without dtype hints | model=%s class=%s",
+                    resolved_model_name_or_path,
+                    getattr(model_class, "__name__", model_class),
+                )
+                retry_kwargs = dict(kwargs)
+                retry_kwargs.pop("dtype", None)
+                retry_kwargs.pop("torch_dtype", None)
+                config = retry_kwargs.get("config")
+                if config is None:
+                    config = AutoConfig.from_pretrained(resolved_model_name_or_path)
+                else:
+                    config = copy.deepcopy(config)
+                if hasattr(config, "dtype"):
+                    config.dtype = None
+                if hasattr(config, "torch_dtype"):
+                    config.torch_dtype = None
+                retry_kwargs["config"] = config
+                return super().load_model(model_class, resolved_model_name_or_path, **retry_kwargs)
+
+    converter = _CompatibleTransformersConverter(model_name_or_path)
+    return converter.convert(output_dir=output_dir, quantization=quantization, force=force)
@@ -31,7 +31,12 @@ class TranslationService:
         if not self._enabled_capabilities:
             raise ValueError("No enabled translation backends found in services.translation.capabilities")
         self._translation_cache = TranslationCache(self.config["cache"])
-        self._backends = self._initialize_backends()
+        self._backends: Dict[str, TranslationBackendProtocol] = {}
+        self._backend_errors: Dict[str, str] = {}
+        self._initialize_backends()
+        if not self._backends:
+            details = ", ".join(f"{name}: {err}" for name, err in sorted(self._backend_errors.items())) or "unknown error"
+            raise RuntimeError(f"No translation backends could be initialized: {details}")
     def _collect_enabled_capabilities(self) -> Dict[str, Dict[str, object]]:
         enabled: Dict[str, Dict[str, object]] = {}
@@ -62,24 +67,47 @@ class TranslationService:
             raise ValueError(f"Unsupported translation backend '{backend_type}' for capability '{name}'")
         return factory(name=name, cfg=cfg)
-    def _initialize_backends(self) -> Dict[str, TranslationBackendProtocol]:
-        backends: Dict[str, TranslationBackendProtocol] = {}
-        for name, capability_cfg in self._enabled_capabilities.items():
-            backend_type = str(capability_cfg["backend"])
-            logger.info("Initializing translation backend | model=%s backend=%s", name, backend_type)
-            backends[name] = self._create_backend(
+    def _load_backend(self, name: str) -> Optional[TranslationBackendProtocol]:
+        capability_cfg = self._enabled_capabilities.get(name)
+        if capability_cfg is None:
+            return None
+        if name in self._backends:
+            return self._backends[name]
+
+        backend_type = str(capability_cfg["backend"])
+        logger.info("Initializing translation backend | model=%s backend=%s", name, backend_type)
+        try:
+            backend = self._create_backend(
                 name=name,
                 backend_type=backend_type,
                 cfg=capability_cfg,
             )
-            logger.info(
-                "Translation backend initialized | model=%s backend=%s use_cache=%s backend_model=%s",
+        except Exception as exc:
+            error_text = str(exc).strip() or exc.__class__.__name__
+            self._backend_errors[name] = error_text
+            logger.error(
+                "Translation backend initialization failed | model=%s backend=%s error=%s",
                 name,
                 backend_type,
-                bool(capability_cfg.get("use_cache")),
-                getattr(backends[name], "model", name),
+                error_text,
+                exc_info=True,
             )
-        return backends
+            return None
+
+        self._backends[name] = backend
+        self._backend_errors.pop(name, None)
+        logger.info(
+            "Translation backend initialized | model=%s backend=%s use_cache=%s backend_model=%s",
+            name,
+            backend_type,
+            bool(capability_cfg.get("use_cache")),
+            getattr(backend, "model", name),
+        )
+        return backend
+
+    def _initialize_backends(self) -> None:
+        for name, capability_cfg in self._enabled_capabilities.items():
+            self._load_backend(name)
     def _create_qwen_mt_backend(self, *, name: str, cfg: Dict[str, object]) -> TranslationBackendProtocol:
         from translation.backends.qwen_mt import QwenMTTranslationBackend
@@ -178,13 +206,27 @@ class TranslationService:
     def loaded_models(self) -> List[str]:
         return list(self._backends.keys())
+    @property
+    def failed_models(self) -> List[str]:
+        return list(self._backend_errors.keys())
+
+    @property
+    def backend_errors(self) -> Dict[str, str]:
+        return dict(self._backend_errors)
+
     def get_backend(self, model: Optional[str] = None) -> TranslationBackendProtocol:
         normalized = normalize_translation_model(self.config, model)
-        backend = self._backends.get(normalized)
+        backend = self._backends.get(normalized) or self._load_backend(normalized)
         if backend is None:
-            raise ValueError(
-                f"Translation model '{normalized}' is not enabled. "
-                f"Available models: {', '.join(self.available_models) or 'none'}"
+            if normalized not in self._enabled_capabilities:
+                raise ValueError(
+                    f"Translation model '{normalized}' is not enabled. "
+                    f"Available models: {', '.join(self.available_models) or 'none'}"
+                )
+            error_text = self._backend_errors.get(normalized) or "unknown initialization error"
+            raise RuntimeError(
+                f"Translation model '{normalized}' failed to initialize: {error_text}. "
+                f"Loaded models: {', '.join(self.loaded_models) or 'none'}"
             )
         return backend