From d2fdd77d869bf3a57cc2706b169a86041d4c6c3e Mon Sep 17 00:00:00 2001 From: wochenlong <117965575+wochenlong@users.noreply.github.com> Date: Wed, 18 Nov 2026 16:50:11 +0800 Subject: [PATCH 1/3] fix(kohya): content-based runtime fingerprint and recovery (#520) --- mikazuki/engines/kohya/extension_state.py | 84 ++++++++++++++++++++--- mikazuki/engines/kohya/install_worker.py | 4 +- tests/test_kohya_fingerprint.py | 82 ++++++++++++++++++++++ tests/test_kohya_main_env_fallback.py | 16 +++-- 4 files changed, 169 insertions(+), 17 deletions(-) create mode 100644 tests/test_kohya_fingerprint.py diff --git a/mikazuki/engines/kohya/extension_state.py b/mikazuki/engines/kohya/extension_state.py index 4b4b392ca..b00f91b3e 100644 --- a/mikazuki/engines/kohya/extension_state.py +++ b/mikazuki/engines/kohya/extension_state.py @@ -1,10 +1,22 @@ -import json import hashlib +import json +import os +import threading import time -from .environment import TRAINING_DEPS, TORCH_PINS, TORCH_PINS_AARCH64, audit_python, compute_drift +from .environment import ( + TORCH_PINS, + TORCH_PINS_AARCH64, + TRAINING_DEPS, + audit_python, + compute_drift, +) from .settings import main_env_python_candidates +FINGERPRINT_SCHEME = "content-v1" +FINGERPRINT_MAX_HASH_BYTES = 8 * 1024 * 1024 +_recovery_lock = threading.Lock() + def write_state(runtime, state, facts=None, reason=""): runtime.root.mkdir(parents=True, exist_ok=True) @@ -18,17 +30,32 @@ def fingerprint(runtime): # only the venv content and the pinned dependency set gate readiness. files = [runtime.python] files += sorted((runtime.root / ".venv").glob("**/*.dist-info/METADATA")) - stats = [] + entries = [] for path in files: - if not path.is_file(): + if not path.is_file() and not path.is_symlink(): continue try: identity = path.relative_to(runtime.root).as_posix() except ValueError: identity = path.name - stats.append((identity, path.stat().st_size, path.stat().st_mtime_ns)) + if path.is_symlink(): + entries.append((identity, path.lstat().st_size, "symlink", os.readlink(path))) + continue + stat = path.stat() + if stat.st_size > FINGERPRINT_MAX_HASH_BYTES: + entries.append((identity, stat.st_size, "size", "")) + continue + digest = hashlib.sha256() + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + digest.update(chunk) + entries.append((identity, stat.st_size, "sha256", digest.hexdigest())) pins = [*TRAINING_DEPS, *TORCH_PINS, *TORCH_PINS_AARCH64] - return hashlib.sha256(json.dumps([pins, stats]).encode()).hexdigest() + return hashlib.sha256(json.dumps([FINGERPRINT_SCHEME, pins, entries]).encode()).hexdigest() + + +def fingerprint_facts(runtime): + return {"fingerprint": fingerprint(runtime), "fingerprint_scheme": FINGERPRINT_SCHEME} # Main-env audits spawn a python subprocess importing torch (seconds), so @@ -155,7 +182,7 @@ def _main_env_upgrade_status(runtime): global _ACTIVE_MAIN_ENV_UPGRADE if not _ACTIVE_MAIN_ENV_UPGRADE: return None - from mikazuki.tasks import tm, TaskStatus + from mikazuki.tasks import TaskStatus, tm task = tm.tasks.get(_ACTIVE_MAIN_ENV_UPGRADE["task_id"]) if task is not None and task.status not in {TaskStatus.FAILED, TaskStatus.TERMINATED, TaskStatus.FINISHED}: return { @@ -170,19 +197,56 @@ def _main_env_upgrade_status(runtime): return None -def read_status(runtime): +def _recover_missing_state(runtime, audit_fn): + if not any(path.exists() for path in (runtime.root / ".venv", runtime.python_install_dir)): + return {"state": "not_installed", "facts": {}} + if not runtime.python.is_file(): + return {"state": "broken", "facts": {}, "reason": "独立 Python 缺失,请修复环境。"} + audit = audit_fn(runtime) + facts = {"recovery": "missing_install_state", "audit": audit} + if not audit.get("ok"): + reason = "; ".join(audit.get("errors") or ["Kohya 环境审计失败。"]) + write_state(runtime, "broken", facts, reason) + return {"state": "broken", "facts": facts, "reason": reason} + facts.update(fingerprint_facts(runtime)) + reason = "状态文件缺失,已根据实体环境自动恢复。" + write_state(runtime, "ready", facts, reason) + return {"state": "ready", "facts": facts, "reason": reason} + + +def read_status(runtime, *, audit_fn=None): upgrading = _main_env_upgrade_status(runtime) if upgrading is not None: return upgrading - data = json.loads(runtime.state_file.read_text(encoding="utf-8")) if runtime.state_file.exists() else {"state": "not_installed", "facts": {}} + if runtime.state_file.exists(): + data = json.loads(runtime.state_file.read_text(encoding="utf-8")) + else: + with _recovery_lock: + if runtime.state_file.exists(): + data = json.loads(runtime.state_file.read_text(encoding="utf-8")) + else: + from .environment import audit_environment + data = _recover_missing_state(runtime, audit_fn or audit_environment) if data["state"] in {"installing", "auditing"}: - from mikazuki.tasks import tm, TaskStatus + from mikazuki.tasks import TaskStatus, tm task = tm.tasks.get(data["facts"].get("task_id")) if task is None or task.status in {TaskStatus.FAILED, TaskStatus.TERMINATED, TaskStatus.FINISHED}: invalidate_main_env_audit_cache() data.update(state="broken", reason="安装中断,请修复 kohya 环境。") if data["state"] == "ready" and not runtime.python.is_file(): data.update(state="broken", reason="独立 Python 缺失,请修复环境。") + if data["state"] == "ready": + if data["facts"].get("fingerprint_scheme") != FINGERPRINT_SCHEME: + from .environment import audit_environment + audit = (audit_fn or audit_environment)(runtime) + data["facts"]["audit"] = audit + if not audit.get("ok"): + data.update(state="broken", reason="; ".join(audit.get("errors") or ["Kohya 环境审计失败。"])) + else: + data["facts"].update(fingerprint_facts(runtime)) + write_state(runtime, "ready", data["facts"], "旧版环境状态已通过审计并迁移。") + elif data["facts"].get("fingerprint") != fingerprint(runtime): + data.update(state="broken", reason="环境已变化,请修复后重新检查。") if data["state"] == "ready": # Pin drift never blocks: the env was audited ready at install time, # so a mismatch with the current pins only means an upgrade is advised. diff --git a/mikazuki/engines/kohya/install_worker.py b/mikazuki/engines/kohya/install_worker.py index 966ac9047..0d3b13a1b 100644 --- a/mikazuki/engines/kohya/install_worker.py +++ b/mikazuki/engines/kohya/install_worker.py @@ -7,7 +7,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[3])) from mikazuki.engines.kohya.environment import install_env, audit_environment, audit_python -from mikazuki.engines.kohya.extension_state import write_state, fingerprint +from mikazuki.engines.kohya.extension_state import write_state, fingerprint_facts from mikazuki.engines.kohya.resource import environment_lock from mikazuki.engines.kohya.settings import Runtime @@ -60,7 +60,7 @@ def main(): print(json.dumps(audit, ensure_ascii=False), flush=True) if not audit['ok']: raise RuntimeError('; '.join(audit['errors'])) - write_state(rt, 'ready', {**facts, 'audit': audit, 'fingerprint': fingerprint(rt)}) + write_state(rt, 'ready', {**facts, 'audit': audit, **fingerprint_facts(rt)}) print('[mikazuki-progress] ' + json.dumps({'percent': 100, 'message': '环境检查完成'}, ensure_ascii=False), flush=True) except Exception as exc: if target == 'standalone': diff --git a/tests/test_kohya_fingerprint.py b/tests/test_kohya_fingerprint.py new file mode 100644 index 000000000..0e25473e4 --- /dev/null +++ b/tests/test_kohya_fingerprint.py @@ -0,0 +1,82 @@ +import os + +from mikazuki.engines.kohya.extension_state import ( + FINGERPRINT_SCHEME, + fingerprint, + fingerprint_facts, + read_status, + write_state, +) +from mikazuki.engines.kohya.settings import Runtime + + +def make_runtime(tmp_path): + runtime = Runtime(tmp_path) + runtime.python.parent.mkdir(parents=True) + runtime.python.write_text("#!/python\n", encoding="utf-8") + metadata = runtime.root / ".venv" / "lib" / "torch-2.7.0.dist-info" + metadata.mkdir(parents=True) + (metadata / "METADATA").write_text("Name: torch\nVersion: 2.7.0\n", encoding="utf-8") + return runtime + + +def successful_audit(runtime): + return {"ok": True, "errors": [], "versions": {}} + + +def test_mtime_only_changes_keep_fingerprint(tmp_path): + runtime = make_runtime(tmp_path) + before = fingerprint(runtime) + stat = runtime.python.stat() + os.utime(runtime.python, ns=(stat.st_atime_ns, stat.st_mtime_ns + 5_000_000_000)) + assert fingerprint(runtime) == before + + +def test_same_length_content_change_is_detected(tmp_path): + runtime = make_runtime(tmp_path) + before = fingerprint(runtime) + runtime.python.write_text("#!/shell\n", encoding="utf-8") + assert fingerprint(runtime) != before + + +def test_legacy_state_audits_and_migrates(tmp_path): + runtime = make_runtime(tmp_path) + write_state(runtime, "ready", {"fingerprint": "0" * 64}) + status = read_status(runtime, audit_fn=successful_audit) + assert status["state"] == "ready" + assert status["facts"]["fingerprint_scheme"] == FINGERPRINT_SCHEME + assert runtime.state_file.is_file() + + +def test_legacy_state_with_failed_audit_is_broken(tmp_path): + runtime = make_runtime(tmp_path) + write_state(runtime, "ready", {"fingerprint": "0" * 64}) + status = read_status(runtime, audit_fn=lambda rt: {"ok": False, "errors": ["bad runtime"]}) + assert status["state"] == "broken" + assert "bad runtime" in status["reason"] + + +def test_current_scheme_mismatch_is_broken(tmp_path): + runtime = make_runtime(tmp_path) + write_state(runtime, "ready", {"fingerprint": "0" * 64, "fingerprint_scheme": FINGERPRINT_SCHEME}) + assert read_status(runtime, audit_fn=successful_audit)["state"] == "broken" + + +def test_missing_state_recovers_complete_environment(tmp_path): + runtime = make_runtime(tmp_path) + status = read_status(runtime, audit_fn=successful_audit) + assert status["state"] == "ready" + assert status["facts"]["recovery"] == "missing_install_state" + assert status["facts"]["fingerprint_scheme"] == FINGERPRINT_SCHEME + + +def test_missing_state_failed_audit_is_broken(tmp_path): + runtime = make_runtime(tmp_path) + status = read_status(runtime, audit_fn=lambda rt: {"ok": False, "errors": ["bad runtime"]}) + assert status["state"] == "broken" + assert "bad runtime" in status["reason"] + + +def test_install_facts_include_scheme(tmp_path): + runtime = make_runtime(tmp_path) + assert fingerprint_facts(runtime)["fingerprint_scheme"] == FINGERPRINT_SCHEME diff --git a/tests/test_kohya_main_env_fallback.py b/tests/test_kohya_main_env_fallback.py index 54af68ee1..daf24c31b 100644 --- a/tests/test_kohya_main_env_fallback.py +++ b/tests/test_kohya_main_env_fallback.py @@ -8,9 +8,13 @@ import pytest -from mikazuki.engines.kohya.settings import Runtime, main_env_python_candidates from mikazuki.engines.kohya import extension_state -from mikazuki.engines.kohya.extension_state import read_status, write_state, fingerprint +from mikazuki.engines.kohya.extension_state import ( + fingerprint_facts, + read_status, + write_state, +) +from mikazuki.engines.kohya.settings import Runtime, main_env_python_candidates @pytest.fixture(autouse=True) @@ -79,7 +83,7 @@ def test_standalone_ready_wins_without_main_env_audit(tmp_path, monkeypatch, mai runtime = Runtime(tmp_path / "Next-Trainer") runtime.python.parent.mkdir(parents=True) runtime.python.write_text("fake", encoding="utf-8") - write_state(runtime, "ready", {"fingerprint": fingerprint(runtime)}) + write_state(runtime, "ready", fingerprint_facts(runtime)) def forbidden_audit(python): raise AssertionError("main env audit must not run when standalone is ready") @@ -198,13 +202,14 @@ def _make_dist_info(runtime, name, version): def _make_ready_standalone(runtime): runtime.python.parent.mkdir(parents=True, exist_ok=True) runtime.python.write_text("fake", encoding="utf-8") - write_state(runtime, "ready", {"fingerprint": "whatever"}) + write_state(runtime, "ready", fingerprint_facts(runtime)) def test_standalone_ready_with_drift_reports_update_available(tmp_path): runtime = Runtime(tmp_path) _make_ready_standalone(runtime) _make_dist_info(runtime, "transformers", "4.51.3") + write_state(runtime, "ready", fingerprint_facts(runtime)) status = read_status(runtime) @@ -241,9 +246,10 @@ def test_main_env_ready_reports_drift_from_audit_versions(tmp_path, monkeypatch, def test_main_env_upgrade_marker_drives_installing_state(tmp_path, monkeypatch, main_python): - from mikazuki.tasks import tm, TaskStatus from types import SimpleNamespace + from mikazuki.tasks import TaskStatus, tm + patch_main_env(monkeypatch, main_python, {"ok": True, "gpu": True, "versions": {}}) runtime = Runtime(tmp_path / "Next-Trainer") task_id = "kohya-install-upgrade-demo" From 87616034af1aae2c66be836e353dd7b61c45c9d9 Mon Sep 17 00:00:00 2001 From: "xixun.bu" Date: Wed, 28 Oct 2026 12:16:10 +0800 Subject: [PATCH 2/3] fix(anima): load JSON captions during training --- docs/anima-lora-parameters-sdxl.md | 20 ++- mikazuki/schema/sd3-lora.ts | 2 +- tests/test_anima_backend_adapter.py | 12 ++ tests/test_anima_json_caption.py | 172 +++++++++++++++++++++++ vendor/sd-scripts/library/config_util.py | 3 + vendor/sd-scripts/library/train_util.py | 113 +++++++++++---- 6 files changed, 292 insertions(+), 30 deletions(-) create mode 100644 tests/test_anima_json_caption.py diff --git a/docs/anima-lora-parameters-sdxl.md b/docs/anima-lora-parameters-sdxl.md index e72fe24d4..e28864d47 100644 --- a/docs/anima-lora-parameters-sdxl.md +++ b/docs/anima-lora-parameters-sdxl.md @@ -97,15 +97,31 @@ Anima 不像 SDXL 只选一个 ckpt,页面上有三项**必填**: |------|------| | `prefer_json_caption` | **建议开启**,优先读同名 `.json` 标签 | | `caption_extension` | 没有 JSON 时,回退读 `.txt` | -| `shuffle_caption` | 训练时打乱标签顺序;JSON 模式下会分组打乱 | +| `shuffle_caption` | 训练时打乱标签顺序;JSON 标签解析后使用相同规则 | | `keep_tokens` | 打乱时保留前几个词不动(触发词建议放前面) | -JSON 标签推荐字段顺序(表单里也有提示): +JSON 标签按以下固定字段顺序展开(表单里也有提示): ```text quality / count / character / series / artist / appearance[] / tags[] / environment[] / nl ``` +例如 `image1.png` 对应 `image1.json`: + +```json +{ + "quality": "masterpiece", + "count": 1, + "character": "character name", + "appearance": ["blue eyes", "red dress"], + "tags": ["smile"], + "environment": ["indoors"], + "nl": "a natural language description" +} +``` + +字段可写字符串、数字或对应数组,空值会跳过。JSON 没有可用内容时回退读取文本标签;JSON 语法错误或字段类型不受支持时会明确报错,不会静默按无标签训练。 + 你以前用「一行逗号 tag」完全可以继续用;如果愿意,把角色名、外观、环境分开写进 JSON,Anima 往往吃得更好。触发词放在 `character` 或 `tags` 前面,并配合 `keep_tokens`,效果更稳。 **注意**:如果开了「缓存文本编码器输出」(`cache_text_encoder_outputs`),需要**关掉** `shuffle_caption`,否则两者会打架。 diff --git a/mikazuki/schema/sd3-lora.ts b/mikazuki/schema/sd3-lora.ts index d702099fa..c1eaf72bb 100644 --- a/mikazuki/schema/sd3-lora.ts +++ b/mikazuki/schema/sd3-lora.ts @@ -197,7 +197,7 @@ Schema.intersect([ Schema.intersect([ Schema.object(UpdateSchema(SHARED_SCHEMAS.RAW.CAPTION_SETTINGS, { caption_extension: Schema.string().default(".txt").description("回退读取的 Tag 文件扩展名"), - shuffle_caption: Schema.boolean().default(false).description("训练时随机打乱 tokens;JSON 模式下会对 appearance / tags / environment 分组打乱"), + shuffle_caption: Schema.boolean().default(false).description("训练时随机打乱 tokens;JSON 标签解析后使用相同的打乱规则"), keep_tokens: Schema.number().min(0).max(255).step(1).default(0).description("随机打乱时保留前 N 个 token 不变"), caption_tag_dropout_rate: Schema.number().min(0).step(0.01).description("按标签随机丢弃 tag 的概率"), prefer_json_caption: Schema.boolean().default(true).description("优先读取同名 JSON 标签文件;适合 Anima 结构化标签流程"), diff --git a/tests/test_anima_backend_adapter.py b/tests/test_anima_backend_adapter.py index 88e3afab7..665e25a36 100644 --- a/tests/test_anima_backend_adapter.py +++ b/tests/test_anima_backend_adapter.py @@ -29,6 +29,18 @@ def test_adapter_keeps_supported_anima_fields(self): self.assertNotIn("enable_preview", adapted) self.assertEqual(warnings, []) + def test_adapter_keeps_json_caption_preference_for_lora_and_finetune(self): + for finetune in (False, True): + with self.subTest(finetune=finetune): + adapted, warnings = adapt_anima_config( + {"prefer_json_caption": True, "caption_extension": ".txt"}, + finetune=finetune, + ) + + self.assertIs(adapted["prefer_json_caption"], True) + self.assertEqual(adapted["caption_extension"], ".txt") + self.assertEqual(warnings, []) + def test_adapter_warns_for_unsupported_debug_fields(self): adapted, warnings = adapt_anima_config( { diff --git a/tests/test_anima_json_caption.py b/tests/test_anima_json_caption.py new file mode 100644 index 000000000..8e7da7eae --- /dev/null +++ b/tests/test_anima_json_caption.py @@ -0,0 +1,172 @@ +import argparse +import json +import sys +from dataclasses import asdict +from pathlib import Path + +import pytest +from PIL import Image + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "vendor" / "sd-scripts")) + +from library.config_util import BlueprintGenerator, ConfigSanitizer, DreamBoothSubsetParams # noqa: E402 +from library.train_util import DreamBoothDataset, DreamBoothSubset, add_dataset_arguments, read_caption # noqa: E402 + + +def write_json(path: Path, value) -> None: + path.write_text(json.dumps(value, ensure_ascii=False), encoding="utf-8") + + +def test_structured_json_fields_are_flattened_in_documented_order(tmp_path): + image = tmp_path / "image1.png" + write_json( + image.with_suffix(".json"), + { + "nl": "a natural language description", + "environment": ["indoors", "window light"], + "tags": ["short hair", "smile"], + "appearance": ["red dress", "blue eyes"], + "artist": "artist name", + "series": "series name", + "character": "character name", + "count": 1, + "quality": "masterpiece", + }, + ) + + caption = read_caption(str(image), ".txt", False, True) + + assert caption == ( + "masterpiece, 1, character name, series name, artist name, red dress, blue eyes, " + "short hair, smile, indoors, window light, a natural language description" + ) + + +def test_json_is_preferred_over_text_caption(tmp_path): + image = tmp_path / "image1.png" + write_json(image.with_suffix(".json"), {"tags": ["from json"]}) + image.with_suffix(".txt").write_text("from text", encoding="utf-8") + + assert read_caption(str(image), ".txt", False, True) == "from json" + + +def test_text_caption_is_used_when_json_is_missing_or_empty(tmp_path): + missing_json_image = tmp_path / "missing.png" + missing_json_image.with_suffix(".txt").write_text("missing json fallback", encoding="utf-8") + empty_json_image = tmp_path / "empty.png" + write_json(empty_json_image.with_suffix(".json"), {"tags": [], "nl": " "}) + empty_json_image.with_suffix(".txt").write_text("empty json fallback", encoding="utf-8") + + assert read_caption(str(missing_json_image), ".txt", False, True) == "missing json fallback" + assert read_caption(str(empty_json_image), ".txt", False, True) == "empty json fallback" + + +def test_disabling_json_preference_preserves_text_only_behavior(tmp_path): + image = tmp_path / "image1.png" + write_json(image.with_suffix(".json"), {"tags": ["from json"]}) + image.with_suffix(".txt").write_text("from text", encoding="utf-8") + + assert read_caption(str(image), ".txt", False, False) == "from text" + + +def test_empty_json_without_text_fallback_is_reported_as_missing(tmp_path): + image = tmp_path / "image1.png" + write_json(image.with_suffix(".json"), {}) + + assert read_caption(str(image), ".txt", False, True) is None + + +def test_face_detection_json_fallback_uses_original_image_name(tmp_path): + image = tmp_path / "character_0_0_0_0.png" + write_json(tmp_path / "character.json", {"character": "character name"}) + + assert read_caption(str(image), ".txt", False, True) == "character name" + + +@pytest.mark.parametrize("content", ["{not json", '["not", "an", "object"]']) +def test_invalid_json_fails_with_file_path(tmp_path, content): + image = tmp_path / "broken.png" + caption_path = image.with_suffix(".json") + caption_path.write_text(content, encoding="utf-8") + + with pytest.raises(ValueError, match="broken.json"): + read_caption(str(image), ".txt", False, True) + + +def test_unsupported_json_field_value_fails_with_field_and_file_path(tmp_path): + image = tmp_path / "broken.png" + write_json(image.with_suffix(".json"), {"tags": [{"name": "nested"}]}) + + with pytest.raises(ValueError) as error: + read_caption(str(image), ".txt", False, True) + + assert "tags" in str(error.value) + assert "broken.json" in str(error.value) + + +def test_prefer_json_caption_flows_from_cli_to_dreambooth_subset(tmp_path): + parser = argparse.ArgumentParser() + add_dataset_arguments(parser, True, True, True) + args = parser.parse_args(["--prefer_json_caption", "--caption_extension", ".txt"]) + sanitizer = ConfigSanitizer( + support_dreambooth=True, + support_finetuning=False, + support_controlnet=False, + support_dropout=True, + ) + user_config = { + "datasets": [ + { + "resolution": 1024, + "subsets": [{"image_dir": str(tmp_path), "num_repeats": 1}], + } + ] + } + + blueprint = BlueprintGenerator(sanitizer).generate(user_config, args) + params = blueprint.dataset_group.datasets[0].subsets[0].params + subset = DreamBoothSubset(**asdict(params)) + + assert params.prefer_json_caption is True + assert subset.prefer_json_caption is True + assert subset.caption_extension == ".txt" + + +def test_dreambooth_dataset_loads_and_caches_json_caption(tmp_path): + image_path = tmp_path / "image1.png" + Image.new("RGB", (8, 8), (255, 0, 0)).save(image_path) + write_json(image_path.with_suffix(".json"), {"character": "character name", "tags": ["smile"]}) + subset = DreamBoothSubset( + **asdict( + DreamBoothSubsetParams( + image_dir=str(tmp_path), + num_repeats=1, + caption_extension=".txt", + prefer_json_caption=True, + cache_info=True, + ) + ) + ) + + dataset = DreamBoothDataset( + subsets=[subset], + is_training_dataset=True, + batch_size=1, + resolution=(8, 8), + network_multiplier=1.0, + enable_bucket=False, + min_bucket_reso=256, + max_bucket_reso=1024, + bucket_reso_steps=64, + bucket_no_upscale=False, + prior_loss_weight=1.0, + train_inpainting=False, + debug_dataset=False, + validation_split=0.0, + validation_seed=None, + resize_interpolation=None, + ) + + assert dataset.image_data[str(image_path)].caption == "character name, smile" + cache = json.loads((tmp_path / "metadata_cache.json").read_text(encoding="utf-8")) + assert cache[str(image_path)]["caption"] == "character name, smile" diff --git a/vendor/sd-scripts/library/config_util.py b/vendor/sd-scripts/library/config_util.py index ca6aa3e8d..0f824defc 100644 --- a/vendor/sd-scripts/library/config_util.py +++ b/vendor/sd-scripts/library/config_util.py @@ -83,6 +83,7 @@ class DreamBoothSubsetParams(BaseSubsetParams): is_reg: bool = False class_tokens: Optional[str] = None caption_extension: str = ".caption" + prefer_json_caption: bool = False cache_info: bool = False alpha_mask: bool = False @@ -210,6 +211,7 @@ def __validate_and_convert_scalar_or_twodim(klass, value: Union[float, Sequence] # DB means DreamBooth DB_SUBSET_ASCENDABLE_SCHEMA = { "caption_extension": str, + "prefer_json_caption": bool, "class_tokens": str, "cache_info": bool, } @@ -577,6 +579,7 @@ def print_info(_datasets, dataset_type: str): is_reg: {subset.is_reg} class_tokens: {subset.class_tokens} caption_extension: {subset.caption_extension} + prefer_json_caption: {subset.prefer_json_caption} \n"""), " ") elif not is_controlnet: info += indent(dedent(f"""\ diff --git a/vendor/sd-scripts/library/train_util.py b/vendor/sd-scripts/library/train_util.py index 121293dba..c387c77af 100644 --- a/vendor/sd-scripts/library/train_util.py +++ b/vendor/sd-scripts/library/train_util.py @@ -410,6 +410,82 @@ def get_augmentor(self, use_color_aug: bool): # -> Optional[Callable[[np.ndarra return self.color_aug if use_color_aug else None +_JSON_CAPTION_FIELD_ORDER = ( + "quality", + "count", + "character", + "series", + "artist", + "appearance", + "tags", + "environment", + "nl", +) + + +def _json_caption_tokens(value, cap_path: str, field: str) -> List[str]: + values = value if isinstance(value, list) else [value] + tokens = [] + for item in values: + if item is None: + continue + if isinstance(item, bool) or not isinstance(item, (str, int, float)): + raise ValueError(f"unsupported value for field '{field}' in JSON caption: {cap_path}") + token = str(item).strip() + if token: + tokens.append(token) + return tokens + + +def _read_json_caption(cap_path: str) -> str: + with open(cap_path, "rt", encoding="utf-8-sig") as f: + try: + data = json.load(f) + except (json.JSONDecodeError, UnicodeDecodeError) as e: + raise ValueError(f"invalid JSON caption: {cap_path}: {e}") from e + if not isinstance(data, dict): + raise ValueError(f"JSON caption must contain an object: {cap_path}") + + tokens = [] + for field in _JSON_CAPTION_FIELD_ORDER: + if field in data: + tokens.extend(_json_caption_tokens(data[field], cap_path, field)) + return ", ".join(tokens) + + +def read_caption(img_path, caption_extension, enable_wildcard, prefer_json_caption=False): + base_name = os.path.splitext(img_path)[0] + base_name_face_det = base_name + tokens = base_name.split("_") + if len(tokens) >= 5: + base_name_face_det = "_".join(tokens[:-4]) + base_names = list(dict.fromkeys([base_name, base_name_face_det])) + text_cap_paths = [base + caption_extension for base in base_names] + json_cap_paths = [base + ".json" for base in base_names] if prefer_json_caption else [] + cap_paths = list(dict.fromkeys(json_cap_paths + text_cap_paths)) + json_cap_path_set = set(json_cap_paths) + + for cap_path in cap_paths: + if not os.path.isfile(cap_path): + continue + if cap_path in json_cap_path_set: + caption = _read_json_caption(cap_path) + if caption: + return caption + continue + with open(cap_path, "rt", encoding="utf-8") as f: + try: + lines = f.readlines() + except UnicodeDecodeError as e: + logger.error(f"illegal char in file (not UTF-8) / ファイルにUTF-8以外の文字があります: {cap_path}") + raise e + assert len(lines) > 0, f"caption file is empty / キャプションファイルが空です: {cap_path}" + if enable_wildcard: + return "\n".join([line.strip() for line in lines if line.strip() != ""]) + return lines[0].strip() + return None + + class BaseSubset: def __init__( self, @@ -501,6 +577,7 @@ def __init__( validation_seed: Optional[int] = None, validation_split: Optional[float] = 0.0, resize_interpolation: Optional[str] = None, + prefer_json_caption: bool = False, ) -> None: assert image_dir is not None, "image_dir must be specified / image_dirは指定が必須です" @@ -536,6 +613,7 @@ def __init__( self.caption_extension = caption_extension if self.caption_extension and not self.caption_extension.startswith("."): self.caption_extension = "." + self.caption_extension + self.prefer_json_caption = prefer_json_caption self.cache_info = cache_info def __eq__(self, other) -> bool: @@ -1999,32 +2077,6 @@ def __init__( self.bucket_reso_steps = None # この情報は使われない self.bucket_no_upscale = False - def read_caption(img_path, caption_extension, enable_wildcard): - # captionの候補ファイル名を作る - base_name = os.path.splitext(img_path)[0] - base_name_face_det = base_name - tokens = base_name.split("_") - if len(tokens) >= 5: - base_name_face_det = "_".join(tokens[:-4]) - cap_paths = [base_name + caption_extension, base_name_face_det + caption_extension] - - caption = None - for cap_path in cap_paths: - if os.path.isfile(cap_path): - with open(cap_path, "rt", encoding="utf-8") as f: - try: - lines = f.readlines() - except UnicodeDecodeError as e: - logger.error(f"illegal char in file (not UTF-8) / ファイルにUTF-8以外の文字があります: {cap_path}") - raise e - assert len(lines) > 0, f"caption file is empty / キャプションファイルが空です: {cap_path}" - if enable_wildcard: - caption = "\n".join([line.strip() for line in lines if line.strip() != ""]) # 空行を除く、改行で連結 - else: - caption = lines[0].strip() - break - return caption - def load_dreambooth_dir(subset: DreamBoothSubset): if not os.path.isdir(subset.image_dir): logger.warning(f"not directory: {subset.image_dir}") @@ -2140,7 +2192,9 @@ def load_dreambooth_dir(subset: DreamBoothSubset): captions = [] missing_captions = [] for img_path in tqdm(img_paths, desc="read caption"): - cap_for_img = read_caption(img_path, subset.caption_extension, subset.enable_wildcard) + cap_for_img = read_caption( + img_path, subset.caption_extension, subset.enable_wildcard, subset.prefer_json_caption + ) if cap_for_img is None and subset.class_tokens is None: logger.warning( f"neither caption file nor class tokens are found. use empty caption for {img_path} / キャプションファイルもclass tokenも見つかりませんでした。空のキャプションを使用します: {img_path}" @@ -4617,6 +4671,11 @@ def add_dataset_arguments( parser.add_argument( "--caption_extension", type=str, default=".caption", help="extension of caption files / 読み込むcaptionファイルの拡張子" ) + parser.add_argument( + "--prefer_json_caption", + action="store_true", + help="prefer structured JSON captions over text captions / テキストcaptionより構造化JSON captionを優先する", + ) parser.add_argument( "--caption_extention", type=str, From 4b7fc4e01cd5b1344423f689d0fd2819bc27cf38 Mon Sep 17 00:00:00 2001 From: wochenlong <117965575+wochenlong@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:59:13 +0800 Subject: [PATCH 3/3] fix(kohya): serialize legacy fingerprint state migration --- mikazuki/engines/kohya/extension_state.py | 32 ++++++++++++++++------- tests/test_kohya_fingerprint.py | 29 ++++++++++++++++++++ 2 files changed, 52 insertions(+), 9 deletions(-) diff --git a/mikazuki/engines/kohya/extension_state.py b/mikazuki/engines/kohya/extension_state.py index b00f91b3e..b3337e09d 100644 --- a/mikazuki/engines/kohya/extension_state.py +++ b/mikazuki/engines/kohya/extension_state.py @@ -3,6 +3,7 @@ import os import threading import time +import uuid from .environment import ( TORCH_PINS, @@ -20,7 +21,7 @@ def write_state(runtime, state, facts=None, reason=""): runtime.root.mkdir(parents=True, exist_ok=True) - temporary = runtime.state_file.with_suffix(".tmp") + temporary = runtime.state_file.with_suffix(f".{uuid.uuid4().hex}.tmp") temporary.write_text(json.dumps({"state": state, "facts": facts or {}, "reason": reason}, ensure_ascii=False, indent=2), encoding="utf-8") temporary.replace(runtime.state_file) @@ -214,6 +215,24 @@ def _recover_missing_state(runtime, audit_fn): return {"state": "ready", "facts": facts, "reason": reason} +def _migrate_legacy_state(runtime, data, audit_fn): + with _recovery_lock: + if runtime.state_file.exists(): + latest = json.loads(runtime.state_file.read_text(encoding="utf-8")) + if latest.get("state") != "ready" or latest.get("facts", {}).get("fingerprint_scheme") == FINGERPRINT_SCHEME: + return latest + data = latest + from .environment import audit_environment + audit = (audit_fn or audit_environment)(runtime) + data["facts"]["audit"] = audit + if not audit.get("ok"): + data.update(state="broken", reason="; ".join(audit.get("errors") or ["Kohya 环境审计失败。"])) + else: + data["facts"].update(fingerprint_facts(runtime)) + write_state(runtime, "ready", data["facts"], "旧版环境状态已通过审计并迁移。") + return data + + def read_status(runtime, *, audit_fn=None): upgrading = _main_env_upgrade_status(runtime) if upgrading is not None: @@ -237,14 +256,9 @@ def read_status(runtime, *, audit_fn=None): data.update(state="broken", reason="独立 Python 缺失,请修复环境。") if data["state"] == "ready": if data["facts"].get("fingerprint_scheme") != FINGERPRINT_SCHEME: - from .environment import audit_environment - audit = (audit_fn or audit_environment)(runtime) - data["facts"]["audit"] = audit - if not audit.get("ok"): - data.update(state="broken", reason="; ".join(audit.get("errors") or ["Kohya 环境审计失败。"])) - else: - data["facts"].update(fingerprint_facts(runtime)) - write_state(runtime, "ready", data["facts"], "旧版环境状态已通过审计并迁移。") + data = _migrate_legacy_state(runtime, data, audit_fn) + if data["state"] == "ready" and data["facts"].get("fingerprint") != fingerprint(runtime): + data.update(state="broken", reason="环境已变化,请修复后重新检查。") elif data["facts"].get("fingerprint") != fingerprint(runtime): data.update(state="broken", reason="环境已变化,请修复后重新检查。") if data["state"] == "ready": diff --git a/tests/test_kohya_fingerprint.py b/tests/test_kohya_fingerprint.py index 0e25473e4..8962a5176 100644 --- a/tests/test_kohya_fingerprint.py +++ b/tests/test_kohya_fingerprint.py @@ -1,4 +1,5 @@ import os +import threading from mikazuki.engines.kohya.extension_state import ( FINGERPRINT_SCHEME, @@ -48,6 +49,34 @@ def test_legacy_state_audits_and_migrates(tmp_path): assert runtime.state_file.is_file() +def test_concurrent_legacy_state_migration_audits_once(tmp_path): + runtime = make_runtime(tmp_path) + write_state(runtime, "ready", {"fingerprint": "0" * 64}) + barrier = threading.Barrier(2) + audit_calls = 0 + + def counted_audit(rt): + nonlocal audit_calls + audit_calls += 1 + return successful_audit(rt) + + results = [] + + def worker(): + barrier.wait() + results.append(read_status(runtime, audit_fn=counted_audit)) + + threads = [threading.Thread(target=worker) for _ in range(2)] + for thread in threads: + thread.start() + for thread in threads: + thread.join() + + assert audit_calls == 1 + assert all(result["state"] == "ready" for result in results) + assert all(result["facts"]["fingerprint_scheme"] == FINGERPRINT_SCHEME for result in results) + + def test_legacy_state_with_failed_audit_is_broken(tmp_path): runtime = make_runtime(tmp_path) write_state(runtime, "ready", {"fingerprint": "0" * 64})