Heretic 教程：先固定版本，再限定研究范围
Heretic 会修改 Transformer 权重以降低拒绝行为。它从两组提示的首 token 残差中估计拒绝方向，对 attention out-projection 和 MLP down-projection 做方向消融，再用 Optuna TPE 搜索参数。这个用途会改变原模型的安全行为，不能把它当作普通推理加速工具。
pyproject.toml 已标为 2.0.0.dev0。教程和实验记录必须写清楚用的是哪一条线。1. 运行结构与指标
Heretic 先计算每层的 residual direction，再分别搜索注意力与 MLP 组件的消融权重。候选以两类信号评估：有害提示中的拒绝数量，以及无害提示相对原模型的 KL 散度。前者越低表示更少拒绝，后者越低表示输出分布偏移较小。
这两个数字都不是安全认证。官方也提醒数学指标和自动 benchmark 不能替代人工判断。提示集覆盖不足、评分器误判或能力侧损伤，都可能被平均数遮住。
2. 版本与环境要求
Python 要求 3.10 或更高。官方要求先安装适合硬件的 PyTorch 2.2+；某些模型需要更新的 PyTorch，例如 MXFP4 权重依赖 2.6 才加入的 torch.accelerator。主依赖还包括 Transformers、accelerate、bitsandbytes、datasets、lm-eval、Optuna 和 PEFT。
python -m venv .venv source .venv/bin/activate # 先按硬件安装 PyTorch pip install -U heretic-llm heretic --help
仓库带 uv.lock，从源码复现时可固定 v1.4.0 后使用 uv run heretic。不要把 master 的 2.0 开发依赖与 v1.4.0 文档混在同一个环境。
3. 权限、网络与输出
首次运行会从 Hugging Face 下载模型和数据集，磁盘和网络开销随模型大小变化。结束后可以保存、聊天、跑 benchmark，或选择上传模型。上传不是自动动作，但一旦选择就需要 Hugging Face 写权限。
受控评估应默认禁止上传，把输入数据、模型权重和输出留在隔离目录。记录模型 commit、Heretic tag、配置、GPU、PyTorch、耗时和输出 hash。官方给出的 RTX 3090 上 4B 模型 20 至 30 分钟只是示例，不能外推到其他硬件。
4. 研究与部署边界
该工具直接降低拒绝行为。适合研究模型行为、对齐稳健性和内部表示，不适合把处理后的权重未经评估直接接入公开聊天服务。上线前至少要重新做滥用测试、能力回归、人工审查、上游模型许可和数据处理检查。
仓库没有订阅、充值或项目方 API 转售。
5. 与 ErisForge 对比
ErisForge提供 Python API，让研究者手工选择层、行为方向和 ablation 或 addition 变换，也带拒绝表达评分。Heretic 把方向构造、TPE 搜索、双目标评估和命令行流程连在一起。
需要明确控制某一层和变换方向时，ErisForge 更直接；需要自动搜参并保存复现实验配置时，Heretic 更省步骤。两者都会修改模型内部行为，安全验收不能省略。
这里仅补原教程没有展开的事实和边界。安装命令与操作步骤仍以前文为准。
先判断这个项目是否适合你
适合谁用
适合受控的模型行为、可解释性和安全稳健性研究。输出模型降低了拒绝行为，有限的拒绝率或 KL 指标不能代表安全，也不适合作为公开部署的唯一验收依据。
原教程未展开的系统信息
核心功能
多架构支持
支持多数 dense、多模态、部分 MoE 和 Qwen3.5 等混合模型；纯 state-space 架构不在开箱支持范围。
评估与研究扩展
可评估已有模型；research extra 还提供残差向量投影、几何指标与图像输出。
架构与数据流
Heretic 从有害与无害示例提示的首 token 残差计算每层方向，再修改支持组件的权重矩阵。Optuna 搜索各组件和层的消融权重，候选以拒绝数和 KL 散度评估。运行结束后可保存到本地、测试、跑 benchmark，或由用户选择上传 Hugging Face。
常见问题
Heretic 当前版本是 v1.4.0 还是 2.0.0.dev0？
v1.4.0 是 2026-06-14 发布的最新正式版；master 的 pyproject.toml 已标为 2.0.0.dev0。生产复现应固定正式 tag，研究开发分支则固定具体 commit。
Heretic 只要 Python 3.10 就能运行吗？
还不够。官方要求先安装适合硬件的 PyTorch 2.2+；部分模型功能需要更高版本，例如 MXFP4 模型用到的 torch.accelerator 要求 PyTorch 2.6+。
Heretic 会自动把模型上传到 Hugging Face 吗？
不会。运行结束后上传只是用户可选动作；模型和数据集下载仍需要网络，选择上传时还会需要 Hugging Face 凭据与写权限。
拒绝率下降且 KL 更低，能证明模型安全吗？
不能。官方也说明数学指标和自动 benchmark 不能替代人工评估；这些指标只描述有限提示集上的拒绝与分布变化。
Heretic 适合直接用于公开聊天服务吗？
不适合直接上线。它的目标就是降低模型拒绝行为，公开部署前必须重新做滥用、安全、许可和人工评估；本教程只覆盖受控研究边界。