Captured at (local ISO): 2026-05-18 05:17:30

Preface

Flux.1-dev is among the strongest open text-to-image models, but 24GB+ parameters make 24GB VRAM (e.g. 3090/4090) setups crash easily. This guide distills real troubleshooting: ModelScope fast download, automatic auth, and sequential CPU offload for a stable single-GPU workflow.

1. Core dependencies

To avoid sentencepiece missing, PEFT backend errors, etc., install once:

# 1. Upgrade core libs
pip install --upgrade diffusers transformers accelerate 

# 2. Tokenizer & LoRA backend (required for load)
pip install sentencepiece protobuf peft

# 3. Download tools
pip install modelscope huggingface_hub

2. Model access and login (required)

Flux.1-dev is gated; you must authenticate before download.

2.1 Web approval

1. Log in to Hugging Face.
2. Open FLUX.1-dev and click “Agree and access repository”. (Screenshot uses FLUX.2 as example if you already agreed.)
   
3. In Settings -> Tokens create a Read token named flux and copy it.
   
   
   Choose scopes as needed; selecting all is fine if unsure.
   

2.2 CLI login

Before downloading, log in on the server:

huggingface-cli login

• “Enter your token”: paste the token (no echo on screen), then Enter.
• “Add token as git credential?”: type n.

3. Fast download (China CDN)

Use ModelScope mirror instead of slow Hugging Face links.

3.1 Base model (~35GB)

mkdir -p ~/workspace/FLUX.1-dev
cd ~/workspace/FLUX.1-dev

modelscope download --model AI-ModelScope/FLUX.1-dev --local_dir .

3.2 360° cockpit LoRA

mkdir -p ~/workspace/lora-cockpit
cd ~/workspace/lora-cockpit

modelscope download --model AI-ModelScope/cockpit-360-lora-flux-dev --local_dir .

4. Inference script (fix OOM)

On 24GB VRAM, normal full-GPU load often OOMs. Use enable_sequential_cpu_offload()—space for time.

Create generate_360.py:

import torch
from diffusers import FluxPipeline
import datetime
import os

# 1. VRAM: expandable segments
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"

# 2. Local paths
base_model_path = "/root/workspace/FLUX.1-dev"
lora_path = "/root/workspace/lora-cockpit"

print(f"[{datetime.datetime.now()}] Loading Flux from disk...")

# 3. Load offline
pipe = FluxPipeline.from_pretrained(
    base_model_path, 
    torch_dtype=torch.bfloat16,
    local_files_only=True
)

# 4. Sequential CPU offload — practical way to run Flux on 24GB
pipe.enable_sequential_cpu_offload()

print(f"[{datetime.datetime.now()}] Loading 360° LoRA...")
pipe.load_lora_weights(lora_path)

# 5. Prompt and size
prompt = "A 360 degree equirectangular panorama of a high-tech spaceship cockpit, glowing blue console, detailed controls, stars outside, 8k"
width = 2048
height = 1024

print(f"[{datetime.datetime.now()}] Inferencing (slower in offload mode)...")

with torch.inference_mode():
    torch.cuda.empty_cache()
    image = pipe(
        prompt, 
        width=width, 
        height=height, 
        num_inference_steps=28, 
        guidance_scale=3.5
    ).images[0]

# 6. Save
image.save("cockpit_360_final.png")
print(f"[{datetime.datetime.now()}] Done. Saved cockpit_360_final.png")

5. Sample output

6. FAQ

1. OSError: model_index.json not found: incomplete ModelScope download—re-run download.
2. sentencepiece error: pip install sentencepiece.
3. CUDA out of memory:
   • Lower resolution first (e.g. 1024×512).
   • Use enable_sequential_cpu_offload(), not enable_model_cpu_offload().
4. 403 auth: agree on the website and confirm huggingface-cli login succeeded.