20 KiB

Raw Permalink Blame History

平台适配器扩展指南

**本文档引用的文件** - [backend/app/workers/platforms/base.py](file://backend/app/workers/platforms/base.py) - [backend/app/workers/platforms/kimi.py](file://backend/app/workers/platforms/kimi.py) - [backend/app/workers/platforms/wenxin.py](file://backend/app/workers/platforms/wenxin.py) - [backend/app/workers/citation_engine.py](file://backend/app/workers/citation_engine.py) - [backend/app/workers/scheduler.py](file://backend/app/workers/scheduler.py) - [backend/app/models/query.py](file://backend/app/models/query.py) - [backend/app/config.py](file://backend/app/config.py) - [frontend/lib/platforms.ts](file://frontend/lib/platforms.ts) - [frontend/components/charts/platform-chart.tsx](file://frontend/components/charts/platform-chart.tsx) - [frontend/lib/api.ts](file://frontend/lib/api.ts) - [tests/test_citation_engine.py](file://tests/test_citation_engine.py)

简介

本指南面向需要为系统新增AI平台适配器的开发者，提供从基类继承、实现必需方法、配置平台参数，到资源管理与性能优化的完整流程。文档同时覆盖两类平台适配策略：基于浏览器自动化（Playwright）的平台与基于API的平台，并给出测试方法、验证标准与常见问题排查建议。

项目结构

后端采用分层架构，平台适配器位于 workers/platforms 子目录；引用检测引擎位于 workers 子目录；查询模型与调度器分别位于 models 与 workers 子目录；前端通过 lib 与 components 提供平台映射、图表展示与API封装。

graph TB
subgraph "后端"
CFG["配置<br/>app/config.py"]
SCH["调度器<br/>workers/scheduler.py"]
CE["引用引擎<br/>workers/citation_engine.py"]
BP["适配器基类<br/>workers/platforms/base.py"]
KIMI["Kimi适配器<br/>workers/platforms/kimi.py"]
WENXIN["文心一言适配器<br/>workers/platforms/wenxin.py"]
QRY["查询模型<br/>models/query.py"]
end
subgraph "前端"
PFM["平台映射<br/>lib/platforms.ts"]
API["API封装<br/>lib/api.ts"]
CHART["平台图表<br/>components/charts/platform-chart.tsx"]
end
SCH --> CE
CE --> KIMI
CE --> WENXIN
CE --> QRY
BP -. 继承 .- KIMI
BP -. 继承 .- WENXIN
PFM --> CHART
API --> SCH

图示来源

章节来源

核心组件

适配器基类 BasePlatformAdapter：定义平台名称、平台URL以及抽象方法 query 与可选方法 close。
具体适配器 KimiAdapter 与 WenxinAdapter：均继承自基类，实现 query 方法并通过 Playwright 自动化浏览器进行交互。
引擎 CitationEngine：负责编排查询、调用适配器、执行品牌匹配与竞争品牌检测、持久化结果。
调度器 QueryScheduler：周期性触发查询任务执行。
查询模型 Query：承载关键词、目标品牌、别名、平台列表、频率与时间戳等元数据。
配置 Settings：集中管理数据库、Redis、JWT、Playwright浏览器路径及第三方API密钥等。

章节来源

架构总览

下图展示了从调度器到引擎再到具体适配器的调用链路，以及前端如何消费平台映射与统计数据。

sequenceDiagram
participant S as "调度器<br/>workers/scheduler.py"
participant E as "引擎<br/>workers/citation_engine.py"
participant A as "适配器<br/>Kimi/Wenxin"
participant DB as "数据库<br/>SQLAlchemy"
S->>E : 触发执行查询
E->>DB : 查询待执行的 Query
loop 遍历平台
E->>A : 调用 query(keyword)
A-->>E : 返回原始响应文本
E->>E : 品牌匹配/竞争品牌检测
E->>DB : 写入引用记录与任务状态
end
E-->>S : 返回本次执行结果

图示来源

详细组件分析

基类与继承规范

必须实现的方法
- query(keyword: str) -> str：在指定平台查询关键词并返回原始响应文本。
可选方法
- close()：释放浏览器或网络连接等资源。
平台元信息
- platform_name：平台标识字符串。
- platform_url：平台主页URL。

classDiagram
class BasePlatformAdapter {
+string platform_name
+string platform_url
+query(keyword) str
+close() void
}
class KimiAdapter {
+platform_name = "kimi"
+platform_url = "https : //kimi.moonshot.cn"
+query(keyword) str
+close() void
}
class WenxinAdapter {
+platform_name = "wenxin"
+platform_url = "https : //yiyan.baidu.com"
+query(keyword) str
+close() void
}
KimiAdapter --|> BasePlatformAdapter
WenxinAdapter --|> BasePlatformAdapter

图示来源

章节来源

backend/app/workers/platforms/base.py:4-17

浏览器驱动型平台适配策略（以Kimi/Wenxin为例）

启动与重用浏览器：首次调用时初始化 Playwright 并启动 Chromium 浏览器，避免重复创建。
页面交互：导航至平台URL，等待并定位输入框，填充关键词，提交（回车或点击发送按钮）。
稳定性检测：持续轮询消息容器，当文本连续多次保持一致时判定回复稳定，返回内容。
错误处理：捕获超时与异常，记录日志并抛出可诊断的错误；提供指数退避重试机制。
资源管理：在 finally 中确保 page/context 关闭；close()统一释放浏览器与Playwright实例。

flowchart TD
Start(["进入 query"]) --> Ensure["确保浏览器已启动"]
Ensure --> TryDo["_do_query 尝试一次查询"]
TryDo --> Stable["等待回复稳定"]
Stable --> Done["返回原始响应文本"]
TryDo --> |异常| Retry{"重试次数 < 3?"}
Retry --> |是| Backoff["指数退避等待"] --> TryDo
Retry --> |否| Raise["抛出最终异常"]
Done --> Close["关闭 page/context"]
Raise --> Close
Close --> End(["结束"])

图示来源

章节来源

API型平台适配策略（扩展指导）

继承基类并实现 query：通过HTTP客户端发起请求，解析JSON响应，提取平台返回的文本内容。
错误处理：区分网络错误、平台限流/鉴权失败、解析异常等，统一转换为可诊断的异常类型。
资源管理：若使用连接池或长连接，实现 close() 以释放连接；否则可为空实现。
配置参数：在 Settings 中添加平台API密钥与基础URL，前端与后端分别读取使用。

（本小节为概念性指导，不直接分析具体文件）

引擎与品牌检测

CitationEngine 负责：
- 初始化各平台适配器实例并注册到平台字典。
- 针对每个 Query 的平台列表依次执行查询。
- 使用 BrandMatcher 执行精确/别名/模糊匹配，返回置信度与位置信息。
- 使用 CompetitorDetector 检测文本中出现的竞争品牌集合。
- 记录 CitationRecord 并更新 Query 的时间戳与下次查询时间。
资源关闭：在 close() 中遍历适配器逐一关闭，避免资源泄漏。

classDiagram
class CitationEngine {
+dict platforms
+BrandMatcher matcher
+CompetitorDetector competitor_detector
+execute_query(query, db) list
+execute_single_platform(keyword, platform, ...) dict
+close() void
}
class BrandMatcher {
+match(text) dict
}
class CompetitorDetector {
+detect(text, target_brand) list
}
CitationEngine --> BrandMatcher : "使用"
CitationEngine --> CompetitorDetector : "使用"

图示来源

章节来源

backend/app/workers/citation_engine.py:1-309

调度与执行

QueryScheduler 使用 APScheduler 定时触发检查与执行逻辑，每小时扫描一次到期的查询任务。
对每个查询任务，CitationEngine.execute_query 会：
- 创建或获取 QueryTask 并更新状态为 running。
- 遍历平台列表执行查询与检测。
- 记录结果并更新 Query 的 last_queried_at 与 next_query_at。
- 若失败则记录错误并写入一条 cited=False 的占位记录。
关闭时统一调用 engine.close() 释放适配器资源。

sequenceDiagram
participant SCH as "调度器"
participant CE as "引擎"
participant DB as "数据库"
SCH->>CE : check_and_execute_queries()
CE->>DB : 查询 active 且到期的 Query
loop 遍历查询
CE->>DB : 获取/创建 QueryTask
CE->>CE : 执行平台查询与检测
CE->>DB : 写入 CitationRecord 与更新 Query
end
SCH->>CE : shutdown()
CE->>CE : close()

图示来源

章节来源

前端集成与展示

平台映射：前端 lib/platforms.ts 定义平台键到中文标签的映射，用于UI显示与图表标签。
图表组件：components/charts/platform-chart.tsx 接收平台统计数据，渲染引用率柱状图。
API封装：frontend/lib/api.ts 提供认证、查询、引用与报表导出等接口封装，便于前端调用。

graph LR
PFM["平台映射<br/>lib/platforms.ts"] --> CHART["平台图表<br/>components/charts/platform-chart.tsx"]
API["API封装<br/>lib/api.ts"] --> SCH["调度器<br/>workers/scheduler.py"]
API --> CE["引擎<br/>workers/citation_engine.py"]

图示来源

章节来源

依赖分析

组件耦合
- CitationEngine 与具体适配器松耦合：通过平台字典注册与动态查找，便于扩展新平台。
- 调度器与引擎解耦：调度器仅负责触发，引擎负责业务逻辑与平台交互。
外部依赖
- Playwright：用于浏览器自动化（Kimi/Wenxin）。
- SQLAlchemy：用于数据库访问与事务控制。
- APScheduler：用于定时任务调度。
- Pydantic Settings：用于配置管理。

graph TB
CE["CitationEngine"] --> KIMI["KimiAdapter"]
CE --> WENXIN["WenxinAdapter"]
CE --> DB["SQLAlchemy"]
SCH["QueryScheduler"] --> CE
CE --> CFG["Settings"]
KIMI --> PW["Playwright"]
WENXIN --> PW

图示来源

章节来源

性能考虑

浏览器复用：避免每次查询都启动/关闭浏览器，减少冷启动开销。
稳定性检测阈值：合理设置“连续稳定”次数与轮询间隔，平衡准确性和延迟。
指数退避：在重试时采用指数退避，降低平台压力并提升成功率。
数据库批处理：批量写入引用记录与任务状态，减少IO往返。
超时与并发：为页面导航、元素等待与响应稳定检测设置合理超时，避免长时间阻塞。
缓存与预热：可在进程启动时预热部分资源（如Playwright浏览器），缩短首次查询耗时。

（本节为通用建议，不直接分析具体文件）

故障排查指南

浏览器相关
- 现象：启动浏览器失败或找不到输入框。
- 排查：确认已安装 Playwright 浏览器；检查平台URL可达性；核对页面选择器是否随平台更新而变更。
- 参考实现：Kimi/Wenxin 适配器在启动失败时抛出明确提示，需按提示执行安装命令。
超时与不稳定
- 现象：页面操作超时或回复未稳定。
- 排查：适当提高等待超时与稳定检测阈值；检查网络环境与平台负载。
- 参考实现：适配器内对超时与异常进行捕获并记录日志。
品牌匹配
- 现象：匹配结果不符合预期。
- 排查：调整别名列表、提高模糊匹配阈值或优化候选词提取逻辑。
- 参考实现：测试用例覆盖精确、别名、模糊与无匹配场景。
调度与状态
- 现象：查询未按时执行或状态异常。
- 排查：检查调度器是否启动、数据库连接与时区设置、Query 的 next_query_at 是否正确更新。
前端展示
- 现象：平台图表标签显示异常。
- 排查：确认前端平台映射与后端平台键一致。

章节来源

结论

通过继承 BasePlatformAdapter 并遵循本文提供的实现规范与最佳实践，可以快速、安全地为系统接入新的AI平台。对于浏览器驱动型平台，重点在于稳定的选择器策略与资源管理；对于API型平台，重点在于健壮的错误处理与配置管理。配合引擎的品牌检测能力与调度器的自动化执行，可构建高可用的跨平台引用检测体系。

附录

新平台接入步骤清单

继承基类并实现必需方法
- 在 workers/platforms 下新建适配器文件，继承 BasePlatformAdapter。
- 实现 query 与可选的 close。
- 设置 platform_name 与 platform_url。
注册到引擎
- 在 CitationEngine 的平台字典中注册新适配器实例。
配置与密钥
- 在 Settings 中添加必要的配置项（如API密钥、基础URL）。
前端集成
- 在前端 lib/platforms.ts 中添加平台键与中文标签。
- 如需展示统计，确保后端返回的数据结构与前端图表组件兼容。
测试与验证
- 编写单元测试覆盖品牌匹配与竞争品牌检测逻辑。
- 进行端到端测试，验证调度器触发、引擎执行与数据库写入。
性能与稳定性
- 评估并优化超时、重试与稳定检测策略。
- 监控日志与错误指标，持续改进。

（本节为流程性说明，不直接分析具体文件）

20 KiB Raw Permalink Blame History Unescape Escape

平台适配器扩展指南

目录

简介

项目结构

核心组件

架构总览

详细组件分析

基类与继承规范

浏览器驱动型平台适配策略（以Kimi/Wenxin为例）

API型平台适配策略（扩展指导）

引擎与品牌检测

调度与执行

前端集成与展示

依赖分析

性能考虑

故障排查指南

结论

附录

新平台接入步骤清单

20 KiB

Raw Permalink Blame History