Skip to content

AI media harness for planning, generating, and editing locally

TypeScript

Select the worker GPU backend and CUDA version

Bitti4ebe251fba2e
diff --git a/README.md b/README.md
index 71e65af..c018f53 100644
--- a/README.md
+++ b/README.md
@@ -53,7 +53,7 @@ Unpack the Slopus worker package (`Slopus-<version>-windows-x64-worker.zip`, con
slopus-worker.exe --weights D:\Models
```
-Allow it through Windows Firewall when asked. In Slopus, open **Settings → Workers** and click **Use** next to the worker. Generators whose weights have download links become usable even if they are not downloaded on this computer; the worker downloads missing weights into its weights folders on first use. Run `slopus-worker.exe --help` for options: `--port`, `--name`, `--token` (require an access token), `--data`, `--weights` (repeatable), `--vulkan` and `--no-mdns`. Choose **This computer** to generate locally again.
+Allow it through Windows Firewall when asked. In Slopus, open **Settings → Workers** and click **Use** next to the worker. Generators whose weights have download links become usable even if they are not downloaded on this computer; the worker downloads missing weights into its weights folders on first use. Run `slopus-worker.exe --help` for options: `--port`, `--name`, `--token` (require an access token), `--data`, `--weights` (repeatable), `--backend` and `--no-mdns`. The worker uses CUDA when it is available (CUDA 13 if installed, otherwise CUDA 12) and otherwise falls back to Vulkan, printing a warning if an NVIDIA GPU is present without a usable CUDA installation. `--backend cuda13`, `--backend cuda12`, `--backend cuda` or `--backend vulkan` overrides the choice. Choose **This computer** to generate locally again.
The project's GPU setup recommendations are:
diff --git a/src-tauri/core/src/slopfab/mod.rs b/src-tauri/core/src/slopfab/mod.rs
index 5820ee1..7f681b0 100644
--- a/src-tauri/core/src/slopfab/mod.rs
+++ b/src-tauri/core/src/slopfab/mod.rs
@@ -28,6 +28,7 @@ pub use types::*;
pub use events::NativeEvent;
pub use icons::{generate_reference_icon_batch, ReferenceIconBatchConfig, ReferenceIconSpec};
pub use planning::resolve_plan;
+pub use platform::{probe_backend, BackendProbe};
pub use status::{status, worker_status};
const DLL_FILE_NAME: &str = "slopfab.dll";
/// Tauri stages the repository's runtime resources in development and release
diff --git a/src-tauri/core/src/slopfab/platform.rs b/src-tauri/core/src/slopfab/platform.rs
index 0e34ff2..484cbdd 100644
--- a/src-tauri/core/src/slopfab/platform.rs
+++ b/src-tauri/core/src/slopfab/platform.rs
@@ -45,3 +45,43 @@ pub(super) fn detect_platform(api: &ffi::Api) -> ComputePlatform {
let _ = api.set_cuda_version("auto");
platform_from_cuda_probe(api.cuda_loaded_major())
}
+
+/// What the GPU backend choice depends on, for a host that picks it itself.
+#[derive(Debug, Clone)]
+pub struct BackendProbe {
+ /// An NVIDIA GPU is present, whether or not CUDA can be used on it.
+ pub nvidia_gpu: bool,
+ /// "CUDA 13" or "CUDA 12" when the CUDA runtime loaded.
+ pub cuda: Option<&'static str>,
+ /// Why CUDA could not be used on an NVIDIA GPU.
+ pub cuda_problem: Option<String>,
+}
+
+/// Probes the engine at `dll_path` for CUDA. `cuda_version` is "auto" (CUDA
+/// 13, then 12), "13" or "12"; the engine fixes the toolkit for the whole
+/// process on first use, so call this before any generation. Fails only when
+/// the engine itself cannot be loaded.
+pub fn probe_backend(dll_path: &std::path::Path, cuda_version: &str) -> Result<BackendProbe, String> {
+ let api = ffi::Api::load(dll_path)?;
+ api.version()?;
+ let cuda_device = ffi::has_cuda_device();
+ // The display adapter list also covers a driver that cannot start CUDA.
+ let nvidia_gpu = cuda_device || crate::weights::hardware_devices().iter()
+ .any(|device| device.name.to_ascii_lowercase().contains("nvidia"));
+ if !cuda_device {
+ let cuda_problem = nvidia_gpu.then(|| "the NVIDIA driver reports no CUDA device".to_string());
+ return Ok(BackendProbe { nvidia_gpu, cuda: None, cuda_problem });
+ }
+ api.set_cuda_version(cuda_version)?;
+ let major = api.cuda_loaded_major();
+ // The toolkit choice lives in the loaded DLL. Keep this instance loaded
+ // so later loads share it instead of starting over with "auto".
+ std::mem::forget(api);
+ Ok(match major {
+ Ok(major) => match platform_from_cuda_probe(Ok(major)) {
+ ComputePlatform::Vulkan => BackendProbe { nvidia_gpu, cuda: None, cuda_problem: Some(format!("CUDA {major} is not supported; install CUDA 12.8 or 13")) },
+ platform => BackendProbe { nvidia_gpu, cuda: Some(platform.label()), cuda_problem: None },
+ },
+ Err(error) => BackendProbe { nvidia_gpu, cuda: None, cuda_problem: Some(error) },
+ })
+}
diff --git a/src-tauri/core/src/worker/mod.rs b/src-tauri/core/src/worker/mod.rs
index 7b3f890..d4b443e 100644
--- a/src-tauri/core/src/worker/mod.rs
+++ b/src-tauri/core/src/worker/mod.rs
@@ -6,4 +6,4 @@ pub mod server;
pub mod store;
pub use protocol::{WorkerRuntime, DEFAULT_PORT};
-pub use server::{run, WorkerOptions};
+pub use server::{run, Backend, WorkerOptions};
diff --git a/src-tauri/core/src/worker/server.rs b/src-tauri/core/src/worker/server.rs
index 120454b..cd31b3c 100644
--- a/src-tauri/core/src/worker/server.rs
+++ b/src-tauri/core/src/worker/server.rs
@@ -26,6 +26,74 @@ use std::{
};
use tiny_http::{Header, Method, Request, Response, Server};
+/// Which GPU backend the worker runs generation on.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Backend {
+ /// CUDA 13, then CUDA 12, when available; otherwise Vulkan.
+ #[default]
+ Auto,
+ /// CUDA 13, then CUDA 12; an error when neither loads.
+ Cuda,
+ Cuda13,
+ Cuda12,
+ Vulkan,
+}
+
+impl Backend {
+ fn is_cuda(self) -> bool {
+ matches!(self, Self::Cuda | Self::Cuda13 | Self::Cuda12)
+ }
+
+ /// The engine's CUDA toolkit request.
+ pub fn cuda_version(self) -> &'static str {
+ match self {
+ Self::Cuda13 => "13",
+ Self::Cuda12 => "12",
+ _ => "auto",
+ }
+ }
+}
+
+impl std::str::FromStr for Backend {
+ type Err = String;
+ fn from_str(value: &str) -> Result<Self, String> {
+ match value.to_ascii_lowercase().replace(['-', ' ', '.'], "").as_str() {
+ "auto" => Ok(Self::Auto),
+ "cuda" => Ok(Self::Cuda),
+ "cuda13" => Ok(Self::Cuda13),
+ "cuda12" => Ok(Self::Cuda12),
+ "vulkan" => Ok(Self::Vulkan),
+ _ => Err(format!("Unknown backend '{value}'. Use auto, cuda, cuda13, cuda12 or vulkan.")),
+ }
+ }
+}
+
+/// The backend to run on, and a warning to show when Auto had to fall back.
+/// Forcing CUDA where it cannot load is an error rather than a silent Vulkan run.
+pub fn choose_backend(requested: Backend, probe: &slopfab::BackendProbe) -> Result<(bool, Option<String>), String> {
+ let problem = probe.cuda_problem.as_deref().unwrap_or("CUDA was not found");
+ let flag = match requested {
+ Backend::Cuda13 => "--backend cuda13",
+ Backend::Cuda12 => "--backend cuda12",
+ _ => "--backend cuda",
+ };
+ let install = match requested {
+ Backend::Cuda13 => "Install the CUDA 13 toolkit",
+ Backend::Cuda12 => "Install the CUDA 12.8 toolkit",
+ _ => "Install CUDA 12.8 (RTX 30/40) or CUDA 13 (RTX 50)",
+ };
+ match (requested, probe.cuda) {
+ (Backend::Vulkan, _) => Ok((true, None)),
+ (_, Some(_)) => Ok((false, None)),
+ (backend, None) if backend.is_cuda() && probe.nvidia_gpu => Err(format!("{flag}: CUDA is not available ({problem}). {install}, or use --backend vulkan.")),
+ (backend, None) if backend.is_cuda() => Err(format!("{flag}: no NVIDIA GPU was found. Use --backend vulkan.")),
+ (Backend::Auto, None) if probe.nvidia_gpu => Ok((true, Some(format!(
+ "WARNING: This NVIDIA GPU supports CUDA, but CUDA was not detected ({problem}). Using the slower Vulkan backend. Install CUDA 12.8 (RTX 30/40) or CUDA 13 (RTX 50) for faster generation."
+ )))),
+ (_, None) => Ok((true, None)),
+ }
+}
+
#[derive(Debug, Clone)]
pub struct WorkerOptions {
pub port: u16,
@@ -33,13 +101,13 @@ pub struct WorkerOptions {
pub token: Option<String>,
pub data: Option<PathBuf>,
pub weights: Vec<PathBuf>,
- pub vulkan: bool,
+ pub backend: Backend,
pub advertise: bool,
}
impl Default for WorkerOptions {
fn default() -> Self {
- Self { port: DEFAULT_PORT, name: None, token: None, data: None, weights: Vec::new(), vulkan: false, advertise: true }
+ Self { port: DEFAULT_PORT, name: None, token: None, data: None, weights: Vec::new(), backend: Backend::Auto, advertise: true }
}
}
@@ -183,11 +251,27 @@ pub fn run(options: WorkerOptions) -> Result<(), String> {
eprintln!("Could not initialize diagnostic logging: {error}");
}
let roots = crate::weights::worker_weight_roots(&options.weights, &data)?;
+ // Vulkan needs no CUDA probe; the engine then keeps its default toolkit choice.
+ let probed = if options.backend == Backend::Vulkan { Err(String::new()) }
+ else { slopfab::probe_backend(&slopfab::default_dll_path(), options.backend.cuda_version()) };
+ let (vulkan, backend) = match probed {
+ Ok(probe) => {
+ let (vulkan, warning) = choose_backend(options.backend, &probe)?;
+ if let Some(warning) = warning {
+ eprintln!("{warning}");
+ diagnostics::warn("worker", "backend.fallback", &warning, serde_json::json!({}));
+ }
+ (vulkan, if vulkan { "Vulkan" } else { probe.cuda.unwrap_or("CUDA") })
+ }
+ Err(_) if options.backend == Backend::Vulkan => (true, "Vulkan"),
+ // The engine could not load; the worker still answers and reports why.
+ Err(_) => (false, "unavailable"),
+ };
let worker = Arc::new(Worker {
id: worker_id(&data)?,
name: options.name.clone().unwrap_or_else(computer_name),
token: options.token.clone().filter(|token| !token.is_empty()),
- vulkan: options.vulkan,
+ vulkan,
store: Arc::new(FileStore::new(&data, roots.clone())?),
data,
runtime: slopfab::SlopfabRuntime::default(),
@@ -198,6 +282,7 @@ pub fn run(options: WorkerOptions) -> Result<(), String> {
let info = worker.info();
println!("Slopus worker '{}' ({}) listening on port {}.", info.name, info.id, options.port);
println!("Engine: {} {}", info.runtime.state, info.runtime.version.as_deref().unwrap_or(""));
+ println!("Backend: {backend}{}", if options.backend == Backend::Auto { " (automatic; override with --backend)" } else { "" });
println!("Weights: {}", roots.iter().map(|root| root.display().to_string()).collect::<Vec<_>>().join("; "));
println!("Data: {}", worker.data.display());
if worker.token.is_some() {
@@ -532,3 +617,43 @@ fn percent_decode(part: &str) -> Result<String, String> {
}
String::from_utf8(decoded).map_err(|_| "Upload paths must be UTF-8.".into())
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn probe(nvidia_gpu: bool, cuda: Option<&'static str>) -> slopfab::BackendProbe {
+ slopfab::BackendProbe { nvidia_gpu, cuda, cuda_problem: (nvidia_gpu && cuda.is_none()).then(|| "cublas64_12.dll not found".into()) }
+ }
+
+ #[test]
+ fn auto_uses_cuda_when_it_loads_and_warns_before_falling_back_on_nvidia() {
+ assert_eq!(choose_backend(Backend::Auto, &probe(true, Some("CUDA 13"))).unwrap(), (false, None));
+ let (vulkan, warning) = choose_backend(Backend::Auto, &probe(true, None)).unwrap();
+ assert!(vulkan);
+ assert!(warning.unwrap().contains("cublas64_12.dll not found"));
+ assert_eq!(choose_backend(Backend::Auto, &probe(false, None)).unwrap(), (true, None), "AMD and Intel use Vulkan quietly");
+ }
+
+ #[test]
+ fn a_requested_cuda_major_must_load() {
+ assert_eq!(Backend::Cuda13.cuda_version(), "13");
+ assert_eq!(Backend::Cuda12.cuda_version(), "12");
+ assert_eq!(Backend::Auto.cuda_version(), "auto");
+ assert_eq!("CUDA-12".parse::<Backend>().unwrap(), Backend::Cuda12);
+ assert_eq!("cuda13".parse::<Backend>().unwrap(), Backend::Cuda13);
+ assert_eq!(choose_backend(Backend::Cuda12, &probe(true, Some("CUDA 12"))).unwrap(), (false, None));
+ let error = choose_backend(Backend::Cuda13, &probe(true, None)).unwrap_err();
+ assert!(error.starts_with("--backend cuda13") && error.contains("CUDA 13 toolkit"), "{error}");
+ }
+
+ #[test]
+ fn an_explicit_backend_overrides_detection_but_cuda_must_exist() {
+ assert_eq!(choose_backend(Backend::Vulkan, &probe(true, Some("CUDA 12"))).unwrap(), (true, None));
+ assert_eq!(choose_backend(Backend::Cuda, &probe(true, Some("CUDA 12"))).unwrap(), (false, None));
+ assert!(choose_backend(Backend::Cuda, &probe(true, None)).unwrap_err().contains("CUDA is not available"));
+ assert!(choose_backend(Backend::Cuda, &probe(false, None)).unwrap_err().contains("no NVIDIA GPU"));
+ assert_eq!("VULKAN".parse::<Backend>().unwrap(), Backend::Vulkan);
+ assert!("metal".parse::<Backend>().is_err());
+ }
+}
diff --git a/src-tauri/worker/src/main.rs b/src-tauri/worker/src/main.rs
index bf2f66d..c03b50d 100644
--- a/src-tauri/worker/src/main.rs
+++ b/src-tauri/worker/src/main.rs
@@ -13,7 +13,8 @@ const USAGE: &str = r"Usage: slopus-worker [options]
--token <text> Require this access token from clients
--data <folder> Uploads, job files and logs (default: %LOCALAPPDATA%\Slopus Worker)
--weights <folder> Extra weights folder to search and download into; repeatable
- --vulkan Use the Vulkan backend instead of CUDA
+ --backend <name> GPU backend: auto (default: CUDA 13, then CUDA 12, else Vulkan),
+ cuda (CUDA 13, then 12), cuda13, cuda12 or vulkan
--no-mdns Do not announce on the network; clients add it by address
--help Show this help";
@@ -31,7 +32,7 @@ fn parse() -> Result<WorkerOptions, String> {
let folder = std::path::absolute(value("--weights")?).map_err(|error| error.to_string())?;
options.weights.push(folder);
}
- "--vulkan" => options.vulkan = true,
+ "--backend" => options.backend = value("--backend")?.parse()?,
"--no-mdns" => options.advertise = false,
"--help" | "-h" => {
println!("{USAGE}");