大模型安全防护网关（llm-safe-stream）
llm-safe-stream（images/serving/llm-safe-stream）是 CubeStudio 推理侧的大模型安全组件，基于 llm-guard 护栏框架 + 中文毒性检测模型，对大模型的输入与输出双向做内容安全扫描，命中风险即拦截。
一、形态
- 安全检测 API：
POST /api/v1/safety-check，传文本数组返回是否安全及命中规则；GET /health；GET /（Gradio Playground，可在线调阈值）。 - 流式安全代理：作为网关转发到上游大模型（OpenAI 兼容
/v1/chat/completions），输入先扫描、输出流式返回时再扫描。 - 实现：FastAPI + gradio + llm-guard（
app.py，约 1124 行）。
二、扫描器与默认阈值
输入侧（build_input_scanners）：
| 扫描器 | 作用 | 默认阈值 |
|---|---|---|
| BanSubstrings | 敏感/违禁词 | — |
| BanTopics | 违禁话题（涉政/涉黄/暴恐等，BAN_TOPICS） |
0.8 |
| PromptInjection | 提示词注入/越狱 | 0.8 |
| ZhToxicityDetector | 中文毒性（逐句打分） | 0.8 |
输出侧（build_output_scanners）：
| 扫描器 | 作用 | 默认阈值 |
|---|---|---|
| BanSubstrings | 敏感词 | — |
| BanTopics | 违禁话题 | 0.4 |
| Sensitive | 敏感实体/PII | 0.0 |
| MaliciousURLs | 恶意链接 | 0.6 |
| Regex | 正则（如手机号） | — |
| ZhToxicity + 银行卡(Luhn) | 中文毒性 + 银行卡号校验 | 0.8 |
设计要点：输出侧 BanTopics 阈值（0.4）比输入侧（0.8）更严；Sensitive 阈值 0.0 表示检出 PII 即拦。阈值可在请求 thresholds 里覆盖，输入/输出分别设。
BAN_TOPICS 六大类（中英文）：涉政（政治/选举/政府/国家领导人）、涉黄（色情/成人内容/porn）、暴恐（恐怖主义/terrorism/violence）、诈骗（scam/fraud/phishing）、毒品武器（制毒/毒品/炸弹/武器）、性犯罪（裸聊/约炮/强奸/未成年色情）。
API 请求/响应格式
请求 SafetyCheckRequest：text（必填数组）+ 预留 image/video/audio（多模态扩展）+ thresholds。响应逐条返回 TextResult{index,text,safe,violations}，每个 Violation 含 check_type（input/output）、scanner、reason、score，便于审计。
环境变量
PORT/WORKERS（端口/进程）、ENABLE_GRADIO（Playground 开关）、LLM_GUARD_USE_ONNX（auto/1/0）、HF_HUB_OFFLINE/TRANSFORMERS_OFFLINE（离线，内网必开）、ZH_TOXICITY_MODEL_ID/ZH_TOXICITY_BACKEND/ZH_TOXICITY_ONNX_PATH（中文毒性模型）。
三、中文毒性检测
在通用 llm-guard 之外额外挂中文毒性模型 ZhToxicityDetector（默认 ZH_TOXICITY_MODEL_ID=/models/textdetox，即 textdetox/bert-multilingual-toxicity-classifier），逐句打分，弥补通用护栏对中文的不足。支持 ONNX（ZH_TOXICITY_BACKEND / ZH_TOXICITY_ONNX_PATH）。
四、部署
镜像 ccr.ccs.tencentyun.com/cube-studio/llm-safety-stream-server:<tag>（Dockerfile：CUDA 12.1 + py311 + torch2.5.1 + transformers + llm-guard + onnxruntime-gpu，预下载 textdetox 模型；CMD ["python","app.py"]）。
- 作为推理服务部署，申请 GPU，配上游大模型地址与阈值；
- 内网离线：
HF_HUB_OFFLINE=1/TRANSFORMERS_OFFLINE=1，毒性模型已打进镜像； - 加速：
LLM_GUARD_USE_ONNX（auto/1/0）控制 llm-guard ONNX 推理。
五、与 llm-safety-eval 的区别
| 能力 | 形态 | 用途 |
|---|---|---|
llm-safety-eval（大模型安全评估） |
任务模板（离线批量） | 上线前评估模型安全性，跑数据集出报告 |
llm-safe-stream（安全网关） |
推理服务（在线实时） | 上线后实时拦截每次对话的输入/输出风险 |
合规场景通常两者都用：先评估达标，再挂网关兜底。
测试样例见
images/serving/llm-safe-stream/测试样例.md。上游地址、API Key 按实际部署配置，勿硬编码内网地址到对外文档。