docs/INFERENCE.md

# Inference

Run commands from the repository root. The four upstream projects do not
necessarily share one dependency set, so separate virtual environments are
recommended.

## 1. Download the HandEdit adapters

Download and extract all four sanitized LoRA adapters:

```bash
python scripts/download_weights.py
```

You can verify an existing local copy with:

```bash
python scripts/verify_weights.py
```

The base models are not bundled. Download them from their official projects and
follow the corresponding licenses and access requirements.

## 2. LongCat-Image-Edit

Install the shared dependencies:

```bash
pip install -r requirements.txt
```

Run batch inference:

```bash
python scripts/infer_longcat_lora.py \
  --input_dir ./examples/input \
  --output_dir ./outputs/longcat \
  --skip_existing
```

The default base model is `meituan-longcat/LongCat-Image-Edit`. Use `--base`
to point to a local model directory, and add `--local_files_only` for an
offline cache.

## 3. OmniGen-v1

Install the official OmniGen repository in its own environment:

```bash
git clone https://github.com/VectorSpaceLab/OmniGen.git third_party/OmniGen
pip install -e third_party/OmniGen
pip install peft pillow
```

Run:

```bash
python scripts/infer_omnigen_lora.py \
  --input_dir ./examples/input \
  --output_dir ./outputs/omnigen \
  --offload_model \
  --skip_existing
```

The default base model is `Shitao/OmniGen-v1`.

## 4. FLUX.2 Klein Base 4B

Install the shared dependencies:

```bash
pip install -r requirements.txt
```

Run:

```bash
python scripts/infer_flux2_lora.py \
  --input_dir ./examples/input \
  --output_dir ./outputs/flux2 \
  --skip_existing
```

The default base model is
`black-forest-labs/FLUX.2-klein-base-4B`. The script uses model CPU offload by
default; select `--offload sequential` for lower VRAM or `--offload none` for
maximum speed on a sufficiently large GPU.

## 5. Step1X-Edit

Clone and install the official repository in its own environment:

```bash
git clone https://github.com/stepfun-ai/Step1X-Edit.git third_party/Step1X-Edit
pip install -r third_party/Step1X-Edit/requirements.txt
```

Prepare the official base-model directory expected by Step1X:

```text
weights/Step1X-Edit/
├── Qwen2.5-VL-7B-Instruct/
├── step1x-edit-i1258.safetensors
└── vae.safetensors
```

Run:

```bash
python scripts/infer_step1x_lora.py \
  --repo_dir ./third_party/Step1X-Edit \
  --model_dir ./weights/Step1X-Edit \
  --input_dir ./examples/input \
  --output_dir ./outputs/step1x \
  --version v1.0 \
  --quantized \
  --offload \
  --skip_existing
```

## Shared edit instruction

The scripts use the following default instruction:

> Edit only the human hand region. Replace the human hand with a realistic
> Inspire robotic hand with correct robotic finger structure and joints.
> Preserve the original wrist pose, palm orientation, finger articulation,
> grasp geometry, and contact points with the object. Keep the object,
> background, lighting, camera viewpoint, and all non-hand regions unchanged.

Override it with `--prompt` when needed.