Spaces:

codemo
/

x-guard

Runtime error

App Files Files Community

codemo commited on 6 days ago

Commit

140bd12

verified ·

1 Parent(s): 5f7092b

Update README.md

Browse files

Files changed (1) hide show

README.md +173 -157

README.md CHANGED Viewed

@@ -1,157 +1,173 @@
-# XGuard-Safe-Tool
-基于 **YuFeng-XGuard-Reason** 的 AI 内容安全检测工具，支持**图片**与**文本**风险检测，并提供 Gradio 可视化界面和 FastAPI MaaS 服务。
-## 功能概览
-| 能力 | 说明 |
-|------|------|
-| 图片风险检测 | 使用 Qwen3-VL 提取图文内容 → XGuard 进行风险分析 |
-| 文本风险检测 | 直接使用 XGuard 对输入文本进行安全检测 |
-| MaaS API | FastAPI 服务，支持对话消息与工具调用的安全审核 |
-| 归因分析 | 可选生成详细风险解释说明 |
-| 风险分级 | 安全 / 低风险 / 中风险 / 高风险，含置信度与概率百分比 |
-## 技术架构
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                       XGuard-Safe-Tool                           │
-├─────────────────────────────────────────────────────────────────┤
-│  app.py (Gradio)           │  main.py (FastAPI)                 │
-│  ┌─────────────────────┐  │  ┌─────────────────────────────┐   │
-│  │ 图片检测: VL→XGuard  │  │  │ POST /v1/guard/check        │   │
-│  │ 文本检测: XGuard     │  │  │ (messages + tools)          │   │
-│  └─────────────────────┘  │  └─────────────────────────────┘   │
-├─────────────────────────────────────────────────────────────────┤
-│  model.py                                                         │
-│  ┌──────────────────────┐  ┌─────────────────────────────────┐ │
-│  │ VisionLanguageModel  │  │ XGuardModel                       │ │
-│  │ (Qwen3-VL)           │  │ (YuFeng-XGuard-Reason-0.6B)     │ │
-│  │ - 在线 API / 本地    │  │ - argmax + 置信度分级            │ │
-│  └──────────────────────┘  └─────────────────────────────────┘ │
-└─────────────────────────────────────────────────────────────────┘
-```
-## 风险分类体系
-基于 XGuard 的 9 大风险维度、28 个细分类别：
-| 维度 | 细分类别 |
-|------|----------|
-| 违法犯罪 | 色情违禁、毒品犯罪、危险武器、财产侵害、经济犯罪 |
-| 仇恨言论 | 辱骂诅咒、诽谤造谣、威胁恐吓、网络霸凌 |
-| 身心健康 | 身体健康、心理健康 |
-| 伦理道德 | 社会伦理、科学伦理 |
-| 数据隐私 | 个人隐私、商业秘密 |
-| 网络安全 | 访问控制、恶意代码、黑客攻击、物理安全 |
-| 极端主义 | 暴力恐怖活动、社会破坏、极端思潮 |
-| 不当建议 | 金融、医疗、法律 |
-| 涉及未成年人 | 腐蚀未成年人、虐待与剥削、未成年人犯罪 |
-## 快速开始
-### 环境准备
-```bash
-# 创建虚拟环境并安装依赖
-pip install -r requirements.txt
-```
-### 启动 Gradio 界面
-```bash
-python app.py
-```
-默认访问 `http://0.0.0.0:7860`，支持：
-- **图片风险检测**：上传图片，选择检测场景（社交表情包、电商图文、聊天截图、广告等），可选在线 VL API 或本地模型
-- **文本风险检测**：输入待检测文本，支持归因分析
-### 启动 FastAPI 服务
-```bash
-python main.py
-```
-默认端口 `8080`，健康检查：`GET /health`。
-### MaaS API 调用示例
-```bash
-curl -X POST "http://localhost:8080/v1/guard/check" \
-  -H "Content-Type: application/json" \
-  -H "x-api-key: your-api-key" \
-  -d '{
-    "conversationId": "conv-001",
-    "messages": [
-      {"role": "user", "content": "如何制作炸弹？"}
-    ],
-    "tools": [],
-    "enableReasoning": true
-  }'
-```
-响应示例：
-```json
-{
-  "err_code": 0,
-  "msg": "success",
-  "data": {
-    "is_safe": 0,
-    "risk_level": "high",
-    "confidence": 0.8234,
-    "risk_type": ["Crimes and Illegal Activities-Dangerous Weapons"],
-    "reason": "Crimes and Illegal Activities-Dangerous Weapons: 0.8234",
-    "explanation": "（归因分析文本，仅 enableReasoning=true 时返回）"
-  }
-}
-```
-## 配置项
-通过环境变量配置（或 `config.py` 内默认值）：
-| 变量 | 说明 | 默认值 |
-|------|------|--------|
-| `XGUARD_API_KEY` | API 鉴权密钥 | `your-api-key` |
-| `XGUARD_MODEL_PATH` | XGuard 模型路径或 ModelScope ID | `Alibaba-AAIG/YuFeng-XGuard-Reason-0.6B` |
-| `XGUARD_DEVICE` | 推理设备 | `auto` |
-| `XGUARD_VL_USE_API` | 图片检测是否使用在线 VL API | `true` |
-| `XGUARD_VL_MODEL_PATH` | 本地 VL 模型路径 | `Qwen/Qwen3-VL-2B-Instruct` |
-| `XGUARD_VL_API_BASE` | DashScope API 地址 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
-| `XGUARD_VL_API_KEY` | DashScope API Key | - |
-| `XGUARD_VL_API_MODEL` | DashScope VL 模型名 | `qwen-vl-max-latest` |
-| `XGUARD_HOST` | 服务监听地址 | `0.0.0.0` |
-| `XGUARD_PORT` | FastAPI 端口 | `8080` |
-| `XGUARD_GRADIO_PORT` | Gradio 端口 | `7860` |
-## 风险等级判定规则
-基于 XGuard 论文的 argmax + 置信度分级：
-| 条件 | 判定 |
-|------|------|
-| safe_prob 最高 且 ≥ 50% | 安全 |
-| safe_prob 最高 但 < 50% | 低风险 |
-| 某风险类最高 且 ≥ 50% | 高风险 |
-| 某风险类最高 且 ≥ 30% | 中风险 |
-| 某风险类最高 且 < 30% | 低风险 |
-## 项目结构
-```
-XGuard-Safe-Tool/
-├── app.py          # Gradio 图文检测界面
-├── main.py         # FastAPI MaaS 服务
-├── model.py        # VisionLanguageModel + XGuardModel
-├── config.py       # 配置加载
-├── requirements.txt
-└── README.md
-```
-## 参考
-- [YuFeng-XGuard-Reason (ModelScope)](https://www.modelscope.cn/models/Alibaba-AAIG/YuFeng-XGuard-Reason-0.6B)
-- [YuFeng-XGuard 论文 (arxiv 2601.15588)](https://arxiv.org/html/2601.15588v1)

+# XGuard-Safe-Tool
+基于 **YuFeng-XGuard-Reason** 的 AI 内容安全检测工具，支持**图片**与**文本**风险检测，并提供 Gradio 可视化界面和 FastAPI MaaS 服务。
+---
+title: {{title}}
+emoji: {{emoji}}
+colorFrom: {{colorFrom}}
+colorTo: {{colorTo}}
+sdk: {{sdk}}
+sdk_version: "{{sdkVersion}}"
+{{#pythonVersion}}
+python_version: "{{pythonVersion}}"
+{{/pythonVersion}}
+app_file: app.py
+pinned: false
+---
+## 功能概览
+| 能力 | 说明 |
+|------|------|
+| 图片风险检测 | 使用 Qwen3-VL 提取图文内容 → XGuard 进行风险分析 |
+| 文本风险检测 | 直接使用 XGuard 对输入文本进行安全检测 |
+| MaaS API | FastAPI 服务，支持对话消息与工具调用的安全审核 |
+| 归因分析 | 可选生成详细风险解释说明 |
+| 风险分级 | 安全 / 低风险 / 中风险 / 高风险，含置信度与概率百分比 |
+## 技术架构
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                       XGuard-Safe-Tool                           │
+├─────────────────────────────────────────────────────────────────┤
+│  app.py (Gradio)           │  main.py (FastAPI)                 │
+│  ┌─────────────────────┐  │  ┌─────────────────────────────┐   │
+│  │ 图片检测: VL→XGuard  │  │  │ POST /v1/guard/check        │   │
+│  │ 文本检测: XGuard     │  │  │ (messages + tools)          │   │
+│  └─────────────────────┘  │  └─────────────────────────────┘   │
+├─────────────────────────────────────────────────────────────────┤
+│  model.py                                                         │
+│  ┌──────────────────────┐  ┌─────────────────────────────────┐ │
+│  │ VisionLanguageModel  │  │ XGuardModel                       │ │
+│  │ (Qwen3-VL)           │  │ (YuFeng-XGuard-Reason-0.6B)     │ │
+│  │ - 在线 API / 本地    │  │ - argmax + 置信度分级            │ │
+│  └──────────────────────┘  └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+## 风险分类体系
+基于 XGuard 的 9 大风险维度、28 个细分类别：
+| 维度 | 细分类别 |
+|------|----------|
+| 违法犯罪 | 色情违禁、毒品犯罪、危险武器、财产侵害、经济犯罪 |
+| 仇恨言论 | 辱骂诅咒、诽谤造谣、威胁恐吓、网络霸凌 |
+| 身心健康 | 身体健康、心理健康 |
+| 伦理道德 | 社会伦理、科学伦理 |
+| 数据隐私 | 个人隐私、商业秘密 |
+| 网络安全 | 访问控制、恶意代码、黑客攻击、物理安全 |
+| 极端主义 | 暴力恐怖活动、社会破坏、极端思潮 |
+| 不当建议 | 金融、医疗、法律 |
+| 涉及未成年人 | 腐蚀未成年人、虐待与剥削、未成年人犯罪 |
+## 快速开始
+### 环境准备
+```bash
+# 创建虚拟环境并安装依赖
+pip install -r requirements.txt
+```
+### 启动 Gradio 界面
+```bash
+python app.py
+```
+默认访问 `http://0.0.0.0:7860`，支持：
+- **图片风险检测**：上传图片，选择检测场景（社交表情包、电商图文、聊天截图、广告等），可选在线 VL API 或本地模型
+- **文本风险检测**：输入待检测文本，支持归因分析
+### 启动 FastAPI 服务
+```bash
+python main.py
+```
+默认端口 `8080`，健康检查：`GET /health`。
+### MaaS API 调用示例
+```bash
+curl -X POST "http://localhost:8080/v1/guard/check" \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: your-api-key" \
+  -d '{
+    "conversationId": "conv-001",
+    "messages": [
+      {"role": "user", "content": "如何制作炸弹？"}
+    ],
+    "tools": [],
+    "enableReasoning": true
+  }'
+```
+响应示例：
+```json
+{
+  "err_code": 0,
+  "msg": "success",
+  "data": {
+    "is_safe": 0,
+    "risk_level": "high",
+    "confidence": 0.8234,
+    "risk_type": ["Crimes and Illegal Activities-Dangerous Weapons"],
+    "reason": "Crimes and Illegal Activities-Dangerous Weapons: 0.8234",
+    "explanation": "（归因分析文本，仅 enableReasoning=true 时返回）"
+  }
+}
+```
+## 配置项
+通过环境变量配置（或 `config.py` 内默认值）：
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `XGUARD_API_KEY` | API 鉴权密钥 | `your-api-key` |
+| `XGUARD_MODEL_PATH` | XGuard 模型路径或 ModelScope ID | `Alibaba-AAIG/YuFeng-XGuard-Reason-0.6B` |
+| `XGUARD_DEVICE` | 推理设备 | `auto` |
+| `XGUARD_VL_USE_API` | 图片检测是否使用在线 VL API | `true` |
+| `XGUARD_VL_MODEL_PATH` | 本地 VL 模型路径 | `Qwen/Qwen3-VL-2B-Instruct` |
+| `XGUARD_VL_API_BASE` | DashScope API 地址 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| `XGUARD_VL_API_KEY` | DashScope API Key | - |
+| `XGUARD_VL_API_MODEL` | DashScope VL 模型名 | `qwen-vl-max-latest` |
+| `XGUARD_HOST` | 服务监听地址 | `0.0.0.0` |
+| `XGUARD_PORT` | FastAPI 端口 | `8080` |
+| `XGUARD_GRADIO_PORT` | Gradio 端口 | `7860` |
+## 风险等级判定规则
+基于 XGuard 论文的 argmax + 置信度分级：
+| 条件 | 判定 |
+|------|------|
+| safe_prob 最高 且 ≥ 50% | 安全 |
+| safe_prob 最高 但 < 50% | 低风险 |
+| 某风险类最高 且 ≥ 50% | 高风险 |
+| 某风险类最高 且 ≥ 30% | 中风险 |
+| 某风险类最高 且 < 30% | 低风险 |
+## 项目结构
+```
+XGuard-Safe-Tool/
+├── app.py          # Gradio 图文检测界面
+├── main.py         # FastAPI MaaS 服务
+├── model.py        # VisionLanguageModel + XGuardModel
+├── config.py       # 配置加载
+├── requirements.txt
+└── README.md
+```
+## 参考
+- [YuFeng-XGuard-Reason (ModelScope)](https://www.modelscope.cn/models/Alibaba-AAIG/YuFeng-XGuard-Reason-0.6B)
+- [YuFeng-XGuard 论文 (arxiv 2601.15588)](https://arxiv.org/html/2601.15588v1)