15 KiB

Raw Permalink Blame History

适配器架构设计

**本文档引用的文件** - [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_engine.py](file://backend/app/workers/citation_engine.py) - [scheduler.py](file://backend/app/workers/scheduler.py) - [queries.py](file://backend/app/api/queries.py) - [query.py](file://backend/app/models/query.py) - [main.py](file://backend/app/main.py) - [platforms.ts](file://frontend/lib/platforms.ts) - [platform-chart.tsx](file://frontend/components/charts/platform-chart.tsx)

简介

本项目采用适配器模式设计了一个可扩展的AI平台查询系统。该架构通过统一的接口抽象，实现了对不同AI平台（如Kimi、文心一言等）的无缝集成和切换。适配器模式在此场景中的应用价值体现在：

统一接口：为不同的AI平台提供一致的查询接口
可扩展性：轻松添加新的AI平台适配器
资源管理：统一的资源清理和生命周期管理
错误处理：标准化的异常处理和重试机制

项目结构

该项目采用前后端分离的架构设计，后端使用Python FastAPI框架，前端使用Next.js React框架。适配器架构主要集中在后端的workers目录中。

graph TB
subgraph "前端层"
FE[前端应用<br/>Next.js React]
PC[平台图表组件<br/>platform-chart.tsx]
PL[平台映射<br/>platforms.ts]
end
subgraph "后端层"
API[FastAPI API]
CE[CitationEngine<br/>引用检测引擎]
SCH[Scheduler<br/>调度器]
subgraph "适配器层"
BA[BasePlatformAdapter<br/>抽象基类]
KA[KimiAdapter<br/>Kimi适配器]
WA[WenxinAdapter<br/>文心一言适配器]
end
end
subgraph "数据层"
DB[(PostgreSQL数据库)]
QM[Query模型]
CRM[CitationRecord模型]
end
FE --> API
API --> CE
CE --> SCH
CE --> BA
BA --> KA
BA --> WA
CE --> DB
QM --> DB
CRM --> DB

图表来源

章节来源

核心组件

BasePlatformAdapter 抽象基类

BasePlatformAdapter是整个适配器架构的核心抽象类，定义了所有AI平台适配器必须实现的标准接口。

设计理念

该类采用了Python的ABC（Abstract Base Classes）机制，确保子类必须实现指定的抽象方法。设计理念包括：

最小接口原则：只定义必要的抽象方法，避免过度设计
职责单一原则：专注于平台适配功能，不包含业务逻辑
扩展性优先：为未来添加新平台预留空间

核心属性

属性名称	类型	描述	示例值
platform_name	str	平台标识符，用于内部识别	"kimi", "wenxin"
platform_url	str	平台官方网站地址	"https://kimi.moonshot.cn"

抽象方法

query(keyword: str) -> str

设计目的：在AI平台上查询关键词并返回原始响应文本
参数规范：
- keyword: str - 要查询的关键词
- 返回值: str - AI平台的原始响应文本
实现要求：必须异步实现，支持重试机制

close()

设计目的：清理适配器使用的系统资源
实现要求：异步方法，确保资源正确释放

章节来源

base.py:4-17

具体适配器实现

KimiAdapter

KimiAdapter是针对Moonshot AI平台的适配器实现，具有以下特点：

浏览器自动化：使用Playwright进行页面交互
智能重试：指数退避重试机制
稳定性保障：超时处理和异常恢复

WenxinAdapter

WenxinAdapter是针对百度文心一言平台的适配器实现：

相似架构：与KimiAdapter类似的实现模式
平台特定：针对文心一言的界面结构优化
一致性保证：保持与BasePlatformAdapter的接口兼容

章节来源

架构概览

整个系统采用分层架构设计，适配器模式位于中间层，向上提供统一接口，向下封装具体实现细节。

sequenceDiagram
participant Client as 客户端
participant API as FastAPI API
participant Engine as CitationEngine
participant Adapter as BasePlatformAdapter
participant Platform as AI平台
Client->>API : 发起查询请求
API->>Engine : execute_query()
Engine->>Engine : 创建BrandMatcher
Engine->>Adapter : execute_single_platform()
Adapter->>Adapter : query(keyword)
Adapter->>Platform : 执行平台查询
Platform-->>Adapter : 返回响应文本
Adapter-->>Engine : 返回原始响应
Engine->>Engine : 品牌匹配和竞争检测
Engine-->>API : 返回检测结果
API-->>Client : 返回查询结果

图表来源

详细组件分析

CitationEngine 引用检测引擎

CitationEngine是系统的中央协调器，负责管理多个平台适配器并执行完整的查询流程。

核心功能

平台管理：维护平台适配器字典
查询执行：协调单个平台的查询过程
结果处理：整合品牌匹配和竞争检测结果
任务跟踪：管理查询任务的状态和历史

关键流程

flowchart TD
Start([开始查询]) --> InitMatcher["初始化BrandMatcher"]
InitMatcher --> GetPlatforms["获取平台列表"]
GetPlatforms --> LoopPlatforms{"遍历平台"}
LoopPlatforms --> CreateTask["创建或获取QueryTask"]
CreateTask --> UpdateStatus["更新任务状态为running"]
UpdateStatus --> ExecutePlatform["执行单个平台查询"]
ExecutePlatform --> BrandMatch["品牌匹配检测"]
BrandMatch --> CompetitorDetect["竞争品牌检测"]
CompetitorDetect --> CreateRecord["创建CitationRecord"]
CreateRecord --> UpdateTaskSuccess["更新任务状态为success"]
UpdateTaskSuccess --> NextPlatform{"还有平台吗?"}
NextPlatform --> |是| LoopPlatforms
NextPlatform --> |否| UpdateQueryTime["更新查询时间字段"]
UpdateQueryTime --> End([结束])
ExecutePlatform --> |异常| CreateFailedRecord["创建失败记录"]
CreateFailedRecord --> UpdateTaskFailed["更新任务状态为failed"]
UpdateTaskFailed --> NextPlatform

图表来源

数据模型

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
datetime created_at
datetime updated_at
}
CITATION_RECORD {
uuid id PK
uuid query_id FK
string platform
boolean cited
integer citation_position
text citation_text
jsonb competitor_brands
text raw_response
datetime created_at
datetime updated_at
}
QUERY_TASK {
uuid id PK
uuid query_id FK
string platform
string status
datetime started_at
datetime completed_at
text error_message
datetime created_at
datetime updated_at
}
USER ||--o{ QUERY : creates
QUERY ||--o{ CITATION_RECORD : generates
QUERY ||--o{ QUERY_TASK : tracks

图表来源

章节来源

Scheduler 调度器

QueryScheduler负责定时执行查询任务，确保系统能够自动运行。

核心特性

定时执行：每小时检查一次到期的查询任务
异步处理：使用AsyncIOScheduler支持异步操作
错误隔离：单个查询失败不影响其他任务
优雅关闭：提供资源清理机制

生命周期管理

stateDiagram-v2
[*] --> 初始化
初始化 --> 启动 : start()
启动 --> 运行中 : 添加定时任务
运行中 --> 执行检查 : 每小时触发
执行检查 --> 处理查询 : 发现到期任务
处理查询 --> 运行中 : 继续监控
处理查询 --> 错误 : 异常处理
错误 --> 运行中 : 记录日志继续
运行中 --> 关闭 : shutdown()
关闭 --> [*]

图表来源

scheduler.py:25-95

章节来源

scheduler.py:25-95

前端集成

前端系统提供了完整的用户界面，支持平台选择和结果展示。

平台映射

前端使用PLATFORM_MAP和PLATFORMS常量来管理平台信息：

平台键	中文名称	用途
wenxin	文心一言	百度AI平台
kimi	Kimi	Moonshot AI平台
tongyi	通义千问	阿里云AI平台
baidu_ai	百度AI搜索	百度搜索服务
yuanbao	腾讯元宝	腾讯AI平台
qingyan	智谱清言	智谱AI平台

图表可视化

平台图表组件使用Recharts库展示各平台的引用率统计：

graph LR
subgraph "数据处理"
RAW[原始统计数据]
TRANSFORM[数据转换]
end
subgraph "可视化组件"
CHART[柱状图]
XAXIS[X轴: 平台名称]
YAXIS[Y轴: 引用率百分比]
TOOLTIP[工具提示]
end
RAW --> TRANSFORM
TRANSFORM --> CHART
CHART --> XAXIS
CHART --> YAXIS
CHART --> TOOLTIP

图表来源

章节来源

依赖关系分析

组件依赖图

graph TB
subgraph "外部依赖"
PW[Playwright]
APS[APScheduler]
SQLA[SQLAlchemy]
FAST[FastAPI]
end
subgraph "核心模块"
BASE[BasePlatformAdapter]
KIMI[KimiAdapter]
WENXIN[WenxinAdapter]
CE[CitationEngine]
SCH[QueryScheduler]
API[FastAPI API]
end
subgraph "数据模型"
QUERY[Query模型]
CITE[CitationRecord模型]
TASK[QueryTask模型]
end
PW --> KIMI
PW --> WENXIN
APS --> SCH
SQLA --> CE
FAST --> API
BASE --> KIMI
BASE --> WENXIN
CE --> BASE
API --> CE
CE --> QUERY
CE --> CITE
CE --> TASK

图表来源

耦合度分析

该系统展现了良好的内聚性和低耦合性：

高内聚：每个适配器专注于单一平台的实现
低耦合：通过抽象基类实现松散耦合
清晰边界：各层职责明确，接口清晰
可测试性：依赖注入和抽象接口便于单元测试

章节来源

性能考虑

异步编程模型

系统全面采用异步编程模式，提升了并发处理能力：

异步适配器：所有适配器方法都使用async/await
异步数据库：使用SQLAlchemy异步会话
异步调度：APScheduler的异步版本
异步HTTP：FastAPI的异步路由

资源管理策略

flowchart TD
InitBrowser["初始化浏览器"] --> UseBrowser["使用浏览器"]
UseBrowser --> CloseBrowser["关闭浏览器"]
CloseBrowser --> CleanupResources["清理系统资源"]
CleanupResources --> End([资源释放完成])
InitBrowser --> Error["异常发生"]
Error --> CleanupOnError["异常时清理资源"]
CleanupOnError --> End

图表来源

缓存和重试机制

指数退避：最多3次重试，间隔呈指数增长
超时控制：页面加载和操作都有超时限制
资源池化：浏览器实例复用，减少启动开销

故障排除指南

常见问题及解决方案

Playwright浏览器问题

症状：启动浏览器失败，提示需要安装Playwright浏览器

解决方案：

安装Playwright浏览器：python -m playwright install chromium
检查网络连接和代理设置
确认Docker环境中的浏览器可用性

页面元素定位失败

症状：无法找到输入框或发送按钮

解决方案：

检查平台URL是否正确
更新选择器表达式以适应页面变化
实现更健壮的元素等待机制

超时问题

症状：页面加载或响应超时

解决方案：

增加超时时间配置
检查网络连接稳定性
实现重试机制

章节来源

调试技巧

启用详细日志：查看适配器的详细执行过程
检查数据库状态：验证查询任务的状态更新
监控资源使用：观察浏览器进程和内存使用情况
测试独立适配器：单独测试某个平台的适配器

结论

该适配器架构设计成功地实现了以下目标：

架构优势

高度可扩展：新增平台只需实现BasePlatformAdapter接口
统一管理：通过CitationEngine集中管理所有平台
资源优化：统一的资源管理和清理机制
错误处理：完善的异常处理和重试机制

最佳实践建议

遵循接口契约：严格实现BasePlatformAdapter的所有抽象方法
资源管理：确保close()方法能够正确清理所有资源
错误处理：实现适当的异常处理和重试逻辑
配置管理：将平台特定的配置参数化
测试覆盖：为新适配器编写充分的单元测试

扩展指南

要为新平台创建适配器，需要：

继承BasePlatformAdapter类
设置platform_name和platform_url属性
实现query()方法的平台特定逻辑
实现close()方法清理资源
在CitationEngine中注册新适配器
编写相应的测试用例

该架构为AI平台集成提供了一个稳健、可扩展的基础，能够支持未来更多的平台集成需求。

15 KiB Raw Permalink Blame History Unescape Escape

适配器架构设计

目录

简介

项目结构

核心组件

BasePlatformAdapter 抽象基类

设计理念

核心属性

抽象方法

具体适配器实现

KimiAdapter

WenxinAdapter

架构概览

详细组件分析

CitationEngine 引用检测引擎

核心功能

关键流程

数据模型

Scheduler 调度器

核心特性

生命周期管理

前端集成

平台映射

图表可视化

依赖关系分析

组件依赖图

耦合度分析

性能考虑

异步编程模型

资源管理策略

缓存和重试机制

故障排除指南

常见问题及解决方案

Playwright浏览器问题

页面元素定位失败

超时问题

调试技巧

结论

架构优势

最佳实践建议

扩展指南

15 KiB

Raw Permalink Blame History