一、项目概述

Heretic 是由 Philipp Emanuel Weidmann 开发的开源工具，它能够全自动地从基于 Transformer 的大语言模型中移除审查机制（也称为"安全对齐"），且无需昂贵的事后训练。该项目在 GitHub 上获得了大量关注，并被评为当日最受欢迎的仓库之一。

核心特性

• 全自动化：结合先进的方向消融（directional ablation）实现与基于 TPE 的参数优化器，自动寻找高质量的消融参数
• 广泛兼容：支持大多数密集模型、多模态模型、多种 MoE 架构，甚至包括 Qwen3.5 等混合模型
• 质量优异：自动生成的去审查模型在保持原始模型智能方面表现出色，KL 散度明显低于手动创建的消融版本
• 易于使用：任何会使用命令行程序的人都可以使用 Heretic 对语言模型进行去审查处理
• 活跃社区：社区已使用 Heretic 创建并发布了超过 3000 个模型

二、技术原理

2.1 方向消融（Directional Ablation）技术

Heretic 实现了参数化的方向消融变体。对于每个支持的 Transformer 组件（目前包括 attention out-projection 和 MLP down-projection），它会：

1. 识别相关矩阵：在每个 Transformer 层中定位相关矩阵
2. 正交化处理：根据相关的"拒绝方向"对这些矩阵进行正交化
3. 抑制表达：抑制该方向在矩阵乘法结果中的表达

2.2 拒绝方向计算

拒绝方向的计算公式为：

拒绝方向 = "有害"示例提示的第一个 token 残差向量的均值 - "无害"示例提示的第一个 token 残差向量的均值

2.3 消融参数优化

消融过程由多个可优化参数控制：

• direction_index：拒绝方向的索引，或特殊值 per layer（每层使用与该层相关的拒绝方向）
• max_weight、max_weight_position、min_weight、min_weight_distance：描述消融权重核在各层上的形状和位置

Heretic 的主要创新点：

1. 灵活的权重核形状：结合自动参数优化，可以改善合规性/质量的权衡
2. 浮点型方向索引：拒绝方向索引是浮点数而非整数，可以对两个最近的拒绝方向向量进行线性插值
3. 组件独立参数：为每个组件单独选择消融参数，通常 MLP 干预比 attention 干预对模型的损害更大

2.4 参数优化策略

Heretic 使用 Optuna 框架的 TPE（Tree-structured Parzen Estimator）采样器来优化参数，通过共同最小化：

• 拒绝次数：对"有害"提示的拒绝响应数量
• KL 散度：去审查模型与原始模型之间的 KL 散度（针对"无害"提示）

这种双重优化目标使得 Heretic 能够在移除审查机制的同时，最大程度保留原始模型的能力。

三、安装与快速开始

3.1 环境要求

• Python 3.10+
• PyTorch 2.2+（某些模型和配置可能需要更高版本的特性）
• 支持 CUDA 的 GPU（推荐，CPU 也可运行但速度极慢）

3.2 安装步骤

使用 pip 安装：

pip install -U heretic-llm

或使用 uv（推荐，依赖管理更可靠）：

# 克隆仓库
git clone https://github.com/p-e-w/heretic.git
cd heretic

# 使用 uv 运行
uv run heretic Qwen/Qwen3-4B-Instruct-2507

3.3 最简运行示例

# 基础用法：去审查一个模型
heretic Qwen/Qwen3-4B-Instruct-2507

# 使用 4-bit 量化以减少 VRAM 需求
heretic Qwen/Qwen3-4B-Instruct-2507 --quantization bnb_4bit

# 去审查后上传到 Hugging Face
heretic Qwen/Qwen3-4B-Instruct-2507 --upload

四、使用方法与实战

4.1 基础用法

# 对指定模型进行去审查
heretic <模型名称或路径>

# 示例：去审查 Gemma 3 12B 模型
heretic google/gemma-3-12b-it

4.2 进阶用法

量化支持

对于显存有限的环境，可以使用 bitsandbytes 4-bit 量化：

heretic Qwen/Qwen3-4B-Instruct-2507 --quantization bnb_4bit

评估模型

Heretic 内置评估功能，可以测试去审查模型的质量：

# 评估原始模型和去审查模型的拒绝率和 KL 散度
heretic --model google/gemma-3-12b-it --evaluate-model p-e-w/gemma-3-12b-it-heretic

研究功能

安装研究扩展以使用高级功能：

pip install -U heretic-llm[research]

# 生成残差向量 plot
heretic Qwen/Qwen3-4B-Instruct-2507 --plot-residuals

# 打印残差几何详情
heretic Qwen/Qwen3-4B-Instruct-2507 --print-residual-geometry

4.3 实际项目示例

以 Gemma 3 12B 模型为例，对比不同去审查方法的效果：

数据显示，Heretic 自动生成的版本在保持相同拒绝抑制水平的同时，实现了更低的 KL 散度，表明对原始模型能力的损害更小。

4.4 工作流程

典型的 Heretic 工作流程：

1. 系统基准测试：自动确定最优批处理大小
2. 参数优化：使用 Optuna 寻找最优消融参数
3. 模型去审查：应用优化后的参数
4. 后处理选项：
   • 保存模型
   • 上传到 Hugging Face
   • 与模型对话测试
   • 运行标准基准测试

五、常见问题与解决方案

5.1 安装失败

问题：pip install heretic-llm 失败

解决方案：

• 确保 Python 版本 ≥ 3.10
• 确保已安装 PyTorch 2.2+（需匹配你的硬件）
• 使用 uv 进行依赖管理：uv run heretic

5.2 运行时错误

问题：CUDA out of memory

解决方案：

• 使用量化：--quantization bnb_4bit
• 减少批处理大小（Heretic 会自动基准测试，但你可以手动覆盖）
• 使用更小的模型

问题：torch.accelerator 属性错误（使用 GPT-OSS 等模型时）

解决方案：

• 升级到 PyTorch 2.6+（该版本添加了 torch.accelerator）

5.3 性能问题

问题：处理速度太慢

解决方案：

• 确保使用支持 CUDA 的 GPU
• 对于 PaCMAP 投影（研究功能），预计需要较长时间（大模型可能超过 1 小时）
• 调整优化配置（减少试验次数）

5.4 兼容性问题

问题：模型不被支持

解决方案：

• 检查模型架构是否受支持（大多数密集模型、多模态模型、MoE 架构受支持）
• 纯状态空间模型和某些研究架构暂时不支持
• 可以在 GitHub 仓库中提出 issue 请求支持

六、总结

Heretic 为大语言模型的去审查化提供了一个强大且全自动的解决方案。通过结合先进的方向消融技术和智能参数优化，它能够在保持模型性能的同时有效移除审查机制。

项目优势：

• ✅ 真正的全自动化，无需人工干预
• ✅ 去审查质量达到甚至超过手动调优的水平
• ✅ 支持广泛的模型架构
• ✅ 活跃的开源社区和持续的维护更新
• ✅ 内置评估工具，方便质量验证

适用场景：

• 研究人员探索模型内部机制
• 开发者需要移除模型审查以进行特定应用
• 任何组织希望深入理解和对齐 LLM 行为

项目资源：

• GitHub：https://github.com/p-e-w/heretic
• Hugging Face：https://huggingface.co/heretic-org
• Discord 社区：https://discord.gg/gdXc48gSyT
• 许可证：AGPL-3.0-or-later

随着大语言模型的广泛应用，对模型行为的深入理解和控制变得越来越重要。Heretic 为我们提供了一个强大的工具，不仅用于去审查，更用于研究模型内部语义的可解释性。无论你是 AI 安全研究员、机器学习工程师，还是对 LLM 内部机制感兴趣的开发者，Heretic 都值得一试。