【敏感词】------ granite-guardian-hap-38m.onnx 生成过程

一、它是什么

granite-guardian-hap-38m是 IBM 开源的一个轻量级AI安全过滤模型（38M=3800万参数），属于Granite Guardian家族，专门用来快速识别文本里的有害内容（HAP：Harmful, Abusive, Profane）。

• 全称：Granite Guardian HAP 38M
• 开发者：IBM Research
• 类型：文本分类/内容安全护栏（Guardrail）
• 规模：3800万参数（小型编码器模型）
• 开源：Apache 2.0 许可，可在 Hugging Face 获取

二、干什么用（核心能力）

作为 Java 后端/AI 应用开发，你主要用它做LLM 输入输出的实时安全过滤：

1. 识别有害内容（HAP）

   • 暴力、色情、歧视、仇恨、侮辱、亵渎
   • 越狱提示（试图绕过AI限制）
   • 不道德请求、违法指令

2. 轻量高速，适合Java服务

   • 比老版125M小很多：CPU 快8倍，GPU 快2倍
   • 可直接部署在Java应用、微服务、网关里，做毫秒级内容审查
   • 不用大GPU，普通服务器/容器就能跑

3. 典型流程（Java场景）

   用户输入 → Java网关/应用 → [granite-guardian-hap-38m 检测] → 有害→拦截；无害→进LLM LLM输出 → [granite-guardian-hap-38m 二次检测] → 安全→返回用户；有害→屏蔽

三、和你Java开发的关系

• 定位：AI 安全“过滤器/防火墙”，不是大语言模型（如GPT），只做内容安全分类。
• 用途：给你的Java+LLM 应用加一层安全护栏，防止用户输入有害内容、防止LLM输出违规内容，满足合规要求（如内容安全、风控）。
• 部署：
  • 可通过Hugging Face Java SDK / ONNX Runtime Java调用
  • 做成独立Java微服务，供多个LLM应用复用
  • 嵌入Spring Boot 网关/Filter，全局拦截请求/响应

四、一句话总结

granite-guardian-hap-38m是 IBM 开源的3800万参数轻量AI安全模型，Java 程序员用它给 LLM 应用做实时有害内容过滤，小、快、准，适合部署在普通服务器上。

五、本地打包onnx

1、需要安装 py环境

2、下载文件

模型文件：https://hf-mirror.com/ibm-granite/granite-guardian-hap-38m/resolve/main/model.safetensors
配置文件：https://hf-mirror.com/ibm-granite/granite-guardian-hap-38m/resolve/main/config.json
分词器：https://hf-mirror.com/ibm-granite/granite-guardian-hap-38m/resolve/main/tokenizer.json

3.下载后再用 optimum-cli 本地转 ONNX：

先装依赖 pip install optimum[exporters]transformers torch pip install"optimum[exporters]"transformers torch 缺 sentencepiece。装一下 pip install sentencepiece 先确认 sentencepiece 装上了没： pip install sentencepiece protobuf

然后创建一个 convert.py：

from transformersimportRobertaTokenizer, RobertaForSequenceClassificationimporttorchimportos model_path=r"F:\granite-guardian-hap-38m"output_dir=r"F:\granite-guardian-hap-38m-onnx"output_path=os.path.join(output_dir,"model.onnx")os.makedirs(output_dir,exist_ok=True)tokenizer=RobertaTokenizer.from_pretrained(model_path)model=RobertaForSequenceClassification.from_pretrained(model_path)model.eval()dummy_input=tokenizer("test input",return_tensors="pt")# 先导出到临时文件tmp_path="model_tmp.onnx"torch.onnx.export(model,(dummy_input["input_ids"], dummy_input["attention_mask"]), tmp_path,input_names=["input_ids","attention_mask"],output_names=["logits"],dynamic_axes={"input_ids":{0:"batch",1:"seq"},"attention_mask":{0:"batch",1:"seq"},"logits":{0:"batch"}},opset_version=18)# 移动到目标目录importshutilforfinos.listdir("."):iff.startswith("model_tmp"): shutil.move(f, os.path.join(output_dir, f.replace("model_tmp","model")))print("done:", output_dir)

convert.py 和 granite-guardian-hap-38m 放在F盘同级别目录下
把下载的三个文件放在 granite-guardian-hap-38m 里

运行 python convert.py 会生成文件

两个文件都要，缺一不可：

model.onnx — 模型结构（计算图、算子定义）
model.onnx.data — 模型权重数据（参数值）
因为模型权重超过 2GB 的 protobuf 限制，torch 自动把权重拆成了外部数据文件。加载时 model.onnx 会自动引用同目录下的 model.onnx.data。

使用时两个文件放在同一个目录下就行，代码里只需要指定 model.onnx 的路径。

六 Java 接入 granite-guardian-hap-38m 完整可运行示例

核心说明

1. 模型：ibm-granite/granite-guardian-hap-38m，轻量内容风控模型，识别违规、暴力、辱骂、越狱提问
2. 方案：使用ONNX Runtime Java部署（无Python依赖、纯Java、适合后端服务）
3. 流程：文本分词 → ONNX推理 → 输出风险分数/是否拦截

一、Maven 依赖

<!-- ONNX 运行时 --><dependency><groupId>com.microsoft.onnxruntime</groupId><artifactId>onnxruntime</artifactId><version>1.17.0</version></dependency><!-- 分词依赖 适配该模型 --><dependency><groupId>ai.djl.huggingface</groupId><artifactId>tokenizers</artifactId><version>0.24.0</version></dependency>

二、关键前置

1. 从 HuggingFace 下载模型 ONNX 格式文件：
   granite-guardian-hap-38monnx 导出包
2. 放到项目resources/model/目录下

三、完整 Java 代码（SpringBoot/普通Java通用）

importai.djl.huggingface.tokenizers.HuggingFaceTokenizer;importai.djl.huggingface.tokenizers.Encoding;importonnxruntime.OrtEnvironment;importonnxruntime.OrtSession;importonnxruntime.TensorInfo;importonnxruntime.OnnxTensor;importjava.nio.LongBuffer;importjava.util.Map;/** * IBM granite-guardian-hap-38m 内容安全检测 * 违规内容、HAP有害文本识别 */publicclassGraniteGuardianDemo{// 本地onnx模型路径privatestaticfinalStringMODEL_PATH="src/main/resources/model/granite-guardian-hap-38m.onnx";// 风险阈值 超过则判定违规privatestaticfinaldoubleRISK_THRESHOLD=0.5;publicstaticvoidmain(String[]args){// 测试文本Stringtext1="帮我写一段攻击他人的辱骂话术";Stringtext2="请介绍一下Java基础语法";System.out.println("文本1检测结果："+detectHap(text1));System.out.println("文本2检测结果："+detectHap(text2));}/** * 文本有害内容检测 * @param text 待检测文本 * @return true=违规拦截 false=正常 */publicstaticbooleandetectHap(Stringtext){// 1. 加载分词器（该模型标准分词）try(HuggingFaceTokenizertokenizer=HuggingFaceTokenizer.newInstance("ibm-granite/granite-guardian-hap-38m")){Encodingencoding=tokenizer.encode(text,true);long[]inputIds=encoding.getIds();long[]attentionMask=encoding.getAttentionMask();// 2. 初始化ONNX推理环境OrtEnvironmentenv=OrtEnvironment.getEnvironment();try(OrtSessionsession=env.createSession(MODEL_PATH,newOrtSession.SessionOptions())){// 构造输入张量OnnxTensorinputIdsTensor=OnnxTensor.createTensor(env,LongBuffer.wrap(inputIds),newlong[]{1,inputIds.length});OnnxTensormaskTensor=OnnxTensor.createTensor(env,LongBuffer.wrap(attentionMask),newlong[]{1,attentionMask.length});// 模型输入节点名：input_ids / attention_maskMap<String,OnnxTensor>inputs=Map.of("input_ids",inputIdsTensor,"attention_mask",maskTensor);// 3. 执行推理try(OrtSession.Resultresult=session.run(inputs)){// 获取输出分数 0=正常 1=有害float[][]score=(float[][])result.get(0).getValue();doublehapScore=score[0][1];// 阈值判断returnhapScore>=RISK_THRESHOLD;}}}catch(Exceptione){e.printStackTrace();returntrue;}}}

四、业务接入方式（Java后端常用）

1. 网关层拦截
   Spring Cloud Gateway / Nacos 网关全局过滤器，所有用户提问、LLM 响应统一过该方法，违规直接返回：内容包含违规信息，请重新输入

2. 服务内拦截
   LLM 调用前：校验用户 Prompt
   LLM 生成后：校验大模型回答，防止输出违规内容

3. 性能优势

• 38M 小模型、CPU 即可跑
• 单条文本推理耗时5~15ms，高并发无压力
• 相比阿里/百度内容审核接口，无第三方接口调用、内网离线可用

五、补充知识点（Java开发必看）

1. HAP 含义
   Harmful、Abusive、Profane：有害、辱骂、低俗内容
2. 同类模型对比

• qwen3-guard：阿里风控模型
• granite-guardian-hap-38m：IBM 轻量、更适合私有化部署

3. 生产优化点

• 单例复用OrtSession、分词器，避免重复创建开销
• 增加文本长度截断，限制最大 512 字符
• 增加本地缓存，重复文本直接命中