heretic

heretic — Abliteration の自動化と拒否方向の解釈可能性

キーワード：heretic · abliterate · decensor a model · remove refusals · refusal direction · plot residuals

責任ある利用について。Heretic は、研究および変更する権利を持つモデルのカスタマイズを目的とする AGPL-3.0 ソフトウェアです。重みをダウンロード、変更、アップロード、提供する際は、各ベースモデルのライセンスと、各プラットフォームの利用規約を遵守してください。Abliteration は、真に有害なトピックを含むすべてのトピックに対するモデルの拒否率を下げます。違法コンテンツ（例：CSAM、大量破壊兵器の能力向上、標的型ハラスメント）を生成するモデルの作成や、契約上従う義務がある安全管理策の回避には使用しないでください。正当な用途には、解釈可能性・アラインメント研究、レッドチーミング、無害なリクエストに対する過剰拒否の軽減、合法的な作業のために自身のハードウェア上で検閲されていないモデルを実行することなどがあります。

heretic は、p-e-w/heretic ツール（AGPL-3.0）を、インストール可能な jeo-skills プラグインとしてパッケージ化したものです。Heretic は、パラメーター化された方向性アブレーションの変種（abliteration、Arditi et al. 2024 に基づく）を実装しています。有害なプロンプトと無害なプロンプトの最初のトークンの残差の平均差から、レイヤーごとの「拒否方向」を算出し、注意機構の出力射影行列と MLP のダウン射影行列をその方向に対して直交化します。これにより、ファインチューニングや事後学習を行わずに拒否を抑制します。**TPE オプティマイザー（Optuna）**がアブレーションカーネルを探索し、元のモデルからの KL ダイバージェンスを低く保ちながら拒否を最小化するため、このプロセスは完全に自動で、設定は不要です。

このスキルはルーティングを優先します。リクエストに対して実用可能な最小のモードを選び、上記の責任ある利用に関するガードレールを念頭に置き、ウェブを使った探索・調査は scrapling 経由で行ってください。

---

使用する場合／使用しない場合

ユーザーが次のことを求めている場合は heretic を使用します。

• オープンウェイトモデル（Qwen、Llama、Gemma、gpt-oss、Mistral、…）の検閲解除／abliteration／拒否解除。
• 性能を維持しながら、無害なリクエストに対する過剰拒否を減らす（KL ダイバージェンスを低く保つ）。
• アブレーションの調整：試行回数の予算、KL ターゲット、VRAM に収まる量子化、実行後のチャット／評価／アップロード。
• モデルの測定：有害なプロンプトに対する拒否数と、元のモデルとの KL ダイバージェンス。
• 解釈可能性の研究：拒否方向の幾何学、残差幾何学の指標、PaCMAP プロット。

ここにはルーティングしないでください（直接回答するか、別の場所にルーティングしてください）。

• 「すでに検閲されていないダウンロード可能なモデルを推薦して」→直接回答する（HF の ?other=heretic を案内）。
• 一般的な LLM のファインチューニング／RLHF／DPO →これはトレーニングであり、アブレーションではありません（別のツールを使用）。
• 目的として考えられるものが、真に違法または有害なコンテンツの生成だけであるリクエスト →断ってください。

---

モード（要件を満たす最小のものを選択）

モード	トリガー	コマンド／アクション
decensor (デフォルト)	「<model>をabliterate／検閲解除して」	heretic <model> — 完全自動。その後、保存／アップロード／チャット／評価を選択
configure	「16GB に収めて」「試行回数を増やして」「性能の低下を抑えて」	config.*.toml を編集するか、フラグ（--quantization bnb_4bit、--n-trials、--kl-divergence-target）を渡す
evaluate	「どれくらい検閲されているか／うまくいったか」	heretic --model <orig> --evaluate-model <candidate> →拒否数＋KL
research	「残差をプロットして」「拒否の幾何学」	pip install -U 'heretic-llm[research]' を実行。--plot-residuals／--print-residual-geometry を使用
discover (scrapling)	「ベースモデル／既存の heretic モデル／ベンチマークを探して」	ウェブ抽出は scrapling 経由で行う（下記参照）

まずは対象を絞ってください。evaluate または discover のリクエストで、数時間に及ぶ完全な検閲解除処理を開始してはいけません。

非検閲化（デフォルト）

pip install -U heretic-llm          # or: uv run heretic  (pins uv.lock for reproducibility)
heretic Qwen/Qwen3-4B-Instruct-2507 # replace with any model you have the right to modify

実行は完全に自動です。Heretic がハードウェアをベンチマークしてバッチサイズを選び、拒否方向を計算した後、Optuna TPE オプティマイザー（デフォルトは n_trials = 200、n_startup_trials = 60）を実行し、（a）有害なプロンプトに対する拒否と、（b）無害なプロンプトに対する元のモデルからの KL ダイバージェンスを同時に最小化します。完了すると、保存、Hugging Face にアップロード、チャット（テスト）、ベンチマークの実行が提示され、任意の組み合わせを選べます。チェックポイントは checkpoints/ に保存されるため、実行を再開できます。

設定

すでに完全自動で動作します。設定を使用するのは、ハードウェアや品質を制御する場合だけです。よく使う設定項目（config.default.toml、または同梱のプリセット config.nohumor.toml／config.noslop.toml を参照）：

• quantization = "bnb_4bit" — bitsandbytes の 4 ビット量子化により、より大きなモデルを少ない VRAM で動作させます。
• kl_divergence_target（デフォルトは 0.01）— 値を上げると、より深いアブレーションを許容します。下げると、能力を保護します。
• n_trials（デフォルトは 200）— 試行回数を増やすと、コンプライアンスと品質のトレードオフが改善しますが、実行時間は長くなります。
• dtypes、device_map、max_batch_size、max_response_length、refusal_markers。

すべての CLI フラグは heretic --help で確認できます。TOML のキーはどれも --kebab-case 形式のフラグとして指定できます。

評価

アブレーションを再実行せずに、指標の表（有害なプロンプトに対する拒否／無害なプロンプトに対する KL ダイバージェンス）を再現します。たとえば、生成したモデルを既存のコミュニティモデルと比較できます。

heretic --model google/gemma-3-12b-it --evaluate-model p-e-w/gemma-3-12b-it-heretic

両方の数値を報告してください。拒否が少ないほど検閲が弱く、KL が低いほど能力へのダメージが少ないことを示します。優れたアブレーションは、他のモデルと同程度に拒否を抑制しながら、はるかに低い KL を実現します（これが Heretic の主要な成果です）。

調査（解釈可能性）

pip install -U 'heretic-llm[research]'
heretic <model> --print-residual-geometry   # metrics table: cosine sims, norms, silhouette
heretic <model> --plot-residuals            # PaCMAP projection PNG per layer + animated GIF

--print-residual-geometry は、各層の S(g,b)、S(g*,b*)、拒否方向のノルム、有害／無害クラスタのシルエット係数を出力します（g＝善／無害の平均、b＝悪／有害の平均、*＝幾何中央値、r = b − g＝拒否方向）。--plot-residuals は PaCMAP による射影を実行し（CPU 負荷が高く、大規模モデルでは 1 時間以上かかります）、層ごとの残差アニメーションを描画します。

発見（scrapling 経由でルーティング）

ベースモデルの特定、既存の heretic／abliterated 版の有無の確認、ベンチマークや先行研究の数値の取得など、ライブウェブが必要な場合は、scrapling スキルにルーティングし、実用可能な最も軽量なモードを選んでください。references/research-and-scrapling.md を参照してください。

---

Heretic の仕組み（概要）

1. 拒否方向。 各層について、有害なプロンプトの最初のトークンの残差平均から、無害なプロンプトの最初のトークンの残差平均を引きます（r = b − g）。浮動小数点数の direction_index は隣接する層の方向を補間し、単一の層では得られない方向を利用できるようにします。
2. アブレーション。 アテンションの出力射影と MLP のダウン射影を r に対して直交化します。柔軟なコンポーネントごとの重みカーネル（max_weight、max_weight_position、min_weight、min_weight_distance）によって、各層のアブレーションの強さを調整します。
3. 最適化。 Optuna TPE がカーネルと方向のパラメーターを探索し、拒否と KL ダイバージェンスを同時に最小化します。アテンションと MLP には別々のパラメーターを設定します（MLP への介入はより大きなダメージを与えます）。

詳細：references/abliteration-and-optimization.md · CLI／設定：references/cli-and-config.md。

ワークフロー

1. リクエストを分類 → モード（decensor / configure / evaluate / research / discover）。 推奨のみのリクエスト、または明らかに違法な目的のリクエストでは、実行を開始しません。
2. 権利とハードウェアを確認します。 モデルはユーザーが変更する権利を持つものにしてください。GPU と十分な VRAM があることを確認します（VRAM が厳しい場合は --quantization bnb_4bit を提案してください）。数時間かかる実行時間や PaCMAP のコストについて警告します。
3. 必要に応じて scrapling で検索します — ベースモデル、既存の heretic バージョン、ベンチマークのベースライン。
4. モードに適した最小限のコマンドをインストールして実行します。再現性のため、uv run heretic を優先してください。
5. メトリクスを報告します — 拒否率と KL、チェックポイント／プロットのパス、さらに次の選択肢（保存／アップロード／チャット／評価／ベンチマーク）。

---

エラー処理と注意点

• torch.accelerator／MXFP4 エラー（例：gpt-oss）→ PyTorch 2.6+ が必要です。torch をアップグレードしてください。
• CUDA の OOM → quantization = "bnb_4bit" を設定するか、max_batch_size を下げるか、より小さいモデルを選んでください。
• PaCMAP の処理が遅い → CPU 上で実行されます。大規模モデルで 1 時間以上かかるのは想定内であり、ハングではありません。
• Research 機能が見つからない → [research] エクストラをインストールしてください（pip install -U 'heretic-llm[research]'）。
• メトリクスが非決定的 → 拒否率／KL の数値はプラットフォームとハードウェアに依存します。環境も報告してください。
• アブレーションの過剰適用（モデルが壊れる／一貫性を失う） → kl_divergence_target を下げる、n_trials を増やす、または MLP のアブレーション重みを下げてください。出荷前に再度 evaluate してください。

次のステップ

• 「VRAM に収まるようにして」→ --quantization bnb_4bit とバッチサイズの縮小（configure）。
• 「まだ拒否される」→ kl_divergence_target／n_trials を増やすか、拒否マーカーを確認します（configure）。
• 「動作することを証明して」→ 元のモデルと信頼できるコミュニティモデルを対象に --evaluate-model を実行します（evaluate）。
• 「拒否の幾何学的な構造を見せて」→ [research] エクストラと --print-residual-geometry／--plot-residuals。
• 「すでに heretic バージョンはある？」→ HuggingFace で scrapling を使って ?other=heretic を検索します（discover）。

---

インストール

# As a jeo-skills plugin (routing skill):
npx skills add https://github.com/akillness/jeo-skills --skill heretic

Heretic ツール自体を Python 環境にインストールします（PyTorch 2.2+ が事前にインストールされていること）：

bash scripts/install.sh # pip install -U heretic-llm（RESEARCH=1 の場合は + [research]） RESEARCH=1 bash scripts/install.sh # 解釈可能性エクストラを含めます UV=1 bash scripts/install.sh # リポジトリをクローンし、固定された再現可能な依存関係のために uv sync を実行します

環境変数の設定項目と再現可能な（uv.lock を使った）セットアップについては、references/install.md を参照してください。

同梱リファレンス

• references/abliteration-and-optimization.md — アルゴリズム、カーネルパラメーター、Optuna の目的関数。
• references/cli-and-config.md — フラグ、config.*.toml のキー、プリセット、量子化。
• references/research-and-scrapling.md — 解釈可能性機能と scrapling による検索方法。
• references/install.md — pip と uv、PyTorch／CUDA／bitsandbytes の前提条件、責任ある使用。

上流：https://github.com/p-e-w/heretic（AGPL-3.0-or-later、© 2025-2026 Philipp Emanuel Weidmann + contributors）。