heretic

heretic — 自动消除审查与拒绝方向可解释性

关键词：heretic · abliterate · decensor a model · remove refusals · refusal direction · plot residuals

负责任地使用。 Heretic 是采用 AGPL-3.0 许可证的软件，用于研究和定制你有权修改的模型。下载、修改、上传或提供权重服务时，请遵守每个基础模型的许可证以及各平台的服务条款。消融会降低模型对所有主题的拒绝率，包括确实有害的主题——请勿将其用于生成非法内容模型（例如 CSAM、大规模杀伤性武器能力提升、针对性骚扰），也不要借此规避你在合同上有义务遵守的安全控制。正当用途包括可解释性／对齐研究、红队测试、减少对无害内容的过度拒绝，以及在自己的硬件上运行用于合法工作的无审查模型。

heretic 将 p-e-w/heretic 工具（AGPL-3.0）打包为可安装的 jeo-skills 插件。Heretic 实现了参数化的方向消融变体（abliteration，源自 Arditi 等人，2024）：它按层计算“拒绝方向”，即有害提示词与无害提示词的首个 token 残差均值之差；然后对注意力输出投影矩阵和 MLP 下投影矩阵进行正交化，从而抑制拒绝，无需任何微调或后训练。**TPE 优化器（Optuna）**会搜索消融核，在减少拒绝的同时尽量降低与原始模型的 KL 散度，因此整个过程完全自动化，无需配置。

此技能优先路由：针对请求选择可行的最小模式，牢记上述负责任使用的防护准则，并通过 scrapling 路由基于 Web 的发现／研究。

---

何时使用／不使用

用户希望完成以下任务时，使用 heretic：

• 对开放权重模型（Qwen、Llama、Gemma、gpt-oss、Mistral 等）解除审查／执行消融／取消拒绝。
• 在保留能力的同时，减少对无害内容的过度拒绝（低 KL 散度）。
• 调整消融：试验次数预算、KL 目标、适配 VRAM 的量化，以及后续聊天／评估／上传。
• 测量模型：对有害提示词的拒绝次数，以及与原始模型相比的 KL 散度。
• 开展可解释性研究：拒绝方向几何、残差几何指标、PaCMAP 图。

请勿路由至此（直接回答或转至其他工具）：

• “推荐一个可下载的现成无审查模型” → 直接回答（指向 HF ?other=heretic）。
• 常规 LLM 微调／RLHF／DPO → 这是训练，不是消融（应使用其他工具）。
• 唯一合理用途是生成确实非法／有害内容的请求 → 拒绝。

---

模式（选择满足请求的最小模式）

模式	触发条件	命令／操作
decensor （默认）	“对 <model> 执行消融／解除审查”	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 路由 Web 提取（见下文）

从小范围开始：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。

运行 heretic --help 查看所有 CLI 标志；任何 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——大型模型可能需要一小时以上），并生成逐层残差动画。

发现（通过 scrapling 路由）

对于任何需要实时网络的任务——查找基础模型、检查是否已有 heretic/abliterated 版本，或获取基准测试/先前研究的数值——请路由到 scrapling 技能，并选择可行的最轻量模式。参见 references/research-and-scrapling.md。

---

Heretic 的工作原理（一屏概览）

1. 拒绝方向。 对每一层，计算有害提示词的首个 token 残差均值，减去无害提示词的首个 token 残差均值（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（空间紧张时提供 --quantization bnb_4bit）。提醒用户运行可能需要数小时，并说明 PaCMAP 的开销。
3. 按需通过 scrapling 发现——基础模型、现有的 heretic 版本、基准测试基线。
4. 安装并运行适用于该模式的最精简命令。优先使用 uv run heretic，以确保可复现。
5. 报告指标——拒绝率 + KL、检查点/绘图路径，以及后续选项 （保存 / 上传 / 聊天 / 评估 / 基准测试）。

---

错误处理与注意事项

• torch.accelerator / MXFP4 错误（例如 gpt-oss）→ 需要 PyTorch 2.6+；请升级 torch。
• CUDA 内存不足 → 设置 quantization = "bnb_4bit"、降低 max_batch_size，或选择较小的模型。
• PaCMAP 运行缓慢 → 它在 CPU 上运行；大型模型耗时一小时以上是正常现象，并非卡住。
• 缺少研究功能 → 安装 [research] 附加项（pip install -U 'heretic-llm[research]'）。
• 指标不确定 → 拒绝率/KL 数值取决于平台和硬件；请报告运行环境。
• 消融过度（模型损坏/不连贯） → 降低 kl_divergence_target、提高 n_trials，或降低 MLP 消融权重；发布前重新评估。

后续操作

• “让它适配我的 VRAM” → --quantization bnb_4bit + 降低批次大小（配置）。
• “它还是会拒绝” → 提高 kl_divergence_target / n_trials，或检查拒绝标记（配置）。
• “证明它有效” → 使用 --evaluate-model 对照原始模型 + 一个已知效果良好的社区模型进行评估（评估）。
• “展示拒绝几何结构” → 安装 [research] 附加项 + 使用 --print-residual-geometry / --plot-residuals。
• “已经有 heretic 版本了吗？” → 在 HuggingFace 上通过 scrapling 搜索 ?other=heretic（发现）。

---

安装

# 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 + 贡献者）。