Instructions to use BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5 with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Notebooks
Google Colab
Kaggle
Local Apps Settings

How to use BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5 with llama.cpp:

Install (macOS, Linux)

curl -LsSf https://llama.app/install.sh | sh
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M
# Run inference directly in the terminal:
llama cli -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Install from WinGet (Windows)

winget install llama.cpp
# Start a local OpenAI-compatible server with a web UI:
llama serve -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M
# Run inference directly in the terminal:
llama cli -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Use pre-built binary

# Download pre-built binary from:
# https://github.com/ggerganov/llama.cpp/releases
# Start a local OpenAI-compatible server with a web UI:
./llama-server -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M
# Run inference directly in the terminal:
./llama-cli -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Build from source code

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build -j --target llama-server llama-cli
# Start a local OpenAI-compatible server with a web UI:
./build/bin/llama-server -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M
# Run inference directly in the terminal:
./build/bin/llama-cli -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Use Docker

docker model run hf.co/BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

LM Studio
Jan
Ollama
How to use BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5 with Ollama:
```
ollama run hf.co/BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M
```
Unsloth Desktop

How to use BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5 with Pi:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Configure the model in Pi

# Install Pi:
npm install -g @earendil-works/pi-coding-agent
# Add to ~/.pi/agent/models.json:
{
  "providers": {
    "llama-cpp": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M"
        }
      ]
    }
  }
}

Run Pi

# Start Pi in your project directory:
pi

Docker Model Runner
How to use BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5 with Docker Model Runner:
```
docker model run hf.co/BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M
```

Lemonade

How to use BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5 with Lemonade:

Pull the model

# Download Lemonade from https://lemonade-server.ai/
lemonade pull BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Run and chat with the model

lemonade run user.Qwen3-4b-Z-Image-Engineer-V2.5-Q4_K_M

List all available models

lemonade list

Hermes Agent

How to use BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5 with Hermes Agent:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Configure Hermes

# Install Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup
# Point Hermes at the local server:
hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:8080/v1
hermes config set model.default BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Run Hermes

hermes

Atomic Chat

OpenClaw

How to use BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5 with OpenClaw:

Start the llama.cpp server

# Install llama.cpp:
brew install llama.cpp
# Start a local OpenAI-compatible server:
llama serve -hf BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M

Configure OpenClaw

# Install OpenClaw:
npm install -g openclaw@latest
# Register the local server and set it as the default model:
openclaw onboard --non-interactive --mode local \
  --auth-choice custom-api-key \
  --custom-base-url http://127.0.0.1:8080/v1 \
  --custom-model-id "BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5:Q4_K_M" \
  --custom-provider-id llama-cpp \
  --custom-compatibility openai \
  --custom-text-input \
  --accept-risk \
  --skip-health

Run OpenClaw

openclaw agent --local --agent main --message "Hello from Hugging Face"

A newer version of this model is available: BennyDaBall/Qwen3-4b-Z-Image-Engineer-V4

🚀 Z-Engineer V2.5 (4B)

Follow me on X @BennyDaBall_OG !

The "Z-Engineer" is back — longer, deeper, and smarter.

This is Z-Engineer V2.5, a specialized 4B parameter model fine-tuned on the Qwen 3 architecture. It serves as a dedicated Creative Director for your image generation workflow, capable of extrapolating complex, cohesive visual narratives from minimal seed concepts. It doesn't just describe a scene; it engineers the light, lens, and atmosphere necessary to render it.

🧠 What is this?

Z-Engineer V2.5 is a merged LoRA fine-tuned version of high-performance text encoder from Tongyi-MAI/Z-Image-Turbo. It has been trained to specifically understand the nuances of AI Image Generation (Z-Image-Turbo, Flux2 Klein). It excels at:

Expanding Concepts: Turn "dog on a bike" into a cinematic narrative.
Technical Precision: It understands lenses (35mm vs 85mm), lighting (rembrandt, volumetric), and film stocks.
Stylistic Consistency: It avoids the robotic "AI feel" and writes with a distinct, creative voice.

🔑 Key Use Cases

✨ Prompt Enhancement: A lightweight, low-VRAM solution to create, edit, and enrich simple image ideas into detailed narratives.
🔌 Z-Image Turbo Encoder: Fully backwards compatible as a drop-in CLIP text encoder for Z-Image Turbo workflows, producing varied and unique results from the same seed.
🛡️ Local & Private: Runs entirely on your machine. No API fees, no data logging, no censorship.
⚡ Hybrid Power: Use it to expand a prompt, then use the model itself as the encoder for the generation stage.

📉 Key Improvements

Base Model Upgrade: Switched from standard Qwen3 Instruct to the native text encoder from Z-Image-Turbo for perfect alignment.
All-Layer Training: Unlike typical lightweight LoRAs, I trained adapters on all 36 layers of the model, ensuring deep behavioral alignment.
Massive Iteration Count: Trained for 10,000 iterations to fully saturate the weights with the dataset concepts.

📊 CLIP Model Comparison

Z-Engineer V2.5 can be used as a drop-in CLIP text encoder for Z-Image-Turbo workflows. Here's how it compares to previous versions and the base model:

Model	Result
Z-Engineer V2.5	✅ Clean, natural output with excellent detail and coherence.
Z-Engineer V2	✅ Good quality, but V2.5 shows improved texture and lighting.
Z-Engineer V1	❌ Broken: Produces severe visual artifacts and distortions.
Base Qwen3 4B	⚠️ Functional but generic; lacks the specialized prompt understanding.

Visual Comparison

Note: V1 exhibits catastrophic artifacts (bottom-left in each grid) due to training instabilities. V2.5 (top-left) consistently produces the cleanest, most natural results.

🔌 ComfyUI Integration (Recommended)

I have released a custom node for seamless integration with ComfyUI!

Features: Optimized for local OpenAI API compatible backends (LM Studio, Ollama, etc.).
Get it here: ComfyUI-Z-Engineer

💻 Training Facts

I believe in open science. Here is exactly how this was built:

Hardware: Trained locally on a Mac with 48GB Unified Memory (Apple Silicon).
Framework: MLX (Apple's native machine learning framework).
Dataset: Generated locally using Qwen3 VL 30B A3B Instruct
- Size: ~34,678 high-quality examples.
- Content: A curated mix of "Prompt Enhancement" pairs, teaching the model how to take a seed idea and "engineer" it into a final prompt.
Hyperparameters:
- Iterations: 10,000
- Batch Size: 4
- LoRA Layers: 36 (All Linear Layers)
- Learning Rate: 1e-5

📦 GGUF & Quantization

I provide a full suite of GGUF quantizations for use with llama.cpp, Ollama, and LM Studio.

Quantization	Size	Use Case
Q4_K_S	2.2 GB	🔻 Max Compression
Q4_K_M	2.3 GB	⚡️ Fast / Mobile / Edge
Q5_K_M	2.7 GB	⚖️ Recommended Balance
Q6_K	3.1 GB	💎 High Quality
Q8_0	4.0 GB	🎬 Near-Lossless
F16	7.5 GB	🧪 Reference / Conversion

⚠️ Disclaimer

This model generates text for image prompts. While I have filtered the dataset, users should use their best judgment. I am not responsible for the content you generate.

Follow me on X @BennyDaBall_OG !

Downloads last month: 1,305

GGUF

Model size

4B params

Architecture

qwen3

Hardware compatibility

4-bit

5-bit

6-bit

8-bit

View +1 variant

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support

Model tree for BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5

Base model

Tongyi-MAI/Z-Image-Turbo

Quantized

(73)

this model

Collection including BennyDaBall/Qwen3-4b-Z-Image-Engineer-V2.5

Z-Image-Engineer

Collection

Various versions of my Z-Image-Engineer models. • 11 items • Updated Jun 6 • 11