Check CPU AVX-512 support before selecting ONNX GPU backends

docs/CONFIGURATION.md

@@ -25,7 +25,7 @@ Selects which speech-to-text engine to use for transcription.
 
 **Values:**
 - `whisper` - OpenAI Whisper via whisper.cpp (default, recommended)
-- `parakeet` - NVIDIA Parakeet via ONNX Runtime (experimental, requires special binary)
+- `parakeet` - NVIDIA Parakeet via ONNX Runtime (requires ONNX binary)
 - `moonshine` - Moonshine encoder-decoder transformer via ONNX Runtime (experimental, requires special binary)
 
 **Example:**
@@ -994,7 +994,7 @@ sudo cp build/bin/whisper-cli /usr/local/bin/
 
 Configuration for the Parakeet speech-to-text engine. This section is only used when `engine = "parakeet"`.
 
-> **Note:** Parakeet support is experimental. See [PARAKEET.md](PARAKEET.md) for detailed setup instructions.
+See [PARAKEET.md](PARAKEET.md) for detailed setup instructions.
 
 ### model
 

docs/PARAKEET.md

@@ -1,10 +1,6 @@
-# Parakeet Backend (Experimental)
+# Parakeet Backend
 
-> **WARNING: Experimental Feature**
->
-> Parakeet support is experimental and not yet fully integrated into voxtype's setup system. Configuration requires manual editing of config files. The API and configuration options may change in future releases. Use at your own risk.
-
-Voxtype 0.5.0+ includes experimental support for NVIDIA's Parakeet ASR models as an alternative to Whisper. Parakeet uses ONNX Runtime and offers excellent CPU performance without requiring a GPU.
+Voxtype supports NVIDIA's Parakeet ASR models as an alternative to Whisper. Parakeet uses ONNX Runtime and offers excellent CPU performance without requiring a GPU.
 
 ## What is Parakeet?
 
@@ -211,7 +207,7 @@ Please report the issue at https://github.com/peteonrails/voxtype/issues with:
 
 ## Feedback
 
-Parakeet support is experimental. Please report issues at:
+Please report issues at:
 https://github.com/peteonrails/voxtype/issues
 
 Include:

src/main.rs

@@ -1121,8 +1121,8 @@ async fn show_config(config: &config::Config) -> anyhow::Result<()> {
         println!("  gpu_device = {}", gpu_device);
     }
 
-    // Show Parakeet status (experimental)
-    println!("\n[parakeet] (EXPERIMENTAL)");
+    // Show Parakeet status
+    println!("\n[parakeet]");
     if let Some(ref parakeet_config) = config.parakeet {
         println!("  model = {:?}", parakeet_config.model);
         if let Some(ref model_type) = parakeet_config.model_type {

src/setup/gpu.rs

@@ -708,6 +708,17 @@ pub fn show_status() {
 fn detect_best_parakeet_gpu_backend() -> Option<(&'static str, &'static str)> {
     let gpus = detect_gpus();
 
+    // The CUDA and ROCm binaries bundle ONNX Runtime which contains AVX-512
+    // instructions. On CPUs without AVX-512 (e.g., Zen 3), these binaries will
+    // crash with SIGILL. Only select GPU backends if the CPU supports AVX-512.
+    let has_avx512 = fs::read_to_string("/proc/cpuinfo")
+        .map(|info| info.contains("avx512f"))
+        .unwrap_or(false);
+
+    if !has_avx512 {
+        return None;
+    }
+
     // Helper to find installed binary, preferring new name over legacy
     let find_binary =
         |new_name: &'static str, legacy_name: &'static str| -> Option<&'static str> {
@@ -758,8 +769,18 @@ pub fn enable() -> anyhow::Result<()> {
             let gpus = detect_gpus();
             let has_amd = gpus.iter().any(|g| g.vendor == GpuVendor::Amd);
             let has_nvidia = gpus.iter().any(|g| g.vendor == GpuVendor::Nvidia);
-
-            let hint = if has_amd {
+            let has_avx512 = fs::read_to_string("/proc/cpuinfo")
+                .map(|info| info.contains("avx512f"))
+                .unwrap_or(false);
+
+            let hint = if (has_amd || has_nvidia) && !has_avx512 {
+                "You have a GPU, but the ONNX GPU binaries (CUDA/ROCm) require a CPU with \
+                 AVX-512 support. Your CPU only supports AVX2.\n\n\
+                 Use ONNX on CPU instead:\n  \
+                 sudo ln -sf /usr/lib/voxtype/voxtype-onnx-avx2 /usr/bin/voxtype\n\n\
+                 Or use the Whisper engine with Vulkan GPU acceleration:\n  \
+                 voxtype setup onnx --disable && sudo voxtype setup gpu --enable"
+            } else if has_amd {
                 "You have an AMD GPU. Install voxtype-onnx-rocm for GPU acceleration."
             } else if has_nvidia {
                 "You have an NVIDIA GPU. Install voxtype-onnx-cuda for GPU acceleration."
@@ -768,10 +789,8 @@ pub fn enable() -> anyhow::Result<()> {
             };
 
             anyhow::anyhow!(
-                "No ONNX GPU backend installed.\n\
-                 Neither voxtype-onnx-cuda nor voxtype-onnx-rocm found in {}\n\n\
+                "No compatible ONNX GPU backend found.\n\n\
                  {}",
-                VOXTYPE_LIB_DIR,
                 hint
             )
         })?;

src/setup/mod.rs

@@ -539,7 +539,7 @@ pub async fn run_setup(
         let model_name = model_override.unwrap(); // Safe: is_parakeet implies Some
 
         if !quiet {
-            println!("\nParakeet model (EXPERIMENTAL)...");
+            println!("\nParakeet model...");
         }
 
         // Check if parakeet feature is enabled
@@ -787,8 +787,8 @@ pub async fn run_checks(config: &Config) -> anyhow::Result<()> {
         all_ok = false;
     }
 
-    // Check Parakeet models (experimental)
-    println!("\nParakeet Models (EXPERIMENTAL):");
+    // Check Parakeet models
+    println!("\nParakeet Models:");
 
     // Find available Parakeet models
     let mut parakeet_models: Vec<(String, u64)> = Vec::new();

src/setup/model.rs

@@ -1501,8 +1501,8 @@ fn update_parakeet_in_config(config: &str, model_name: &str) -> String {
 
 /// List installed Parakeet models
 pub fn list_installed_parakeet() {
-    println!("\nInstalled Parakeet Models (EXPERIMENTAL)\n");
-    println!("=========================================\n");
+    println!("\nInstalled Parakeet Models\n");
+    println!("=========================\n");
 
     let models_dir = Config::models_dir();
 

src/setup/parakeet.rs

@@ -132,23 +132,27 @@ fn detect_best_parakeet_backend() -> Option<ParakeetBackend> {
         return None;
     }
 
-    // Prefer CUDA if available and NVIDIA GPU detected
-    if available.contains(&ParakeetBackend::Cuda) && detect_nvidia_gpu() {
+    let has_avx512 = fs::read_to_string("/proc/cpuinfo")
+        .map(|info| info.contains("avx512f"))
+        .unwrap_or(false);
+
+    // Prefer CUDA if available and NVIDIA GPU detected.
+    // The CUDA binary bundles ONNX Runtime which may contain AVX-512 instructions,
+    // so only select it if the CPU supports AVX-512.
+    if available.contains(&ParakeetBackend::Cuda) && detect_nvidia_gpu() && has_avx512 {
         return Some(ParakeetBackend::Cuda);
     }
 
-    // Prefer ROCm if available and AMD GPU detected
-    if available.contains(&ParakeetBackend::Rocm) && detect_amd_gpu() {
+    // Prefer ROCm if available and AMD GPU detected.
+    // The ROCm binary bundles ONNX Runtime which contains AVX-512 instructions,
+    // so only select it if the CPU supports AVX-512.
+    if available.contains(&ParakeetBackend::Rocm) && detect_amd_gpu() && has_avx512 {
         return Some(ParakeetBackend::Rocm);
     }
 
-    // Check for AVX-512 support
-    if available.contains(&ParakeetBackend::Avx512) {
-        if let Ok(cpuinfo) = fs::read_to_string("/proc/cpuinfo") {
-            if cpuinfo.contains("avx512f") {
-                return Some(ParakeetBackend::Avx512);
-            }
-        }
+    // Check for AVX-512 CPU-only backend
+    if available.contains(&ParakeetBackend::Avx512) && has_avx512 {
+        return Some(ParakeetBackend::Avx512);
     }
 
     // Fall back to AVX2
@@ -316,6 +320,10 @@ pub fn show_status() {
     println!();
     let has_nvidia = detect_nvidia_gpu();
     let has_amd = detect_amd_gpu();
+    let has_avx512 = fs::read_to_string("/proc/cpuinfo")
+        .map(|info| info.contains("avx512f"))
+        .unwrap_or(false);
+
     if has_nvidia {
         println!("NVIDIA GPU: detected");
     }
@@ -325,6 +333,11 @@ pub fn show_status() {
     if !has_nvidia && !has_amd {
         println!("GPU: not detected");
     }
+    if (has_nvidia || has_amd) && !has_avx512 {
+        println!("\nNote: ONNX GPU binaries (CUDA/ROCm) require AVX-512 CPU support.");
+        println!("  Your CPU supports AVX2 only. Use ONNX (AVX2) for CPU-based inference,");
+        println!("  or use the Whisper engine with Vulkan for GPU acceleration.");
+    }
 
     // Usage hints
     println!();