abliterix

---

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.

Safety and Responsible Use

[!WARNING] Abliterix intentionally modifies model internals to reduce refusal behavior. This can weaken or remove safeguards and may cause resulting models to generate inaccurate, biased, offensive, explicit, dangerous, or illegal content.

Abliterix is experimental research software. You are responsible for evaluating any resulting model, complying with applicable laws and third-party terms, and deploying appropriate safeguards. Do not rely on generated outputs for medical, legal, financial, safety-critical, or other high-stakes decisions without qualified human review.

Before use or deployment, read the full Safety, Responsible Use, and Disclaimer Notice. The software is provided "AS IS", without warranty, under Sections 15–17 of the AGPL-3.0-or-later. The safety guidance does not add restrictions to the rights granted by the AGPL.

Table of Contents

• Safety and Responsible Use
• 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.

Defense	Released model	Best trial	ASR (LLM judge)	Hardcore 15
DeepRefusal (EMNLP 2025)	Llama-3-8B-Instruct-DeepRefusal-Broken ⚔️	11/100 refusals, KL 0.053	89 %	14 / 15
Circuit Breakers / RR (NeurIPS 2024)	Mistral-7B-Instruct-RR-Abliterated ⚔️	12/100 refusals, KL 0.042	88 %	15 / 15
Circuit Breakers / RR (NeurIPS 2024)	Llama-3-8B-Instruct-RR-Abliterated ⚔️	1/100 refusals, KL 0.017	99 %	15 / 15

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

Results

Abliterated models uploaded to Hugging Face:

Model	Refusals	KL Divergence	Trials	Method
Llama-3-8B-Instruct-DeepRefusal-Broken ⚔️	11/100 (11%)	0.053	60	LoRA-Δ attenuation + Direct
Mistral-7B-Instruct-RR-Abliterated ⚔️	12/100 (12%)	0.042	60	Full LoRA-Δ strip + Direct
Llama-3-8B-Instruct-RR-Abliterated ⚔️	1/100 (1%)	0.017	60	Full LoRA-Δ strip + Direct
Qwen3.6-35B-A3B	7/100 (7%)	0.0189	24	LoRA + EGA + MoE
Qwen3.6-27B-abliterated (GGUF)	10/100 (10%)	0.0242 (cumulative)	30 + 30	LoRA + manual iterative peel
Qwen3.6-27B-abliterated	10/100 (10%)	0.0061	30	LoRA + unified GDN/full-attn bucket
gpt-oss-20b	6/100 (6%)	0.0098	100	Direct + EGA + Router
gpt-oss-120b	26/100 (26%)	5.4e-06	100	Direct + EGA + Router + vLLM-TP
Gemma-4-E4B	7/100 (7%)	0.0006	100	Direct + Q/K/V/O
Gemma-4-E2B	9/100 (9%)	0.0004	100	Direct + Q/K/V/O
Gemma-4-31B	3/100 (3%)	0.0012	120	SRA + Direct
LFM2-24B-A2B	0/100 (0%)	0.0079	50	LoRA
GLM-4.7-Flash	1/100 (1%)	0.0133	50	LoRA
Devstral-Small-2-24B	3/100 (3%)	0.0086	50	LoRA
Qwen3.5-122B-A10B	1/200 (0.5%)	0.0115	25	LoRA + MoE
Qwen3.5-35B-A3B	3/200 (1.5%)	0.0035	50	LoRA + MoE
Qwen3.5-27B	3/200 (1.5%)	0.0051	35	LoRA
Qwen3.5-9B	2/200 (1%)	0.0105	50	LoRA
Qwen3.5-4B	3/200 (1.5%)	0.0065	50	LoRA
Qwen3.5-0.8B	0/200 (0%)	0.0087	100	LoRA

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:

Architecture	Families	Example Models
Dense	Llama, Gemma, Phi, Qwen, Mistral, Yi, InternLM, Falcon, Cohere, EXAONE, Granite, OLMo, SmolLM, SOLAR, Zephyr	Llama-3.1-405B, Gemma-3-27B, Phi-4, DeepSeek-R1-Distill
MoE	Qwen3/3.5/3.6 MoE, Mixtral, DeepSeek, Phi-3.5-MoE, Granite MoE, DBRX, Llama-4 Scout/Maverick, gpt-oss (MXFP4)	gpt-oss-120b, Qwen3.6-35B-A3B, Qwen3.5-122B, Mixtral-8x22B, Llama-4-Maverick-401B
SSM/Hybrid	Jamba (Mamba+attention), Nemotron-Cascade (Mamba-2+attention)	Jamba-1.5-Large-94B, Nemotron-Cascade-30B
Vision-Language	Qwen2-VL, InternVL2, LLaVA-NeXT, Pixtral, Mistral3-VL	Qwen2-VL-7B, LLaVA-NeXT-34B, Pixtral-12B

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.

For native DeepSeek-V4 and GLM-5.3-Flash multi-stream readouts, use the separate runtime profile and review the validation scope. Tiny native models are tested through the HF engine on CPU and CUDA; full released-checkpoint and quality acceptance remain open in #19.

The same runtime includes native Kimi wrapper tests for loading, modification, and export with small local models. Full K2.5/K2.6 checkpoint acceptance is tracked in #16.

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

Default runs use the public mlabonne/harmless_alpaca and mlabonne/harmful_behaviors datasets. Historical recipes also reference local bilingual good_* / harmful_* corpora for vector extraction and trial scoring. Those corpora are not bundled in this repository, and their historical Hugging Face location was not publicly retrievable in our 2026-11-01 access check. The original harmful_500 / good_500 files are required to reproduce the SHA256-pinned HonestAbliterationBench protocol; substitute datasets produce different results.

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.
• November 2026 evaluation reliability review — current research, bounded-memory KL, benchmark integrity, and measured performance tradeoffs.
• 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 — current public defaults, prompt roles, and historical bilingual corpus availability. Bilingual coverage requires supplying those datasets; it is not included automatically.
• docs/minimax-h3.md — source-preserving video Prompt Sets, media manifests, and the H3 training boundary.
• docs/video-dataset-audit-2026-08.md — historical video dataset report and current validation limitations.
• 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
• Security vulnerabilities: follow the private reporting process in SECURITY.md
• 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