# 引用检测算法

<cite>
**本文档引用的文件**
- [citation_engine.py](file://backend/app/workers/citation_engine.py)
- [base.py](file://backend/app/workers/platforms/base.py)
- [kimi.py](file://backend/app/workers/platforms/kimi.py)
- [wenxin.py](file://backend/app/workers/platforms/wenxin.py)
- [citation_record.py](file://backend/app/models/citation_record.py)
- [query.py](file://backend/app/models/query.py)
- [query_task.py](file://backend/app/models/query_task.py)
- [citation.py](file://backend/app/services/citation.py)
- [scheduler.py](file://backend/app/workers/scheduler.py)
- [citations.py](file://backend/app/api/citations.py)
- [config.py](file://backend/app/config.py)
- [database.py](file://backend/app/database.py)
- [test_citation_engine.py](file://tests/test_citation_engine.py)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件系统性阐述引用检测算法的设计与实现，重点覆盖以下方面：
- 品牌匹配策略：精确匹配、别名匹配、模糊匹配的判定逻辑与置信度评分
- 竞争品牌识别机制：基于预定义品牌库的竞争者发现
- 置信度评分系统：关键词匹配权重、上下文相关性评估与结果排序规则
- 引用上下文提取技术：文本片段截取、语义分析与相关性判断
- 算法优化策略：性能提升与准确性改进方法
- 算法调优指南与实际应用场景示例

## 项目结构
后端采用分层架构，围绕“查询-执行-记录-统计”闭环组织：
- 查询模型与任务模型负责用户查询配置与执行计划
- 引擎模块负责跨平台调用、品牌匹配与竞争品牌识别
- 适配器模块封装不同AI平台的网页自动化交互
- 服务模块提供API接口、统计数据与导出功能
- 定时调度器按频率自动触发查询任务

```mermaid
graph TB
subgraph "查询与任务"
Q["Query<br/>查询配置"]
QT["QueryTask<br/>查询任务"]
end
subgraph "引擎与适配器"
CE["CitationEngine<br/>引用检测引擎"]
BM["BrandMatcher<br/>品牌匹配器"]
CD["CompetitorDetector<br/>竞争品牌检测器"]
KP["KimiAdapter<br/>Kimi适配器"]
WP["WenxinAdapter<br/>文心一言适配器"]
end
subgraph "数据与服务"
CR["CitationRecord<br/>引用记录"]
SVC["Citation Services<br/>统计与导出"]
SCH["QueryScheduler<br/>定时调度器"]
end
Q --> CE
Q --> QT
CE --> BM
CE --> CD
CE --> KP
CE --> WP
CE --> CR
SVC --> CR
SCH --> CE
```

图表来源
- [citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [kimi.py:11-206](file://backend/app/workers/platforms/kimi.py#L11-L206)
- [wenxin.py:11-205](file://backend/app/workers/platforms/wenxin.py#L11-L205)
- [scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [citation.py:24-269](file://backend/app/services/citation.py#L24-L269)

章节来源
- [citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [kimi.py:11-206](file://backend/app/workers/platforms/kimi.py#L11-L206)
- [wenxin.py:11-205](file://backend/app/workers/platforms/wenxin.py#L11-L205)
- [scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [citation.py:24-269](file://backend/app/services/citation.py#L24-L269)

## 核心组件
- 引用检测引擎：协调平台查询、品牌匹配与竞争品牌识别，并持久化结果
- 品牌匹配器：提供精确、别名与模糊三种匹配策略，输出置信度与上下文
- 竞争品牌检测器：基于预定义品牌库识别文本中的竞争者
- 平台适配器：封装Kimi与文心一言的网页自动化查询流程
- 数据模型：查询、查询任务、引用记录支撑业务数据流转
- 统计服务：提供引用统计、趋势与CSV导出能力
- 定时调度器：按频率自动触发查询任务

章节来源
- [citation_engine.py:19-120](file://backend/app/workers/citation_engine.py#L19-L120)
- [citation_engine.py:122-146](file://backend/app/workers/citation_engine.py#L122-L146)
- [citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [base.py:4-18](file://backend/app/workers/platforms/base.py#L4-L18)
- [kimi.py:11-206](file://backend/app/workers/platforms/kimi.py#L11-L206)
- [wenxin.py:11-205](file://backend/app/workers/platforms/wenxin.py#L11-L205)
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [citation.py:76-201](file://backend/app/services/citation.py#L76-L201)
- [scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)

## 架构总览
下图展示从查询配置到结果统计的完整流程，包括定时触发、平台查询、匹配与记录写入。

```mermaid
sequenceDiagram
participant User as "用户"
participant API as "API层"
participant Svc as "统计服务"
participant Sch as "调度器"
participant Eng as "引用检测引擎"
participant Plat as "平台适配器"
participant DB as "数据库"
User->>API : 触发查询/查看统计
API->>Svc : 获取引用记录/统计
Svc->>DB : 查询引用记录
DB-->>Svc : 返回记录
Svc-->>API : 返回统计结果
Sch->>DB : 查询到期的查询
DB-->>Sch : 返回查询集合
Sch->>Eng : 执行查询
Eng->>Plat : 平台查询(keyword)
Plat-->>Eng : 返回原始响应
Eng->>Eng : 品牌匹配/竞争品牌识别
Eng->>DB : 写入引用记录
DB-->>Eng : 确认写入
Eng-->>Sch : 返回执行结果
```

图表来源
- [scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [kimi.py:33-48](file://backend/app/workers/platforms/kimi.py#L33-L48)
- [wenxin.py:33-48](file://backend/app/workers/platforms/wenxin.py#L33-L48)
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [citation.py:24-73](file://backend/app/services/citation.py#L24-L73)

## 详细组件分析

### 品牌匹配器（BrandMatcher）
- 精确匹配：直接包含目标品牌或别名即命中，置信度最高
- 别名匹配：对别名列表逐一匹配，命中则置信度较高
- 模糊匹配：基于候选词集合与编辑相似度阈值进行匹配，置信度由相似度决定
- 上下文提取：按段落定位首次出现位置，截取固定长度片段作为引用上下文
- 结果字段：是否引用、置信度、匹配类型、段落位置、引用上下文

```mermaid
flowchart TD
Start(["进入匹配"]) --> CheckEmpty{"文本为空？"}
CheckEmpty --> |是| ReturnNoMatch["返回未命中"]
CheckEmpty --> |否| Exact["精确匹配"]
Exact --> ExactHit{"命中？"}
ExactHit --> |是| ReturnExact["返回精确匹配结果"]
ExactHit --> |否| Alias["别名匹配"]
Alias --> AliasHit{"命中？"}
AliasHit --> |是| ReturnAlias["返回别名匹配结果"]
AliasHit --> |否| Fuzzy["模糊匹配"]
Fuzzy --> Extract["提取候选词"]
Extract --> Similarity["计算相似度"]
Similarity --> Best{"最佳相似度>阈值？"}
Best --> |是| ReturnFuzzy["返回模糊匹配结果"]
Best --> |否| ReturnNoMatch
```

图表来源
- [citation_engine.py:26-120](file://backend/app/workers/citation_engine.py#L26-L120)

章节来源
- [citation_engine.py:19-120](file://backend/app/workers/citation_engine.py#L19-L120)

### 竞争品牌检测器（CompetitorDetector）
- 基于预定义行业分类的品牌集合进行全量扫描
- 排除目标品牌，返回去重后的竞争品牌列表
- 支持多行业类别扩展，便于后续维护与增长

```mermaid
flowchart TD
Start(["开始检测"]) --> Empty{"文本为空？"}
Empty --> |是| ReturnEmpty["返回空列表"]
Empty --> |否| LoopCat["遍历行业类别"]
LoopCat --> LoopBrand["遍历类别内品牌"]
LoopBrand --> Exclude{"是否为目标品牌？"}
Exclude --> |是| NextBrand["跳过"]
Exclude --> |否| CheckInText{"品牌是否出现在文本？"}
CheckInText --> |是| Add["加入候选集"]
CheckInText --> |否| NextBrand
NextBrand --> LoopBrand
LoopBrand --> Done{"遍历结束？"}
Done --> |否| LoopCat
Done --> |是| Sort["排序并返回"]
```

图表来源
- [citation_engine.py:122-146](file://backend/app/workers/citation_engine.py#L122-L146)

章节来源
- [citation_engine.py:122-146](file://backend/app/workers/citation_engine.py#L122-L146)

### 引用检测引擎（CitationEngine）
- 单平台执行：获取适配器、发起查询、执行匹配与竞争品牌识别
- 多平台执行：遍历配置平台，维护任务状态，持久化结果
- 时间控制：根据频率计算下次查询时间，避免重复触发
- 错误处理：捕获异常并记录失败任务与错误信息

```mermaid
sequenceDiagram
participant Q as "Query"
participant CE as "CitationEngine"
participant AD as "平台适配器"
participant BM as "BrandMatcher"
participant CD as "CompetitorDetector"
participant DB as "数据库"
CE->>Q : 读取配置关键词/品牌/别名/平台/频率
loop 遍历平台
CE->>AD : query(keyword)
AD-->>CE : raw_response
CE->>BM : match(raw_response)
BM-->>CE : 匹配结果
CE->>CD : detect(raw_response, target_brand)
CD-->>CE : 竞争品牌列表
CE->>DB : 写入CitationRecord
end
CE->>Q : 更新last_queried_at/next_query_at
```

图表来源
- [citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [citation_engine.py:236-266](file://backend/app/workers/citation_engine.py#L236-L266)

章节来源
- [citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)

### 平台适配器（BasePlatformAdapter/Kimi/Wenxin）
- 抽象基类定义统一接口：平台名称、URL与查询方法
- 具体适配器通过Playwright自动化访问平台页面，输入关键词并等待稳定回复
- 提供指数退避重试、超时处理与资源清理

```mermaid
classDiagram
class BasePlatformAdapter {
+string platform_name
+string platform_url
+query(keyword) str
+close()
}
class KimiAdapter {
+query(keyword) str
+close()
}
class WenxinAdapter {
+query(keyword) str
+close()
}
BasePlatformAdapter <|-- KimiAdapter
BasePlatformAdapter <|-- WenxinAdapter
```

图表来源
- [base.py:4-18](file://backend/app/workers/platforms/base.py#L4-L18)
- [kimi.py:11-206](file://backend/app/workers/platforms/kimi.py#L11-L206)
- [wenxin.py:11-205](file://backend/app/workers/platforms/wenxin.py#L11-L205)

章节来源
- [base.py:4-18](file://backend/app/workers/platforms/base.py#L4-L18)
- [kimi.py:11-206](file://backend/app/workers/platforms/kimi.py#L11-L206)
- [wenxin.py:11-205](file://backend/app/workers/platforms/wenxin.py#L11-L205)

### 数据模型与统计服务
- 查询模型：存储关键词、目标品牌、别名、平台、频率与时间控制字段
- 查询任务模型：跟踪每次执行的状态、错误信息与时间戳
- 引用记录模型：保存是否引用、引用位置、引用文本、竞争品牌与原始响应
- 统计服务：提供总量、引用率、平均位置、按平台分布与近30天趋势

```mermaid
erDiagram
QUERY {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
datetime last_queried_at
datetime next_query_at
}
QUERY_TASK {
uuid id PK
uuid query_id FK
string platform
string status
text error_message
datetime scheduled_at
datetime started_at
datetime completed_at
}
CITATION_RECORD {
uuid id PK
uuid query_id FK
string platform
boolean cited
int citation_position
text citation_text
json competitor_brands
text raw_response
datetime queried_at
}
QUERY ||--o{ QUERY_TASK : "包含"
QUERY ||--o{ CITATION_RECORD : "包含"
```

图表来源
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)

章节来源
- [query.py:11-55](file://backend/app/models/query.py#L11-L55)
- [query_task.py:11-39](file://backend/app/models/query_task.py#L11-L39)
- [citation_record.py:11-42](file://backend/app/models/citation_record.py#L11-L42)
- [citation.py:76-201](file://backend/app/services/citation.py#L76-L201)

### 定时调度器与API
- 定时调度器：每小时检查到期查询并执行
- API层：提供引用列表、统计与立即执行接口

```mermaid
sequenceDiagram
participant SCH as "调度器"
participant DB as "数据库"
participant CE as "引擎"
participant API as "API"
participant SVC as "服务"
SCH->>DB : 查询到期查询
DB-->>SCH : 返回查询集合
SCH->>CE : 执行查询
CE-->>DB : 写入记录
API->>SVC : 获取统计/列表
SVC->>DB : 查询数据
DB-->>SVC : 返回结果
SVC-->>API : 返回统计/列表
```

图表来源
- [scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [citations.py:25-77](file://backend/app/api/citations.py#L25-L77)
- [citation.py:24-73](file://backend/app/services/citation.py#L24-L73)

章节来源
- [scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [citations.py:25-77](file://backend/app/api/citations.py#L25-L77)
- [citation.py:24-269](file://backend/app/services/citation.py#L24-L269)

## 依赖关系分析
- 引擎依赖适配器接口，通过平台名称映射具体实现
- 引擎依赖数据库模型进行任务与结果持久化
- 统计服务依赖查询与记录模型进行聚合
- 调度器依赖引擎与数据库进行周期性执行

```mermaid
graph LR
CE["CitationEngine"] --> BM["BrandMatcher"]
CE --> CD["CompetitorDetector"]
CE --> KP["KimiAdapter"]
CE --> WP["WenxinAdapter"]
CE --> CR["CitationRecord"]
CE --> Q["Query"]
CE --> QT["QueryTask"]
SCH["QueryScheduler"] --> CE
SVC["Citation Services"] --> CR
API["API"] --> SVC
```

图表来源
- [citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [citation.py:24-269](file://backend/app/services/citation.py#L24-L269)

章节来源
- [citation_engine.py:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [scheduler.py:25-95](file://backend/app/workers/scheduler.py#L25-L95)
- [citation.py:24-269](file://backend/app/services/citation.py#L24-L269)

## 性能考虑
- 并发与重试：平台适配器采用指数退避重试，降低网络波动影响
- 资源管理：适配器在finally中释放浏览器与上下文，避免资源泄漏
- 数据库索引：对查询与记录的关键字段建立索引，加速统计与筛选
- 异步执行：引擎与调度器均采用异步模式，提高吞吐量
- 上下文截取：限定片段长度，减少存储与传输开销

章节来源
- [kimi.py:33-48](file://backend/app/workers/platforms/kimi.py#L33-L48)
- [wenxin.py:33-48](file://backend/app/workers/platforms/wenxin.py#L33-L48)
- [citation_record.py:37-41](file://backend/app/models/citation_record.py#L37-L41)
- [database.py:1-29](file://backend/app/database.py#L1-L29)

## 故障排查指南
- 平台适配器初始化失败：检查Playwright浏览器安装与路径配置
- 页面元素定位失败：适配器内置多种选择器与超时处理，可关注日志中的选择器尝试顺序
- 引擎执行异常：查看任务状态与错误信息，确认查询配置与平台可用性
- 统计结果异常：核对查询所有权验证与时间范围过滤条件

章节来源
- [kimi.py:21-32](file://backend/app/workers/platforms/kimi.py#L21-L32)
- [wenxin.py:21-32](file://backend/app/workers/platforms/wenxin.py#L21-L32)
- [citation_engine.py:211-227](file://backend/app/workers/citation_engine.py#L211-L227)
- [citation.py:14-21](file://backend/app/services/citation.py#L14-L21)

## 结论
该引用检测算法以清晰的分层设计实现了从平台查询到品牌匹配与统计分析的完整链路。通过精确、别名与模糊匹配相结合的策略，辅以上下文提取与竞争品牌识别，能够有效支撑品牌监测与竞品分析场景。建议在生产环境中结合业务需求持续优化阈值与品牌库，并完善监控与告警体系。

## 附录

### 置信度评分系统
- 精确匹配：置信度为最高值
- 别名匹配：置信度为较高值
- 模糊匹配：置信度由编辑相似度决定，超过阈值方可视为命中
- 上下文相关性：通过段落位置与片段长度间接反映相关性

章节来源
- [citation_engine.py:26-100](file://backend/app/workers/citation_engine.py#L26-L100)

### 引用上下文提取技术
- 文本分段：按换行符拆分段落，定位首次出现位置
- 片段截取：限定最大长度，保证上下文可读性与性能
- 相关性判断：结合段落位置与关键词密度进行粗略评估

章节来源
- [citation_engine.py:107-119](file://backend/app/workers/citation_engine.py#L107-L119)

### 算法优化策略
- 性能提升：异步并发、指数退避重试、资源及时释放
- 准确性改进：调整模糊匹配阈值、扩展品牌别名库、引入更细粒度的上下文特征
- 可靠性增强：完善错误分类与日志记录、增加健康检查与降级策略

章节来源
- [kimi.py:33-48](file://backend/app/workers/platforms/kimi.py#L33-L48)
- [wenxin.py:33-48](file://backend/app/workers/platforms/wenxin.py#L33-L48)
- [citation_engine.py:291-300](file://backend/app/workers/citation_engine.py#L291-L300)

### 算法调优指南
- 调整阈值：根据业务反馈微调模糊匹配阈值与置信度边界
- 品牌库维护：定期更新行业品牌清单与别名，提升识别覆盖率
- 上下文长度：根据下游应用需求调整片段长度，平衡信息量与性能
- 平台选择：针对不同关键词特性选择更适合的平台，必要时并行执行取并集

章节来源
- [test_citation_engine.py:6-54](file://tests/test_citation_engine.py#L6-L54)
- [citation_engine.py:126-130](file://backend/app/workers/citation_engine.py#L126-L130)

### 实际应用场景示例
- 品牌监测：对目标品牌进行周期性监测，追踪提及次数与趋势
- 竞品分析：识别文本中的竞争品牌，辅助市场情报收集
- 舆情预警：结合置信度与上下文，筛选高风险或高热度提及

章节来源
- [citation.py:76-201](file://backend/app/services/citation.py#L76-L201)
- [citations.py:25-77](file://backend/app/api/citations.py#L25-L77)