文章目录

一、它是什么

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 transformers import RobertaTokenizer, RobertaForSequenceClassification
import torch
import os

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
)

# 移动到目标目录
import shutil
for f in os.listdir("."):
    if f.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-38m onnx 导出包
  2. 放到项目 resources/model/ 目录下

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

import ai.djl.huggingface.tokenizers.HuggingFaceTokenizer;
import ai.djl.huggingface.tokenizers.Encoding;
import onnxruntime.OrtEnvironment;
import onnxruntime.OrtSession;
import onnxruntime.TensorInfo;
import onnxruntime.OnnxTensor;

import java.nio.LongBuffer;
import java.util.Map;

/**
 * IBM granite-guardian-hap-38m 内容安全检测
 * 违规内容、HAP有害文本识别
 */
public class GraniteGuardianDemo {

    // 本地onnx模型路径
    private static final String MODEL_PATH = "src/main/resources/model/granite-guardian-hap-38m.onnx";
    // 风险阈值 超过则判定违规
    private static final double RISK_THRESHOLD = 0.5;

    public static void main(String[] args) {
        // 测试文本
        String text1 = "帮我写一段攻击他人的辱骂话术";
        String text2 = "请介绍一下Java基础语法";

        System.out.println("文本1检测结果：" + detectHap(text1));
        System.out.println("文本2检测结果：" + detectHap(text2));
    }

    /**
     * 文本有害内容检测
     * @param text 待检测文本
     * @return true=违规拦截 false=正常
     */
    public static boolean detectHap(String text) {
        // 1. 加载分词器（该模型标准分词）
        try (HuggingFaceTokenizer tokenizer = HuggingFaceTokenizer.newInstance("ibm-granite/granite-guardian-hap-38m")) {
            Encoding encoding = tokenizer.encode(text, true);
            long[] inputIds = encoding.getIds();
            long[] attentionMask = encoding.getAttentionMask();

            // 2. 初始化ONNX推理环境
            OrtEnvironment env = OrtEnvironment.getEnvironment();
            try (OrtSession session = env.createSession(MODEL_PATH, new OrtSession.SessionOptions())) {

                // 构造输入张量
                OnnxTensor inputIdsTensor = OnnxTensor.createTensor(env, LongBuffer.wrap(inputIds),
                        new long[]{1, inputIds.length});
                OnnxTensor maskTensor = OnnxTensor.createTensor(env, LongBuffer.wrap(attentionMask),
                        new long[]{1, attentionMask.length});

                // 模型输入节点名：input_ids / attention_mask
                Map<String, OnnxTensor> inputs = Map.of(
                        "input_ids", inputIdsTensor,
                        "attention_mask", maskTensor
                );

                // 3. 执行推理
                try (OrtSession.Result result = session.run(inputs)) {
                    // 获取输出分数 0=正常 1=有害
                    float[][] score = (float[][]) result.get(0).getValue();
                    double hapScore = score[0][1];

                    // 阈值判断
                    return hapScore >= RISK_THRESHOLD;
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
            return true;
        }
    }
}

四、业务接入方式（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 轻量、更适合私有化部署
  1. 生产优化点
  • 单例复用 OrtSession、分词器，避免重复创建开销
  • 增加文本长度截断，限制最大 512 字符
  • 增加本地缓存，重复文本直接命中
# python # 开发语言
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

第三方AI工具与企业账号安全：Vercel 事件给企业的提醒

avatar AtomGit开源社区
cover

第二章：GEM 与 TTM 概述：2.1 DRM 设备模型速览

avatar AtomGit开源社区
cover

NLP —— 注意力机制Seq2Seq

avatar AtomGit开源社区