263 lines
6.0 KiB
Markdown
263 lines
6.0 KiB
Markdown
# ai_review — AI 内容审核服务
|
||
|
||
基于 DeepSeek LLM + RAG 向量检索的文本内容审核微服务。接收纯文本，返回是否违规。
|
||
|
||
## 架构
|
||
|
||
```
|
||
Client ──POST /review──▶ Flask (:8007)
|
||
│
|
||
ReviewAgent.review()
|
||
│
|
||
┌─────────┴─────────┐
|
||
▼ ▼
|
||
RAGStore.query() DeepSeek API
|
||
(ChromaDB top-3) (chat completion)
|
||
└───────┬───────────┘
|
||
▼
|
||
{"invalid": "true"/"false"}
|
||
```
|
||
|
||
审核流程：从 ChromaDB 中检索与待审文本最相似的 3 条已标注样本，注入 system prompt 作为参考，交由 DeepSeek 做单轮判定。违规类别涵盖色情、毒品、赌博、诈骗、仇恨/暴力/恐怖主义，灰色内容从严判定。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
ai_review/
|
||
├── ai_review.py # Flask 入口 (waitress)
|
||
├── .env # 环境变量配置
|
||
├── requirements.txt # Python 依赖
|
||
├── _set.sh # 初始化: 创建 venv、安装依赖
|
||
├── _run.sh # 启动服务
|
||
├── test_app.py # Streamlit 调试 UI
|
||
└── agent/
|
||
├── __init__.py
|
||
├── review_agent.py # 核心审核逻辑 (DeepSeek + RAG)
|
||
├── rag_store.py # ChromaDB 向量存储 (MD5 去重)
|
||
└── knowledge_base.json # 种子样本 (7 违规 + 7 安全)
|
||
```
|
||
|
||
## 接口文档
|
||
|
||
基础地址：`http://127.0.0.1:8007`
|
||
|
||
---
|
||
|
||
### POST /review
|
||
|
||
提交文本进行内容审核。
|
||
|
||
**Request**
|
||
|
||
```
|
||
Content-Type: application/json
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| content | string | 是 | 待审核文本，不可为空 |
|
||
|
||
```json
|
||
{"content": "待审核的文本内容"}
|
||
```
|
||
|
||
**Response 200**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| invalid | string | `"true"` 违规 / `"false"` 安全 |
|
||
| error | string | 仅异常时出现：`"api_error"` 或 `"parse_failed"` |
|
||
| detail | string | 仅 `api_error` 时出现，异常描述 |
|
||
| raw | string | 仅 `parse_failed` 时出现，模型原始输出 |
|
||
|
||
```json
|
||
{"invalid": "true"}
|
||
```
|
||
|
||
```json
|
||
{"invalid": "false"}
|
||
```
|
||
|
||
API 不可用时 fail-open：
|
||
|
||
```json
|
||
{"invalid": "false", "error": "api_error", "detail": "Connection timeout"}
|
||
```
|
||
|
||
**Response 400**
|
||
|
||
```json
|
||
{"error": "content is required"}
|
||
{"error": "content cannot be empty"}
|
||
```
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8007/review \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"content": "这是一段正常文本"}'
|
||
```
|
||
|
||
---
|
||
|
||
### POST /rag/feedback
|
||
|
||
人工纠偏接口。当 AI 审核结果与人工判断不一致时调用，将样本写入 RAG 知识库影响后续审核。
|
||
|
||
**Request**
|
||
|
||
```
|
||
Content-Type: application/json
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| content | string | 是 | 被误判的文本 |
|
||
| correct_type | string | 否 | `"violation"`（AI 漏判）或 `"safe"`（AI 误杀），默认 `"violation"` |
|
||
|
||
```json
|
||
{"content": "被误判的文本", "correct_type": "safe"}
|
||
```
|
||
|
||
**Response 200**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| added | boolean | 是否成功写入 |
|
||
| id | string/null | 新条目 ID（格式 `{v|s}_{md5前12位}`），重复时为 null |
|
||
| md5 | string | 文本的 MD5 哈希 |
|
||
| reason | string/null | 失败原因，成功时为 null，重复时为 `"duplicate"` |
|
||
|
||
新增成功：
|
||
|
||
```json
|
||
{"added": true, "id": "s_a1b2c3d4e5f6", "md5": "a1b2c3d4e5f6...", "reason": null}
|
||
```
|
||
|
||
重复提交：
|
||
|
||
```json
|
||
{"added": false, "id": null, "md5": "a1b2c3d4e5f6...", "reason": "duplicate"}
|
||
```
|
||
|
||
**Response 400**
|
||
|
||
```json
|
||
{"error": "content is required"}
|
||
{"error": "content cannot be empty"}
|
||
{"error": "correct_type must be 'violation' or 'safe'"}
|
||
```
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8007/rag/feedback \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"content": "这段文本被误杀了", "correct_type": "safe"}'
|
||
```
|
||
|
||
---
|
||
|
||
### GET /rag/list
|
||
|
||
列出 RAG 知识库中的全部条目。
|
||
|
||
**Request**
|
||
|
||
无参数。
|
||
|
||
**Response 200**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| total | integer | 条目总数 |
|
||
| entries | array | 条目列表 |
|
||
| entries[].id | string | 条目 ID |
|
||
| entries[].text | string | 样本文本 |
|
||
| entries[].type | string | `"violation"` 或 `"safe"` |
|
||
| entries[].category | string | 分类标签（如 `adult_content`、`gambling`、`human_feedback` 等） |
|
||
|
||
```json
|
||
{
|
||
"total": 14,
|
||
"entries": [
|
||
{"id": "v_001", "text": "...", "type": "violation", "category": "adult_service"},
|
||
{"id": "s_001", "text": "...", "type": "safe", "category": "daily"}
|
||
]
|
||
}
|
||
```
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8007/rag/list
|
||
```
|
||
|
||
---
|
||
|
||
### GET /health
|
||
|
||
健康检查。
|
||
|
||
**Request**
|
||
|
||
无参数。
|
||
|
||
**Response 200**
|
||
|
||
```json
|
||
{"status": "ok"}
|
||
```
|
||
|
||
**curl 示例**
|
||
|
||
```bash
|
||
curl http://127.0.0.1:8007/health
|
||
```
|
||
|
||
## 配置 (.env)
|
||
|
||
```
|
||
DEEPSEEK_API_KEY=<your-key>
|
||
DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||
DEEPSEEK_MODEL=deepseek-chat
|
||
DEEPSEEK_TEMPERATURE=0.0
|
||
DEEPSEEK_MAX_TOKENS=128
|
||
AI_REVIEW_HOST=127.0.0.1
|
||
AI_REVIEW_PORT=8007
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 初始化环境
|
||
bash _set.sh
|
||
|
||
# 填入 .env 中的 DEEPSEEK_API_KEY
|
||
|
||
# 启动服务
|
||
bash _run.sh
|
||
```
|
||
|
||
服务默认监听 `127.0.0.1:8007`。
|
||
|
||
## 调试 UI
|
||
|
||
```bash
|
||
streamlit run test_app.py
|
||
```
|
||
|
||
提供文本提交、结果展示、人工纠错按钮、RAG 知识库浏览等功能。
|
||
|
||
## 设计要点
|
||
|
||
- **RAG 增强审核**：推理时检索相似已标注样本辅助判定，支持运行时持续学习。
|
||
- **人工反馈闭环**：通过 `/rag/feedback` 纠正误判，新样本即时持久化并影响后续审核。
|
||
- **MD5 去重**：防止向量库中出现重复条目。
|
||
- **Fail-open**：DeepSeek API 不可用时放行内容（返回 `invalid: "false"`）。
|
||
|
||
## 依赖
|
||
|
||
openai, flask, flask-cors, waitress, chromadb, python-dotenv
|