Skip to content

armgit / kokon

Public Imported from GitHub
0

Edit photos by describing the change, on your own GPU. A free, open-source alternative to Nano Banana and ChatGPT image editing: photos stay on your computer, no daily limit. One installer for Windows, Mac and Linux sets up the best open model (Qwen-Image 2.1). MCP server for AI agents.

feat(setup): use model files you already have (#14)

Gabriele Lozuponee860a01775cb
diff --git a/crates/qls-core/src/catalog.rs b/crates/qls-core/src/catalog.rs
index d8fcf4c..ab582e6 100644
--- a/crates/qls-core/src/catalog.rs
+++ b/crates/qls-core/src/catalog.rs
@@ -54,8 +54,12 @@ pub struct Download {
pub engine_tag: Option<&'static str>,
}
-/// `base` + a catalog path written with `/`, as native components.
+/// `base` + a catalog path written with `/`, as native components. An absolute path (a model
+/// downloaded into a folder of the user's, [`Download::at`]) is used as is.
pub fn join_rel(base: &Path, rel: &str) -> PathBuf {
+ if Path::new(rel).is_absolute() {
+ return PathBuf::from(rel);
+ }
rel.split('/').filter(|c| !c.is_empty()).fold(base.to_path_buf(), |p, c| p.join(c))
}
@@ -68,6 +72,16 @@ impl Download {
join_rel(sdcpp_dir, self.dest)
}
+ /// The file name it is saved under.
+ pub fn file_name(&self) -> &'static str {
+ self.dest.rsplit('/').next().unwrap_or(self.dest)
+ }
+
+ /// The same file, saved at `path` (anywhere) instead of the stable-diffusion.cpp folder.
+ pub fn at(self, path: &Path) -> Download {
+ Download { dest: Box::leak(path.to_string_lossy().into_owned().into_boxed_str()), ..self }
+ }
+
/// Every URL to try, in order.
pub fn urls(&self) -> impl Iterator<Item = &'static str> {
std::iter::once(self.url).chain(self.fallback_urls.iter().copied())
@@ -515,6 +529,34 @@ pub fn downloads_for(p: &Preset, backend: GpuBackend) -> Vec<Download> {
v
}
+/// The model files a profile can download: official files it points to that are not there
+/// (a piece the user chose to download, or an official file deleted from their folder), each
+/// saved where the profile expects it. Existing files are never replaced, whatever their name.
+pub fn profile_model_downloads(profile: &crate::config::ModelProfile) -> Vec<Download> {
+ let official = [TURBO_Q4_K, VAE, TEXT_ENCODER_Q4_K_M, TEXT_ENCODER_Q8_0, VISION_PROJECTOR];
+ profile
+ .files()
+ .into_iter()
+ .filter(|(_, p, _)| !p.exists())
+ .filter_map(|(_, p, _)| {
+ let name = p.file_name()?.to_string_lossy().to_string();
+ official.iter().find(|d| d.file_name().eq_ignore_ascii_case(&name)).map(|d| d.at(p))
+ })
+ .collect()
+}
+
+/// Everything a user profile needs on `backend`: the engine, the upscalers, then the model
+/// files of [`profile_model_downloads`]. The official profile uses [`downloads_for`].
+pub fn downloads_for_profile(profile: &crate::config::ModelProfile, backend: GpuBackend) -> Vec<Download> {
+ let mut v = engine_downloads(backend);
+ v.push(UPSCALER);
+ if backend != GpuBackend::Metal {
+ v.push(SUPERSCALE);
+ }
+ v.extend(profile_model_downloads(profile));
+ v
+}
+
/// Folder a zip is extracted into: the folder of its `dest`.
pub fn zip_dir(d: &Download, sdcpp_dir: &Path) -> PathBuf {
d.path(sdcpp_dir).parent().map(Path::to_path_buf).unwrap_or_else(|| sdcpp_dir.to_path_buf())
@@ -646,6 +688,28 @@ mod tests {
assert!(ENGINE_VULKAN.is_present(dir.path()));
}
+ #[test]
+ fn user_profiles_download_only_missing_official_files() {
+ let dir = tempfile::tempdir().unwrap();
+ let own = dir.path().join("own");
+ std::fs::create_dir_all(&own).unwrap();
+ // The user's diffusion model is there; the VAE is the official file (deleted, or chosen
+ // to download); the text encoder is the user's own and missing (a drive not connected).
+ std::fs::write(own.join("turbo_int8.safetensors"), b"x").unwrap();
+ let vae = own.join(VAE.file_name());
+ let p = crate::config::ModelProfile::user(own.join("turbo_int8.safetensors"), vae.clone(), own.join("mine.safetensors"), Some(dir.path().join("dl").join(VISION_PROJECTOR.file_name())));
+ let models = profile_model_downloads(&p);
+ assert_eq!(models.iter().map(|d| d.id).collect::<Vec<_>>(), ["vae", "vision_projector"], "own files are never downloaded");
+ assert_eq!(models[0].path(Path::new("ignored")), vae, "saved where the profile expects it");
+ assert_eq!(models[1].path(dir.path()), dir.path().join("dl").join(VISION_PROJECTOR.file_name()));
+ assert_eq!((models[0].size, models[0].sha256), (VAE.size, VAE.sha256));
+ // An official name with other content (wrong size) is the user's file: never replaced.
+ std::fs::write(&vae, b"mine").unwrap();
+ assert_eq!(profile_model_downloads(&p).len(), 1);
+ let all = downloads_for_profile(&p, GpuBackend::Vulkan);
+ assert_eq!(all.iter().map(|d| d.id).collect::<Vec<_>>(), ["engine_vulkan", "upscaler", "upscaler_superscale", "vision_projector"]);
+ }
+
#[test]
fn presence_checks() {
let dir = tempfile::tempdir().unwrap();
diff --git a/crates/qls-core/src/config.rs b/crates/qls-core/src/config.rs
index db2ecf6..d03a9e6 100644
--- a/crates/qls-core/src/config.rs
+++ b/crates/qls-core/src/config.rs
@@ -19,7 +19,9 @@ pub const DEFAULT_SERVER_PORT: u16 = 39150;
pub const DEFAULT_SERVICE_PORT: u16 = 39151;
/// Schema 8 (2026-10-12): the upscalers folder setting is gone (always `<sdcpp>/models/upscalers`)
/// and ESRGAN tile sizes reset to automatic.
-const SCHEMA_VERSION: u32 = 8;
+/// Schema 9 (2026-10-16, #14): profiles record their model and source; model paths edited by
+/// hand on the official profile move to a profile of the user's own files.
+const SCHEMA_VERSION: u32 = 9;
/// `upscaler_model` value for a plain Lanczos resize (no model).
pub const LANCZOS: &str = "lanczos";
/// Upscalers offered in Settings: (file stem, label). Superscale-SP is a setup download, MoSR is
@@ -38,6 +40,11 @@ pub const DEFAULT_UPSCALER: &str = if cfg!(target_os = "macos") { LANCZOS } else
pub const UPSCALER_EXTENSIONS: &[&str] = &["pth", "safetensors", "gguf", "pt"];
/// Profile id of the official Qwen-Image 2.1 weights (the default since schema 5).
pub const OFFICIAL_PROFILE_ID: &str = "qwen-image-2.1";
+/// Profile id of Qwen-Image 2.1 files the user already had (#14): one per model.
+pub const USER_PROFILE_ID: &str = "qwen-image-2.1-user";
+/// The model a profile's files are (`ModelProfile::model`). Today the only one; future model
+/// definitions (strategy, presets, prompts) will be looked up by this id.
+pub const QWEN_IMAGE_21: &str = "qwen-image-2.1";
/// Where the text encoder's weights live. Compute always runs on the selected GPU except
/// for `Cpu`, which also computes on the CPU (slow for image editing, measured ~35×).
@@ -164,11 +171,26 @@ impl Default for ProfileCapabilities {
}
}
+/// Where a profile's files come from.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ProfileSource {
+ /// Downloaded by Setup from the catalog, tested with Kokon. Paths follow the folder and preset.
+ Official,
+ /// Files the user already had (any folder, any quantization), not tested by Kokon.
+ User,
+}
+
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct ModelProfile {
pub id: String,
pub display_name: String,
+ /// The model these files are ([`QWEN_IMAGE_21`]).
+ pub model: String,
+ pub source: ProfileSource,
+ /// Folder the user's files were found in (Setup searches it again when one has moved).
+ pub scan_dir: Option<PathBuf>,
pub diffusion_model: PathBuf,
pub vae: PathBuf,
pub text_encoder: PathBuf,
@@ -194,6 +216,9 @@ impl ModelProfile {
Self {
id: OFFICIAL_PROFILE_ID.into(),
display_name: format!("Qwen-Image 2.1 Turbo {quant} (official)"),
+ model: QWEN_IMAGE_21.into(),
+ source: ProfileSource::Official,
+ scan_dir: None,
diffusion_model: preset.diffusion.path(sdcpp_dir),
vae: VAE.path(sdcpp_dir),
text_encoder: preset.text_encoder.path(sdcpp_dir),
@@ -217,6 +242,29 @@ impl ModelProfile {
v
}
+ /// Files the user already had.
+ pub fn user(diffusion_model: PathBuf, vae: PathBuf, text_encoder: PathBuf, vision_projector: Option<PathBuf>) -> Self {
+ Self {
+ id: USER_PROFILE_ID.into(),
+ display_name: "Qwen-Image 2.1 (your files)".into(),
+ source: ProfileSource::User,
+ scan_dir: None,
+ diffusion_model,
+ vae,
+ text_encoder,
+ vision_projector,
+ ..Self::default()
+ }
+ }
+
+ pub fn is_official(&self) -> bool {
+ self.source == ProfileSource::Official
+ }
+
+ fn same_files(&self, o: &ModelProfile) -> bool {
+ (&self.diffusion_model, &self.vae, &self.text_encoder, &self.vision_projector) == (&o.diffusion_model, &o.vae, &o.text_encoder, &o.vision_projector)
+ }
+
pub fn model_name(&self) -> String {
self.diffusion_model.file_stem().map(|s| s.to_string_lossy().into_owned()).unwrap_or_else(|| self.display_name.clone())
}
@@ -408,11 +456,6 @@ impl AppConfig {
c.profiles.push(ModelProfile::official(&c.sdcpp_dir, c.preset()));
c.active_profile = OFFICIAL_PROFILE_ID.into();
}
- // A file without profiles got the default one, built for the default
- // folder and preset: build it for the configured folder and preset.
- if c.profiles.len() == 1 && c.profiles[0] == ModelProfile::default() {
- c.profiles[0] = ModelProfile::official(&c.sdcpp_dir, c.preset());
- }
if c.schema_version < 8 {
// ESRGAN tile sizes don't carry over to MoSR, which picks its own by
// GPU memory. The custom upscalers folder key is ignored.
@@ -441,11 +484,19 @@ impl AppConfig {
if std::env::var("QLS_DATA_DIR").is_err() {
c.relocate_paths(&legacy_data_dir(), &data_dir());
}
- if c.schema_version < 5 && !c.profiles.iter().any(|p| p.id == OFFICIAL_PROFILE_ID) {
- // The official weights become available as a profile; the active one
- // stays until the user downloads them (setup wizard) or switches.
- c.profiles.push(ModelProfile::official(&c.sdcpp_dir, c.preset()));
+ if c.schema_version < 9 {
+ // Older files have no source: every profile but the official one is
+ // the user's.
+ for p in &mut c.profiles {
+ if p.id != OFFICIAL_PROFILE_ID {
+ p.source = ProfileSource::User;
+ }
+ }
+ c.keep_hand_edited_paths();
}
+ // The official weights are always available as a profile, built for the
+ // configured folder and preset; the active one stays as it is.
+ c.normalize();
c.schema_version = c.schema_version.max(SCHEMA_VERSION);
c
}
@@ -479,6 +530,113 @@ impl AppConfig {
self.profiles.iter().find(|p| p.id == self.active_profile).unwrap_or(&self.profiles[0])
}
+ pub fn user_profile(&self) -> Option<&ModelProfile> {
+ self.profiles.iter().find(|p| p.id == USER_PROFILE_ID)
+ }
+
+ /// Keeps the invariants every saved config has: the official profile exists and points to
+ /// the official files of the configured folder and preset (its tuning is kept), every
+ /// other profile is the user's, and the active profile exists.
+ pub fn normalize(&mut self) {
+ for p in &mut self.profiles {
+ p.source = if p.id == OFFICIAL_PROFILE_ID { ProfileSource::Official } else { ProfileSource::User };
+ if p.model.trim().is_empty() {
+ p.model = QWEN_IMAGE_21.into();
+ }
+ }
+ let mut official = ModelProfile::official(&self.sdcpp_dir, self.preset());
+ match self.profiles.iter_mut().find(|p| p.id == OFFICIAL_PROFILE_ID) {
+ Some(p) => {
+ official.recommended_settings = p.recommended_settings.clone();
+ official.backend_args = p.backend_args.clone();
+ official.capabilities = p.capabilities.clone();
+ *p = official;
+ }
+ None => self.profiles.insert(0, official),
+ }
+ if !self.profiles.iter().any(|p| p.id == self.active_profile) {
+ self.active_profile = OFFICIAL_PROFILE_ID.into();
+ }
+ }
+
+ /// Before schema 9, own files were set by editing the official profile's paths
+ /// (Settings → Models, or config.json by hand). When those files are all there, they move
+ /// to the user profile (active if the official one was), so presets can't overwrite them.
+ fn keep_hand_edited_paths(&mut self) {
+ let canonical = ModelProfile::official(&self.sdcpp_dir, self.preset());
+ let Some(p) = self.profiles.iter().find(|p| p.id == OFFICIAL_PROFILE_ID) else { return };
+ if p.same_files(&canonical) || !p.files().iter().all(|(_, f, _)| f.is_file()) || self.user_profile().is_some() {
+ return;
+ }
+ let mut user = ModelProfile::user(p.diffusion_model.clone(), p.vae.clone(), p.text_encoder.clone(), p.vision_projector.clone());
+ user.recommended_settings = p.recommended_settings.clone();
+ user.backend_args = p.backend_args.clone();
+ tracing::info!("model paths edited on the official profile moved to the profile of your own files");
+ self.profiles.push(user);
+ if self.active_profile == OFFICIAL_PROFILE_ID {
+ self.active_profile = USER_PROFILE_ID.into();
+ }
+ }
+
+ /// Saves the user's own files as the user profile and makes it active. Tuning of an
+ /// earlier user profile is kept.
+ pub fn set_user_files(&mut self, mut profile: ModelProfile) {
+ profile.id = USER_PROFILE_ID.into();
+ profile.source = ProfileSource::User;
+ if let Some(old) = self.user_profile() {
+ profile.recommended_settings = old.recommended_settings.clone();
+ profile.backend_args = old.backend_args.clone();
+ }
+ self.profiles.retain(|p| p.id != USER_PROFILE_ID);
+ self.profiles.push(profile);
+ self.active_profile = USER_PROFILE_ID.into();
+ }
+
+ /// Makes the official files the active model (they may still need downloading).
+ pub fn use_official(&mut self) {
+ self.normalize();
+ self.active_profile = OFFICIAL_PROFILE_ID.into();
+ }
+
+ /// Model files of the active profile that are not there (label, path).
+ pub fn missing_files(&self) -> Vec<(&'static str, PathBuf)> {
+ self.profile().files().into_iter().filter(|(_, p, required)| *required && !p.is_file()).map(|(l, p, _)| (l, p.to_path_buf())).collect()
+ }
+
+ /// Why the inference server cannot start: the engine or a model file is missing.
+ pub fn missing_files_error(&self) -> Option<AppError> {
+ let exe = self.server_exe();
+ if !exe.is_file() {
+ return Some(
+ AppError::new(ErrorCode::MissingModel, format!("sd-server was not found in {}.", self.engine_dir().display()))
+ .suggest("Install it from Settings → Models → Set up models…, or set the stable-diffusion.cpp folder in Settings."),
+ );
+ }
+ let missing = self.missing_files();
+ let (label, path) = missing.first()?;
+ let more = match missing.len() {
+ 1 => String::new(),
+ n => format!(" (and {} more)", n - 1),
+ };
+ Some(
+ AppError::new(ErrorCode::MissingModel, format!("{label} not found: {}{more}", path.display()))
+ .suggest("If it is on a drive that is not connected, connect it and try again. Otherwise open Setup to find the file again, choose other files, or download the missing ones."),
+ )
+ }
+
+ /// VRAM (MiB) the user's own files take beyond the official ones, which the planner's
+ /// budgets were measured with: a larger diffusion model (and, with unified memory, a larger
+ /// text encoder) leaves less room for the images. 0 for the official files.
+ pub fn model_vram_extra_mib(&self, unified: bool) -> u64 {
+ let p = self.profile();
+ if p.is_official() {
+ return 0;
+ }
+ let size = |f: &Path| std::fs::metadata(f).map(|m| m.len()).unwrap_or(0);
+ let te = size(&p.text_encoder) + p.vision_projector.as_deref().map(size).unwrap_or(0);
+ extra_weights_mib(size(&p.diffusion_model), te, unified)
+ }
+
pub fn relocate_paths(&mut self, old: &Path, new: &Path) {
relocate(&mut self.sdcpp_dir, old, new);
for p in &mut self.profiles {
@@ -495,20 +653,13 @@ impl AppConfig {
crate::catalog::preset(&self.hardware_preset).unwrap_or_else(|| crate::catalog::preset(crate::catalog::DEFAULT_PRESET).unwrap())
}
- /// Switches to the official weights of `preset` (replacing an older official profile)
- /// and its runtime settings. Used when the setup wizard finishes.
+ /// Uses `preset`'s runtime settings, and its files for the official profile (tuning kept).
+ /// The active profile stays: a preset never replaces the user's own files. Setup also calls
+ /// [`Self::use_official`] when it installs the official files.
pub fn apply_preset(&mut self, preset: &crate::catalog::Preset) {
- let mut profile = ModelProfile::official(&self.sdcpp_dir, preset);
- if let Some(old) = self.profiles.iter().find(|p| p.id == OFFICIAL_PROFILE_ID) {
- // Keep presets the user tuned on the official profile.
- profile.recommended_settings = old.recommended_settings.clone();
- profile.backend_args = old.backend_args.clone();
- }
- self.profiles.retain(|p| p.id != OFFICIAL_PROFILE_ID);
- self.profiles.insert(0, profile);
- self.active_profile = OFFICIAL_PROFILE_ID.into();
self.hardware_preset = preset.id.into();
self.text_encoder_placement = preset.text_encoder_placement;
+ self.normalize();
}
/// VRAM the planner should assume: the override when set, otherwise the detected size.
@@ -600,10 +751,128 @@ impl AppConfig {
}
}
+/// [`AppConfig::model_vram_extra_mib`] for files of these sizes (bytes; text encoder plus
+/// vision projector together). Smaller files give nothing back: the budgets stay as measured.
+fn extra_weights_mib(diffusion: u64, text_encoder: u64, unified: bool) -> u64 {
+ use crate::catalog::{TEXT_ENCODER_Q4_K_M, TURBO_Q4_K, VISION_PROJECTOR};
+ let mut extra = diffusion.saturating_sub(TURBO_Q4_K.size);
+ if unified {
+ extra += text_encoder.saturating_sub(TEXT_ENCODER_Q4_K_M.size + VISION_PROJECTOR.size);
+ }
+ extra >> 20
+}
+
#[cfg(test)]
mod tests {
use super::*;
+ /// Empty files at every path of `p`.
+ fn touch_files(p: &ModelProfile) {
+ for (_, f, _) in p.files() {
+ std::fs::create_dir_all(f.parent().unwrap()).unwrap();
+ std::fs::write(f, b"").unwrap();
+ }
+ }
+
+ fn own_files(dir: &Path) -> ModelProfile {
+ let m = dir.join("ComfyUI").join("models");
+ ModelProfile::user(m.join("diffusion_models").join("turbo_int8.safetensors"), m.join("vae").join("vae.safetensors"), m.join("text_encoders").join("qwen3vl_fused.safetensors"), None)
+ }
+
+ #[test]
+ fn hand_edited_official_paths_move_to_the_user_profile() {
+ let dir = tempfile::tempdir().unwrap();
+ let sd = dir.path().join("sd");
+ let mine = own_files(dir.path());
+ touch_files(&mine);
+ // badraymen's config (#14): the official profile pointed at ComfyUI files by hand.
+ let mut old = AppConfig { sdcpp_dir: sd.clone(), schema_version: 8, ..AppConfig::default() };
+ old.normalize();
+ let p = &mut old.profiles[0];
+ (p.diffusion_model, p.vae, p.text_encoder, p.vision_projector) = (mine.diffusion_model.clone(), mine.vae.clone(), mine.text_encoder.clone(), None);
+ p.backend_args = vec!["--x".into()];
+ let path = dir.path().join("config.json");
+ old.save_to(&path).unwrap();
+ let c = AppConfig::load_from(&path);
+ assert_eq!(c.active_profile, USER_PROFILE_ID, "the edited files stay in use");
+ let user = c.profile();
+ assert_eq!((user.source, user.diffusion_model.clone(), user.vision_projector.clone()), (ProfileSource::User, mine.diffusion_model.clone(), None));
+ assert_eq!(user.backend_args, vec!["--x".to_string()]);
+ assert_eq!(user.model, QWEN_IMAGE_21);
+ let off = c.profiles.iter().find(|p| p.id == OFFICIAL_PROFILE_ID).unwrap();
+ assert!(off.same_files(&ModelProfile::official(&sd, c.preset())) && off.is_official(), "the official profile is official again");
+ c.save_to(&path).unwrap();
+ assert_eq!(AppConfig::load_from(&path), c, "nothing changes on the next load");
+
+ // Edited paths whose files are gone are not kept: back to the official files.
+ std::fs::remove_file(&mine.vae).unwrap();
+ old.save_to(&path).unwrap();
+ let c = AppConfig::load_from(&path);
+ assert_eq!((c.active_profile.as_str(), c.profiles.len()), (OFFICIAL_PROFILE_ID, 1));
+ assert!(c.profile().same_files(&ModelProfile::official(&sd, c.preset())));
+ }
+
+ #[test]
+ fn presets_never_replace_the_users_files() {
+ let dir = tempfile::tempdir().unwrap();
+ let mut c = AppConfig { sdcpp_dir: dir.path().join("sd"), ..AppConfig::default() };
+ c.normalize();
+ let mut mine = own_files(dir.path());
+ mine.scan_dir = Some(dir.path().join("ComfyUI"));
+ c.set_user_files(mine.clone());
+ c.profiles.iter_mut().find(|p| p.id == USER_PROFILE_ID).unwrap().recommended_settings.area_fast = 768 * 768;
+ c.apply_preset(crate::catalog::preset("32gb").unwrap());
+ assert_eq!(c.active_profile, USER_PROFILE_ID);
+ assert_eq!((c.profile().text_encoder.clone(), c.hardware_preset.as_str()), (mine.text_encoder.clone(), "32gb"));
+ let off = c.profiles.iter().find(|p| p.id == OFFICIAL_PROFILE_ID).unwrap();
+ assert!(off.text_encoder.ends_with("Qwen3VL-8B-Instruct-Q8_0.gguf"), "the official profile follows the preset");
+ // Choosing files again keeps the tuning; switching to the official files keeps them.
+ c.set_user_files(own_files(dir.path()));
+ assert_eq!(c.profile().recommended_settings.area_fast, 768 * 768);
+ assert_eq!(c.profiles.len(), 2);
+ c.use_official();
+ assert_eq!(c.active_profile, OFFICIAL_PROFILE_ID);
+ assert!(c.user_profile().is_some(), "the user's profile is never deleted");
+ // The official files follow the folder.
+ c.sdcpp_dir = dir.path().join("elsewhere");
+ c.normalize();
+ assert!(c.profile().diffusion_model.starts_with(dir.path().join("elsewhere")));
+ // An active profile that is gone falls back to the official one.
+ c.active_profile = "nope".into();
+ c.normalize();
+ assert_eq!(c.active_profile, OFFICIAL_PROFILE_ID);
+ }
+
+ #[test]
+ fn missing_files_are_reported() {
+ let dir = tempfile::tempdir().unwrap();
+ let mut c = AppConfig { sdcpp_dir: dir.path().join("sd"), ..AppConfig::default() };
+ c.normalize();
+ assert!(c.missing_files_error().unwrap().message.contains("sd-server"), "the engine first");
+ std::fs::create_dir_all(c.engine_dir()).unwrap();
+ std::fs::write(c.server_exe(), b"").unwrap();
+ let mine = own_files(dir.path());
+ c.set_user_files(mine.clone());
+ assert_eq!(c.missing_files().len(), 3);
+ let e = c.missing_files_error().unwrap();
+ assert_eq!(e.code, ErrorCode::MissingModel);
+ assert!(e.message.starts_with("Diffusion model not found") && e.message.ends_with("(and 2 more)"), "{}", e.message);
+ touch_files(&mine);
+ assert!(c.missing_files().is_empty() && c.missing_files_error().is_none());
+ }
+
+ #[test]
+ fn larger_own_files_take_planning_memory() {
+ use crate::catalog::{TEXT_ENCODER_Q8_0, TURBO_Q4_K};
+ assert_eq!(extra_weights_mib(TURBO_Q4_K.size, 0, false), 0);
+ assert_eq!(extra_weights_mib(TURBO_Q4_K.size / 2, 0, false), 0, "smaller files give nothing back");
+ assert_eq!(extra_weights_mib(TURBO_Q4_K.size + (6 << 30), 0, false), 6 * 1024);
+ assert_eq!(extra_weights_mib(0, TEXT_ENCODER_Q8_0.size, false), 0, "the text encoder sits in system RAM");
+ assert!(extra_weights_mib(0, TEXT_ENCODER_Q8_0.size, true) > 2000, "unified memory: it shares the GPU's memory");
+ // The official profile is what the budgets were measured with.
+ assert_eq!(AppConfig::default().model_vram_extra_mib(true), 0);
+ }
+
#[test]
fn defaults_match_spec() {
let c = AppConfig::default();
diff --git a/crates/qls-core/src/diagnostics.rs b/crates/qls-core/src/diagnostics.rs
index 476e785..a7177e2 100644
--- a/crates/qls-core/src/diagnostics.rs
+++ b/crates/qls-core/src/diagnostics.rs
@@ -209,6 +209,16 @@ fn fmt_size(bytes: u64) -> String {
/// First-launch / settings checks. `server_ok` is the live health result if known.
pub fn setup_checks(cfg: &AppConfig, server_ok: Option<bool>) -> SetupReport {
+ let exe = cfg.server_exe();
+ let probe = exe.is_file();
+ let devices = if probe { list_devices(&exe) } else { vec![] };
+ let version = if probe { backend_version(&exe) } else { None };
+ setup_checks_with(cfg, server_ok, devices, version)
+}
+
+/// [`setup_checks`] with the engine's devices and version already known (the service keeps
+/// them per engine build: each probe starts sd-server, which takes seconds).
+pub fn setup_checks_with(cfg: &AppConfig, server_ok: Option<bool>, devices: Vec<(String, String)>, backend_version: Option<String>) -> SetupReport {
let mut checks = Vec::new();
let dir_ok = cfg.sdcpp_dir.is_dir();
checks.push(Check { id: "sdcpp_dir", label: "stable-diffusion.cpp folder".into(), ok: dir_ok, detail: cfg.sdcpp_dir.display().to_string() });
@@ -227,7 +237,6 @@ pub fn setup_checks(cfg: &AppConfig, server_ok: Option<bool>) -> SetupReport {
},
});
}
- let devices = if exe_ok { list_devices(&exe) } else { vec![] };
let wanted = cfg.effective_device();
let dev = devices.iter().find(|(n, _)| n.to_ascii_lowercase() == wanted);
let gpu_ok = dev.is_some();
@@ -254,7 +263,7 @@ pub fn setup_checks(cfg: &AppConfig, server_ok: Option<bool>) -> SetupReport {
if exe_ok {
checks.push(engine_release_check(cfg));
}
- let backend_version = if exe_ok { backend_version(&exe) } else { None };
+ let backend_version = if exe_ok { backend_version } else { None };
// Informational: the server starts on demand; an engine of an older release still
// generates (enlargements fall back to Lanczos), and Setup offers the update.
let ready = checks.iter().filter(|c| c.id != "server" && c.id != "engine_release").all(|c| c.ok);
diff --git a/crates/qls-core/src/engine.rs b/crates/qls-core/src/engine.rs
index f4b70c0..be95ebd 100644
--- a/crates/qls-core/src/engine.rs
+++ b/crates/qls-core/src/engine.rs
@@ -186,15 +186,20 @@ impl Engine {
}
/// Replaces the configuration. Returns true when the backend must restart.
- pub fn set_config(&self, new: AppConfig) -> AppResult<bool> {
+ pub fn set_config(&self, mut new: AppConfig) -> AppResult<bool> {
+ // The official profile follows the folder and preset; see `AppConfig::normalize`.
+ new.normalize();
new.validate()?;
new.save()?;
let mut g = self.cfg.write().unwrap();
let restart = crate::process::build_server_args(&g, g.profile()) != crate::process::build_server_args(&new, new.profile())
|| g.sdcpp_dir != new.sdcpp_dir
|| g.gpu_backend != new.gpu_backend;
+ // The engine's version is probed again only when another build is in use.
+ if g.server_exe() != new.server_exe() {
+ *self.backend_version.lock().unwrap() = None;
+ }
*g = new;
- *self.backend_version.lock().unwrap() = None;
drop(g);
self.place_bundled_upscaler();
Ok(restart)
@@ -408,6 +413,12 @@ impl Engine {
if request.images.len() > 16 {
return Err(AppError::invalid("Too many images."));
}
+ // A model file on a drive that is not connected, moved or deleted: say so now, so the
+ // app can guide the user (Setup), instead of failing once the job starts. Also with the
+ // model loaded: sd-server opens the files again for every image.
+ if let Some(e) = self.config().missing_files_error() {
+ return Err(e);
+ }
if let Some(seed) = request.seed
&& seed < 0
{
@@ -557,10 +568,18 @@ impl Engine {
self.speed.get(&crate::speed::machine_key(cfg, self.gpu().as_ref())).map(|c| c.factor)
}
+ /// VRAM to plan with: the card's (or the simulated size), less what the user's own model
+ /// files take beyond the official ones the budgets were measured with.
+ fn planning_vram(&self, cfg: &AppConfig) -> Option<u64> {
+ let gpu = self.gpu();
+ let unified = gpu.as_ref().is_some_and(|g| g.unified);
+ cfg.planning_vram_mib(gpu.map(|g| g.planning_mib())).map(|v| v.saturating_sub(cfg.model_vram_extra_mib(unified)))
+ }
+
/// Dry run: the plan a request would get (used by the UI to show working sizes).
pub fn preview_plan(&self, req: &GenerationRequest, sizes: Vec<Size>, mask: Option<(Size, Option<crate::geometry::Rect>, f64)>) -> AppResult<Plan> {
let cfg = self.config();
- let vram = cfg.planning_vram_mib(self.gpu().map(|g| g.planning_mib()));
+ let vram = self.planning_vram(&cfg);
let mut inputs = plan_inputs(&cfg, sizes, mask, vram);
inputs.speed_factor = self.speed_factor(&cfg);
inputs.unified_memory = self.gpu().is_some_and(|g| g.unified);
@@ -579,6 +598,10 @@ impl Engine {
j.view.started_at = Some(now_rfc3339());
j.view.queue_position = 0;
});
+ // A file that went missing while the job was queued (see `submit`).
+ if let Some(e) = self.config().missing_files_error() {
+ return Err(e);
+ }
// 1. Load inputs (off the async runtime: decoding large photos is CPU work).
let this = self.clone();
@@ -608,7 +631,7 @@ impl Engine {
// 2. Plan.
let cfg = self.config();
let profile = cfg.profile().clone();
- let vram = cfg.planning_vram_mib(self.gpu().map(|g| g.planning_mib()));
+ let vram = self.planning_vram(&cfg);
let mask_info = mask.as_ref().map(|(m, _)| (Size::new(m.width(), m.height()), imaging::mask_bbox(m, 16), imaging::mask_coverage(m, 16)));
let mut plan_inputs = plan_inputs(&cfg, images.iter().map(|i| i.size()).collect(), mask_info, vram);
plan_inputs.speed_factor = self.speed_factor(&cfg);
@@ -1236,7 +1259,24 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
// SAFETY: test-only env override, single-threaded setup.
unsafe { std::env::set_var("QLS_CONFIG_DIR", dir.path().join("cfg")) };
- let e = Engine::new(AppConfig::default(), dir.path()).unwrap();
+ // Engine and model files (empty) in the test's own folder, never the real one.
+ let mut cfg = AppConfig::default();
+ cfg.sdcpp_dir = dir.path().join("sdcpp");
+ cfg.normalize();
+ std::fs::create_dir_all(cfg.engine_dir()).unwrap();
+ std::fs::write(cfg.server_exe(), b"").unwrap();
+ for (_, p, _) in cfg.profile().files() {
+ std::fs::create_dir_all(p.parent().unwrap()).unwrap();
+ std::fs::write(p, b"").unwrap();
+ }
+ let te = cfg.profile().text_encoder.clone();
+ let e = Engine::new(cfg, dir.path()).unwrap();
+ // A model file that is gone (drive disconnected, moved): refused before queueing.
+ std::fs::rename(&te, te.with_extension("moved")).unwrap();
+ let err = e.submit(GenerationRequest { prompt: "a fox".into(), ..Default::default() }, None).unwrap_err();
+ assert_eq!(err.code, ErrorCode::MissingModel);
+ assert!(err.message.contains("Text encoder") && err.suggestion.as_deref().unwrap().contains("drive"), "{err:?}");
+ std::fs::rename(te.with_extension("moved"), &te).unwrap();
assert!(e.submit(GenerationRequest { prompt: " ".into(), ..Default::default() }, None).is_err());
// Remove needs no prompt; other inpaint actions do.
let remove = GenerationRequest { images: vec!["gen:x".into()], mask: Some("input:m".into()), inpaint_action: planner::InpaintAction::Remove, ..Default::default() };
diff --git a/crates/qls-core/src/error.rs b/crates/qls-core/src/error.rs
index 85cb63f..c89d536 100644
--- a/crates/qls-core/src/error.rs
+++ b/crates/qls-core/src/error.rs
@@ -127,6 +127,13 @@ pub fn translate_generation_failure(backend_message: &str, log_tail: &str, size:
};
return e.detail(combined);
}
+ // A model file that went missing after the job was queued (sd-server opens the files for
+ // every image): the app guides the user to find, choose or download it.
+ if lc.contains("cannot inspect model source") || (lc.contains("model") && (lc.contains("cannot find the file") || lc.contains("cannot find the path") || lc.contains("no such file"))) {
+ return AppError::new(ErrorCode::MissingModel, "A model file could not be found.")
+ .suggest("If it is on a drive that is not connected, connect it and try again. Otherwise open Setup to find the file again, choose other files, or download the missing ones.")
+ .detail(combined);
+ }
if lc.contains("requires qwen3-vl vision weights") || lc.contains("llm_vision") {
return AppError::new(ErrorCode::InvalidConfig, "Image editing needs the vision projector (mmproj) model.")
.suggest("Set the vision projector file in Settings.")
@@ -193,6 +200,17 @@ mod tests {
assert_eq!(e.code, ErrorCode::GenerationFailed);
}
+ #[test]
+ fn model_file_gone_while_loaded() {
+ // Seen 2026-10-16: the text encoder moved after the model was loaded.
+ let log = r"[E] cannot inspect model source 'C:\models\qwen3vl.gguf': The system cannot find the file specified. --- model_loader_files.cpp:25";
+ let e = translate_generation_failure("generate_image returned no results", log, (1024, 1024), None);
+ assert_eq!(e.code, ErrorCode::MissingModel);
+ assert!(e.suggestion.unwrap().contains("drive"));
+ let e = translate_generation_failure("", r"[E] cannot inspect model source 'K:\models\x.gguf': The system cannot find the path specified.", (1024, 1024), None);
+ assert_eq!(e.code, ErrorCode::MissingModel, "a drive that is gone");
+ }
+
#[test]
fn startup_failures() {
assert_eq!(translate_startup_failure("failed to open 'x.gguf'").code, ErrorCode::MissingModel);
diff --git a/crates/qls-core/src/lib.rs b/crates/qls-core/src/lib.rs
index 9e2840d..0474d69 100644
--- a/crates/qls-core/src/lib.rs
+++ b/crates/qls-core/src/lib.rs
@@ -10,6 +10,7 @@ pub mod hdr;
pub mod heif;
pub mod imaging;
pub mod installer;
+pub mod modelfile;
pub mod paths;
pub mod pipeline;
pub mod planner;
diff --git a/crates/qls-core/src/modelfile.rs b/crates/qls-core/src/modelfile.rs
new file mode 100644
index 0000000..7bbc1dc
--- /dev/null
+++ b/crates/qls-core/src/modelfile.rs
@@ -0,0 +1,767 @@
+//! Model files the user already has (#14): what a `.gguf` or `.safetensors` file is, read from
+//! its header only (a few KB to a few MB, never the weights), and a folder scan that finds the
+//! Qwen-Image 2.1 pieces in it (e.g. a ComfyUI `models` folder).
+//!
+//! The checks mirror how stable-diffusion.cpp recognizes the files (commit af46afa):
+//! - diffusion model: Qwen-Image 2.1 has `txt_in.text_norm.weight` (`model_loader.cpp`), older
+//! Qwen-Image models don't;
+//! - VAE: the 2.1 VAE has a 64-channel latent (`wan_vae.hpp`, `z_dim = 64`), seen in the shape
+//! of its post-quantization conv (`conv2`, or `post_quant_conv` in diffusers files);
+//! - text encoder: Qwen3-VL 8B (QK-norm, hidden size 4096); vision weights (`visual.*`) in the
+//! same file make the separate vision projector unnecessary (`llm.hpp`);
+//! - vision projector: Qwen3-VL vision weights projecting to 4096.
+
+use std::collections::HashMap;
+use std::io::{BufReader, Read, Seek, SeekFrom};
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+
+use crate::catalog::{Download, Preset, TEXT_ENCODER_Q4_K_M, TEXT_ENCODER_Q8_0, TURBO_Q4_K, VAE, VISION_PROJECTOR};
+use crate::config::ModelProfile;
+use crate::error::AppError;
+
+/// Hidden size of Qwen3-VL 8B, the text encoder of Qwen-Image 2.1.
+const TEXT_HIDDEN: u64 = 4096;
+/// Latent channels of the Qwen-Image 2.1 VAE.
+const VAE_LATENT: u64 = 64;
+/// Smaller files are not image-model weights (configs, LoRAs, embeddings).
+pub const SCAN_MIN_BYTES: u64 = 32 << 20;
+const SCAN_MAX_DEPTH: usize = 8;
+const SCAN_MAX_ENTRIES: usize = 50_000;
+const SCAN_MAX_FILES: usize = 2_000;
+/// Folders a scan never enters (ComfyUI's own code, environments, outputs).
+const SCAN_SKIP: &[&str] = &["custom_nodes", "node_modules", "venv", ".venv", "__pycache__", "output", "input", "temp", ".git", ".cache"];
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Role {
+ Diffusion,
+ Vae,
+ TextEncoder,
+ VisionProjector,
+}
+
+impl Role {
+ pub const ALL: [Role; 4] = [Role::Diffusion, Role::Vae, Role::TextEncoder, Role::VisionProjector];
+
+ pub fn label(self) -> &'static str {
+ match self {
+ Role::Diffusion => "Diffusion model",
+ Role::Vae => "VAE",
+ Role::TextEncoder => "Text encoder (Qwen3-VL)",
+ Role::VisionProjector => "Vision projector (mmproj)",
+ }
+ }
+}
+
+/// What a model file is and whether Kokon can use it for Qwen-Image 2.1.
+#[derive(Debug, Clone, PartialEq, Serialize)]
+pub struct FileInfo {
+ pub path: PathBuf,
+ pub size: u64,
+ /// None: not a model file Kokon recognizes.
+ pub role: Option<Role>,
+ /// Usable as `role` with Qwen-Image 2.1.
+ pub compatible: bool,
+ /// A text encoder that carries the vision weights (no separate projector needed).
+ pub has_vision: bool,
+ /// Main weight type, e.g. "Q4_K", "BF16", "FP8", "INT8".
+ pub weights: String,
+ /// The file Kokon's setup downloads (same name and size).
+ pub official: bool,
+ /// Why it can't be used, when it can't.
+ pub problem: Option<String>,
+}
+
+struct Tensor {
+ name: String,
+ /// PyTorch order (outermost first); GGUF dimensions are reversed to match.
+ shape: Vec<u64>,
+ dtype: String,
+}
+
+/// The catalog download a file with this name and size is (any folder).
+pub fn official_download(path: &Path, size: u64) -> Option<Download> {
+ let name = path.file_name()?.to_string_lossy().to_ascii_lowercase();
+ [TURBO_Q4_K, VAE, TEXT_ENCODER_Q4_K_M, TEXT_ENCODER_Q8_0, VISION_PROJECTOR]
+ .into_iter()
+ .find(|d| d.size == size && d.dest.rsplit('/').next().is_some_and(|f| f.eq_ignore_ascii_case(&name)))
+}
+
+/// Reads the header of `path` and says what it is. Errors only for files that cannot be read.
+pub fn inspect(path: &Path) -> std::io::Result<FileInfo> {
+ let meta = std::fs::metadata(path)?;
+ if !meta.is_file() {
+ return Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, "not a file"));
+ }
+ let size = meta.len();
+ let mut info = FileInfo { path: path.to_path_buf(), size, role: None, compatible: false, has_vision: false, weights: String::new(), official: false, problem: None };
+ let name = path.file_name().map(|n| n.to_string_lossy().to_ascii_lowercase()).unwrap_or_default();
+ let ext = name.rsplit_once('.').map(|(_, e)| e).unwrap_or("");
+ let parsed = match ext {
+ "gguf" => read_gguf(path),
+ "safetensors" => {
+ if is_shard(&name) {
+ info.problem = Some("This is one part of a model split into several files. Use a single-file version (.safetensors or .gguf).".into());
+ return Ok(info);
+ }
+ read_safetensors(path)
+ }
+ "ckpt" | "pt" | "pth" | "bin" => {
+ info.problem = Some("Kokon only reads .gguf and .safetensors model files (.ckpt, .pt and .bin files can run code when loaded).".into());
+ return Ok(info);
+ }
+ _ => {
+ info.problem = Some("Not a model file (.gguf or .safetensors).".into());
+ return Ok(info);
+ }
+ };
+ let (tensors, meta) = match parsed {
+ Ok(t) => t,
+ Err(e) => {
+ info.problem = Some(format!("Could not read the file's header ({e}). It may be incomplete or damaged."));
+ return Ok(info);
+ }
+ };
+ info.weights = main_weight_type(&tensors);
+ classify(&tensors, &meta, &mut info);
+ info.official = info.compatible && official_download(path, size).is_some();
+ Ok(info)
+}
+
+/// `name-00001-of-00004.safetensors`
+fn is_shard(name: &str) -> bool {
+ let stem = name.trim_end_matches(".safetensors");
+ let parts: Vec<&str> = stem.rsplitn(4, '-').collect();
+ parts.len() == 4 && parts[1] == "of" && [parts[0], parts[2]].iter().all(|p| p.len() >= 3 && p.chars().all(|c| c.is_ascii_digit()))
+}
+
+fn classify(t: &[Tensor], meta: &HashMap<String, String>, info: &mut FileInfo) {
+ let ends = |s: &str| t.iter().any(|x| x.name.ends_with(s));
+ let contains = |s: &str| t.iter().any(|x| x.name.contains(s));
+ let find = |s: &str| t.iter().find(|x| x.name.ends_with(s));
+
+ // Diffusion model.
+ if ends("txt_in.text_norm.weight") {
+ info.role = Some(Role::Diffusion);
+ info.compatible = true;
+ return;
+ }
+ if contains("transformer_blocks.") && ends("img_in.weight") {
+ info.role = Some(Role::Diffusion);
+ info.problem = Some("This is an older Qwen-Image model, not Qwen-Image 2.1. Kokon needs Qwen-Image 2.1 (Turbo).".into());
+ return;
+ }
+ if ["double_blocks.", "single_blocks.", "joint_blocks.", "input_blocks.", "transformer_blocks.", "single_transformer_blocks."].iter().any(|s| contains(s)) {
+ info.role = Some(Role::Diffusion);
+ info.problem = Some("This image model is not Qwen-Image 2.1.".into());
+ return;
+ }
+
+ // VAE: its post-quantization conv maps the latent to itself.
+ if contains("decoder.") && contains("encoder.") {
+ info.role = Some(Role::Vae);
+ let post = t.iter().find(|x| {
+ let n = x.name.trim_start_matches("first_stage_model.").trim_start_matches("vae.");
+ n == "conv2.weight" || n == "post_quant_conv.weight"
+ });
+ match post.and_then(|x| x.shape.first().copied()) {
+ Some(VAE_LATENT) => info.compatible = true,
+ Some(z) => info.problem = Some(format!("This VAE belongs to another model (latent size {z}). Kokon needs the Qwen-Image 2.1 VAE.")),
+ None => info.problem = Some("Not recognized as the Qwen-Image 2.1 VAE.".into()),
+ }
+ return;
+ }
+
+ let vision = contains("visual.") || t.iter().any(|x| x.name.starts_with("v.blk.") || x.name.starts_with("v.patch_embd"));
+ // Text encoder: a language model with layers.
+ let layers = t.iter().any(|x| (x.name.contains("layers.") && x.name.contains("self_attn.")) || (x.name.starts_with("blk.") && x.name.contains(".attn_")));
+ if layers {
+ info.role = Some(Role::TextEncoder);
+ info.has_vision = vision;
+ let qk_norm = ends("self_attn.q_norm.weight") || ends("attn_q_norm.weight");
+ let hidden = find("embed_tokens.weight").or_else(|| find("token_embd.weight")).and_then(|x| x.shape.get(1).copied());
+ let hidden = hidden.or_else(|| meta.iter().find(|(k, _)| k.ends_with(".embedding_length")).and_then(|(_, v)| v.parse().ok()));
+ if qk_norm && hidden == Some(TEXT_HIDDEN) {
+ info.compatible = true;
+ } else if hidden == Some(3584) {
+ info.problem = Some("This is the Qwen2.5-VL text encoder of older Qwen-Image models. Qwen-Image 2.1 needs Qwen3-VL 8B.".into());
+ } else {
+ info.problem = Some("Not the Qwen3-VL 8B text encoder that Qwen-Image 2.1 needs.".into());
+ }
+ return;
+ }
+
+ // Vision projector (mmproj): vision weights only.
+ if vision || meta.get("general.architecture").is_some_and(|a| a == "clip") {
+ info.role = Some(Role::VisionProjector);
+ let out = meta
+ .get("clip.vision.projection_dim")
+ .and_then(|v| v.parse::<u64>().ok())
+ .or_else(|| find("visual.merger.linear_fc2.weight").or_else(|| find("visual.merger.mlp.2.weight")).and_then(|x| x.shape.first().copied()));
+ match out {
+ Some(TEXT_HIDDEN) | None => info.compatible = true,
+ Some(d) => info.problem = Some(format!("These vision weights belong to a different Qwen-VL model (output size {d}). Qwen-Image 2.1 needs the Qwen3-VL 8B ones.")),
+ }
+ return;
+ }
+ info.problem = Some("Not a Qwen-Image 2.1 model file.".into());
+}
+
+/// The weight type holding most of the parameters (matrices only).
+fn main_weight_type(t: &[Tensor]) -> String {
+ let mut by: HashMap<&str, u64> = HashMap::new();
+ for x in t.iter().filter(|x| x.shape.len() >= 2) {
+ *by.entry(x.dtype.as_str()).or_default() += x.shape.iter().product::<u64>();
+ }
+ by.into_iter().max_by_key(|(_, n)| *n).map(|(d, _)| d.to_string()).unwrap_or_default()
+}
+
+fn safetensors_dtype(d: &str) -> String {
+ match d {
+ "F8_E4M3" | "F8_E5M2" | "F8_E4M3FN" => "FP8".into(),
+ "I8" => "INT8".into(),
+ "U8" => "UINT8".into(),
+ other => other.to_string(),
+ }
+}
+
+fn read_safetensors(path: &Path) -> std::io::Result<(Vec<Tensor>, HashMap<String, String>)> {
+ let mut f = std::fs::File::open(path)?;
+ let mut len = [0u8; 8];
+ f.read_exact(&mut len)?;
+ let n = u64::from_le_bytes(len);
+ if n == 0 || n > 128 << 20 {
+ return Err(bad("unexpected header size"));
+ }
+ let mut buf = vec![0u8; n as usize];
+ f.read_exact(&mut buf)?;
+ let v: serde_json::Map<String, serde_json::Value> = serde_json::from_slice(&buf).map_err(|_| bad("header is not valid JSON"))?;
+ let mut meta = HashMap::new();
+ let mut tensors = Vec::new();
+ for (name, val) in v {
+ if name == "__metadata__" {
+ if let Some(m) = val.as_object() {
+ meta.extend(m.iter().filter_map(|(k, v)| v.as_str().map(|s| (k.clone(), s.to_string()))));
+ }
+ continue;
+ }
+ let dtype = val.get("dtype").and_then(|d| d.as_str()).unwrap_or("").to_string();
+ let shape = val.get("shape").and_then(|s| s.as_array()).map(|a| a.iter().filter_map(|x| x.as_u64()).collect()).unwrap_or_default();
+ tensors.push(Tensor { name, shape, dtype: safetensors_dtype(&dtype) });
+ }
+ Ok((tensors, meta))
+}
+
+fn bad(msg: &str) -> std::io::Error {
+ std::io::Error::new(std::io::ErrorKind::InvalidData, msg.to_string())
+}
+
+fn ggml_type(t: u32) -> String {
+ const NAMES: &[(u32, &str)] = &[
+ (0, "F32"),
+ (1, "F16"),
+ (2, "Q4_0"),
+ (3, "Q4_1"),
+ (6, "Q5_0"),
+ (7, "Q5_1"),
+ (8, "Q8_0"),
+ (9, "Q8_1"),
+ (10, "Q2_K"),
+ (11, "Q3_K"),
+ (12, "Q4_K"),
+ (13, "Q5_K"),
+ (14, "Q6_K"),
+ (15, "Q8_K"),
+ (16, "IQ2_XXS"),
+ (17, "IQ2_XS"),
+ (18, "IQ3_XXS"),
+ (19, "IQ1_S"),
+ (20, "IQ4_NL"),
+ (21, "IQ3_S"),
+ (22, "IQ2_S"),
+ (23, "IQ4_XS"),
+ (24, "I8"),
+ (29, "IQ1_M"),
+ (30, "BF16"),
+ ];
+ NAMES.iter().find(|(n, _)| *n == t).map(|(_, s)| s.to_string()).unwrap_or_else(|| format!("type {t}"))
+}
+
+struct Gguf<R> {
+ r: R,
+}
+
+impl<R: Read + Seek> Gguf<R> {
+ fn u32(&mut self) -> std::io::Result<u32> {
+ let mut b = [0u8; 4];
+ self.r.read_exact(&mut b)?;
+ Ok(u32::from_le_bytes(b))
+ }
+
+ fn u64(&mut self) -> std::io::Result<u64> {
+ let mut b = [0u8; 8];
+ self.r.read_exact(&mut b)?;
+ Ok(u64::from_le_bytes(b))
+ }
+
+ fn string(&mut self) -> std::io::Result<String> {
+ let n = self.u64()?;
+ if n > 16 << 20 {
+ return Err(bad("string too long"));
+ }
+ let mut b = vec![0u8; n as usize];
+ self.r.read_exact(&mut b)?;
+ Ok(String::from_utf8_lossy(&b).into_owned())
+ }
+
+ fn skip(&mut self, n: u64) -> std::io::Result<()> {
+ self.r.seek(SeekFrom::Current(i64::try_from(n).map_err(|_| bad("bad length"))?))?;
+ Ok(())
+ }
+
+ /// A metadata value: kept as text when it is a string or a number, skipped otherwise.
+ fn value(&mut self, ty: u32) -> std::io::Result<Option<String>> {
+ let fixed = |t: u32| -> Option<u64> {
+ match t {
+ 0 | 1 | 7 => Some(1),
+ 2 | 3 => Some(2),
+ 4..=6 => Some(4),
+ 10..=12 => Some(8),
+ _ => None,
+ }
+ };
+ Ok(match ty {
+ 8 => Some(self.string()?),
+ 9 => {
+ let et = self.u32()?;
+ let n = self.u64()?;
+ if n > 100_000_000 {
+ return Err(bad("array too long"));
+ }
+ match (et, fixed(et)) {
+ (8, _) => {
+ for _ in 0..n {
+ let len = self.u64()?;
+ self.skip(len)?;
+ }
+ }
+ (_, Some(s)) => self.skip(s * n)?,
+ _ => return Err(bad("nested arrays are not supported")),
+ }
+ None
+ }
+ 4 => Some(self.u32()?.to_string()),
+ 5 => Some((self.u32()? as i32).to_string()),
+ 10 => Some(self.u64()?.to_string()),
+ t => {
+ self.skip(fixed(t).ok_or_else(|| bad("unknown value type"))?)?;
+ None
+ }
+ })
+ }
+}
+
+fn read_gguf(path: &Path) -> std::io::Result<(Vec<Tensor>, HashMap<String, String>)> {
+ let mut g = Gguf { r: BufReader::with_capacity(1 << 20, std::fs::File::open(path)?) };
+ let mut magic = [0u8; 4];
+ g.r.read_exact(&mut magic)?;
+ if &magic != b"GGUF" {
+ return Err(bad("not a GGUF file"));
+ }
+ if g.u32()? < 2 {
+ return Err(bad("GGUF version 1 is not supported"));
+ }
+ let (n_tensors, n_kv) = (g.u64()?, g.u64()?);
+ if n_tensors > 100_000 || n_kv > 100_000 {
+ return Err(bad("too many entries"));
+ }
+ let mut meta = HashMap::new();
+ for _ in 0..n_kv {
+ let key = g.string()?;
+ let ty = g.u32()?;
+ if let Some(v) = g.value(ty)? {
+ meta.insert(key, v);
+ }
+ }
+ let mut tensors = Vec::with_capacity(n_tensors as usize);
+ for _ in 0..n_tensors {
+ let name = g.string()?;
+ let nd = g.u32()?;
+ if nd > 8 {
+ return Err(bad("bad tensor dimensions"));
+ }
+ let mut shape = (0..nd).map(|_| g.u64()).collect::<std::io::Result<Vec<u64>>>()?;
+ shape.reverse();
+ let ty = g.u32()?;
+ g.u64()?; // offset
+ tensors.push(Tensor { name, shape, dtype: ggml_type(ty) });
+ }
+ Ok((tensors, meta))
+}
+
+/// Every model file under `dir` (sub-folders included) that Kokon recognizes, usable or not.
+pub fn scan(dir: &Path) -> Vec<FileInfo> {
+ scan_with(dir, SCAN_MIN_BYTES)
+}
+
+fn scan_with(dir: &Path, min_bytes: u64) -> Vec<FileInfo> {
+ let mut out = Vec::new();
+ let mut stack = vec![(dir.to_path_buf(), 0usize)];
+ let mut entries = 0usize;
+ let mut candidates = 0usize;
+ while let Some((d, depth)) = stack.pop() {
+ let Ok(rd) = std::fs::read_dir(&d) else { continue };
+ for e in rd.flatten() {
+ entries += 1;
+ if entries > SCAN_MAX_ENTRIES || candidates > SCAN_MAX_FILES {
+ return out;
+ }
+ let Ok(ft) = e.file_type() else { continue };
+ let name = e.file_name().to_string_lossy().to_ascii_lowercase();
+ if ft.is_dir() {
+ // Symlinked folders are not followed (no loops, no surprises).
+ if depth < SCAN_MAX_DEPTH && !name.starts_with('.') && !SCAN_SKIP.contains(&name.as_str()) {
+ stack.push((e.path(), depth + 1));
+ }
+ continue;
+ }
+ if !(name.ends_with(".gguf") || name.ends_with(".safetensors")) {
+ continue;
+ }
+ let p = e.path();
+ if std::fs::metadata(&p).map(|m| m.len() < min_bytes).unwrap_or(true) {
+ continue;
+ }
+ candidates += 1;
+ if let Ok(info) = inspect(&p)
+ && info.role.is_some()
+ {
+ out.push(info);
+ }
+ }
+ }
+ out.sort_by(|a, b| a.path.cmp(&b.path));
+ out
+}
+
+/// The files a scan suggests for each role (None: not found). The official files win; then a
+/// text encoder that carries its vision weights (no projector needed); then a diffusion model
+/// that leaves room on a card with `vram_mib`.
+#[derive(Debug, Clone, Default, PartialEq, Serialize)]
+pub struct Picks {
+ pub diffusion: Option<PathBuf>,
+ pub vae: Option<PathBuf>,
+ pub text_encoder: Option<PathBuf>,
+ /// None also when the text encoder has the vision weights.
+ pub vision_projector: Option<PathBuf>,
+}
+
+pub fn best(files: &[FileInfo], vram_mib: Option<u64>) -> Picks {
+ let usable = |r: Role| files.iter().filter(move |f| f.role == Some(r) && f.compatible);
+ let diffusion = usable(Role::Diffusion)
+ .min_by_key(|f| {
+ let fits = vram_mib.is_none_or(|v| f.size / (1 << 20) + 6 * 1024 <= v);
+ // Official first; then the largest that fits; then the smallest.
+ (!f.official, !fits, if fits { u64::MAX - f.size } else { f.size })
+ })
+ .map(|f| f.path.clone());
+ let vae = usable(Role::Vae).min_by_key(|f| (!f.official, f.size)).map(|f| f.path.clone());
+ let te = usable(Role::TextEncoder).min_by_key(|f| (!f.official, !f.has_vision, f.size));
+ let vision_projector = match te {
+ Some(t) if t.has_vision => None,
+ _ => usable(Role::VisionProjector).min_by_key(|f| (!f.official, f.size)).map(|f| f.path.clone()),
+ };
+ Picks { diffusion, vae, text_encoder: te.map(|f| f.path.clone()), vision_projector }
+}
+
+/// What the user chose for a role in Setup: a file of theirs, or the official file downloaded
+/// into a folder.
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Slot {
+ Path(PathBuf),
+ Download(PathBuf),
+}
+
+/// The official file Setup downloads for a role (the text encoder of `preset`).
+pub fn official_for(role: Role, preset: &Preset) -> Download {
+ match role {
+ Role::Diffusion => preset.diffusion,
+ Role::Vae => VAE,
+ Role::TextEncoder => preset.text_encoder,
+ Role::VisionProjector => VISION_PROJECTOR,
+ }
+}
+
+/// The path a slot resolves to, checked: the user's file must be a usable `role` file; an
+/// official download goes into the folder under its own name (a file of that name already
+/// there must be the official one). Also returns whether a text encoder has vision weights.
+fn resolve(slot: &Slot, role: Role, preset: &Preset) -> Result<(PathBuf, bool), AppError> {
+ match slot {
+ Slot::Path(p) => {
+ let info = inspect(p).map_err(|e| AppError::io("read", p, e))?;
+ if info.role != Some(role) {
+ let what = match (info.role, info.problem) {
+ (Some(r), _) => format!("this is a {} file", r.label().to_lowercase()),
+ (None, Some(problem)) => problem,
+ (None, None) => "not recognized".into(),
+ };
+ return Err(AppError::invalid(format!("{}: {what} ({}).", role.label(), p.display())));
+ }
+ if !info.compatible {
+ return Err(AppError::invalid(format!("{}: {}", role.label(), info.problem.unwrap_or_else(|| "not usable with Qwen-Image 2.1.".into()))));
+ }
+ Ok((p.clone(), info.has_vision))
+ }
+ Slot::Download(dir) => {
+ let d = official_for(role, preset);
+ let path = dir.join(d.file_name());
+ if let Ok(m) = std::fs::metadata(&path)
+ && m.len() != d.size
+ {
+ return Err(AppError::invalid(format!("{}: {} already exists and is not the official file. Choose another folder, or choose that file instead.", role.label(), path.display())));
+ }
+ Ok((path, false))
+ }
+ }
+}
+
+/// The user profile for the files chosen in Setup, every one checked. The vision projector is
+/// left out when the text encoder carries the vision weights, and required otherwise
+/// (editing needs it).
+pub fn user_profile(diffusion: &Slot, vae: &Slot, text_encoder: &Slot, vision: Option<&Slot>, scan_dir: Option<PathBuf>, preset: &Preset) -> Result<ModelProfile, AppError> {
+ let (diffusion, _) = resolve(diffusion, Role::Diffusion, preset)?;
+ let (vae, _) = resolve(vae, Role::Vae, preset)?;
+ let (te, te_vision) = resolve(text_encoder, Role::TextEncoder, preset)?;
+ let vision = match (vision, te_vision) {
+ (_, true) => None,
+ (Some(v), false) => Some(resolve(v, Role::VisionProjector, preset)?.0),
+ (None, false) => return Err(AppError::invalid("This text encoder has no vision weights, which editing needs: choose the vision projector (mmproj), or download it.")),
+ };
+ let mut p = ModelProfile::user(diffusion, vae, te, vision);
+ p.scan_dir = scan_dir;
+ Ok(p)
+}
+
+#[cfg(test)]
+pub(crate) mod tests {
+ use super::*;
+
+ /// A safetensors file with these tensors (header only; no weights).
+ pub(crate) fn write_st(path: &Path, tensors: &[(&str, &str, &[u64])]) {
+ let mut m = serde_json::Map::new();
+ m.insert("__metadata__".into(), serde_json::json!({ "format": "pt" }));
+ for (n, d, s) in tensors {
+ m.insert(n.to_string(), serde_json::json!({ "dtype": d, "shape": s, "data_offsets": [0, 0] }));
+ }
+ let h = serde_json::to_vec(&m).unwrap();
+ let mut b = (h.len() as u64).to_le_bytes().to_vec();
+ b.extend(h);
+ std::fs::write(path, b).unwrap();
+ }
+
+ /// A GGUF file with string/u32 metadata and these tensors (dims in GGUF order).
+ pub(crate) fn write_gguf(path: &Path, kv: &[(&str, &str)], kv_u32: &[(&str, u32)], tensors: &[(&str, u32, &[u64])]) {
+ let s = |b: &mut Vec<u8>, x: &str| {
+ b.extend((x.len() as u64).to_le_bytes());
+ b.extend(x.as_bytes());
+ };
+ let mut b = b"GGUF".to_vec();
+ b.extend(3u32.to_le_bytes());
+ b.extend((tensors.len() as u64).to_le_bytes());
+ b.extend(((kv.len() + kv_u32.len() + 1) as u64).to_le_bytes());
+ for (k, v) in kv {
+ s(&mut b, k);
+ b.extend(8u32.to_le_bytes());
+ s(&mut b, v);
+ }
+ for (k, v) in kv_u32 {
+ s(&mut b, k);
+ b.extend(4u32.to_le_bytes());
+ b.extend(v.to_le_bytes());
+ }
+ // A tokenizer-like string array, skipped by the reader.
+ s(&mut b, "tokenizer.ggml.tokens");
+ b.extend(9u32.to_le_bytes());
+ b.extend(8u32.to_le_bytes());
+ b.extend(3u64.to_le_bytes());
+ for t in ["a", "bb", "ccc"] {
+ s(&mut b, t);
+ }
+ for (n, ty, dims) in tensors {
+ s(&mut b, n);
+ b.extend((dims.len() as u32).to_le_bytes());
+ for d in *dims {
+ b.extend(d.to_le_bytes());
+ }
+ b.extend(ty.to_le_bytes());
+ b.extend(0u64.to_le_bytes());
+ }
+ std::fs::write(path, b).unwrap();
+ }
+
+ /// A set of synthetic files like a ComfyUI models folder: the 2.1 Turbo as INT8
+ /// safetensors, the 2.1 VAE, a Qwen3-VL text encoder with the vision tower, plus files of
+ /// other models.
+ pub(crate) fn comfy_folder(dir: &Path) -> (PathBuf, PathBuf, PathBuf) {
+ let m = dir.join("models");
+ for sub in ["diffusion_models", "vae", "text_encoders", "custom_nodes"] {
+ std::fs::create_dir_all(m.join(sub)).unwrap();
+ }
+ let dit = m.join("diffusion_models").join("qwen_image_2.1_turbo_int8_convrot.safetensors");
+ write_st(&dit, &[("model.diffusion_model.txt_in.text_norm.weight", "BF16", &[4096]), ("model.diffusion_model.transformer_blocks.0.img_mod.1.weight", "I8", &[24576, 4096]), ("model.diffusion_model.img_in.weight", "BF16", &[4096, 64])]);
+ let vae = m.join("vae").join("qwen_image_2.1_vae_bf16.safetensors");
+ write_st(&vae, &[("conv2.weight", "BF16", &[64, 64, 1, 1, 1]), ("decoder.conv1.weight", "BF16", &[1152, 64, 1, 3, 3]), ("encoder.conv1.weight", "BF16", &[96, 3, 3, 3, 3])]);
+ let te = m.join("text_encoders").join("qwen3vl_8b_int8_convrot.safetensors");
+ write_st(
+ &te,
+ &[
+ ("model.embed_tokens.weight", "BF16", &[151936, 4096]),
+ ("model.layers.0.self_attn.q_proj.weight", "I8", &[4096, 4096]),
+ ("model.layers.0.self_attn.q_norm.weight", "BF16", &[128]),
+ ("visual.blocks.0.attn.qkv.weight", "BF16", &[3456, 1152]),
+ ("visual.merger.linear_fc2.weight", "BF16", &[4096, 4608]),
+ ],
+ );
+ // Another model's files, and one inside a folder a scan skips.
+ write_st(&m.join("diffusion_models").join("qwen_image_2512.safetensors"), &[("transformer_blocks.0.img_mod.1.weight", "BF16", &[18432, 3072]), ("img_in.weight", "BF16", &[3072, 64])]);
+ write_st(&m.join("vae").join("qwen_image_vae.safetensors"), &[("conv2.weight", "BF16", &[16, 16, 1, 1, 1]), ("decoder.conv1.weight", "BF16", &[384, 16, 1, 3, 3]), ("encoder.conv1.weight", "BF16", &[96, 3, 3, 3, 3])]);
+ write_st(&m.join("custom_nodes").join("hidden.safetensors"), &[("txt_in.text_norm.weight", "BF16", &[4096])]);
+ (dit, vae, te)
+ }
+
+ #[test]
+ fn recognizes_comfyui_files() {
+ let dir = tempfile::tempdir().unwrap();
+ let (dit, vae, te) = comfy_folder(dir.path());
+ let d = inspect(&dit).unwrap();
+ assert_eq!((d.role, d.compatible, d.weights.as_str(), d.official), (Some(Role::Diffusion), true, "INT8", false));
+ let v = inspect(&vae).unwrap();
+ assert_eq!((v.role, v.compatible), (Some(Role::Vae), true));
+ assert!(!v.official, "the official name, but not its size");
+ let t = inspect(&te).unwrap();
+ assert_eq!((t.role, t.compatible, t.has_vision), (Some(Role::TextEncoder), true, true));
+ let old = inspect(&dir.path().join("models/diffusion_models/qwen_image_2512.safetensors")).unwrap();
+ assert_eq!((old.role, old.compatible), (Some(Role::Diffusion), false));
+ assert!(old.problem.unwrap().contains("not Qwen-Image 2.1"));
+ let old_vae = inspect(&dir.path().join("models/vae/qwen_image_vae.safetensors")).unwrap();
+ assert!(!old_vae.compatible && old_vae.problem.unwrap().contains("latent size 16"));
+ }
+
+ #[test]
+ fn recognizes_gguf_files() {
+ let dir = tempfile::tempdir().unwrap();
+ let dit = dir.path().join("turbo.gguf");
+ write_gguf(&dit, &[], &[], &[("model.diffusion_model.txt_in.text_norm.weight", 30, &[4096]), ("model.diffusion_model.img_in.weight", 12, &[64, 4096]), ("model.diffusion_model.proj_out.weight", 12, &[4096, 64])]);
+ let d = inspect(&dit).unwrap();
+ assert_eq!((d.role, d.compatible, d.weights.as_str()), (Some(Role::Diffusion), true, "Q4_K"));
+ let te = dir.path().join("te.gguf");
+ write_gguf(&te, &[("general.architecture", "qwen3vl")], &[("qwen3vl.embedding_length", 4096)], &[("token_embd.weight", 12, &[4096, 151936]), ("blk.0.attn_q.weight", 12, &[4096, 4096]), ("blk.0.attn_q_norm.weight", 0, &[128])]);
+ let t = inspect(&te).unwrap();
+ assert_eq!((t.role, t.compatible, t.has_vision), (Some(Role::TextEncoder), true, false));
+ let old_te = dir.path().join("qwen25.gguf");
+ write_gguf(&old_te, &[("general.architecture", "qwen2vl")], &[], &[("token_embd.weight", 12, &[3584, 152064]), ("blk.0.attn_q.weight", 12, &[3584, 3584])]);
+ assert!(inspect(&old_te).unwrap().problem.unwrap().contains("Qwen2.5-VL"));
+ let mm = dir.path().join("mmproj.gguf");
+ write_gguf(&mm, &[("general.architecture", "clip")], &[("clip.vision.projection_dim", 4096)], &[("v.blk.0.attn_qkv.weight", 1, &[1152, 3456]), ("mm.2.weight", 1, &[4608, 4096])]);
+ let p = inspect(&mm).unwrap();
+ assert_eq!((p.role, p.compatible), (Some(Role::VisionProjector), true));
+ let mm4b = dir.path().join("mmproj-4b.gguf");
+ write_gguf(&mm4b, &[("general.architecture", "clip")], &[("clip.vision.projection_dim", 2560)], &[("v.blk.0.attn_qkv.weight", 1, &[1024, 3072])]);
+ assert!(!inspect(&mm4b).unwrap().compatible);
+ }
+
+ #[test]
+ fn rejects_unsafe_split_and_broken_files() {
+ let dir = tempfile::tempdir().unwrap();
+ for (name, needle) in [("model.ckpt", "can run code"), ("model.bin", "can run code"), ("model-00001-of-00004.safetensors", "split into several"), ("notes.txt", "Not a model file")] {
+ let p = dir.path().join(name);
+ std::fs::write(&p, b"0123456789").unwrap();
+ let i = inspect(&p).unwrap();
+ assert!(i.role.is_none() && !i.compatible && i.problem.as_deref().unwrap().contains(needle), "{name}: {:?}", i.problem);
+ }
+ let p = dir.path().join("broken.safetensors");
+ std::fs::write(&p, b"\xff\xff\xff\xff\xff\xff\xff\xffgarbage").unwrap();
+ assert!(inspect(&p).unwrap().problem.unwrap().contains("header"));
+ let p = dir.path().join("broken.gguf");
+ std::fs::write(&p, b"GGUF\x03\x00\x00\x00").unwrap();
+ assert!(inspect(&p).unwrap().problem.unwrap().contains("header"));
+ assert!(inspect(&dir.path().join("missing.gguf")).is_err());
+ }
+
+ #[test]
+ fn official_files_by_name_and_size() {
+ let p = Path::new("D:/anywhere/Qwen3VL-8B-Instruct-Q4_K_M.gguf");
+ assert_eq!(official_download(p, TEXT_ENCODER_Q4_K_M.size).unwrap().id, "text_encoder_q4_k_m");
+ assert!(official_download(p, 123).is_none(), "same name, other size");
+ assert!(official_download(Path::new("D:/x/renamed.gguf"), TEXT_ENCODER_Q4_K_M.size).is_none());
+ }
+
+ #[test]
+ fn scan_finds_the_pieces_and_picks_the_best() {
+ let dir = tempfile::tempdir().unwrap();
+ let (dit, vae, te) = comfy_folder(dir.path());
+ let files = scan_with(dir.path(), 0);
+ assert_eq!(files.len(), 5, "skipped folders are not entered: {files:#?}");
+ let picks = best(&files, Some(16_303));
+ assert_eq!(picks, Picks { diffusion: Some(dit.clone()), vae: Some(vae), text_encoder: Some(te), vision_projector: None }, "the text encoder carries the vision weights");
+ // A text encoder without vision needs the projector, when there is one.
+ let mm = dir.path().join("models").join("mmproj.gguf");
+ write_gguf(&mm, &[("general.architecture", "clip")], &[("clip.vision.projection_dim", 4096)], &[("v.blk.0.attn_qkv.weight", 1, &[1152, 3456])]);
+ let mut files = scan_with(dir.path(), 0);
+ for f in files.iter_mut().filter(|f| f.role == Some(Role::TextEncoder)) {
+ f.has_vision = false;
+ }
+ assert_eq!(best(&files, None).vision_projector, Some(mm));
+ // The minimum size skips small files.
+ assert!(scan_with(dir.path(), 1 << 20).is_empty());
+ assert!(scan(&dir.path().join("missing")).is_empty());
+ }
+
+ #[test]
+ fn user_profile_checks_every_choice() {
+ let dir = tempfile::tempdir().unwrap();
+ let (dit, vae, te) = comfy_folder(dir.path());
+ let preset = crate::catalog::preset("16gb").unwrap();
+ let path = |p: &Path| Slot::Path(p.to_path_buf());
+ // badraymen's set (#14): the fused text encoder needs no projector.
+ let p = user_profile(&path(&dit), &path(&vae), &path(&te), None, Some(dir.path().to_path_buf()), preset).unwrap();
+ assert_eq!((p.id.as_str(), p.vision_projector.clone(), p.scan_dir.clone()), (crate::config::USER_PROFILE_ID, None, Some(dir.path().to_path_buf())));
+ // ...and a projector chosen anyway is not passed.
+ let mm = dir.path().join("mm.gguf");
+ write_gguf(&mm, &[("general.architecture", "clip")], &[("clip.vision.projection_dim", 4096)], &[("v.blk.0.attn_qkv.weight", 1, &[1152, 3456])]);
+ assert_eq!(user_profile(&path(&dit), &path(&vae), &path(&te), Some(&path(&mm)), None, preset).unwrap().vision_projector, None);
+ // Wrong file for the role, or a file of another model.
+ let e = user_profile(&path(&vae), &path(&vae), &path(&te), None, None, preset).unwrap_err();
+ assert!(e.message.starts_with("Diffusion model: this is a vae file"), "{}", e.message);
+ let old = dir.path().join("models/diffusion_models/qwen_image_2512.safetensors");
+ assert!(user_profile(&path(&old), &path(&vae), &path(&te), None, None, preset).unwrap_err().message.contains("not Qwen-Image 2.1"));
+ // Official pieces to download: the official text encoder has no vision, so the
+ // projector is required, and downloaded too.
+ let dl = dir.path().join("dl");
+ let e = user_profile(&path(&dit), &path(&vae), &Slot::Download(dl.clone()), None, None, preset).unwrap_err();
+ assert!(e.message.contains("vision projector"), "{}", e.message);
+ let p = user_profile(&path(&dit), &Slot::Download(dl.clone()), &Slot::Download(dl.clone()), Some(&Slot::Download(dl.clone())), None, preset).unwrap();
+ assert_eq!(p.vae, dl.join(VAE.file_name()));
+ assert_eq!(p.text_encoder, dl.join(preset.text_encoder.file_name()));
+ assert_eq!(p.vision_projector, Some(dl.join(VISION_PROJECTOR.file_name())));
+ assert_eq!(crate::catalog::profile_model_downloads(&p).len(), 3, "and they are what the install downloads");
+ // A different file under the official name is never overwritten.
+ std::fs::create_dir_all(&dl).unwrap();
+ std::fs::write(dl.join(VAE.file_name()), b"mine").unwrap();
+ assert!(user_profile(&path(&dit), &Slot::Download(dl), &path(&te), None, None, preset).unwrap_err().message.contains("not the official file"));
+ }
+
+ #[test]
+ fn diffusion_pick_follows_vram() {
+ let f = |name: &str, gib: u64| FileInfo { path: PathBuf::from(name), size: gib << 30, role: Some(Role::Diffusion), compatible: true, has_vision: false, weights: String::new(), official: false, problem: None };
+ let files = [f("bf16", 20), f("int8", 10), f("q4", 5)];
+ assert_eq!(best(&files, Some(16 * 1024)).diffusion, Some(PathBuf::from("int8")), "the largest that leaves room");
+ assert_eq!(best(&files, Some(8 * 1024)).diffusion, Some(PathBuf::from("q4")), "nothing fits: the smallest");
+ let mut off = f("official", 4);
+ off.official = true;
+ assert_eq!(best(&[files[0].clone(), off], Some(32 * 1024)).diffusion, Some(PathBuf::from("official")));
+ }
+}
diff --git a/crates/qls-core/src/process.rs b/crates/qls-core/src/process.rs
index c137a57..5d67ba4 100644
--- a/crates/qls-core/src/process.rs
+++ b/crates/qls-core/src/process.rs
@@ -476,18 +476,8 @@ impl ServerManager {
e
};
let exe = cfg.server_exe();
- if !exe.is_file() {
- return Err(fail(
- AppError::new(ErrorCode::MissingModel, format!("sd-server was not found in {}.", cfg.engine_dir().display()))
- .suggest("Install it from Settings → Models → Set up models…, or set the stable-diffusion.cpp folder in Settings."),
- ));
- }
- for (label, path, required) in profile.files() {
- if required && !path.is_file() {
- return Err(fail(
- AppError::new(ErrorCode::MissingModel, format!("{label} not found: {}", path.display())).suggest("Fix the model path in Settings."),
- ));
- }
+ if let Some(e) = cfg.missing_files_error() {
+ return Err(fail(e));
}
let log_path = self.log_path();
if let Some(d) = log_path.parent() {
diff --git a/crates/qls-service/src/api.rs b/crates/qls-service/src/api.rs
index 96c6ca9..6789654 100644
--- a/crates/qls-service/src/api.rs
+++ b/crates/qls-service/src/api.rs
@@ -18,12 +18,14 @@ use axum::{
use futures_util::stream::Stream;
use qls_core::{
catalog,
- config::{AppConfig, GpuBackend},
+ config::{AppConfig, GpuBackend, OFFICIAL_PROFILE_ID, USER_PROFILE_ID},
diagnostics,
engine::{APP_VERSION, JobView},
error::{AppError, ErrorCode},
geometry::{ExpansionUnits, Size, aspect_label},
- imaging, installer, paths,
+ imaging, installer,
+ modelfile::{self, FileInfo, Role, Slot},
+ paths,
planner::{GenerationRequest, InpaintAction, Mode, OutpaintSpec, Quality, UpscaleMethod, UpscaleSpec},
store::{GenerationRecord, ListQuery},
};
@@ -63,6 +65,11 @@ pub fn router(state: Arc<AppState>) -> Router {
.route("/setup/install/cancel", post(install_cancel))
.route("/setup/gpu", post(setup_gpu))
.route("/setup/legacy-upscalers", get(legacy_upscalers).delete(remove_legacy_upscalers))
+ .route("/models", get(models_status))
+ .route("/models/scan", post(models_scan))
+ .route("/models/inspect", post(models_inspect))
+ .route("/models/user", post(models_set_user))
+ .route("/models/use", post(models_use))
.route("/upscalers", get(list_upscalers))
.route("/upscalers/{name}/download", post(download_upscaler))
.route("/config", get(get_config).put(put_config))
@@ -199,7 +206,7 @@ async fn status(State(s): St) -> Json<Value> {
},
"upscaler": { "model": cfg.upscaler().map(|u| u.0).unwrap_or_else(|| cfg.upscaler_model.clone()), "available": cfg.upscaler_file().is_some() },
"engine": { "release": catalog::engine_tag(), "update_needed": engine_update },
- "profile": { "id": cfg.profile().id, "display_name": cfg.profile().display_name },
+ "profile": { "id": cfg.profile().id, "display_name": cfg.profile().display_name, "source": cfg.profile().source },
"gpu": gpu,
"active_job": s.engine.active_job(),
"queue": { "queued": queued, "jobs": jobs.iter().filter(|j| !j.status.is_terminal()).collect::<Vec<_>>() },
@@ -212,7 +219,8 @@ async fn setup(State(s): St) -> ApiResult<Json<Value>> {
let _ = tokio::task::spawn_blocking(move || e.place_bundled_upscaler()).await;
let cfg = s.engine.config();
let srv_ok = s.engine.server.status().state == qls_core::process::ServerState::Ready;
- let report = tokio::task::spawn_blocking(move || diagnostics::setup_checks(&cfg, Some(srv_ok))).await.map_err(AppError::internal)?;
+ let e = s.engine.clone();
+ let report = tokio::task::spawn_blocking(move || diagnostics::setup_checks_with(&cfg, Some(srv_ok), e.devices(), e.backend_version())).await.map_err(AppError::internal)?;
Ok(Json(serde_json::to_value(report).unwrap()))
}
@@ -254,7 +262,16 @@ async fn setup_hardware(State(s): St, Query(q): Query<HardwareQ>) -> ApiResult<J
})
})
.collect();
+ // The user's own files: what their profile still needs (engine, upscalers, official
+ // pieces they chose to download).
+ let user_files = cfg.user_profile().map(|u| {
+ let files = catalog::downloads_for_profile(u, backend);
+ let (download, disk) = installer::space_needed(&dir, &files);
+ json!({ "files": installer::preview(&dir, &files), "download_bytes": download, "disk_bytes": disk })
+ });
json!({
+ "active_source": cfg.profile().source,
+ "user_files": user_files,
"gpu": gpu,
"gpus": cards.iter().map(|c| json!({ "name": c.name, "memory_total_mib": c.memory_total_mib })).collect::<Vec<_>>(),
"gpu_index": card,
@@ -291,6 +308,10 @@ struct InstallBody {
apply: bool,
/// Card (index in `/setup/hardware` `gpus`) to run on once the engine is installed.
gpu: Option<usize>,
+ /// Which files: "official" (the preset's, made active when done) or "user" (the engine
+ /// and what the user's own profile still needs). Default: "official" when `apply`, else
+ /// the active profile's (an engine update never downloads models a user doesn't use).
+ target: Option<String>,
}
fn yes() -> bool {
@@ -298,11 +319,23 @@ fn yes() -> bool {
}
/// Starts downloading a preset into the configured folder. When every file is installed the
-/// official profile of that preset becomes active.
+/// preset's runtime settings apply, and for the official files their profile becomes active.
async fn install_start(State(s): St, Json(b): Json<InstallBody>) -> ApiResult<Json<Value>> {
let preset = catalog::preset(&b.preset).ok_or_else(|| AppError::invalid(format!("Unknown preset {}.", b.preset)))?;
let cfg = s.engine.config();
let backend = b.backend.unwrap_or(cfg.gpu_backend);
+ let user = match b.target.as_deref() {
+ Some("user") => true,
+ Some("official") => false,
+ None => !b.apply && !cfg.profile().is_official(),
+ Some(t) => return Err(AppError::invalid(format!("Unknown install target {t}.")).into()),
+ };
+ let downloads = if user {
+ let u = cfg.user_profile().ok_or_else(|| AppError::invalid("Choose your model files first."))?;
+ catalog::downloads_for_profile(u, backend)
+ } else {
+ catalog::downloads_for(preset, backend)
+ };
// A running server keeps its DLLs open; the engine zip may need to replace them.
let st = s.engine.server.status();
if st.owned && st.state != qls_core::process::ServerState::Stopped {
@@ -323,6 +356,9 @@ async fn install_start(State(s): St, Json(b): Json<InstallBody>) -> ApiResult<Js
}
let mut c = engine.config();
c.apply_preset(preset);
+ if !user {
+ c.use_official();
+ }
c.gpu_backend = backend;
if backend == GpuBackend::Metal && small_unified {
c.text_encoder_placement = qls_core::config::TextEncoderPlacement::Disk;
@@ -342,7 +378,8 @@ async fn install_start(State(s): St, Json(b): Json<InstallBody>) -> ApiResult<Js
// The bundled upscaler first, so it is not downloaded again.
let e = s.engine.clone();
let _ = tokio::task::spawn_blocking(move || e.place_bundled_upscaler()).await;
- s.engine.installer.start(cfg.sdcpp_dir.clone(), preset.id, catalog::downloads_for(preset, backend), on_finish)?;
+ let label = if user { format!("user:{}", preset.id) } else { preset.id.to_string() };
+ s.engine.installer.start(cfg.sdcpp_dir.clone(), &label, downloads, on_finish)?;
Ok(Json(serde_json::to_value(s.engine.installer.status()).unwrap()))
}
@@ -504,12 +541,19 @@ async fn diagnostics_json(State(s): St) -> ApiResult<Json<Value>> {
}
let _ = writeln!(text, "\n[Configuration]");
let _ = writeln!(text, "sdcpp dir: {}", cfg.sdcpp_dir.display());
- let _ = writeln!(text, "Preset: {}, profile: {}", cfg.hardware_preset, cfg.profile().display_name);
+ let official = cfg.profile().is_official();
+ let _ = writeln!(text, "Preset: {}, profile: {} ({})", cfg.hardware_preset, cfg.profile().display_name, if official { "official files" } else { "the user's own files, not tested by Kokon" });
if cfg.vram_override_mib > 0 {
let _ = writeln!(text, "Simulated VRAM for planning: {} MiB", cfg.vram_override_mib);
}
for (label, p, _) in cfg.profile().files() {
- let _ = writeln!(text, "{label}: {} ({})", p.display(), if p.is_file() { "ok" } else { "MISSING" });
+ let state = match (p.is_file(), official) {
+ (false, _) => "MISSING".to_string(),
+ (true, true) => "ok".to_string(),
+ // Own files: what they are, so a report shows the quantization in use.
+ (true, false) => modelfile::inspect(p).map(|i| format!("ok, {:.2} GB, {}{}", i.size as f64 / 1e9, i.weights, i.problem.map(|e| format!(", {e}")).unwrap_or_default())).unwrap_or_else(|e| e.to_string()),
+ };
+ let _ = writeln!(text, "{label}: {} ({state})", p.display());
}
let _ = writeln!(text, "Device: {}, text encoder: {:?}, VRAM reserve: {} GiB, flash attention: {}, sage attention: {}", cfg.device, cfg.text_encoder_placement, cfg.vram_reserve_gib, cfg.flash_attention, cfg.sage_attention);
let _ = writeln!(text, "VAE tile size: {}, upscale tile size: {}", cfg.vae_tile_size, cfg.upscale_tile_size);
@@ -1026,3 +1070,149 @@ fn percent_decode(s: &str) -> String {
}
String::from_utf8_lossy(&out).into_owned()
}
+
+// ---------------------------------------------------------------------------------------
+// The user's own model files (#14)
+// ---------------------------------------------------------------------------------------
+
+/// Saves `cfg`; restarts an idle server of ours when the model changed.
+async fn save_and_restart(s: &AppState, cfg: AppConfig) -> ApiResult<()> {
+ let restart = s.engine.set_config(cfg)?;
+ let st = s.engine.server.status();
+ if restart && st.owned && st.state != qls_core::process::ServerState::Stopped && !s.engine.has_pending_work() {
+ s.engine.server.stop().await;
+ s.engine.emit_server();
+ }
+ Ok(())
+}
+
+fn role_of(label: &str) -> Option<Role> {
+ Role::ALL.into_iter().find(|r| r.label() == label)
+}
+
+/// The active model: its files (what each is, whether it is there), what is missing and what
+/// can be done about it. Setup shows this when a file is missing.
+async fn models_status(State(s): St) -> ApiResult<Json<Value>> {
+ let cfg = s.engine.config();
+ let v = tokio::task::spawn_blocking(move || {
+ let p = cfg.profile();
+ let slots: Vec<Value> = p
+ .files()
+ .into_iter()
+ .map(|(label, path, _)| {
+ let exists = path.is_file();
+ // Own files only: the official ones are known (and their headers are big).
+ let info = (exists && !p.is_official()).then(|| modelfile::inspect(path).ok()).flatten();
+ json!({ "role": role_of(label), "label": label, "path": path, "exists": exists, "info": info })
+ })
+ .collect();
+ let downloadable: Vec<&str> = catalog::profile_model_downloads(p).iter().map(|d| d.label).collect();
+ let official_installed = cfg.profiles.iter().find(|q| q.id == OFFICIAL_PROFILE_ID).is_some_and(|q| q.files().iter().all(|(_, f, _)| f.is_file()));
+ json!({
+ "active": { "id": p.id, "display_name": p.display_name, "source": p.source, "model": p.model },
+ "slots": slots,
+ "missing": cfg.missing_files().iter().map(|(l, f)| json!({ "label": l, "path": f })).collect::<Vec<_>>(),
+ "downloadable": downloadable,
+ "engine_installed": cfg.server_exe().is_file(),
+ // The folder the active files were found in (none for the official ones), and the
+ // one of the user's own files (offered to switch back to them).
+ "scan_dir": p.scan_dir,
+ "user_scan_dir": cfg.user_profile().and_then(|u| u.scan_dir.clone()),
+ "has_user_profile": cfg.user_profile().is_some(),
+ "user_installed": cfg.user_profile().is_some_and(|u| u.files().iter().all(|(_, f, _)| f.is_file())),
+ "official_installed": official_installed,
+ "default_download_dir": catalog::join_rel(&cfg.sdcpp_dir, catalog::MODEL_SUBDIR),
+ })
+ })
+ .await
+ .map_err(AppError::internal)?;
+ Ok(Json(v))
+}
+
+#[derive(Deserialize)]
+struct ScanBody {
+ dir: PathBuf,
+}
+
+/// Every model file in a folder (sub-folders included), the suggested file for each role, and
+/// files with the same name as missing ones of the active profile (moved within the folder).
+async fn models_scan(State(s): St, Json(b): Json<ScanBody>) -> ApiResult<Json<Value>> {
+ if !b.dir.is_dir() {
+ return Err(AppError::invalid(format!("{} is not a folder.", b.dir.display())).into());
+ }
+ let engine = s.engine.clone();
+ let v = tokio::task::spawn_blocking(move || {
+ let cfg = engine.config();
+ let files = modelfile::scan(&b.dir);
+ let vram = cfg.planning_vram_mib(engine.gpu().map(|g| g.planning_mib()));
+ let picks = modelfile::best(&files, vram);
+ let mut moved = serde_json::Map::new();
+ for (label, path) in cfg.missing_files() {
+ let name = path.file_name().map(|n| n.to_ascii_lowercase());
+ let role = role_of(label);
+ if let Some(f) = files.iter().find(|f| f.compatible && f.role == role && f.path.file_name().map(|n| n.to_ascii_lowercase()) == name) {
+ moved.insert(serde_json::to_value(role).unwrap().as_str().unwrap_or_default().to_string(), json!(f.path));
+ }
+ }
+ json!({ "dir": b.dir, "files": files, "picks": picks, "moved": moved })
+ })
+ .await
+ .map_err(AppError::internal)?;
+ Ok(Json(v))
+}
+
+#[derive(Deserialize)]
+struct InspectBody {
+ path: PathBuf,
+}
+
+async fn models_inspect(Json(b): Json<InspectBody>) -> ApiResult<Json<FileInfo>> {
+ let p = b.path.clone();
+ let info = tokio::task::spawn_blocking(move || modelfile::inspect(&p)).await.map_err(AppError::internal)?.map_err(|e| AppError::io("read", &b.path, e))?;
+ Ok(Json(info))
+}
+
+#[derive(Deserialize)]
+struct UserFilesBody {
+ diffusion_model: Slot,
+ vae: Slot,
+ text_encoder: Slot,
+ /// None: not needed (the text encoder carries the vision weights).
+ vision_projector: Option<Slot>,
+ scan_dir: Option<PathBuf>,
+}
+
+/// Saves the user's own files (checked) as the active profile. Official pieces to download are
+/// then fetched by `/setup/install` with target "user", together with the engine.
+async fn models_set_user(State(s): St, Json(b): Json<UserFilesBody>) -> ApiResult<Json<Value>> {
+ let engine = s.engine.clone();
+ let cfg = tokio::task::spawn_blocking(move || -> Result<AppConfig, AppError> {
+ let mut cfg = engine.config();
+ let p = modelfile::user_profile(&b.diffusion_model, &b.vae, &b.text_encoder, b.vision_projector.as_ref(), b.scan_dir, cfg.preset())?;
+ cfg.set_user_files(p);
+ Ok(cfg)
+ })
+ .await
+ .map_err(AppError::internal)??;
+ save_and_restart(&s, cfg).await?;
+ models_status(State(s)).await
+}
+
+#[derive(Deserialize)]
+struct UseBody {
+ /// "official" or "user".
+ profile: String,
+}
+
+/// Switches between the official files and the user's own (both stay saved).
+async fn models_use(State(s): St, Json(b): Json<UseBody>) -> ApiResult<Json<Value>> {
+ let mut cfg = s.engine.config();
+ match b.profile.as_str() {
+ "official" => cfg.use_official(),
+ "user" if cfg.user_profile().is_some() => cfg.active_profile = USER_PROFILE_ID.into(),
+ "user" => return Err(AppError::invalid("Choose your model files first.").into()),
+ other => return Err(AppError::invalid(format!("Unknown profile {other}.")).into()),
+ }
+ save_and_restart(&s, cfg).await?;
+ models_status(State(s)).await
+}
diff --git a/mcp/src/tools.ts b/mcp/src/tools.ts
index 2aef1da..bb1f31e 100644
--- a/mcp/src/tools.ts
+++ b/mcp/src/tools.ts
@@ -397,7 +397,7 @@ export function toErrorResult(e: unknown): ToolResult {
if (e instanceof ServiceError) {
const suggestion =
e.code === "missing_model"
- ? "Open the Kokon app and finish the setup (it downloads the model), or use Settings → Models → Set up models…, then try again."
+ ? "A model file or the engine is missing (for example on a drive that is not connected, or moved). Connect the drive and try again, or open the Kokon app: it shows which file is missing and finds, replaces or downloads it."
: e.suggestion;
return errorResult(e.message, e.code, suggestion, e.detail);
}
diff --git a/scripts/dev/test-own-models.ps1 b/scripts/dev/test-own-models.ps1
new file mode 100644
index 0000000..c83d3fe
--- /dev/null
+++ b/scripts/dev/test-own-models.ps1
@@ -0,0 +1,175 @@
+# Manual test of "Use model files I already have" (#14) in an isolated Kokon: its own config,
+# data, ports and stable-diffusion.cpp folder under .test-data\own-models. The installed Kokon,
+# %APPDATA%\Kokon\config.json and the real model folders are never written to.
+#
+# A fake ComfyUI folder is made of renamed hardlinks to the official files of your installed
+# Kokon (no extra disk space; deleting or renaming a link never touches the original).
+#
+# powershell -ExecutionPolicy Bypass -File scripts\dev\test-own-models.ps1 [-Action <action>] [options]
+#
+# Actions
+# setup (default) Build the test environment and start Kokon on it (npm run tauri dev).
+# -Scenario fresh first run, nothing configured (the setup wizard)
+# -Scenario migrate a 0.9.2 config whose official profile was pointed at the
+# ComfyUI files by hand (badraymen's config): 0.9.3 must keep them
+# -DownloadEngine do not copy your engine: Setup downloads it (~0.9 GB with CUDA)
+# -Reset delete the previous test environment first
+# move Move the text encoder to another sub-folder (a file the user moved).
+# restore Move it back.
+# unplug Remove drive -Drive (default K:), made with "plug" (a disconnected drive).
+# plug Map -Drive to the fake ComfyUI folder (choose K:\models in Setup to use it).
+# status What the test Kokon sees: active profile, missing files (GET /models).
+# stop Stop the test service and its sd-server (they outlive the window). Only processes
+# started from this repository or the test folder; the installed Kokon keeps running.
+#
+# Close the installed Kokon first: both would load a model on the same GPU.
+param(
+ [ValidateSet('setup', 'move', 'restore', 'unplug', 'plug', 'status', 'stop')] [string]$Action = 'setup',
+ [ValidateSet('fresh', 'migrate')] [string]$Scenario = 'fresh',
+ [string]$From = (Join-Path $env:LOCALAPPDATA 'KokonData\sdcpp'),
+ [string]$Drive = 'K:',
+ [switch]$DownloadEngine,
+ [switch]$Reset
+)
+
+$ErrorActionPreference = 'Stop'
+$root = Resolve-Path "$PSScriptRoot\..\.."
+$test = Join-Path $root '.test-data\own-models'
+$data = Join-Path $test 'data'
+$config = Join-Path $test 'config'
+$sdcpp = Join-Path $test 'sdcpp'
+$comfy = Join-Path $test 'ComfyUI'
+$models = Join-Path $comfy 'models'
+$te = Join-Path $models 'text_encoders\qwen3vl_8b_instruct_q4km.gguf'
+$teMoved = Join-Path $models 'text_encoders\old\qwen3vl_8b_instruct_q4km.gguf'
+$realConfig = Join-Path $env:APPDATA 'Kokon\config.json'
+
+function RealConfigHash {
+ if (Test-Path $realConfig) { (Get-FileHash $realConfig -Algorithm SHA256).Hash.Substring(0, 16) } else { 'none' }
+}
+
+function StopTestProcesses {
+ $mine = Get-Process kokon-service, sd-server -ErrorAction SilentlyContinue | Where-Object { $_.Path -and ($_.Path.StartsWith("$root\target", 'OrdinalIgnoreCase') -or $_.Path.StartsWith("$test", 'OrdinalIgnoreCase')) }
+ foreach ($p in $mine) {
+ Write-Host "Stopping $($p.Name) ($($p.Path))"
+ Stop-Process -Id $p.Id -Force
+ }
+ if (-not $mine) { Write-Host 'No test processes running.' }
+}
+
+switch ($Action) {
+ 'stop' {
+ StopTestProcesses
+ return
+ }
+ 'move' {
+ New-Item -ItemType Directory -Force (Split-Path $teMoved) | Out-Null
+ Move-Item $te $teMoved
+ Write-Host "Moved the text encoder to $teMoved"
+ return
+ }
+ 'restore' {
+ Move-Item $teMoved $te
+ Write-Host "Moved the text encoder back to $te"
+ return
+ }
+ 'plug' {
+ subst $Drive $comfy
+ Write-Host "$Drive is now the fake ComfyUI folder. In Setup choose $Drive\models."
+ return
+ }
+ 'unplug' {
+ subst $Drive /d
+ Write-Host "$Drive removed (like a disconnected drive)."
+ return
+ }
+ 'status' {
+ $info = Get-Content (Join-Path $data 'service.json') -Raw | ConvertFrom-Json
+ $h = @{ Authorization = "Bearer $($info.token)" }
+ $m = Invoke-RestMethod -Uri "http://127.0.0.1:$($info.port)/api/v1/models" -Headers $h
+ Write-Host "Active: $($m.active.display_name) ($($m.active.source))"
+ foreach ($s in $m.slots) {
+ $what = if ($s.info) { " [$($s.info.weights), $([math]::Round($s.info.size / 1e9, 2)) GB]" } else { '' }
+ Write-Host (" {0,-26} {1} {2}{3}" -f $s.label, $(if ($s.exists) { 'ok ' } else { 'MISSING' }), $s.path, $what)
+ }
+ Write-Host "Engine installed: $($m.engine_installed); official files installed: $($m.official_installed); scan folder: $($m.scan_dir)"
+ Write-Host "Real config.json (must not change): $(RealConfigHash)"
+ return
+ }
+}
+
+# --- setup ---
+$off = Join-Path $From 'models\qwen21'
+$official = @{
+ diffusion = Join-Path $off 'qwen-image-2.1-turbo-Q4_K.gguf'
+ vae = Join-Path $off 'qwen_image_2.1_vae_bf16.safetensors'
+ te = Join-Path $off 'Qwen3VL-8B-Instruct-Q4_K_M.gguf'
+ mmproj = Join-Path $off 'mmproj-Qwen3VL-8B-Instruct-F16.gguf'
+}
+foreach ($f in $official.Values) { if (-not (Test-Path $f)) { throw "Not found: $f. Pass -From with the folder of your installed Kokon models." } }
+if ([IO.Path]::GetPathRoot($off) -ne [IO.Path]::GetPathRoot("$test")) { throw "Hardlinks need $test on the same drive as $off." }
+if (Get-Process sd-server -ErrorAction SilentlyContinue) { Write-Warning "sd-server is running: close Kokon first, or both load a model on the GPU." }
+
+# A test service left running would keep the old build (and lock its exe).
+StopTestProcesses
+if ($Reset -and (Test-Path $test)) {
+ # Only the test folder; the model files in it are hardlinks (the originals stay).
+ Remove-Item -Recurse -Force $test
+}
+New-Item -ItemType Directory -Force $data, $config, $sdcpp, (Join-Path $test 'output') | Out-Null
+
+# The fake ComfyUI folder: official files under ComfyUI-style names (recognized by their
+# contents, not as the official files), the VAE under its own name (as ComfyUI keeps it), and
+# files of other kinds a scan must skip.
+$links = @(
+ @{ path = Join-Path $models 'diffusion_models\qwen_image_2.1_turbo_q4k.gguf'; target = $official.diffusion },
+ @{ path = Join-Path $models 'vae\qwen_image_2.1_vae_bf16.safetensors'; target = $official.vae },
+ @{ path = $te; target = $official.te },
+ @{ path = Join-Path $models 'clip_vision\mmproj_qwen3vl_8b_f16.gguf'; target = $official.mmproj }
+)
+foreach ($l in $links) {
+ if ((Test-Path $l.path) -or ($l.path -eq $te -and (Test-Path $teMoved))) { continue }
+ New-Item -ItemType Directory -Force (Split-Path $l.path) | Out-Null
+ New-Item -ItemType HardLink -Path $l.path -Target $l.target | Out-Null
+}
+New-Item -ItemType Directory -Force (Join-Path $models 'loras'), (Join-Path $comfy 'custom_nodes') | Out-Null
+Set-Content (Join-Path $models 'loras\readme.txt') 'not a model'
+
+# The engine (and upscalers) of your installed Kokon, unless Setup should download it.
+if (-not $DownloadEngine -and -not (Test-Path (Join-Path $sdcpp 'sd-server.exe'))) {
+ Get-ChildItem $From -File | Where-Object { $_.Extension -in '.exe', '.dll' -or $_.Name -eq 'kokon-engine.txt' } | Copy-Item -Destination $sdcpp
+ $up = Join-Path $From 'models\upscalers'
+ if (Test-Path $up) {
+ New-Item -ItemType Directory -Force (Join-Path $sdcpp 'models\upscalers') | Out-Null
+ Get-ChildItem $up -File | Copy-Item -Destination (Join-Path $sdcpp 'models\upscalers')
+ }
+ Write-Host "Copied the engine from $From"
+}
+
+$cfg = @{ sdcppDir = "$sdcpp"; serverPort = 39190; servicePort = 39191; outputDir = (Join-Path $test 'output'); idleUnloadMinutes = 5 }
+if ($Scenario -eq 'migrate') {
+ # 0.9.2: own files set by editing the official profile.
+ $cfg.schemaVersion = 8
+ $cfg.setupComplete = $true
+ $cfg.activeProfile = 'qwen-image-2.1'
+ $cfg.profiles = @(@{
+ id = 'qwen-image-2.1'; displayName = 'Qwen-Image 2.1 Turbo Q4_K (official)'
+ diffusionModel = (Join-Path $models 'diffusion_models\qwen_image_2.1_turbo_q4k.gguf')
+ vae = (Join-Path $models 'vae\qwen_image_2.1_vae_bf16.safetensors')
+ textEncoder = $te
+ visionProjector = (Join-Path $models 'clip_vision\mmproj_qwen3vl_8b_f16.gguf')
+ })
+} else {
+ $cfg.setupComplete = $false
+}
+# UTF-8 without BOM (Set-Content -Encoding utf8 in PowerShell 5.1 writes one; Kokon accepts both).
+[IO.File]::WriteAllText((Join-Path $config 'config.json'), ($cfg | ConvertTo-Json -Depth 5))
+
+Write-Host "Test environment: $test" -ForegroundColor Cyan
+Write-Host "Fake ComfyUI models folder: $models"
+Write-Host "Real config.json (must not change): $(RealConfigHash)"
+Write-Host "Starting Kokon on it (close the window to stop)..." -ForegroundColor Cyan
+$env:QLS_DATA_DIR = $data
+$env:QLS_CONFIG_DIR = $config
+Push-Location $root
+try { npm run tauri dev } finally { Pop-Location }
diff --git a/src/App.tsx b/src/App.tsx
index b9272d6..f8f6ef0 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -4,7 +4,7 @@ import { useEffect, useRef, useState } from "react";
import { api, configure } from "./lib/api";
import { native } from "./lib/native";
import {
- addExampleProjects, addInputs, dismissToast, getState, newProject, redoVersion, refreshStatus, selectItem, setPrivateMode, setState, startEvents, startTour, submitComposer, toastError, toastInfo, undoKey, undoVersion, useStore,
+ addExampleProjects, addInputs, dismissToast, getState, isMissingModel, newProject, openModelSetup, redoVersion, refreshStatus, selectItem, setPrivateMode, setState, startEvents, startTour, submitComposer, toastError, toastInfo, undoKey, undoVersion, useStore,
} from "./lib/store";
import { Composer, importPaths } from "./components/Composer";
import { ExpandEditor } from "./components/ExpandEditor";
@@ -47,7 +47,7 @@ function StatusIndicator() {
case "error":
cls = "dot error";
text = server.error?.message ?? "Inference server error";
- title = "Open Diagnostics";
+ title = isMissingModel(server.error) ? "Find or download the missing file" : "Open Diagnostics";
break;
default:
text = "Model not loaded";
@@ -59,7 +59,8 @@ function StatusIndicator() {
className="status"
title={title}
onClick={() => {
- if (server.state === "error") setState({ overlay: "settings" });
+ if (server.state === "error" && isMissingModel(server.error)) openModelSetup();
+ else if (server.state === "error") setState({ overlay: "settings" });
else if (server.state === "stopped" && connected) api.startBackend().then(refreshStatus, toastError);
}}
>
diff --git a/src/components/OwnModels.tsx b/src/components/OwnModels.tsx
new file mode 100644
index 0000000..5d650c0
--- /dev/null
+++ b/src/components/OwnModels.tsx
@@ -0,0 +1,320 @@
+import { Check, CircleAlert, Download, FileSearch, FolderOpen, Loader2 } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { api } from "../lib/api";
+import { formatBytes } from "../lib/logic";
+import { native } from "../lib/native";
+import { toastError } from "../lib/store";
+import type { InstallItem, ModelFileInfo, ModelRole, ModelScan, ModelSlot, ModelsStatus } from "../lib/types";
+
+const ROLES: { role: ModelRole; label: string; official: string }[] = [
+ { role: "diffusion", label: "Image model", official: "turbo_q4_k" },
+ { role: "vae", label: "VAE", official: "vae" },
+ { role: "text_encoder", label: "Text encoder", official: "text_encoder" },
+ { role: "vision_projector", label: "Vision projector", official: "vision_projector" },
+];
+
+/** A file of the user's, the official file downloaded into `downloadDir`, or (vision projector
+ * only) nothing because the text encoder has the vision weights. */
+type Choice = { kind: "path"; path: string } | { kind: "download" } | { kind: "none" };
+
+const fileName = (p: string) => p.split(/[\\/]/).pop() ?? p;
+const folderName = (p: string) => p.split(/[\\/]/).filter(Boolean).pop() ?? p;
+
+function describe(f: ModelFileInfo): string {
+ return [f.weights, formatBytes(f.size), f.official ? "official file" : null].filter(Boolean).join(" · ");
+}
+
+/** Setup's "Use models I already have", as a guided flow: choose the folder (e.g. ComfyUI's
+ * models folder), check what was found (one row per piece, changed only where needed), use
+ * them. Pieces the user lacks are the official files, downloaded into a folder of their choice.
+ * Files are used where they are. */
+export function OwnModels(props: {
+ models: ModelsStatus;
+ /** The chosen preset's official model files (sizes of what can be downloaded). */
+ officialFiles: InstallItem[];
+ vramMib: number | null;
+ /** A scan to start from (Setup's "Search another folder"). */
+ initialScan: ModelScan | null;
+ /** Resolves once Setup has checked the new files (the button spins until then). */
+ onSaved: (s: ModelsStatus) => Promise<void>;
+}) {
+ const { models } = props;
+ const inUse = models.active.source === "user";
+ const [scan, setScan] = useState<ModelScan | null>(props.initialScan);
+ const [scanning, setScanning] = useState(false);
+ const [saving, setSaving] = useState(false);
+ // Pick each file without a folder scan.
+ const [manual, setManual] = useState(false);
+ // Changing files that are in use (otherwise their summary is shown).
+ const [editing, setEditing] = useState(!inUse || models.missing.length > 0 || !!props.initialScan);
+ // The row whose options are open.
+ const [open, setOpen] = useState<ModelRole | null>(null);
+ // Files chosen with "Choose a file…" (not in the scan), and the current profile's own files.
+ const [extra, setExtra] = useState<ModelFileInfo[]>([]);
+ const [downloadDir, setDownloadDir] = useState(models.default_download_dir);
+ const [choice, setChoice] = useState<Record<ModelRole, Choice>>(() => {
+ const c: Record<ModelRole, Choice> = { diffusion: { kind: "download" }, vae: { kind: "download" }, text_encoder: { kind: "download" }, vision_projector: { kind: "download" } };
+ if (inUse) {
+ for (const s of models.slots) if (s.role) c[s.role] = { kind: "path", path: s.path };
+ if (!models.slots.some((s) => s.role === "vision_projector")) c.vision_projector = { kind: "none" };
+ }
+ return c;
+ });
+
+ // The user profile's files, with what they are (missing ones are shown as such).
+ useEffect(() => {
+ if (inUse) setExtra(models.slots.filter((s) => s.info).map((s) => s.info!));
+ }, [models]);
+
+ const known = useMemo(() => {
+ const all = [...(scan?.files ?? []), ...extra];
+ return all.filter((f, i) => all.findIndex((g) => g.path === f.path) === i);
+ }, [scan, extra]);
+ const info = (path: string) => known.find((f) => f.path === path) ?? null;
+
+ const applyPicks = (s: ModelScan) => {
+ const te = s.picks.text_encoder ? s.files.find((f) => f.path === s.picks.text_encoder) : null;
+ setChoice(() => {
+ const n = {} as Record<ModelRole, Choice>;
+ for (const { role } of ROLES) {
+ const p = s.picks[role];
+ n[role] = p ? { kind: "path", path: p } : { kind: "download" };
+ }
+ // A text encoder with the vision weights: no projector needed.
+ if (te?.has_vision) n.vision_projector = { kind: "none" };
+ return n;
+ });
+ };
+
+ // A search from the missing-files card that did not find everything: continue from it.
+ useEffect(() => {
+ if (!props.initialScan) return;
+ setScan(props.initialScan);
+ applyPicks(props.initialScan);
+ setEditing(true);
+ }, [props.initialScan]);
+
+ const chooseFolder = async () => {
+ const dir = await native.pickFolder(scan?.dir ?? models.scan_dir ?? models.user_scan_dir ?? undefined);
+ if (!dir) return;
+ setScanning(true);
+ try {
+ const s = await api.scanModels(dir);
+ setScan(s);
+ applyPicks(s);
+ setEditing(true);
+ setOpen(null);
+ } catch (e) {
+ toastError(e);
+ } finally {
+ setScanning(false);
+ }
+ };
+
+ const browse = async (role: ModelRole) => {
+ const cur = choice[role];
+ const p = await native.pickFile(["gguf", "safetensors"], cur.kind === "path" ? cur.path : scan?.dir);
+ if (!p) return;
+ try {
+ const f = await api.inspectModel(p);
+ setExtra((x) => [...x.filter((g) => g.path !== f.path), f]);
+ pick(role, { kind: "path", path: p }, f);
+ } catch (e) {
+ toastError(e);
+ }
+ };
+
+ const pick = (role: ModelRole, c: Choice, f: ModelFileInfo | null = c.kind === "path" ? info(c.path) : null) => {
+ setChoice((x) => ({ ...x, [role]: c, ...(role === "text_encoder" && f?.has_vision ? { vision_projector: { kind: "none" } } : {}) }));
+ setOpen(null);
+ };
+
+ const teInfo = choice.text_encoder.kind === "path" ? info(choice.text_encoder.path) : null;
+ const teHasVision = !!teInfo?.has_vision;
+ const officialSize = (role: ModelRole) => {
+ const id = ROLES.find((r) => r.role === role)!.official;
+ return props.officialFiles.find((f) => f.id === id || (id === "text_encoder" && f.id.startsWith("text_encoder")))?.size ?? 0;
+ };
+
+ // What each row says, and whether the set can be used.
+ const rows = ROLES.map(({ role, label }) => {
+ const c = role === "vision_projector" && teHasVision ? ({ kind: "none" } as Choice) : choice[role];
+ let state: "ok" | "download" | "bad";
+ let text: string;
+ let detail: string | null = null;
+ if (c.kind === "none" && teHasVision) [state, text] = ["ok", "Not needed: included in your text encoder"];
+ else if (c.kind === "none") [state, text] = ["bad", "Needed for editing: this text encoder has no vision weights"];
+ else if (c.kind === "download") [state, text] = ["download", `${scan ? "Not found in this folder: " : ""}the official file will be downloaded (${formatBytes(officialSize(role))})`];
+ else {
+ const f = info(c.path);
+ const slot = models.slots.find((s) => s.path === c.path);
+ detail = c.path;
+ if (slot && !slot.exists) [state, text] = ["bad", "Not found"];
+ else if (!f) [state, text] = ["ok", fileName(c.path)];
+ else if (f.role !== role) [state, text] = ["bad", f.role ? `${fileName(c.path)} is a ${f.role.replace("_", " ")} file` : f.problem ?? "Not a Qwen-Image 2.1 file"];
+ else if (!f.compatible) [state, text] = ["bad", f.problem ?? "Not usable with Qwen-Image 2.1"];
+ else [state, text] = ["ok", `${fileName(c.path)} · ${describe(f)}`];
+ }
+ const candidates = known.filter((f) => f.role === role && f.compatible);
+ return { role, label, c, state, text, detail, candidates };
+ });
+ const canSave = rows.every((r) => r.state !== "bad");
+ const downloads = rows.filter((r) => r.c.kind === "download");
+ const found = rows.filter((r) => r.c.kind === "path").length;
+ const dit = choice.diffusion.kind === "path" ? info(choice.diffusion.path) : null;
+ const tooLarge = !!dit && props.vramMib != null && dit.size / 2 ** 20 > props.vramMib - 4096;
+ const skipped = scan ? scan.files.filter((f) => !f.compatible).length : 0;
+
+ const save = async () => {
+ const slot = (c: Choice): ModelSlot | null => (c.kind === "path" ? { path: c.path } : c.kind === "download" ? { download: downloadDir } : null);
+ setSaving(true);
+ try {
+ const s = await api.setUserModels({
+ diffusion_model: slot(rows[0].c)!,
+ vae: slot(rows[1].c)!,
+ text_encoder: slot(rows[2].c)!,
+ vision_projector: slot(rows[3].c),
+ scan_dir: scan?.dir ?? models.scan_dir ?? models.user_scan_dir,
+ });
+ await props.onSaved(s);
+ setEditing(false);
+ } catch (e) {
+ toastError(e);
+ } finally {
+ setSaving(false);
+ }
+ };
+
+ const icon = (state: "ok" | "download" | "bad") => (state === "ok" ? <Check size={16} /> : state === "download" ? <Download size={16} /> : <CircleAlert size={16} />);
+
+ // Step 1: where are the models?
+ if (editing && !scan && !manual && !inUse) {
+ return (
+ <div className="own-start">
+ <FolderOpen size={26} strokeWidth={1.6} />
+ <strong>Choose the folder with your models</strong>
+ <span className="muted">
+ For example <code>ComfyUI\models</code>. Kokon finds the Qwen-Image 2.1 files in it and in its sub-folders, as GGUF or safetensors. Nothing is copied or moved.
+ </span>
+ <button className="btn primary big" onClick={chooseFolder} disabled={scanning}>
+ {scanning ? <Loader2 className="spin" size={16} /> : <FolderOpen size={16} />} {scanning ? "Looking for models…" : "Choose folder…"}
+ </button>
+ <button className="link-btn" onClick={() => setManual(true)}>
+ or pick each file yourself
+ </button>
+ </div>
+ );
+ }
+
+ return (
+ <div className="own-models">
+ <div className="own-head">
+ <div>
+ <strong>{!editing ? "Using your own files" : scan ? `In ${folderName(scan.dir)}` : "Your files"}</strong>
+ <span className="muted">
+ {!editing
+ ? "Not tested by Kokon. Change them at any time, or switch back to the official files above."
+ : scan
+ ? `Found ${found} of 4${downloads.length ? `; ${downloads.length === 1 ? "1 piece" : `${downloads.length} pieces`} will be downloaded` : ""}${skipped ? ` · ${skipped} file${skipped === 1 ? "" : "s"} of other models skipped` : ""}`
+ : "Choose a file for each piece, or download the official one."}
+ </span>
+ </div>
+ {editing ? (
+ <button className="btn" onClick={chooseFolder} disabled={scanning}>
+ {scanning ? <Loader2 className="spin" size={14} /> : <FolderOpen size={14} />} {scan || inUse ? "Another folder…" : "Search a folder…"}
+ </button>
+ ) : (
+ <button className="btn" onClick={() => setEditing(true)}>
+ Change files
+ </button>
+ )}
+ </div>
+
+ <div className="own-list">
+ {rows.map((r) => (
+ <div className={`own-row ${r.state}`} key={r.role}>
+ <div className="own-row-main">
+ {icon(r.state)}
+ <div className="own-row-text">
+ <span className="own-row-label">{r.label}</span>
+ <span className="own-row-value">{r.text}</span>
+ {r.detail && <span className="own-row-path">{r.detail}</span>}
+ </div>
+ {editing && (
+ <button className="btn small" onClick={() => setOpen(open === r.role ? null : r.role)} aria-expanded={open === r.role}>
+ Change
+ </button>
+ )}
+ </div>
+ {editing && open === r.role && (
+ <div className="own-options">
+ {r.candidates.map((f) => (
+ <button key={f.path} className={`own-option ${r.c.kind === "path" && r.c.path === f.path ? "on" : ""}`} onClick={() => pick(r.role, { kind: "path", path: f.path }, f)}>
+ <span>{fileName(f.path)}</span>
+ <span className="muted">{describe(f)}</span>
+ </button>
+ ))}
+ {r.role === "vision_projector" && teHasVision && (
+ <button className={`own-option ${r.c.kind === "none" ? "on" : ""}`} onClick={() => pick(r.role, { kind: "none" })}>
+ <span>Not needed</span>
+ <span className="muted">your text encoder includes the vision weights</span>
+ </button>
+ )}
+ <button className={`own-option ${r.c.kind === "download" ? "on" : ""}`} onClick={() => pick(r.role, { kind: "download" })}>
+ <span>
+ <Download size={13} /> Download the official file
+ </span>
+ <span className="muted">{formatBytes(officialSize(r.role))}</span>
+ </button>
+ <button className="own-option" onClick={() => browse(r.role)}>
+ <span>
+ <FileSearch size={13} /> Choose a file…
+ </span>
+ <span className="muted">.gguf or .safetensors</span>
+ </button>
+ </div>
+ )}
+ </div>
+ ))}
+ </div>
+
+ {editing && downloads.length > 0 && (
+ <div className="own-download">
+ <span className="muted">
+ Downloads go to <strong>{downloadDir}</strong>
+ </span>
+ <button
+ className="link-btn"
+ onClick={async () => {
+ const d = await native.pickFolder(downloadDir);
+ if (d) setDownloadDir(d);
+ }}
+ >
+ Change
+ </button>
+ </div>
+ )}
+
+ {editing && tooLarge && (
+ <div className="setup-note">
+ This image model is {formatBytes(dit!.size)}, probably too large for {Math.round((props.vramMib ?? 0) / 1024)} GB of VRAM. Kokon makes smaller images to fit, but it may still run out of memory
+ or be slow. A 4-bit or 8-bit version (GGUF Q4_K or Q8_0, or INT8) works better on this card.
+ </div>
+ )}
+
+ {editing && (
+ <div className="own-actions">
+ <button className="btn primary" disabled={!canSave || saving} onClick={save}>
+ {saving ? <Loader2 className="spin" size={14} /> : <Check size={14} />} {saving ? "Checking the files…" : "Use these files"}
+ </button>
+ {inUse && models.missing.length === 0 && (
+ <button className="btn ghost" onClick={() => setEditing(false)}>
+ Cancel
+ </button>
+ )}
+ {!tooLarge && <span className="muted">Your own files are not tested by Kokon: quality and speed may differ.</span>}
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/src/components/Settings.tsx b/src/components/Settings.tsx
index 3962958..937241a 100644
--- a/src/components/Settings.tsx
+++ b/src/components/Settings.tsx
@@ -3,12 +3,12 @@ import { useEffect, useState } from "react";
import { writeText } from "@tauri-apps/plugin-clipboard-manager";
import { api } from "../lib/api";
import { native } from "../lib/native";
-import { getState, refreshStatus, setState, startTour, toastError, toastInfo } from "../lib/store";
+import { getState, openModelSetup, refreshStatus, setState, startTour, toastError, toastInfo } from "../lib/store";
import { formatBytes } from "../lib/logic";
import { setThemeChoice, themeChoice, type ThemeChoice } from "../lib/theme";
import { UpscalerControls } from "./Upscalers";
import { WHATS_NEW_VERSION } from "./WhatsNew";
-import type { AppConfig, Check, ModelProfile, SetupReport, TextEncoderPlacement } from "../lib/types";
+import type { AppConfig, Check, ModelProfile, ModelsStatus, SetupReport, TextEncoderPlacement } from "../lib/types";
import { IconButton, Seg, Switch } from "./ui";
import { autoCheckEnabled, checkForUpdate } from "../lib/updates";
@@ -91,6 +91,8 @@ export function Settings() {
const [cfg, setCfg] = useState<AppConfig | null>(null);
const [devices, setDevices] = useState<[string, string][]>([]);
const [upscaler, setUpscaler] = useState<Check | null>(null);
+ // The saved model setup: what is missing, whether the official files are downloaded.
+ const [ms, setMs] = useState<ModelsStatus | null>(null);
const [legacy, setLegacy] = useState<{ files: string[]; bytes: number } | null>(null);
const [dirty, setDirty] = useState(false);
const [theme, setTheme] = useState(themeChoice);
@@ -104,6 +106,7 @@ export function Settings() {
},
() => {},
);
+ api.models().then(setMs, () => {});
}, []);
// Upscaler files not in use, keeping the model chosen here even before Save.
const draftModel = cfg?.upscalerModel;
@@ -261,7 +264,7 @@ export function Settings() {
<div className="setting-card">
<div className="setting-card-text">
<strong>Model setup</strong>
- <span className="muted">Downloads the official Qwen-Image 2.1 weights for your graphics card, or switches between the 12, 16, 24 and 32 GB presets.</span>
+ <span className="muted">Downloads the official Qwen-Image 2.1 weights for your graphics card, uses model files you already have, or switches between the 12, 16, 24 and 32 GB presets.</span>
</div>
<button
className="btn primary"
@@ -288,10 +291,57 @@ export function Settings() {
) : (
<span className="muted">Model: {profile.displayName}</span>
)}
- <PathField label="Diffusion model" value={profile.diffusionModel} onChange={(v) => setProfile({ diffusionModel: v })} />
- <PathField label="VAE" value={profile.vae} onChange={(v) => setProfile({ vae: v })} />
- <PathField label="Text encoder (Qwen3-VL)" value={profile.textEncoder} onChange={(v) => setProfile({ textEncoder: v })} />
- <PathField label="Vision projector (mmproj)" value={profile.visionProjector ?? ""} onChange={(v) => setProfile({ visionProjector: v || null })} />
+ {profile.source === "official" ? (
+ // The official files follow the install folder and preset; own files get their own profile.
+ <div className="setting-card">
+ <div className="setting-card-text">
+ <strong>Official model</strong>
+ <span className="muted">
+ {ms === null
+ ? "Qwen-Image 2.1 Turbo, tested with Kokon."
+ : ms.official_installed
+ ? "Qwen-Image 2.1 Turbo, tested with Kokon. Downloaded."
+ : "Qwen-Image 2.1 Turbo, tested with Kokon. Not downloaded into this folder yet: Download… gets it, or use model files you already have."}
+ </span>
+ <details className="model-files">
+ <summary>Files</summary>
+ {[profile.diffusionModel, profile.vae, profile.textEncoder, profile.visionProjector].filter(Boolean).map((p) => (
+ <span key={p}>{p}</span>
+ ))}
+ </details>
+ </div>
+ <div style={{ display: "flex", flexDirection: "column", gap: 6 }}>
+ {ms && !ms.official_installed && (
+ <button
+ className="btn primary"
+ onClick={() => {
+ if (dirty && !window.confirm("Discard the unsaved changes and open the model setup?")) return;
+ openModelSetup("official");
+ }}
+ >
+ <Download size={15} /> Download…
+ </button>
+ )}
+ <button
+ className="btn"
+ onClick={() => {
+ if (dirty && !window.confirm("Discard the unsaved changes and choose your own model files?")) return;
+ openModelSetup("own");
+ }}
+ >
+ <FolderOpen size={15} /> Use my own files…
+ </button>
+ </div>
+ </div>
+ ) : (
+ <>
+ <span className="muted">Your own files: not tested by Kokon. Set up models… checks them and finds them again if they move.</span>
+ <PathField label="Diffusion model" value={profile.diffusionModel} onChange={(v) => setProfile({ diffusionModel: v })} />
+ <PathField label="VAE" value={profile.vae} onChange={(v) => setProfile({ vae: v })} />
+ <PathField label="Text encoder (Qwen3-VL)" value={profile.textEncoder} onChange={(v) => setProfile({ textEncoder: v })} />
+ <PathField label="Vision projector (mmproj)" value={profile.visionProjector ?? ""} onChange={(v) => setProfile({ visionProjector: v || null })} />
+ </>
+ )}
<UpscalerControls
model={cfg.upscalerModel}
blend={cfg.upscaleBlend}
diff --git a/src/components/Setup.tsx b/src/components/Setup.tsx
index 3367302..32ea913 100644
--- a/src/components/Setup.tsx
+++ b/src/components/Setup.tsx
@@ -1,10 +1,11 @@
-import { Bug, Check, ChevronDown, CircleAlert, Download, ExternalLink, FolderOpen, Loader2, Pause, Play, RefreshCw, Settings2 } from "lucide-react";
+import { ArrowLeft, ArrowLeftRight, Bug, Check, ChevronDown, CircleAlert, Download, ExternalLink, FileSearch, FolderOpen, Loader2, Pause, Play, RefreshCw, Settings2 } from "lucide-react";
import { useEffect, useRef, useState } from "react";
import { api } from "../lib/api";
import { formatBytes, installItemShort, installProgress, installStep, installTimeLeft } from "../lib/logic";
import { native } from "../lib/native";
-import { refreshStatus, setState, toastError, useStore } from "../lib/store";
-import type { GpuBackend, HardwareReport, InstallItem, InstallStatus, SetupReport } from "../lib/types";
+import { refreshStatus, setState, toastError, toastInfo, useStore } from "../lib/store";
+import type { GpuBackend, HardwareReport, InstallItem, InstallStatus, ModelScan, ModelSlot, ModelsStatus, SetupReport } from "../lib/types";
+import { OwnModels } from "./OwnModels";
import { Seg } from "./ui";
import { ReadyTips, Showcase } from "./Welcome";
@@ -77,8 +78,59 @@ function FileList({ items }: { items: InstallItem[] }) {
);
}
+/** Another way out of missing files: what it does, in one line. */
+interface RepairOption {
+ icon: React.ReactNode;
+ title: string;
+ detail: string;
+ run: () => void;
+}
+
+/** A model file is missing (drive not connected, moved, deleted): which, the one action that
+ * fixes most cases (look again, also in the folder the files were found in), and the other
+ * ways out, each saying what it does. */
+function Repair(props: { models: ModelsStatus; busy: string | null; note: string | null; onLookAgain: () => void; options: RepairOption[] }) {
+ const { models } = props;
+ const n = models.missing.length;
+ return (
+ <div className="setup-note setup-repair">
+ <strong>{n === 1 ? "Kokon can't find a model file" : `Kokon can't find ${n} model files`}</strong>
+ {models.missing.map((m) => (
+ <div className="missing" key={m.path}>
+ {m.label}: {m.path}
+ </div>
+ ))}
+ <span>
+ If they are on a drive that is not connected, connect it first.
+ {models.scan_dir ? ` Kokon checks again and also looks for them in ${models.scan_dir}, in case they were moved.` : ""}
+ </span>
+ <div className="actions">
+ <button className="btn primary" onClick={props.onLookAgain} disabled={!!props.busy}>
+ {props.busy ? <Loader2 className="spin" size={14} /> : <RefreshCw size={14} />} {props.busy ?? "Look for them again"}
+ </button>
+ {props.note && !props.busy && <span className="repair-result">{props.note}</span>}
+ </div>
+ {props.options.length > 0 && (
+ <div className="repair-options">
+ <span className="muted">Or:</span>
+ {props.options.map((o) => (
+ <button key={o.title} className="repair-option" onClick={o.run} disabled={!!props.busy}>
+ {o.icon}
+ <span>
+ <strong>{o.title}</strong>
+ <span className="muted">{o.detail}</span>
+ </span>
+ </button>
+ ))}
+ </div>
+ )}
+ </div>
+ );
+}
+
/** First launch (and Settings → Models → Set up models): detect the GPU, pick a preset,
- * download stable-diffusion.cpp and the official Qwen-Image 2.1 weights, then start. */
+ * download stable-diffusion.cpp and the official Qwen-Image 2.1 weights, then start. Or use
+ * the Qwen-Image 2.1 files the user already has (#14), downloading only the engine. */
export function Setup() {
const [hw, setHw] = useState<HardwareReport | null>(null);
const [report, setReport] = useState<SetupReport | null>(null);
@@ -89,6 +141,11 @@ export function Setup() {
const [card, setCard] = useState<number | null>(null);
const [showFiles, setShowFiles] = useState(false);
const [checking, setChecking] = useState(false);
+ const [models, setModels] = useState<ModelsStatus | null>(null);
+ // Official files, or files the user already has.
+ const requestedMode = useStore((s) => s.setupMode);
+ const [mode, setMode] = useState<"official" | "own" | null>(requestedMode);
+ const [scan, setScan] = useState<ModelScan | null>(null);
const wasRunning = useRef(false);
const setupDone = useStore((s) => s.status?.setup_complete ?? false);
const engineUpdate = useStore((s) => s.status?.engine);
@@ -96,12 +153,15 @@ export function Setup() {
const refresh = async (engine: GpuBackend | null = backend, gpu: number | null = card) => {
setChecking(true);
try {
- const [h, r, i] = await Promise.all([api.hardware(engine ?? undefined, gpu ?? undefined), api.setup(), api.installStatus()]);
+ const [h, r, i, m] = await Promise.all([api.hardware(engine ?? undefined, gpu ?? undefined), api.setup(), api.installStatus(), api.models()]);
setHw(h);
+ setModels(m);
+ setMode((x) => x ?? (h.active_source === "user" ? "own" : "official"));
setBackend(h.backend);
setReport(r);
setInst(i);
- setPreset((p) => p ?? (i.running && i.preset ? i.preset : h.recommended));
+ // A running install of the user's own files is labelled "user:<preset>".
+ setPreset((p) => p ?? (i.running && i.preset ? i.preset.replace(/^user:/, "") : h.recommended));
} catch (e) {
toastError(e);
} finally {
@@ -141,12 +201,111 @@ export function Setup() {
const install = async () => {
if (!preset) return;
try {
- setInst(await api.install(preset, backend ?? hw?.backend ?? "cuda", true, card ?? undefined));
+ setInst(await api.install(preset, backend ?? hw?.backend ?? "cuda", true, card ?? undefined, mode === "own" ? "user" : "official"));
+ } catch (e) {
+ toastError(e);
+ }
+ };
+
+ // The missing-files card: what it is doing now, and what its last search found.
+ const [repairBusy, setRepairBusy] = useState<string | null>(null);
+ const [repairNote, setRepairNote] = useState<string | null>(null);
+
+ /** Missing files of `m` found under the same name in `dir` (moved there): when all are
+ * found they are used right away. */
+ const relocate = async (m: ModelsStatus, dir: string) => {
+ const sc = await api.scanModels(dir);
+ const missing = m.slots.filter((x) => !x.exists && x.role);
+ const found = missing.filter((x) => sc.moved[x.role!]);
+ const all = missing.length > 0 && found.length === missing.length;
+ if (all) {
+ const slot = (role: string): ModelSlot | null => {
+ const x = m.slots.find((y) => y.role === role);
+ return x ? { path: sc.moved[x.role!] ?? x.path } : null;
+ };
+ setModels(await api.setUserModels({ diffusion_model: slot("diffusion")!, vae: slot("vae")!, text_encoder: slot("text_encoder")!, vision_projector: slot("vision_projector"), scan_dir: dir }));
+ setScan(null);
+ toastInfo(found.length === 1 ? `Found the missing file in ${dir}. It is used from there now.` : `Found the ${found.length} missing files in ${dir}. They are used from there now.`);
+ await refresh();
+ }
+ return { all, found: found.length, missing: missing.length, scan: sc };
+ };
+
+ // Check the same paths again (a drive connected again), then the folder the files were
+ // found in (files moved inside it).
+ const lookAgain = async () => {
+ setRepairNote(null);
+ setRepairBusy("Checking the files…");
+ try {
+ const m = await api.models();
+ setModels(m);
+ if (m.missing.length === 0) {
+ toastInfo("All model files are there again.");
+ await refresh();
+ return;
+ }
+ if (m.scan_dir) {
+ setRepairBusy(`Looking in ${m.scan_dir}…`);
+ const r = await relocate(m, m.scan_dir);
+ if (r.all) return;
+ setRepairNote(r.found ? `Found ${r.found} of ${r.missing} in ${m.scan_dir}. Choose one of the options below for the others.` : "Still not found. If they are on a drive, connect it and try again, or choose one of the options below.");
+ return;
+ }
+ setRepairNote("Still not found. If they are on a drive, connect it and try again, or choose one of the options below.");
+ } catch (e) {
+ toastError(e);
+ } finally {
+ setRepairBusy(null);
+ }
+ };
+
+ // Files moved to another folder: look for them there; otherwise choose them by hand.
+ const searchElsewhere = async () => {
+ const d = await native.pickFolder(models?.scan_dir ?? models?.user_scan_dir ?? undefined);
+ if (!d || !models) return;
+ setRepairNote(null);
+ setRepairBusy(`Looking in ${d}…`);
+ try {
+ const r = await relocate(models, d);
+ if (!r.all) {
+ setRepairNote(r.found ? `Found ${r.found} of ${r.missing} in that folder: choose the others in "Your files" below.` : `They are not in ${d}. Choose the files in "Your files" below.`);
+ setScan(r.scan);
+ showOwn();
+ }
} catch (e) {
toastError(e);
+ } finally {
+ setRepairBusy(null);
}
};
+ // "Use models I already have", scrolled into view (it sits below the missing-files card).
+ const showOwn = () => {
+ setMode("own");
+ window.setTimeout(() => document.getElementById("own-models")?.scrollIntoView({ behavior: "smooth", block: "start" }), 50);
+ };
+
+ const download = (target: "official" | "user") => {
+ if (!preset) return;
+ setMode(target === "official" ? "official" : "own");
+ api.install(preset, backend ?? hw?.backend ?? "cuda", true, undefined, target).then(setInst, toastError);
+ };
+
+ const switchTo = async (profile: "official" | "user") => {
+ setRepairBusy(profile === "user" ? "Switching to your files…" : "Switching to the official model…");
+ try {
+ setModels(await api.useModels(profile));
+ setMode(profile === "user" ? "own" : "official");
+ await refresh();
+ } catch (e) {
+ toastError(e);
+ } finally {
+ setRepairBusy(null);
+ }
+ };
+
+ const back = () => setState({ needsSetup: false, setupMode: null });
+
const start = async () => {
try {
if (hw && card !== null && card !== hw.gpu_in_use) await api.setGpu(card);
@@ -155,7 +314,7 @@ export function Setup() {
const ui = { ...((cfg.ui ?? {}) as Record<string, unknown>) };
if (st?.engine?.update_needed) ui.engineUpdateSkipped = st.engine.release;
await api.saveConfig({ ...cfg, setupComplete: true, ui });
- setState({ needsSetup: false });
+ setState({ needsSetup: false, setupMode: null });
// Load the model in the background; the status indicator shows progress.
api.startBackend().then(refreshStatus, toastError);
refreshStatus();
@@ -166,16 +325,47 @@ export function Setup() {
const chosen = hw?.presets.find((p) => p.id === preset) ?? null;
const running = inst?.running ?? false;
+ const own = mode === "own";
+ // Own files: what their profile needs, once saved and active (until then nothing to install).
+ const ownActive = own && hw?.active_source === "user" && !!hw.user_files;
// While (or after) installing this preset, show the live list; otherwise what is on disk.
- const live = !!inst && inst.preset === preset && inst.items.length > 0 && (running || inst.items.some((i) => i.state !== "pending" && i.state !== "present"));
- const items = live ? inst!.items : chosen?.files ?? [];
+ const installKey = own ? `user:${preset}` : preset;
+ const live = !!inst && inst.preset === installKey && inst.items.length > 0 && (running || inst.items.some((i) => i.state !== "pending" && i.state !== "present"));
+ const items = live ? inst!.items : own ? (ownActive ? hw!.user_files!.files : []) : chosen?.files ?? [];
const missing = items.filter((i) => i.state !== "present" && i.state !== "done");
const failed = items.filter((i) => i.state === "failed");
const paused = !running && items.some((i) => i.state === "cancelled" || (i.state === "pending" && i.received > 0));
const toDownload = missing.reduce((a, i) => a + Math.max(0, i.size - i.received), 0);
const prog = installProgress(items);
- const lowSpace = hw?.free_bytes != null && chosen != null && hw.free_bytes < chosen.disk_bytes;
- const presetInstalled = missing.length === 0;
+ // Size of the official model files (for the choice between downloading and own files).
+ const modelBytes = (chosen?.files ?? []).filter((f) => f.kind === "model").reduce((a, f) => a + f.size, 0);
+ const diskNeeded = own ? hw?.user_files?.disk_bytes ?? 0 : chosen?.disk_bytes ?? 0;
+ const lowSpace = hw?.free_bytes != null && chosen != null && hw.free_bytes < diskNeeded;
+ // Own files not chosen yet: nothing to install, nothing ready.
+ const presetInstalled = missing.length === 0 && (!own || ownActive);
+ const repair = setupDone && !!models && models.missing.length > 0 && !running;
+ // The other ways out of missing files, each saying what it does.
+ const repairOptions: RepairOption[] = [];
+ if (models) {
+ const userActive = models.active.source === "user";
+ repairOptions.push({ icon: <FolderOpen size={16} />, title: "Find them in another folder", detail: "If you moved your models: Kokon looks for the same files there.", run: searchElsewhere });
+ repairOptions.push({ icon: <FileSearch size={16} />, title: "Choose other files", detail: "Pick the files yourself, below.", run: showOwn });
+ if (userActive && models.downloadable.length > 0) {
+ repairOptions.push({ icon: <Download size={16} />, title: "Download the missing files", detail: `The official ${models.downloadable.join(", ")}, saved where the missing file was.`, run: () => download("user") });
+ }
+ if (userActive) {
+ repairOptions.push(
+ models.official_installed
+ ? { icon: <ArrowLeftRight size={16} />, title: "Use the official model", detail: "Already downloaded: switch to it. Your files stay set up.", run: () => switchTo("official") }
+ : { icon: <Download size={16} />, title: "Download the official model", detail: `${formatBytes(modelBytes)}, tested with Kokon, into ${hw?.sdcpp_dir ?? "the install folder"}.`, run: () => download("official") },
+ );
+ } else {
+ repairOptions.push({ icon: <Download size={16} />, title: "Download the official model", detail: `${formatBytes(modelBytes)}, into ${hw?.sdcpp_dir ?? "the install folder"}.`, run: () => download("official") });
+ if (models.user_installed) {
+ repairOptions.push({ icon: <ArrowLeftRight size={16} />, title: "Use your own files again", detail: models.user_scan_dir ? `The ones in ${models.user_scan_dir}.` : "The files you chose before.", run: () => switchTo("user") });
+ }
+ }
+ }
const ready = !!report?.ready && !running;
const rate = inst?.bytes_per_sec ?? 0;
const vram = hw?.vram_mib ?? null;
@@ -187,11 +377,16 @@ export function Setup() {
<div>
<h1>{setupDone ? "Models" : "Welcome to Kokon"}</h1>
<p className="setup-lead">
- Everything runs on this PC. Setup downloads the image model once ({chosen ? formatBytes(chosen.files.reduce((a, f) => a + f.size, 0)) : "about 12 GB"}); after that, nothing
- leaves your computer.
+ {own
+ ? "Everything runs on this PC. Use the Qwen-Image 2.1 files you already have, for example from ComfyUI: Setup only downloads the engine and what you don't have."
+ : `Everything runs on this PC. Setup downloads the image model once (${chosen ? formatBytes(chosen.files.reduce((a, f) => a + f.size, 0)) : "about 12 GB"}); after that, nothing leaves your computer.`}
</p>
</div>
+ {repair && (
+ <Repair models={models!} busy={repairBusy} note={repairNote} onLookAgain={lookAgain} options={repairOptions} />
+ )}
+
{setupDone && engineUpdate?.update_needed && engineMissing.length > 0 && !running && (
<div className="setup-note">
This version of Kokon enlarges images with Superscale-SP by default, adds an upscaler strength slider and the experimental MoSR model. It needs the updated engine:
@@ -243,6 +438,43 @@ export function Setup() {
</div>
) : (
<>
+ {/* Where the model comes from: the first choice, so it is seen first. */}
+ <div className="field">
+ <span>Image model</span>
+ <div className="choice-cards" role="radiogroup">
+ <button className={`choice-card ${!own ? "on" : ""}`} role="radio" aria-checked={!own} onClick={() => setMode("official")}>
+ <Download size={20} />
+ <div>
+ <strong>Download the model</strong>
+ <span>Qwen-Image 2.1 Turbo, tested with Kokon{modelBytes ? ` · ${formatBytes(modelBytes)}` : ""}</span>
+ </div>
+ </button>
+ <button className={`choice-card ${own ? "on" : ""}`} role="radio" aria-checked={own} onClick={() => setMode("own")}>
+ <FolderOpen size={20} />
+ <div>
+ <strong>Use models I already have</strong>
+ <span>From ComfyUI or another folder; only the engine is downloaded</span>
+ </div>
+ </button>
+ </div>
+ </div>
+ {own && models && (
+ <div id="own-models">
+ <OwnModels
+ // A new set of files (saved, found again): start from it, not from the old choices.
+ key={models.active.id + models.slots.map((x) => `${x.path}:${x.exists}`).join("|")}
+ models={models}
+ officialFiles={(chosen?.files ?? []).filter((f) => f.kind === "model")}
+ vramMib={vram}
+ initialScan={scan}
+ onSaved={async (m) => {
+ setModels(m);
+ setScan(null);
+ await refresh();
+ }}
+ />
+ </div>
+ )}
{hw.gpus.length > 1 && (
<label className="field">
<span>Graphics card</span>
@@ -283,7 +515,8 @@ export function Setup() {
<div className="field">
<span>{hw.gpu?.unified ? "Preset for your Mac's memory" : "Preset for your graphics card"}</span>
<Seg<string> value={preset ?? hw.recommended} options={hw.presets.map((p) => ({ value: p.id, label: p.label }))} onChange={setPreset} />
- {chosen && (
+ {chosen && own && <span className="muted">How Kokon runs the model on your card: memory use and image sizes. Your files are kept.</span>}
+ {chosen && !own && (
<span className="muted">
{chosen.summary}.{chosen.id === hw.recommended ? " Recommended for your GPU." : ""}
{hw.gpu?.unified ? " Not yet tested on a Mac." : chosen.verified ? "" : " Not yet tested on a real card of this size."}
@@ -353,44 +586,64 @@ export function Setup() {
</div>
)}
- {presetInstalled && !running && (
+ {checking && !running ? (
+ // Checking the files and the engine takes a few seconds: say so.
<div className="setup-card setup-ready">
- <Check size={18} />
- <span>{hw.current === chosen?.id || !chosen ? "Everything is installed." : `The ${chosen.label} files are already here.`}</span>
+ <Loader2 className="spin" size={18} />
+ <span>Checking the model files and the engine…</span>
</div>
+ ) : (
+ presetInstalled &&
+ !running && (
+ <div className="setup-card setup-ready">
+ <Check size={18} />
+ <span>{hw.current === chosen?.id || !chosen ? "Everything is installed." : `The ${chosen.label} files are already here.`}</span>
+ </div>
+ )
)}
{presetInstalled && !running && !setupDone && <ReadyTips />}
{(running || paused) && <Showcase />}
- {/* What gets installed. */}
- <div className="field">
- <button className="setup-toggle" onClick={() => setShowFiles((v) => !v)} aria-expanded={showFiles || running}>
- <ChevronDown size={14} style={{ transform: showFiles || running ? "none" : "rotate(-90deg)", transition: "transform 0.15s" }} />
- {items.length} files · {missing.length ? `${formatBytes(toDownload)} to download` : "all installed"}
- </button>
- {(showFiles || running) && <FileList items={items} />}
- </div>
+ {/* What gets installed (nothing to list while own files are being chosen). */}
+ {items.length > 0 && (
+ <div className="field">
+ <button className="setup-toggle" onClick={() => setShowFiles((v) => !v)} aria-expanded={showFiles || running}>
+ <ChevronDown size={14} style={{ transform: showFiles || running ? "none" : "rotate(-90deg)", transition: "transform 0.15s" }} />
+ {items.length} files · {missing.length ? `${formatBytes(toDownload)} to download` : "all installed"}
+ </button>
+ {(showFiles || running) && <FileList items={items} />}
+ </div>
+ )}
</>
)}
<div className="setup-actions">
- {hw && !running && !paused && !presetInstalled && (
+ {hw && !running && !paused && !presetInstalled && (!own || ownActive) && (
<button className="btn primary big" disabled={!chosen || lowSpace} onClick={install}>
<Download size={16} /> {failed.length ? "Try again" : `Install · ${formatBytes(toDownload)}`}
</button>
)}
- {hw && presetInstalled && !running && chosen && (hw.current !== chosen.id || hw.current_backend !== hw.backend) && (
+ {hw && presetInstalled && !running && chosen && (hw.current !== chosen.id || hw.current_backend !== hw.backend || (!own && hw.active_source === "user")) && (
// Files of another preset or engine are already here: switch without downloading.
<button className="btn" onClick={install}>
- {hw.current_backend !== hw.backend ? `Use ${{ cuda: "CUDA", vulkan: "Vulkan", metal: "Metal" }[hw.backend]} with the ${chosen.label} preset` : `Use the ${chosen.label} preset`}
+ {!own && hw.active_source === "user"
+ ? "Use the official files"
+ : hw.current_backend !== hw.backend
+ ? `Use ${{ cuda: "CUDA", vulkan: "Vulkan", metal: "Metal" }[hw.backend]} with the ${chosen.label} preset`
+ : `Use the ${chosen.label} preset`}
</button>
)}
{(ready || presetInstalled) && !running && (
- <button className={`btn big ${presetInstalled ? "primary" : ""}`} disabled={!ready} onClick={start}>
+ <button className={`btn big ${presetInstalled ? "primary" : ""}`} disabled={!ready || checking} onClick={start}>
{setupDone ? "Done" : "Start"}
</button>
)}
<span style={{ flex: 1 }} />
+ {setupDone && (
+ <button className="btn ghost" onClick={back} disabled={running}>
+ <ArrowLeft size={14} /> Back
+ </button>
+ )}
<button className="btn ghost" onClick={() => setState({ overlay: "settings" })} disabled={running}>
<Settings2 size={14} /> Settings
</button>
@@ -399,8 +652,11 @@ export function Setup() {
</button>
</div>
- {report && !report.ready && !running && !paused && missing.length === 0 && (
+ {/* Files installed but something else stops the start (e.g. the GPU is not found). Not
+ while own files are still being chosen, and not twice with the missing-files card. */}
+ {report && !report.ready && !running && !paused && presetInstalled && !repair && !checking && (
<div className="setup-note">
+ <div style={{ marginBottom: 6 }}>Kokon can't start yet:</div>
{report.checks
.filter((c) => !c.ok)
.map((c, i) => (
diff --git a/src/components/WhatsNew.tsx b/src/components/WhatsNew.tsx
index 34e5916..e96065f 100644
--- a/src/components/WhatsNew.tsx
+++ b/src/components/WhatsNew.tsx
@@ -73,7 +73,9 @@ export function WhatsNew() {
api.hardware().then((h) => {
const preset = h.presets.find((p) => p.id === h.current) ?? h.presets.find((p) => p.id === h.recommended);
setTarget(preset ? { preset: preset.id, backend: h.backend } : null);
- setMissing((preset?.files ?? []).filter((f) => f.state !== "present"));
+ // With the user's own model files, the update downloads the engine, not official models.
+ const files = h.active_source === "user" ? h.user_files?.files ?? [] : preset?.files ?? [];
+ setMissing(files.filter((f) => f.state !== "present"));
}, toastError);
api.installStatus().then((i) => i.running && setInst(i), () => {});
}, [needsEngine]);
diff --git a/src/lib/api.ts b/src/lib/api.ts
index a1d82f9..a85eb3d 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -3,8 +3,8 @@
import type {
GpuBackend,
- AppConfig, AppErrorBody, GenerationRecord, GenerationRequest, HardwareReport, InputRecord, InstallStatus, JobView, Plan, ServiceEvent, SetupReport, StatusResponse,
- UpscalerItem,
+ AppConfig, AppErrorBody, GenerationRecord, GenerationRequest, HardwareReport, InputRecord, InstallStatus, JobView, ModelFileInfo, ModelScan, ModelSlot, ModelsStatus, Plan,
+ ServiceEvent, SetupReport, StatusResponse, UpscalerItem,
} from "./types";
export class ApiError extends Error {
@@ -64,7 +64,17 @@ export const api = {
},
/** `apply = false`: only download (an engine update), keeping the configured preset and settings.
* `gpu`: card to run on once installed (index in `hardware().gpus`). */
- install: (preset: string, backend: GpuBackend, apply = true, gpu?: number) => call<InstallStatus>("/setup/install", { method: "POST", body: json({ preset, backend, apply, gpu }) }),
+ install: (preset: string, backend: GpuBackend, apply = true, gpu?: number, target?: "official" | "user") =>
+ call<InstallStatus>("/setup/install", { method: "POST", body: json({ preset, backend, apply, gpu, target }) }),
+ /** The active model's files and what is missing. */
+ models: () => call<ModelsStatus>("/models"),
+ /** Model files in a folder (sub-folders included), with a suggested file per role. */
+ scanModels: (dir: string) => call<ModelScan>("/models/scan", { method: "POST", body: json({ dir }) }),
+ inspectModel: (path: string) => call<ModelFileInfo>("/models/inspect", { method: "POST", body: json({ path }) }),
+ /** Saves the user's own files (checked) as the active model; `vision_projector` null = not needed. */
+ setUserModels: (b: { diffusion_model: ModelSlot; vae: ModelSlot; text_encoder: ModelSlot; vision_projector: ModelSlot | null; scan_dir: string | null }) =>
+ call<ModelsStatus>("/models/user", { method: "POST", body: json(b) }),
+ useModels: (profile: "official" | "user") => call<ModelsStatus>("/models/use", { method: "POST", body: json({ profile }) }),
/** Runs the engine on another card (index in `hardware().gpus`); needs the engine installed. */
setGpu: (gpu: number) => call<{ saved: boolean }>("/setup/gpu", { method: "POST", body: json({ gpu }) }),
upscalers: () => call<{ selected: string; active: string | null; items: UpscalerItem[] }>("/upscalers"),
diff --git a/src/lib/store.ts b/src/lib/store.ts
index b1ba176..9a2a00c 100644
--- a/src/lib/store.ts
+++ b/src/lib/store.ts
@@ -73,6 +73,8 @@ export interface State {
toasts: Toast[];
galleryVersion: number;
needsSetup: boolean;
+ /** Setup opens on "Use models I already have" or on the official download (Settings → Models). */
+ setupMode: "own" | "official" | null;
/** Before/after view for results made from another image; kept while switching results. */
compare: CompareMode;
/** Flicker period in ms. */
@@ -281,6 +283,7 @@ let state: State = {
toasts: [],
galleryVersion: 0,
needsSetup: false,
+ setupMode: null,
compare: "off",
flickerMs: 500,
privateMode: false,
@@ -333,6 +336,14 @@ export function toastError(e: unknown) {
pushToast({ id: newKey(), message: body.message, suggestion: body.suggestion, detail: body.detail, kind: "error" });
}
+/** Opens Setup (also over a finished setup): to fix missing model files, or to choose own files. */
+export function openModelSetup(mode: "own" | "official" | null = null) {
+ setState({ overlay: null, needsSetup: true, setupMode: mode });
+}
+
+/** The engine or a model file is missing (drive not connected, moved, deleted). */
+export const isMissingModel = (e: unknown) => (e instanceof ApiError ? e.body.code : (e as AppErrorBody | null)?.code) === "missing_model";
+
export function toastInfo(message: string) {
pushToast({ id: newKey(), message, kind: "info" });
}
@@ -382,6 +393,12 @@ export function startEvents() {
}
function onJob(job: JobView) {
+ // A model file went missing between submitting and starting: Setup shows what and how to fix
+ // it (only for a job that just failed, not old ones listed again after reconnecting).
+ const prev = getState().jobs[job.id];
+ if (job.status === "failed" && prev?.status !== "failed" && isMissingModel(job.error) && job.finished_at && Date.now() - Date.parse(job.finished_at) < 60_000) {
+ openModelSetup();
+ }
setState((s) => {
const jobs = { ...s.jobs, [job.id]: job };
if (job.status !== "done") return { jobs };
@@ -753,6 +770,8 @@ export async function submitRequest(req: GenerationRequest) {
setState((s) => ({ jobs: { ...s.jobs, [job.id]: job }, session: [...s.session, item], selected: item.key, redo: [] }));
return true;
} catch (e) {
+ // The prompt and images stay in the composer: once the files are back, Generate again.
+ if (isMissingModel(e)) openModelSetup();
toastError(e);
return false;
}
diff --git a/src/lib/types.ts b/src/lib/types.ts
index 096d43d..319733f 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -182,7 +182,7 @@ export type ServerState = "stopped" | "starting" | "ready" | "error";
export interface StatusResponse {
service: { version: string; pid: number; uptime_s: number };
server: { state: ServerState; owned: boolean; pid: number | null; port: number; model: string | null; model_loaded: boolean; error: AppErrorBody | null };
- profile: { id: string; display_name: string };
+ profile: { id: string; display_name: string; source: ProfileSource };
gpu: { name: string; vendor: string; unified: boolean; memory_total_mib: number; memory_used_mib: number; memory_free_mib: number; driver_version: string } | null;
active_job: JobView | null;
queue: { queued: number; jobs: JobView[] };
@@ -197,9 +197,17 @@ export interface SetupReport { ready: boolean; checks: Check[]; devices: [string
export type TextEncoderPlacement = "ram" | "gpu" | "cpu" | "auto" | "disk";
+/** Official: files Setup downloaded and Kokon tested. User: files the user already had. */
+export type ProfileSource = "official" | "user";
+
export interface ModelProfile {
id: string;
displayName: string;
+ /** The model the files are ("qwen-image-2.1"). */
+ model: string;
+ source: ProfileSource;
+ /** Folder the user's files were found in. */
+ scanDir: string | null;
diffusionModel: string;
vae: string;
textEncoder: string;
@@ -287,7 +295,58 @@ export interface HardwarePreset {
disk_bytes: number;
}
+export type ModelRole = "diffusion" | "vae" | "text_encoder" | "vision_projector";
+
+/** What a model file is (read from its header). */
+export interface ModelFileInfo {
+ path: string;
+ size: number;
+ role: ModelRole | null;
+ /** Usable with Qwen-Image 2.1 in this role. */
+ compatible: boolean;
+ /** A text encoder with the vision weights (no projector needed). */
+ has_vision: boolean;
+ /** Main weight type, e.g. "Q4_K", "BF16", "INT8". */
+ weights: string;
+ official: boolean;
+ problem: string | null;
+}
+
+export interface ModelScan {
+ dir: string;
+ files: ModelFileInfo[];
+ picks: Record<"diffusion" | "vae" | "text_encoder" | "vision_projector", string | null>;
+ /** Missing files of the active profile found under the same name (moved). */
+ moved: Partial<Record<ModelRole, string>>;
+}
+
+/** A file the user chose, or an official file to download into a folder. */
+export type ModelSlot = { path: string } | { download: string };
+
+/** The active model's files and what is missing (`GET /models`). */
+export interface ModelsStatus {
+ active: { id: string; display_name: string; source: ProfileSource; model: string };
+ slots: { role: ModelRole | null; label: string; path: string; exists: boolean; info: ModelFileInfo | null }[];
+ missing: { label: string; path: string }[];
+ /** Missing files Setup can download (official ones). */
+ downloadable: string[];
+ engine_installed: boolean;
+ /** Folder the active files were found in (none for the official files). */
+ scan_dir: string | null;
+ /** Folder of the user's own files. */
+ user_scan_dir: string | null;
+ has_user_profile: boolean;
+ /** Every file of the user's own profile is there. */
+ user_installed: boolean;
+ official_installed: boolean;
+ default_download_dir: string;
+}
+
export interface HardwareReport {
+ /** Source of the active profile. */
+ active_source: ProfileSource;
+ /** What the user's own-files profile still needs (engine, upscalers, official pieces). */
+ user_files: { files: InstallItem[]; download_bytes: number; disk_bytes: number } | null;
/** The card the presets are sized for (`gpu_index` in `gpus`). */
gpu: StatusResponse["gpu"];
gpus: { name: string; memory_total_mib: number }[];
diff --git a/src/styles.css b/src/styles.css
index 8156b82..88adf16 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -614,3 +614,62 @@ kbd { min-width: 22px; height: 22px; padding: 0 6px; border-radius: 6px; display
.tips-check svg { color: var(--good); flex: none; }
.tips-more { align-self: center; flex: none; margin-top: 2px; }
@media (max-width: 640px) { .tips-check { grid-template-columns: 1fr; } }
+/* Setup: where the model comes from (two cards), and the user's own files (#14) */
+.choice-cards { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+.choice-card { display: flex; gap: 12px; align-items: flex-start; text-align: left; padding: 14px 16px; border: 1px solid var(--border); border-radius: 12px; background: transparent; color: var(--text-2); cursor: pointer; font: inherit; }
+.choice-card:hover { background: var(--surface); }
+.choice-card.on { border-color: var(--text-2); background: var(--surface); color: var(--text); }
+.choice-card svg { flex: none; margin-top: 2px; }
+.choice-card strong { display: block; font-size: 14px; color: var(--text); margin-bottom: 3px; }
+.choice-card span { font-size: 12px; line-height: 1.4; }
+.own-start { display: flex; flex-direction: column; align-items: center; text-align: center; gap: 10px; padding: 26px 24px 20px; border: 1px dashed var(--border); border-radius: 12px; color: var(--text-2); }
+.own-start strong { font-size: 15px; color: var(--text); }
+.own-start .muted { max-width: 440px; line-height: 1.45; }
+.own-start .btn { margin-top: 6px; }
+.link-btn { background: none; border: 0; padding: 0; font: inherit; font-size: 12px; color: var(--text-2); text-decoration: underline; text-underline-offset: 2px; cursor: pointer; }
+.link-btn:hover { color: var(--text); }
+.own-models { display: flex; flex-direction: column; gap: 12px; }
+.own-head { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.own-head > div { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.own-head strong { font-size: 14px; }
+.own-head .muted { font-size: 12px; }
+.own-head .btn { flex: none; }
+.own-list { display: flex; flex-direction: column; border: 1px solid var(--border); border-radius: 12px; overflow: hidden; }
+.own-row { border-top: 1px solid var(--border); }
+.own-row:first-child { border-top: 0; }
+.own-row-main { display: grid; grid-template-columns: 16px 1fr auto; gap: 12px; align-items: center; padding: 10px 14px; }
+.own-row-main > svg { color: var(--text-2); }
+.own-row.bad .own-row-main > svg, .own-row.bad .own-row-value { color: var(--text); font-weight: 600; }
+.own-row-text { display: flex; flex-direction: column; gap: 1px; min-width: 0; }
+.own-row-label { font-size: 12px; color: var(--text-2); }
+.own-row-value { font-size: 13px; overflow-wrap: anywhere; }
+.own-row-path { font-size: 11px; color: var(--text-3); overflow-wrap: anywhere; }
+.btn.small { height: 28px; padding: 0 10px; font-size: 12px; border-radius: 8px; }
+.own-options { display: flex; flex-direction: column; gap: 2px; padding: 0 10px 10px 42px; }
+.own-option { display: flex; justify-content: space-between; align-items: center; gap: 12px; padding: 7px 10px; border-radius: 8px; background: transparent; border: 1px solid transparent; font: inherit; font-size: 13px; color: var(--text); text-align: left; cursor: pointer; }
+.own-option > span:first-child { display: inline-flex; align-items: center; gap: 6px; overflow-wrap: anywhere; }
+.own-option .muted { font-size: 12px; flex: none; }
+.own-option:hover { background: var(--surface); }
+.own-option.on { border-color: var(--border); background: var(--surface); }
+.own-download { display: flex; gap: 10px; align-items: baseline; flex-wrap: wrap; font-size: 12px; }
+.own-download strong { font-weight: 500; color: var(--text); overflow-wrap: anywhere; }
+.own-actions { display: flex; gap: 10px; align-items: center; flex-wrap: wrap; }
+.own-actions .muted { font-size: 12px; }
+@media (max-width: 560px) { .choice-cards { grid-template-columns: 1fr; } }
+.setup-repair { display: flex; flex-direction: column; gap: 8px; }
+.setup-repair strong { color: var(--text); font-size: 14px; }
+.setup-repair .missing { font-size: 12px; word-break: break-word; }
+.setup-repair .actions { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 4px; }
+.setup-repair .actions { align-items: center; }
+.repair-result { font-size: 12px; color: var(--text); }
+.repair-options { display: flex; flex-direction: column; gap: 4px; margin-top: 6px; }
+.repair-options > .muted { font-size: 12px; margin-bottom: 2px; }
+.repair-option { display: flex; gap: 12px; align-items: flex-start; text-align: left; padding: 9px 12px; border: 1px solid var(--border); border-radius: 10px; background: transparent; font: inherit; color: var(--text); cursor: pointer; }
+.repair-option:hover:not(:disabled) { background: var(--surface); }
+.repair-option:disabled { opacity: 0.5; cursor: default; }
+.repair-option > svg { flex: none; margin-top: 2px; color: var(--text-2); }
+.repair-option > span { display: flex; flex-direction: column; gap: 1px; min-width: 0; }
+.repair-option strong { font-size: 13px; font-weight: 600; }
+.repair-option .muted { font-size: 12px; overflow-wrap: anywhere; }
+.model-files summary { cursor: pointer; font-size: 12px; color: var(--text-2); margin-top: 4px; }
+.model-files span { display: block; font-size: 11px; color: var(--text-3); overflow-wrap: anywhere; }