abliterix 1.12.2

7% refusal rate on Gemma 4  ·  0.0006 KL divergence  ·  150+ model configs  ·  Zero manual tuning

🔥 Breaks DeepRefusal (EMNLP 2025) and Circuit Breakers / Representation Rerouting (NeurIPS 2024) — same lerp-then-abliterate recipe, zero fine-tuning

Abliterix finds the optimal abliteration parameters for any transformer model using Optuna TPE optimization. It co-minimizes refusals and KL divergence from the original model — producing decensored models that retain as much intelligence as possible. Works with dense, MoE, SSM/hybrid, and vision-language architectures, with 150+ pre-built configs.

It also ships HonestAbliterationBench, a reproducible public benchmark that resists the two failure modes (short generations + keyword-only judges) that make most abliteration leaderboards meaningless.

Table of Contents

• Quick Start
• Stable and Reproducible by Default
• How It Works
• Broken Defenses
• Results
• Honest Abliteration Leaderboard
• Model Support
• Hardware & VRAM
• Datasets
• Documentation
• Citation
• Acknowledgments
• Contributing
• Community
• License

Quick Start

pip install -U abliterix
abliterix --model Qwen/Qwen3-4B-Instruct-2507

That's it. The process is fully automatic — after optimization completes, you can save the model, upload to Hugging Face, or chat with it interactively.

The default evaluator is deterministic and offline. For a semantic LLM-judge audit, opt in explicitly; the credential is checked before any model is loaded:

export OPENROUTER_API_KEY=...
abliterix --model Qwen/Qwen3-4B-Instruct-2507 --detection.llm-judge

Reproducible install (recommended): Abliterix uses uv and commits a uv.lock pinning every dependency, plus a [tool.uv] exclude-newer cutoff so lock regeneration can't drift onto a newer dep that breaks the GPU path. If you use uv, clone the repo and run uv run abliterix --model <model> to get the exact dependency set the maintainers tested against.

Windows: use python scripts/run_abliterix.py --model <model> or set PYTHONIOENCODING=utf-8 to avoid Rich encoding issues.

Stable and Reproducible by Default

Abliterix resolves every remote model and dataset input to an immutable Hugging Face commit before loading it. The HF default uses orthogonal projection plus full row-norm preservation; vLLM automatically uses pre, the strongest normalization its rank-1 projection cache can materialize. A global seed controls search and randomized low-rank operations.

Published reproducibility manifests use schema v2 and include the resolved configuration, exact winning-trial steering recipe, model/dataset commits, environment, metrics, and model-weight SHA256 values. The reproducible tag is only added when all inputs are pinned, the source tree is clean, the evaluator is deterministic, and the backend supports exact materialization.

# Exact replay: verifies manifest integrity, applies the winning trial without
# searching, then independently re-measures KL divergence and refusal count.
abliterix --reproduce reproduce/reproduce.json

# Headless optimization + exact best-trial export + hashes + manifest.
abliterix --model org/model --non-interactive \
  --non-interactive-output-dir ./verified-model

CI also runs a commit-pinned tiny model twice, requires identical exported weight hashes, and verifies exact manifest replay. See tests/e2e/ and the Heretic parity audit.

How It Works

Abliterix modifies model internals rather than relying on prompt-level jailbreaks. Its basic assumption is that benign prompts and prompts that trigger refusal produce measurably different activation patterns in the model's residual stream.

For each layer, let $g$ be the mean activation for benign prompts and $b$ the mean activation for target prompts. The simplest refusal direction is:

$$ r = \frac{b-g}{\lVert b-g \rVert_2} $$

Abliteration removes weight components aligned with this direction. A simplified input-side transformation is:

$$ W' = W-\alpha(Wr)r^\top $$

where $\alpha$ controls the intervention strength. In practice, Abliterix can apply the corresponding projection on either side of a weight matrix, depending on whether a module reads from or writes to the residual stream.

The automated pipeline is:

1. Extract activations — run benign and target prompt sets through the original model and capture hidden states from every layer.
2. Derive steering vectors — compute a refusal direction or subspace using mean difference, PCA, SRA, SAE, SOM, optimal transport, RDO, or other configured methods.
3. Apply candidate edits — modify attention, MLP, and, where applicable, MoE expert/router components using reversible LoRA adapters, direct weight projections, or runtime steering hooks.
4. Evaluate the trade-off — count refusals on target prompts while measuring KL divergence and generation quality against the untouched model on benign prompts.
5. Optimize automatically — use Optuna TPE to search layer locations, component strengths, decay profiles, vector scope, and MoE routing parameters. The result is a Pareto frontier balancing fewer refusals against less behavioral drift.

In short, Abliterix identifies refusal-related geometry in hidden space, suppresses it in the model, and automatically searches for the least damaging effective intervention. See docs/architecture.md for the full pipeline and docs/methods.md for the available steering methods.

Broken Defenses

Abliterix has end-to-end broken three of the strongest published "anti-abliteration" releases with the same minimal recipe: SVD-diagnose the rank-16 LoRA delta, lerp it away with λ=0.0 (bit-exact base weights), then run single-direction direct-mode abliteration. No fine-tuning, no iterative subspace, no SOM, no manual prompt engineering. Full lessons-learned write-up: docs/broken_defenses.md.

Full write-ups, attack recipes, and reproduction commands: docs/broken_defenses.md.

Results

Abliterated models uploaded to Hugging Face:

Numbers worth ~20× the average abliteration leaderboard. Most published refusal rates collapse under longer generations and a real judge — see docs/evaluation.md for the methodology, and the leaderboard below for community submissions vetted under the same contract.

Honest Abliteration Leaderboard

A reproducible public benchmark for abliterated models built on the same pipeline. Every row is generated under a frozen contract (min_new_tokens=100, max_new_tokens=150, greedy, LLM judge with degenerate filter, KL measured against the declared base) — see benchmarks/SPEC.md for the full spec and benchmarks/CONTRIBUTING.md for how to submit a row.

No results yet. See benchmarks/CONTRIBUTING.md for how to submit one.

Model Support

Abliterix ships with 150+ pre-built configs covering 4 architecture types across 20+ model families:

Generate configs for new models:

python scripts/generate_configs.py                 # Generate all missing configs
python scripts/generate_configs.py --family llama   # Only Llama family

For MoE-specific steering mechanisms (EGA, expert profiling, router suppression), see docs/moe.md.

Hardware & VRAM

Abliterix auto-detects available accelerators (CUDA, XPU, MLU, MUSA, SDAA, NPU, MPS) and distributes layers across devices with device_map = "auto".

For large models:

• 4-bit quantization: --model.quant-method bnb_4bit cuts VRAM by ~4x (LoRA mode; the quantised base stays frozen and the ablation rides in a BF16 adapter)
• 8-bit quantization: --model.quant-method bnb_8bit — higher quality than 4-bit, ~2x VRAM reduction with CPU offload
• Native FP4 models (gpt-oss MXFP4, DeepSeek-V4-Flash routed experts): abliterate and re-pack without a BF16 blow-up via abliterix-abliterate-fp4 — the output stays 4-bit and serves natively on vLLM. Validated end to end on gpt-oss-20b. core.frozen_experts additionally lets the search run against packed 4-bit weights by applying the rank-1 EGA edit at forward time instead of mutating weights. See docs/fp4_repack.md.
• Per-device memory limits: set [model] max_memory = {"0": "20GB", "cpu": "64GB"} in your config
• Non-interactive mode: --non-interactive for fully automated batch runs

Datasets

Bilingual harm/benign evaluation datasets live in datasets/ and on Hugging Face at wangzhang/abliterix-datasets. The 500-example sets (harmful_500, good_500) are the recommended starting point — they're also the SHA256-pinned inputs to HonestAbliterationBench.

See docs/datasets.md for the design rationale, category breakdown, and a comparison with public alternatives.

Documentation

The deep details live in docs/ and benchmarks/:

• docs/architecture.md — the 9 papers Abliterix integrates and the 5-step pipeline.
• docs/methods.md — every steering method (SRA, Spherical, SVF, Projected, Discriminative, COSMIC, Angular, OT, Multi-direction) with the TOML knobs that control it.
• docs/method_maturity.md — evidence levels for every method, from implementation to leading claims.
• docs/evaluation.md — why most abliteration benchmarks lie, our standards, and the architecture A/B test.
• docs/evidence_resources.md — GPU/API/storage resources needed to turn method claims into reproducible evidence.
• docs/moe.md — the four independent MoE steering mechanisms and supported MoE models.
• docs/fp4_repack.md — abliterate native FP4 (MXFP4/NVFP4) models and re-pack to 4-bit offline, no BF16 blow-up.
• docs/configuration.md — config loading order, the 150+ shipped configs, the Web UI, and research-mode visualization.
• docs/datasets.md — bilingual dataset design rationale and metadata schema.
• docs/references.md — paper references and BibTeX.
• docs/benchmarks/2026-05-pod-validation.md — measured 10-feature sweep on Qwen2.5-7B-Instruct with LLM judge (Blackwell GPU).
• benchmarks/METHOD_MATRIX.md — cross-model method matrix for promoting methods through the maturity ladder.
• benchmarks/SPEC.md — the frozen HonestAbliterationBench contract (spec_version 1.1).
• benchmarks/CONTRIBUTING.md — how to submit a leaderboard row (self-reported / verified tiers).

Citation

@software{abliterix,
  author = {Wu, Wangzhang},
  title = {Abliterix: Automated LLM Abliteration},
  year = {2026},
  url = {https://github.com/wuwangzhang1216/abliterix}
}

Acknowledgments

Abliterix is a derivative work of Heretic by Philipp Emanuel Weidmann (@p-e-w), licensed under AGPL-3.0-or-later. The original Heretic codebase provided the foundation for this project; Abliterix extends it with Optuna-based multi-objective optimization, LoRA-based steering, MoE architecture support, orthogonal projection, LLM judge detection, and additional model integrations.

All modifications are Copyright (C) 2026 Wangzhang Wu and are released under the same AGPL-3.0-or-later license. See NOTICE for details.

@misc{heretic,
  author = {Weidmann, Philipp Emanuel},
  title = {Heretic: Fully automatic censorship removal for language models},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/p-e-w/heretic}}
}

Contributing

Contributions of all kinds are welcome — new model configs, benchmark results, bug reports, documentation, new steering methods. See CONTRIBUTING.md for development setup, the PR process, and guidance on adding model configs.

The single most impactful contribution is a tested TOML config for a model we don't yet support. Every new config unlocks a new architecture for everyone.

All contributions are released under the AGPL-3.0 license.

Community

• Questions & ideas: GitHub Discussions
• Bugs & feature requests: GitHub Issues
• Share your models: tag models you publish with abliterix on the Hugging Face Hub so others can find them — browse the growing list at huggingface.co/models?other=abliterix. Uploading through the built-in menu adds this tag (plus a reproducible tag and a reproduce/ manifest) automatically.

License

Abliterix is a derivative work of Heretic by Philipp Emanuel Weidmann, licensed under the GNU Affero General Public License v3.0 or later.

Original work Copyright (C) 2025 Philipp Emanuel Weidmann Modified work Copyright (C) 2026 Wangzhang Wu