大模型幻觉治理：HfDetect——零训练、能出检测证明的不确定性过滤库

在华为云 / ModelArts 上做大模型应用时，幻觉、RAG 冲突、脏样本污染是高频痛点：训练数据里混进一句自相矛盾的高熵文本，权重一旦被污染就不可逆；审核用关键词，改个说法就绕过。

HfDetect 是我开源的一个纯 Python 库，用一套统一的数学度量——失败熵 Hf，对任意文本算出"内部振荡 / 矛盾 / 风险"的连续分值，按档位分级处置（放行 / 人工复核 / 拦截）。不提升模型智商，只让模型少犯错；只标不确定性，不做"对 / 错"终局判决，把最终决定权交还给人。

核心公式（标准数学，可复现）
Hf = Σ(Ni·Ei·Ii) / D
Ni = Ai·|sin(π/2·min(|ri−r0|/Δmax, 1))|
r0 = 0.645，Δmax = 0.30
- ri：稳态自洽强度（越接近 r0 越稳）
- Ai：振荡振幅（内部矛盾剧烈程度）
- Ei：代价项（算力 / 污染 / 时间损耗）
- Ii：不可逆伤害系数（0~1）
- D：自由度维度

为什么省
同一套公式跨场景只做变量业务含义映射，不逐场景重训模型。纯 Python 标准库、零第三方依赖，可部署在云上推理服务 / API 网关侧，对每一条生成结果做实时过滤与复核。

适用场景
LLM 幻觉输出过滤、Agent 分支剪枝、RAG 冲突文档过滤、训练集脏样本清洗、垃圾 / 诈骗邮件识别、短视频虚假广告风控、财报疑点扫描、稿件筛选。

双档位
- 通用业务档：过滤 70%–85% 高风险，中等不确定性进人工复核
- AI 强防护档：高熵脏样本近乎 100% 拦截，优先护模型权重

边界（丑话说前头）
只识别"内部逻辑自相矛盾"；逻辑自洽但客观事实错误的样本会漏报，需配知识库 + 人工。只给风险标签，不做正确 / 错误终判。

怎么用（详见 README）
python hf_detect.py 文本.txt --mode strong
自动输出 JSON + Markdown 检测证明（含估算变量、计算过程、信号诊断、判定、置信度、边界声明）。

开源地址：https://gitee.com/wanxiangguiy/hf-detect （MIT）

欢迎试用、提 Issue / PR，也欢迎按你的具体场景一起把变量映射进去。