Java 高级调用私有化部署 Qwen3Guard-Stream 内容防护：核心配置+参数全解

Qwen3Guard-Stream 是阿里云通义千问开源的流式内容安全检测模型，私有化部署后，Java 调用核心需要掌握 部署配置、接口参数、鉴权/通信配置、流式调用参数 四大类信息，我直接给你开箱即用的完整清单，包含私有化场景必须的所有配置和参数。

一、先明确：私有化 Qwen3Guard-Stream 核心形态

私有化部署的 Qwen3Guard-Stream 本质是：
HTTP 服务（支持标准 POST + SSE 流式响应）
Java 调用就是发起 HTTP 请求 + 解析 SSE 流，无需依赖官方 SDK，纯原生/通用 HTTP 客户端即可调用。

---

二、必须知道的【部署基础配置】（私有化必填）

这是 Java 调用的根配置，没有这些无法连接服务：

配置项	含义	示例	备注
服务地址 (Base URL)	私有化部署的 Qwen3Guard 服务根地址	http://192.168.1.100:8000	内网/私有网络地址，无公网访问
接口路径	内容检测接口固定路径	/v1/guard	官方标准路径，私有化一般不修改
端口	服务监听端口	8000 / 8080 / 9000	部署时自定义，防火墙必须放行
协议	通信协议	http / https	私有化默认 http，https 需额外配置证书
模型版本	Qwen3Guard 模型版本	qwen3-guard-7b / qwen3-guard-1.8b	决定检测能力，请求无需传参，但需匹配部署
部署模式	单机/集群	单机	调用无区别，负载均衡配置地址即可

Java 拼接最终调用地址：

// 完整检测地址 = 基础地址 + 接口路径
String guardUrl = "http://192.168.1.100:8000/v1/guard";

---

三、【请求头参数】（Java 调用必须携带）

Qwen3Guard-Stream 是标准大模型流式接口，请求头固定如下：

1. 必选请求头

Header 键	值	作用
Content-Type	application/json	声明请求体为 JSON 格式
Accept	text/event-stream	核心：声明接收 SSE 流式响应
Cache-Control	no-cache	禁用缓存，保证实时流
Connection	keep-alive	保持长连接，适配流式传输

Java 代码示例（设置请求头）

// HttpURLConnection / OkHttp 通用头配置
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
headers.set("Accept", "text/event-stream");
headers.set("Cache-Control", "no-cache");
headers.set("Connection", "keep-alive");

---

四、【请求体核心参数】（检测内容的关键）

这是内容防护的核心参数，决定检测什么、怎么检测，私有化和官方开源版完全一致。

完整请求体 JSON 结构

{
  "input": "需要检测的文本内容",
  "stream": true,
  "tasks": ["text_moderation"],
  "parameters": {
    "moderation_level": "strict",
    "return_details": true
  }
}

逐字段详解（Java 封装对象必用）

参数名	类型	必填	可选值/说明
input	String	✅ 是	待检测的用户输入/对话内容
stream	boolean	✅ 是	true=流式返回（Qwen3Guard-Stream） false=一次性返回
tasks	Array[String]	✅ 是	固定值：["text_moderation"]（文本安全检测）
parameters	Object	否	检测策略配置（高级控制）
↳ moderation_level	String	否	检测严格度： loose（宽松）/ moderate（标准）/ strict（严格） 默认：moderate
↳ return_details	boolean	否	是否返回详细违规类型： true=返回分类+理由 false=仅返回通过/违规

简化版（最小可用请求体）

{
  "input": "这是需要检测的文本",
  "stream": true,
  "tasks": ["text_moderation"]
}

---

五、【流式响应 SSE 格式】（Java 解析必须匹配）

Qwen3Guard-Stream 采用 SSE(Server-Sent Events) 流式返回，每一条消息以 data: 开头，Java 必须按此格式解析。

1. 响应数据结构

data: {"id":"xxx","model":"qwen3-guard","choices":[{"delta":{"content":"{...检测结果}"},"finish_reason":null}]}

data: [DONE]  // 流结束标志

2. 检测结果核心字段（content 内）

字段	含义
is_safe	true=安全 / false=违规
categories	违规类型数组（涉政/色情/暴力/辱骂等）
confidence	置信度 0~1
message	检测说明

---

六、【私有化专属高级配置】（生产环境必须）

1. 网络与访问控制

• 内网白名单：Java 服务所在服务器 IP 必须加入 Qwen3Guard 部署机白名单
• 无公网访问：私有化部署默认无鉴权（无需 AK/SK），纯内网通信
• 超时配置：流式请求超时建议 ≥30s（避免模型推理超时）

2. 模型性能配置（对接部署方确认）

配置	Java 调用影响
并发数	单实例最大并发 QPS，超过会拒绝请求
推理精度	fp16 / int8，不影响调用参数
最长文本长度	输入 input 最大字符数（默认 8192）

---

七、Java 调用完整代码示例（开箱即用）

基于 Spring WebClient + SSE 流式解析（最适合 Java 后端调用）：

1. 依赖（Maven）

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

2. 核心调用代码

import org.springframework.http.MediaType;
import org.springframework.web.reactive.function.BodyInserters;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Flux;

public class Qwen3GuardStreamClient {
    // 私有化部署地址
    private static final String GUARD_URL = "http://192.168.1.100:8000/v1/guard";

    public Flux<String> checkTextStream(String inputText) {
        // 构建请求体
        GuardRequest request = new GuardRequest();
        request.setInput(inputText);
        request.setStream(true);
        request.setTasks(new String[]{"text_moderation"});
        
        // 流式调用
        return WebClient.create()
                .post()
                .uri(GUARD_URL)
                .contentType(MediaType.APPLICATION_JSON)
                .header("Accept", "text/event-stream")
                .body(BodyInserters.fromValue(request))
                .retrieve()
                .bodyToFlux(String.class) // 接收 SSE 流
                .filter(line -> !line.isEmpty());
    }

    // 请求体实体类
    static class GuardRequest {
        private String input;
        private boolean stream;
        private String[] tasks;
        // getter/setter
    }
}

---

八、你必须向部署方确认的【最终清单】

1. 服务内网地址 + 端口
2. 接口路径（默认 /v1/guard）
3. 最大输入文本长度
4. 支持的并发 QPS
5. 是否开启 https（如需则要证书）
6. 模型版本（1.8b/7b）

---

总结

1. 核心调用方式：Java 发送 POST 请求 + SSE 流式接收，纯 HTTP 无特殊依赖
2. 必填参数：input(检测文本)、stream=true、tasks=["text_moderation"]
3. 私有化关键：内网地址、端口、网络白名单，无鉴权参数
4. 响应格式：SSE 流，以 data: 开头，[DONE] 结束