fix: 修复 AI 垃圾评论检测架构文档中的 Mermaid 语法错误
- 移除 subgraph 标签中的引号，避免解析错误 - 将体育场形状节点 ([]) 改为普通方形节点 [] - 确保所有 Mermaid 图表语法兼容 v11 版本
This commit is contained in:
344
docs/ai-spam-detection-architecture.md
Normal file
344
docs/ai-spam-detection-architecture.md
Normal file
@@ -0,0 +1,344 @@
|
|||||||
|
# AI 垃圾评论检测系统架构
|
||||||
|
|
||||||
|
## 系统概述
|
||||||
|
|
||||||
|
本文档展示 Argon 主题的 AI 垃圾评论检测系统的完整架构和流程。
|
||||||
|
|
||||||
|
## 主流程图
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
Start[用户提交评论]
|
||||||
|
PreProcess[预处理评论]
|
||||||
|
CheckEnabled{启用 AI 检测?}
|
||||||
|
DirectSave[直接保存评论]
|
||||||
|
CheckMode{检测模式?}
|
||||||
|
CheckKeyword[检查关键字]
|
||||||
|
CheckSample[智能抽样]
|
||||||
|
NeedCheck[需要检测]
|
||||||
|
KeywordMatch{匹配关键字?}
|
||||||
|
SampleDecision{抽中?}
|
||||||
|
SetPending[设置待审核状态]
|
||||||
|
SaveWithFlag[保存评论并标记]
|
||||||
|
TriggerDetect[触发 AI 检测]
|
||||||
|
CallAPI[调用 AI API]
|
||||||
|
ParseResult[解析结果]
|
||||||
|
CheckConfidence{置信度?}
|
||||||
|
AutoHandle[自动处理]
|
||||||
|
ManualReview[人工审核]
|
||||||
|
MarkNormal[标记正常]
|
||||||
|
CheckAction{处理方式?}
|
||||||
|
MoveTrash[移入回收站]
|
||||||
|
KeepPending[保持待审核]
|
||||||
|
JustMark[仅标记]
|
||||||
|
NotifyAdmin[通知管理员]
|
||||||
|
SaveResult[保存结果]
|
||||||
|
AILearn{启用学习?}
|
||||||
|
ExtractKeywords[提取关键词]
|
||||||
|
UpdateDB[更新词库]
|
||||||
|
End[结束]
|
||||||
|
|
||||||
|
Start --> PreProcess
|
||||||
|
PreProcess --> CheckEnabled
|
||||||
|
CheckEnabled -->|否| DirectSave
|
||||||
|
CheckEnabled -->|是| CheckMode
|
||||||
|
CheckMode -->|manual| DirectSave
|
||||||
|
CheckMode -->|keyword| CheckKeyword
|
||||||
|
CheckMode -->|sample| CheckSample
|
||||||
|
CheckMode -->|all| NeedCheck
|
||||||
|
CheckKeyword --> KeywordMatch
|
||||||
|
KeywordMatch -->|是| NeedCheck
|
||||||
|
KeywordMatch -->|否| DirectSave
|
||||||
|
CheckSample --> SampleDecision
|
||||||
|
SampleDecision -->|是| NeedCheck
|
||||||
|
SampleDecision -->|否| DirectSave
|
||||||
|
NeedCheck --> SetPending
|
||||||
|
SetPending --> SaveWithFlag
|
||||||
|
SaveWithFlag --> TriggerDetect
|
||||||
|
TriggerDetect --> CallAPI
|
||||||
|
CallAPI --> ParseResult
|
||||||
|
ParseResult --> CheckConfidence
|
||||||
|
CheckConfidence -->|高| AutoHandle
|
||||||
|
CheckConfidence -->|中| ManualReview
|
||||||
|
CheckConfidence -->|低| MarkNormal
|
||||||
|
AutoHandle --> CheckAction
|
||||||
|
CheckAction -->|trash| MoveTrash
|
||||||
|
CheckAction -->|hold| KeepPending
|
||||||
|
CheckAction -->|mark| JustMark
|
||||||
|
MoveTrash --> NotifyAdmin
|
||||||
|
KeepPending --> NotifyAdmin
|
||||||
|
JustMark --> SaveResult
|
||||||
|
ManualReview --> SaveResult
|
||||||
|
MarkNormal --> SaveResult
|
||||||
|
NotifyAdmin --> SaveResult
|
||||||
|
SaveResult --> AILearn
|
||||||
|
AILearn -->|是| ExtractKeywords
|
||||||
|
AILearn -->|否| End
|
||||||
|
ExtractKeywords --> UpdateDB
|
||||||
|
UpdateDB --> End
|
||||||
|
DirectSave --> End
|
||||||
|
|
||||||
|
style Start fill:#e1f5e1,stroke:#2e7d32,stroke-width:2px
|
||||||
|
style End fill:#e1f5e1,stroke:#2e7d32,stroke-width:2px
|
||||||
|
style MoveTrash fill:#ff6b6b,stroke:#c62828,stroke-width:2px
|
||||||
|
style MarkNormal fill:#95e1d3,stroke:#2e7d32,stroke-width:2px
|
||||||
|
style ManualReview fill:#ffa500,stroke:#ff8f00,stroke-width:2px
|
||||||
|
```
|
||||||
|
|
||||||
|
## 检测模式详解
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
subgraph Manual[Manual 模式]
|
||||||
|
M1[关闭实时检测]
|
||||||
|
M2[仅手动扫描]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Keyword[Keyword 模式]
|
||||||
|
K1[关键字触发]
|
||||||
|
K2[精准检测]
|
||||||
|
K3[低成本]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Sample[Sample 模式]
|
||||||
|
S1[智能抽样]
|
||||||
|
S2[平衡准确性]
|
||||||
|
S3[控制成本]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph All[All 模式]
|
||||||
|
A1[全量检测]
|
||||||
|
A2[最高准确性]
|
||||||
|
A3[高成本]
|
||||||
|
end
|
||||||
|
|
||||||
|
style Manual fill:#e3f2fd
|
||||||
|
style Keyword fill:#fff3e0
|
||||||
|
style Sample fill:#f3e5f5
|
||||||
|
style All fill:#fce4ec
|
||||||
|
```
|
||||||
|
|
||||||
|
## AI 检测流程
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant User as 用户
|
||||||
|
participant WP as WordPress
|
||||||
|
participant Argon as Argon 主题
|
||||||
|
participant AI as AI API
|
||||||
|
participant DB as 数据库
|
||||||
|
|
||||||
|
User->>WP: 提交评论
|
||||||
|
WP->>Argon: 触发 preprocess_comment
|
||||||
|
Argon->>Argon: 检查检测规则
|
||||||
|
|
||||||
|
alt 需要检测
|
||||||
|
Argon->>DB: 保存评论（待审核）
|
||||||
|
Argon->>AI: 发送检测请求
|
||||||
|
AI-->>Argon: 返回检测结果
|
||||||
|
Argon->>Argon: 解析结果和置信度
|
||||||
|
|
||||||
|
alt 高置信度垃圾评论
|
||||||
|
Argon->>DB: 移入回收站
|
||||||
|
Argon->>WP: 发送通知邮件
|
||||||
|
else 中等置信度
|
||||||
|
Argon->>DB: 标记待人工审核
|
||||||
|
else 正常评论
|
||||||
|
Argon->>DB: 标记为正常
|
||||||
|
end
|
||||||
|
|
||||||
|
Argon->>DB: 保存检测记录
|
||||||
|
|
||||||
|
opt 启用 AI 学习
|
||||||
|
Argon->>AI: 提取关键词
|
||||||
|
AI-->>Argon: 返回关键词
|
||||||
|
Argon->>DB: 更新学习词库
|
||||||
|
end
|
||||||
|
else 跳过检测
|
||||||
|
Argon->>DB: 直接保存评论
|
||||||
|
end
|
||||||
|
|
||||||
|
WP-->>User: 显示提交结果
|
||||||
|
```
|
||||||
|
|
||||||
|
## 数据库结构
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
erDiagram
|
||||||
|
COMMENT ||--o{ COMMENT_META : has
|
||||||
|
COMMENT {
|
||||||
|
bigint comment_ID PK
|
||||||
|
bigint comment_post_ID FK
|
||||||
|
text comment_content
|
||||||
|
varchar comment_author
|
||||||
|
varchar comment_author_email
|
||||||
|
varchar comment_author_IP
|
||||||
|
datetime comment_date
|
||||||
|
varchar comment_approved
|
||||||
|
}
|
||||||
|
|
||||||
|
COMMENT_META {
|
||||||
|
bigint meta_id PK
|
||||||
|
bigint comment_id FK
|
||||||
|
varchar meta_key
|
||||||
|
longtext meta_value
|
||||||
|
}
|
||||||
|
|
||||||
|
SPAM_DETECTION ||--|| COMMENT : detects
|
||||||
|
SPAM_DETECTION {
|
||||||
|
bigint id PK
|
||||||
|
bigint comment_id FK
|
||||||
|
varchar result
|
||||||
|
float confidence
|
||||||
|
text reason
|
||||||
|
text keywords
|
||||||
|
datetime detected_at
|
||||||
|
varchar detection_code
|
||||||
|
}
|
||||||
|
|
||||||
|
LEARNED_KEYWORDS ||--o{ SPAM_DETECTION : learns_from
|
||||||
|
LEARNED_KEYWORDS {
|
||||||
|
bigint id PK
|
||||||
|
varchar keyword
|
||||||
|
int weight
|
||||||
|
varchar category
|
||||||
|
datetime created_at
|
||||||
|
datetime updated_at
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 系统状态机
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
stateDiagram-v2
|
||||||
|
[*] --> Submitted: 用户提交
|
||||||
|
Submitted --> Pending: 需要检测
|
||||||
|
Submitted --> Approved: 跳过检测
|
||||||
|
|
||||||
|
Pending --> Detecting: 开始检测
|
||||||
|
Detecting --> Analyzed: 检测完成
|
||||||
|
|
||||||
|
Analyzed --> Spam: 高置信度垃圾
|
||||||
|
Analyzed --> Suspicious: 中等置信度
|
||||||
|
Analyzed --> Clean: 低置信度/正常
|
||||||
|
|
||||||
|
Spam --> Trash: 自动处理
|
||||||
|
Spam --> Hold: 保持待审核
|
||||||
|
Spam --> Marked: 仅标记
|
||||||
|
|
||||||
|
Suspicious --> ManualReview: 等待人工审核
|
||||||
|
Clean --> Approved: 自动通过
|
||||||
|
|
||||||
|
ManualReview --> Approved: 管理员批准
|
||||||
|
ManualReview --> Trash: 管理员拒绝
|
||||||
|
|
||||||
|
Hold --> Approved: 管理员批准
|
||||||
|
Hold --> Trash: 管理员拒绝
|
||||||
|
|
||||||
|
Marked --> Approved: 管理员批准
|
||||||
|
Marked --> Trash: 管理员拒绝
|
||||||
|
|
||||||
|
Trash --> [*]
|
||||||
|
Approved --> [*]
|
||||||
|
|
||||||
|
note right of Detecting
|
||||||
|
调用 AI API
|
||||||
|
解析返回结果
|
||||||
|
计算置信度
|
||||||
|
end note
|
||||||
|
|
||||||
|
note right of ManualReview
|
||||||
|
显示在后台
|
||||||
|
等待管理员操作
|
||||||
|
end note
|
||||||
|
```
|
||||||
|
|
||||||
|
## 性能优化策略
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
subgraph Input[输入优化]
|
||||||
|
I1[关键字预过滤]
|
||||||
|
I2[白名单用户]
|
||||||
|
I3[智能抽样]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Process[处理优化]
|
||||||
|
P1[异步检测]
|
||||||
|
P2[批量处理]
|
||||||
|
P3[缓存结果]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph API[API 优化]
|
||||||
|
A1[Prompt 优化]
|
||||||
|
A2[Token 控制]
|
||||||
|
A3[超时处理]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Storage[存储优化]
|
||||||
|
S1[索引优化]
|
||||||
|
S2[定期清理]
|
||||||
|
S3[归档历史]
|
||||||
|
end
|
||||||
|
|
||||||
|
Input --> Process
|
||||||
|
Process --> API
|
||||||
|
API --> Storage
|
||||||
|
|
||||||
|
style Input fill:#e8f5e9
|
||||||
|
style Process fill:#e3f2fd
|
||||||
|
style API fill:#fff3e0
|
||||||
|
style Storage fill:#f3e5f5
|
||||||
|
```
|
||||||
|
|
||||||
|
## 关键技术点
|
||||||
|
|
||||||
|
### 1. 异步检测机制
|
||||||
|
- 评论提交后立即返回，不阻塞用户
|
||||||
|
- 后台异步调用 AI API 进行检测
|
||||||
|
- 使用 WordPress Cron 或队列系统
|
||||||
|
|
||||||
|
### 2. 智能抽样算法
|
||||||
|
- 基于用户历史行为的动态抽样率
|
||||||
|
- 新用户抽样率更高
|
||||||
|
- 可信用户抽样率降低
|
||||||
|
|
||||||
|
### 3. 置信度评分系统
|
||||||
|
- 0.9-1.0：非常确定，可自动处理
|
||||||
|
- 0.7-0.9：比较确定，建议自动处理
|
||||||
|
- 0.5-0.7：中等确定，建议人工审核
|
||||||
|
- 0.0-0.5：不太确定，必须人工审核
|
||||||
|
|
||||||
|
### 4. 学习优化机制
|
||||||
|
- 记录管理员的审核决策
|
||||||
|
- 分析误判模式
|
||||||
|
- 自动调整检测策略
|
||||||
|
- 提取高频垃圾关键词
|
||||||
|
|
||||||
|
### 5. 容错与降级
|
||||||
|
- API 失败时自动降级
|
||||||
|
- 保证评论系统正常运行
|
||||||
|
- 记录错误日志供后续分析
|
||||||
|
|
||||||
|
## 配置建议
|
||||||
|
|
||||||
|
### 小型博客（< 100 评论/天）
|
||||||
|
- 检测模式：Sample（30%）
|
||||||
|
- Prompt 模式：Standard
|
||||||
|
- 自动处理阈值：0.9
|
||||||
|
- 异步检测：启用
|
||||||
|
|
||||||
|
### 中型博客（100-500 评论/天）
|
||||||
|
- 检测模式：Sample（40%）
|
||||||
|
- Prompt 模式：Standard
|
||||||
|
- 自动处理阈值：0.85
|
||||||
|
- 异步检测：启用
|
||||||
|
- 批量扫描：每日一次
|
||||||
|
|
||||||
|
### 大型博客（> 500 评论/天）
|
||||||
|
- 检测模式：Keyword + Sample（50%）
|
||||||
|
- Prompt 模式：Minimal
|
||||||
|
- 自动处理阈值：0.8
|
||||||
|
- 异步检测：启用
|
||||||
|
- 批量扫描：每日两次
|
||||||
|
- 启用缓存和队列优化
|
||||||
Reference in New Issue
Block a user