refactor(inference): unify request handling across entrypoints

README.md

@@ -176,6 +176,8 @@ For attention operators installation, please refer to our documentation: **[Engl
 
 ### Usage Example
 
+See the [MiniMax-H3 guide](scripts/minimax_h3/README.md) for checkpoint layout, local LoRA paths, CLI presets, and server/POST examples.
+
 ```python
 # examples/minimax_h3/minimax_h3_t2av_dmd.py
 """
@@ -194,7 +196,7 @@ pipe = LightX2VPipeline(
 # The DMD config uses the released 768p LoRA, 4 inference steps,
 # video_flow_shift=6, audio_flow_shift=3, and lora alpha=128.
 pipe.create_generator(
-    config_json="configs/minimax_h3/dmd/minimax_h3_bf16_4step_single_gpu_offload.json"
+    config_json="configs/minimax_h3/dmd/minimax_h3_bf16_4step.json"
 )
 
 # Generation parameters

README_zh.md

@@ -176,6 +176,9 @@ uv pip install -v . # pip install -v .
 注意力算子安装说明请参考我们的文档：**[英文文档](https://lightx2v-en.readthedocs.io/en/latest/getting_started/quickstart.html#step-4-install-attention-operators) | [中文文档](https://lightx2v-zhcn.readthedocs.io/zh-cn/latest/getting_started/quickstart.html#id9)**
 
 ### 使用示例
+
+权重目录、本地 LoRA 路径、CLI 配置及服务与 POST 示例见 [MiniMax-H3 使用说明](scripts/minimax_h3/README_zh.md)。
+
 ```python
 # examples/minimax_h3/minimax_h3_t2av_dmd.py
 """
@@ -194,7 +197,7 @@ pipe = LightX2VPipeline(
 # DMD 配置使用已发布的 768p LoRA、4 步推理、
 # video_flow_shift=6、audio_flow_shift=3 和 LoRA alpha=128。
 pipe.create_generator(
-    config_json="configs/minimax_h3/dmd/minimax_h3_bf16_4step_single_gpu_offload.json"
+    config_json="configs/minimax_h3/dmd/minimax_h3_bf16_4step.json"
 )
 
 # 生成参数

app/gradio_demo.py

@@ -10,13 +10,12 @@
 import os
 import warnings
 
-import torch
 from loguru import logger
 from utils.i18n import DEFAULT_LANG, set_language
 from utils.model_utils import cleanup_memory, extract_op_name, get_model_configs
 from utils.ui_builder import build_ui, generate_unique_filename, get_auto_config_dict
 
-from lightx2v.utils.input_info import init_empty_input_info, update_input_info_from_dict
+from lightx2v.models.runners.runner_factory import build_runner
 from lightx2v.utils.set_config import get_default_config
 
 warnings.filterwarnings("ignore", category=UserWarning, module="huggingface_hub")
@@ -41,12 +40,8 @@
 
 
 global_runner = None
-current_config = None
-cur_dit_path = None
-cur_use_lora = None
-cur_lora_path = None
-cur_high_lora_path = None
-cur_low_lora_path = None
+current_startup_config = None
+current_lora_configs = []
 
 
 def run_inference(
@@ -146,17 +141,10 @@ def run_inference(
     model_cls = model_config["model_cls"]
     model_path = model_config["model_path"]
 
-    global global_runner, current_config, cur_dit_path, cur_use_lora, cur_lora_path, cur_high_lora_path, cur_low_lora_path
+    global global_runner, current_startup_config, current_lora_configs
 
     logger.info(f"Auto-determined model_cls: {model_cls} (model type: {model_type_input})")
 
-    if model_cls.startswith("wan2.2"):
-        current_dit_path = f"{high_noise_path_input}|{low_noise_path_input}" if high_noise_path_input and low_noise_path_input else None
-    else:
-        current_dit_path = dit_path_input
-
-    needs_reinit = lazy_load or unload_modules or global_runner is None or cur_dit_path != current_dit_path or cur_use_lora != use_lora
-
     config_graio = {
         "infer_steps": infer_steps,
         "target_video_length": num_frames,
@@ -207,22 +195,8 @@ def run_inference(
         "aspect_ratio": aspect_ratio,
     }
 
-    args = argparse.Namespace(
-        model_cls=model_cls,
-        seed=seed,
-        task=task,
-        model_path=model_path,
-        prompt=prompt,
-        negative_prompt=negative_prompt,
-        image_path=image_path,
-        save_result_path=save_result_path,
-        return_result_tensor=False,
-        aspect_ratio=aspect_ratio,
-        target_shape=[],
-    )
-    input_info = init_empty_input_info(args.task)
     config = get_default_config()
-    config.update({k: v for k, v in vars(args).items()})
+    config.update({"model_cls": model_cls, "task": task, "model_path": model_path})
     config.update(config_graio)
     config.update(model_config)
 
@@ -233,92 +207,62 @@ def run_inference(
     logger.info(f"Using model: {model_path}")
     logger.info(f"Inference config:\n{json.dumps(config, indent=4, ensure_ascii=False)}")
 
+    startup_config = {key: value for key, value in config.items() if key not in {"aspect_ratio", "target_video_length", "lora_configs"}}
+    lora_configs = config.get("lora_configs") or []
+
+    current_targets = {item.get("name") for item in current_lora_configs}
+    new_targets = {item.get("name") for item in lora_configs}
+    config_changed = current_startup_config != startup_config
+    # Wan2.2 switch_lora cannot remove an adapter from a branch.
+    lora_targets_changed = current_targets != new_targets
+    needs_reinit = global_runner is None or lazy_load or unload_modules or config_changed or lora_targets_changed
+
     # 初始化或重用 runner
     runner = global_runner
     if needs_reinit:
         if runner is not None:
+            global_runner = None
             del runner
-            torch.cuda.empty_cache()
-            gc.collect()
-
-        from lightx2v.infer import init_runner
-
-        runner = init_runner(config)
+            # Inference freezes the model graph; unfreeze it before collection.
+            gc.unfreeze()
+            cleanup_memory()
 
-        data = args.__dict__
-        update_input_info_from_dict(input_info, data)
-
-        current_config = config
-        cur_dit_path = current_dit_path
-        cur_use_lora = use_lora
-        cur_lora_path = lora_path
-
-        # 保存 Wan2.2 的 LoRA 路径
-        if model_cls.startswith("wan2.2"):
-            lora_configs = config.get("lora_configs")
-            if lora_configs:
-                lora_name_to_info = {item["name"]: item for item in lora_configs}
-                cur_high_lora_path = lora_name_to_info.get("high_noise_model", {}).get("path")
-                cur_low_lora_path = lora_name_to_info.get("low_noise_model", {}).get("path")
-            else:
-                cur_high_lora_path = None
-                cur_low_lora_path = None
+        runner = build_runner(config)
 
         if not lazy_load:
             global_runner = runner
-    else:
-        runner.config = config
-        data = args.__dict__
-        update_input_info_from_dict(input_info, data)
-
-        # 如果 use_lora 为 True 且 lora_path 变化了，调用 switch_lora
-        if use_lora:
-            lora_configs = config.get("lora_configs")
-            if model_cls.startswith("wan2.2") and lora_configs:
-                # 对于 Wan2.2 模型，从 lora_configs 中获取 high_noise 和 low_noise 的 LoRA 路径
-                lora_name_to_info = {item["name"]: item for item in lora_configs}
-                high_lora_path = None
-                high_lora_strength = 1.0
-                low_lora_path = None
-                low_lora_strength = 1.0
-
-                if "high_noise_model" in lora_name_to_info:
-                    high_lora_info = lora_name_to_info["high_noise_model"]
-                    high_lora_path = high_lora_info["path"]
-                    high_lora_strength = high_lora_info.get("strength", 1.0)
-
-                if "low_noise_model" in lora_name_to_info:
-                    low_lora_info = lora_name_to_info["low_noise_model"]
-                    low_lora_path = low_lora_info["path"]
-                    low_lora_strength = low_lora_info.get("strength", 1.0)
-
-                # 检查 high_lora_path 和 low_lora_path 是否变化
-                high_lora_changed = high_lora_path != cur_high_lora_path
-                low_lora_changed = low_lora_path != cur_low_lora_path
-
-                if high_lora_changed or low_lora_changed:
-                    if hasattr(runner, "switch_lora"):
-                        runner.switch_lora(
-                            high_lora_path=high_lora_path,
-                            high_lora_strength=high_lora_strength,
-                            low_lora_path=low_lora_path,
-                            low_lora_strength=low_lora_strength,
-                        )
-                        logger.info(f"Switched LoRA for Wan2.2: high={high_lora_path}, low={low_lora_path}")
-                        cur_high_lora_path = high_lora_path
-                        cur_low_lora_path = low_lora_path
-                    else:
-                        logger.warning("Runner does not support switch_lora method")
-            elif lora_path and lora_path != cur_lora_path:
-                lora_strength_val = float(lora_strength) if lora_strength is not None else 1.0
-                if hasattr(runner, "switch_lora"):
-                    runner.switch_lora(lora_path, lora_strength_val)
-                    logger.info(f"Switched LoRA to: {lora_path} with strength={lora_strength_val}")
-                else:
-                    logger.warning("Runner does not support switch_lora method")
-                cur_lora_path = lora_path
-
-    runner.run_pipeline(input_info)
+    elif lora_configs != current_lora_configs:
+        if model_cls.startswith("wan2.2"):
+            lora_by_name = {item["name"]: item for item in lora_configs}
+            high_lora = lora_by_name.get("high_noise_model", {})
+            low_lora = lora_by_name.get("low_noise_model", {})
+            switched = runner.switch_lora(
+                high_lora_path=high_lora.get("path"),
+                high_lora_strength=high_lora.get("strength", 1.0),
+                low_lora_path=low_lora.get("path"),
+                low_lora_strength=low_lora.get("strength", 1.0),
+            )
+        else:
+            switched = runner.switch_lora(lora_configs[0]["path"], lora_configs[0]["strength"])
+        if not switched:
+            raise RuntimeError("Failed to switch LoRA")
+
+    current_startup_config = startup_config
+    current_lora_configs = lora_configs
+
+    form_data = {
+        "prompt": prompt,
+        "negative_prompt": negative_prompt,
+        "image_path": image_path,
+        "seed": seed,
+        "save_result_path": save_result_path,
+        "return_result_tensor": False,
+        "aspect_ratio": aspect_ratio,
+        "target_video_length": num_frames,
+    }
+    supported_request_fields = runner.get_supported_request_fields(task)
+    input_info = runner.prepare_request({key: value for key, value in form_data.items() if key in supported_request_fields})
+    runner.run_request(input_info)
     cleanup_memory()
 
     return save_result_path

configs/cosmos3/cosmos3_nano_omni_action_fd_agibotworld.json

@@ -6,7 +6,7 @@
     "target_width": 640,
     "target_video_length": 17,
     "target_fps": 10.0,
-    "enable_cfg": true,
+    "enable_cfg": false,
     "action_mode": "forward_dynamics",
     "domain_name": "agibotworld",
     "view_point": "concat_view",

configs/cosmos3/cosmos3_nano_omni_action_fd_agibotworld_multichunk.json

@@ -6,7 +6,7 @@
     "target_width": 640,
     "target_video_length": 17,
     "target_fps": 10.0,
-    "enable_cfg": true,
+    "enable_cfg": false,
     "action_mode": "forward_dynamics",
     "domain_name": "agibotworld",
     "view_point": "concat_view",

configs/cosmos3/cosmos3_nano_omni_action_id_av.json

@@ -6,7 +6,7 @@
     "target_width": 832,
     "target_video_length": 61,
     "target_fps": 10.0,
-    "enable_cfg": true,
+    "enable_cfg": false,
     "action_mode": "inverse_dynamics",
     "domain_name": "av",
     "view_point": "ego_view",

configs/cosmos3/cosmos3_super_omni_action_fd_agibotworld.json

@@ -6,7 +6,7 @@
     "target_width": 640,
     "target_video_length": 17,
     "target_fps": 10.0,
-    "enable_cfg": true,
+    "enable_cfg": false,
     "action_mode": "forward_dynamics",
     "domain_name": "agibotworld",
     "view_point": "concat_view",

configs/cosmos3/cosmos3_super_omni_action_fd_agibotworld_multichunk.json

@@ -6,7 +6,7 @@
     "target_width": 640,
     "target_video_length": 17,
     "target_fps": 10.0,
-    "enable_cfg": true,
+    "enable_cfg": false,
     "action_mode": "forward_dynamics",
     "domain_name": "agibotworld",
     "view_point": "concat_view",

configs/cosmos3/cosmos3_super_omni_action_id_av.json

@@ -6,7 +6,7 @@
     "target_width": 832,
     "target_video_length": 61,
     "target_fps": 10.0,
-    "enable_cfg": true,
+    "enable_cfg": false,
     "action_mode": "inverse_dynamics",
     "domain_name": "av",
     "view_point": "ego_view",

configs/disagg/multi_node/wan22_i2v_distill_controller.json

@@ -43,7 +43,6 @@
     "low_noise_quantized_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
     "high_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step.safetensors",
     "low_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
-    "image_path": "/path/to/img_0.jpg",
     "disagg_mode": "controller",
     "disagg_config": {
         "bootstrap_addr": "192.168.0.166",

configs/disagg/multi_node/wan22_i2v_distill_decoder.json

@@ -43,7 +43,6 @@
     "low_noise_quantized_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
     "high_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step.safetensors",
     "low_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
-    "image_path": "/path/to/img_0.jpg",
     "disagg_mode": "decoder",
     "disagg_config": {
         "bootstrap_addr": "192.168.0.166",

configs/disagg/multi_node/wan22_i2v_distill_encoder.json

@@ -43,7 +43,6 @@
     "low_noise_quantized_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
     "high_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step.safetensors",
     "low_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
-    "image_path": "/path/to/img_0.jpg",
     "disagg_mode": "encoder",
     "disagg_config": {
         "bootstrap_addr": "192.168.0.166",

configs/disagg/multi_node/wan22_i2v_distill_transformer.json

@@ -43,7 +43,6 @@
     "low_noise_quantized_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
     "high_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step.safetensors",
     "low_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
-    "image_path": "/path/to/img_0.jpg",
     "disagg_mode": "transformer",
     "disagg_config": {
         "bootstrap_addr": "192.168.0.166",

configs/disagg/single_node/wan22_i2v_distill_controller.json

@@ -43,7 +43,6 @@
     "low_noise_quantized_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
     "high_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_high_noise_int8_lightx2v_4step.safetensors",
     "low_noise_original_ckpt": "/path/to/wan2.2_i2v_A14b_low_noise_int8_lightx2v_4step.safetensors",
-    "image_path": "/path/to/img_0.jpg",
     "disagg_mode": "controller",
     "disagg_config": {
         "bootstrap_addr": "127.0.0.1",

configs/dreamzero/dreamzero_droid_i2va.json

@@ -15,7 +15,6 @@
   "cross_attn_1_type": "dreamzero_cross_fa",
   "cross_attn_2_type": "dreamzero_cross_fa",
   "rms_norm_type": "torch",
-  "negative_prompt": "Vibrant colors, overexposed, static, blurry details, text, subtitles, style, artwork, painting, image, still, grayscale, dull, worst quality, low quality, JPEG artifacts, ugly, mutilated, extra fingers, bad hands, bad face, deformed, disfigured, mutated limbs, fused fingers, stagnant image, cluttered background, three legs, many people in the background, walking backwards.",
   "num_chunks": 15,
   "dit_step_mask": [true, true, true, false, false, false, true, false, false, false, true, false, false, true, true, true],
   "obs_cam_keys": [

configs/dreamzero/dreamzero_droid_i2va_dist_cfg.json

@@ -15,7 +15,6 @@
   "cross_attn_1_type": "dreamzero_cross_fa",
   "cross_attn_2_type": "dreamzero_cross_fa",
   "rms_norm_type": "torch",
-  "negative_prompt": "Vibrant colors, overexposed, static, blurry details, text, subtitles, style, artwork, painting, image, still, grayscale, dull, worst quality, low quality, JPEG artifacts, ugly, mutilated, extra fingers, bad hands, bad face, deformed, disfigured, mutated limbs, fused fingers, stagnant image, cluttered background, three legs, many people in the background, walking backwards.",
   "num_chunks": 15,
   "dit_step_mask": [true, true, true, false, false, false, true, false, false, false, true, false, false, true, true, true],
   "obs_cam_keys": [

configs/hunyuan_video_15/vsr/hy15_i2v_480p.json

@@ -13,6 +13,7 @@
         "flow_shift": 2.0,
         "base_resolution": "480p",
         "guidance_scale": 1.0,
+        "enable_cfg": false,
         "num_inference_steps": 6,
         "use_meanflow": true
     }

configs/minimax_h3/dmd/minimax_h3_bf16_4step_single_gpu_offload.json → configs/minimax_h3/dmd/minimax_h3_bf16_4step.json

@@ -1,5 +1,5 @@
 {
-  "infer_steps": 5,
+  "infer_steps": 4,
   "target_video_length": 362,
   "target_height": 768,
   "target_width": 1344,
@@ -22,13 +22,10 @@
   "h3_step_update": "training_euler",
   "vae_spatial_scale_factor": 16,
   "audio_sampling_rate": 32000,
-  "audio_latents_per_second": 40,
-  "audio_channels": 2,
-  "keep_latents_dtype_in_scheduler": true,
   "lora_dynamic_apply": true,
   "lora_configs": [
     {
-      "path": "lightx2v/Minimax-h3-Turbo/minimax_h3_fl2v_turbo_4step_v1.0_768p_bf16.safetensors",
+      "path": "/path/to/minimax_h3_fl2v_turbo_4step_v1.0_768p_bf16.safetensors",
       "strength": 1.0,
       "alpha": 128
     }