fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/AI平台集成/平台适配器扩展指南.md

408 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 平台适配器扩展指南
<cite>
**本文档引用的文件**
- [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)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南面向需要为系统新增AI平台适配器的开发者，提供从基类继承、实现必需方法、配置平台参数，到资源管理与性能优化的完整流程。文档同时覆盖两类平台适配策略：基于浏览器自动化（Playwright）的平台与基于API的平台，并给出测试方法、验证标准与常见问题排查建议。
## 项目结构
后端采用分层架构，平台适配器位于 workers/platforms 子目录；引用检测引擎位于 workers 子目录；查询模型与调度器分别位于 models 与 workers 子目录；前端通过 lib 与 components 提供平台映射、图表展示与API封装。
```mermaid
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
```
**图示来源**
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
**章节来源**
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
## 核心组件
- 适配器基类 BasePlatformAdapter：定义平台名称、平台URL以及抽象方法 query 与可选方法 close。
- 具体适配器 KimiAdapter 与 WenxinAdapter：均继承自基类，实现 query 方法并通过 Playwright 自动化浏览器进行交互。
- 引擎 CitationEngine：负责编排查询、调用适配器、执行品牌匹配与竞争品牌检测、持久化结果。
- 调度器 QueryScheduler：周期性触发查询任务执行。
- 查询模型 Query：承载关键词、目标品牌、别名、平台列表、频率与时间戳等元数据。
- 配置 Settings：集中管理数据库、Redis、JWT、Playwright浏览器路径及第三方API密钥等。
**章节来源**
- [backend/app/workers/platforms/base.py:1-18](file://backend/app/workers/platforms/base.py#L1-L18)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/models/query.py:1-55](file://backend/app/models/query.py#L1-L55)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
## 架构总览
下图展示了从调度器到引擎再到具体适配器的调用链路，以及前端如何消费平台映射与统计数据。
```mermaid
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 : 返回本次执行结果
```
**图示来源**
- [backend/app/workers/scheduler.py:51-84](file://backend/app/workers/scheduler.py#L51-L84)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
- [backend/app/workers/platforms/kimi.py:33-48](file://backend/app/workers/platforms/kimi.py#L33-L48)
- [backend/app/workers/platforms/wenxin.py:33-48](file://backend/app/workers/platforms/wenxin.py#L33-L48)
## 详细组件分析
### 基类与继承规范
- 必须实现的方法
- query(keyword: str) -> str：在指定平台查询关键词并返回原始响应文本。
- 可选方法
- close()：释放浏览器或网络连接等资源。
- 平台元信息
- platform_name：平台标识字符串。
- platform_url：平台主页URL。
```mermaid
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](file://backend/app/workers/platforms/base.py#L4-L17)
- [backend/app/workers/platforms/kimi.py:11-20](file://backend/app/workers/platforms/kimi.py#L11-L20)
- [backend/app/workers/platforms/wenxin.py:11-20](file://backend/app/workers/platforms/wenxin.py#L11-L20)
**章节来源**
- [backend/app/workers/platforms/base.py:4-17](file://backend/app/workers/platforms/base.py#L4-L17)
### 浏览器驱动型平台适配策略（以Kimi/Wenxin为例）
- 启动与重用浏览器：首次调用时初始化 Playwright 并启动 Chromium 浏览器，避免重复创建。
- 页面交互：导航至平台URL，等待并定位输入框，填充关键词，提交（回车或点击发送按钮）。
- 稳定性检测：持续轮询消息容器，当文本连续多次保持一致时判定回复稳定，返回内容。
- 错误处理：捕获超时与异常，记录日志并抛出可诊断的错误；提供指数退避重试机制。
- 资源管理：在 finally 中确保 page/context 关闭；close()统一释放浏览器与Playwright实例。
```mermaid
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(["结束"])
```
**图示来源**
- [backend/app/workers/platforms/kimi.py:21-48](file://backend/app/workers/platforms/kimi.py#L21-L48)
- [backend/app/workers/platforms/kimi.py:50-124](file://backend/app/workers/platforms/kimi.py#L50-L124)
- [backend/app/workers/platforms/kimi.py:126-196](file://backend/app/workers/platforms/kimi.py#L126-L196)
- [backend/app/workers/platforms/kimi.py:198-205](file://backend/app/workers/platforms/kimi.py#L198-L205)
- [backend/app/workers/platforms/wenxin.py:21-48](file://backend/app/workers/platforms/wenxin.py#L21-L48)
- [backend/app/workers/platforms/wenxin.py:50-123](file://backend/app/workers/platforms/wenxin.py#L50-L123)
- [backend/app/workers/platforms/wenxin.py:124-195](file://backend/app/workers/platforms/wenxin.py#L124-L195)
- [backend/app/workers/platforms/wenxin.py:197-204](file://backend/app/workers/platforms/wenxin.py#L197-L204)
**章节来源**
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
### API型平台适配策略（扩展指导）
- 继承基类并实现 query：通过HTTP客户端发起请求，解析JSON响应，提取平台返回的文本内容。
- 错误处理：区分网络错误、平台限流/鉴权失败、解析异常等，统一转换为可诊断的异常类型。
- 资源管理：若使用连接池或长连接，实现 close() 以释放连接；否则可为空实现。
- 配置参数：在 Settings 中添加平台API密钥与基础URL，前端与后端分别读取使用。
（本小节为概念性指导，不直接分析具体文件）
### 引擎与品牌检测
- CitationEngine 负责：
- 初始化各平台适配器实例并注册到平台字典。
- 针对每个 Query 的平台列表依次执行查询。
- 使用 BrandMatcher 执行精确/别名/模糊匹配，返回置信度与位置信息。
- 使用 CompetitorDetector 检测文本中出现的竞争品牌集合。
- 记录 CitationRecord 并更新 Query 的时间戳与下次查询时间。
- 资源关闭：在 close() 中遍历适配器逐一关闭，避免资源泄漏。
```mermaid
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:148-309](file://backend/app/workers/citation_engine.py#L148-L309)
- [backend/app/workers/citation_engine.py:19-120](file://backend/app/workers/citation_engine.py#L19-L120)
- [backend/app/workers/citation_engine.py:122-146](file://backend/app/workers/citation_engine.py#L122-L146)
**章节来源**
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
### 调度与执行
- QueryScheduler 使用 APScheduler 定时触发检查与执行逻辑，每小时扫描一次到期的查询任务。
- 对每个查询任务，CitationEngine.execute_query 会：
- 创建或获取 QueryTask 并更新状态为 running。
- 遍历平台列表执行查询与检测。
- 记录结果并更新 Query 的 last_queried_at 与 next_query_at。
- 若失败则记录错误并写入一条 cited=False 的占位记录。
- 关闭时统一调用 engine.close() 释放适配器资源。
```mermaid
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()
```
**图示来源**
- [backend/app/workers/scheduler.py:30-90](file://backend/app/workers/scheduler.py#L30-L90)
- [backend/app/workers/citation_engine.py:159-234](file://backend/app/workers/citation_engine.py#L159-L234)
**章节来源**
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
### 前端集成与展示
- 平台映射：前端 lib/platforms.ts 定义平台键到中文标签的映射，用于UI显示与图表标签。
- 图表组件：components/charts/platform-chart.tsx 接收平台统计数据，渲染引用率柱状图。
- API封装：frontend/lib/api.ts 提供认证、查询、引用与报表导出等接口封装，便于前端调用。
```mermaid
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"]
```
**图示来源**
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [frontend/components/charts/platform-chart.tsx:34-39](file://frontend/components/charts/platform-chart.tsx#L34-L39)
- [frontend/lib/api.ts:23-57](file://frontend/lib/api.ts#L23-L57)
**章节来源**
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
- [frontend/components/charts/platform-chart.tsx:1-68](file://frontend/components/charts/platform-chart.tsx#L1-L68)
- [frontend/lib/api.ts:1-58](file://frontend/lib/api.ts#L1-L58)
## 依赖分析
- 组件耦合
- CitationEngine 与具体适配器松耦合：通过平台字典注册与动态查找，便于扩展新平台。
- 调度器与引擎解耦：调度器仅负责触发，引擎负责业务逻辑与平台交互。
- 外部依赖
- Playwright：用于浏览器自动化（Kimi/Wenxin）。
- SQLAlchemy：用于数据库访问与事务控制。
- APScheduler：用于定时任务调度。
- Pydantic Settings：用于配置管理。
```mermaid
graph TB
CE["CitationEngine"] --> KIMI["KimiAdapter"]
CE --> WENXIN["WenxinAdapter"]
CE --> DB["SQLAlchemy"]
SCH["QueryScheduler"] --> CE
CE --> CFG["Settings"]
KIMI --> PW["Playwright"]
WENXIN --> PW
```
**图示来源**
- [backend/app/workers/citation_engine.py:152-155](file://backend/app/workers/citation_engine.py#L152-L155)
- [backend/app/workers/scheduler.py:26-28](file://backend/app/workers/scheduler.py#L26-L28)
- [backend/app/config.py:11-14](file://backend/app/config.py#L11-L14)
- [backend/app/workers/platforms/kimi.py:4-6](file://backend/app/workers/platforms/kimi.py#L4-L6)
- [backend/app/workers/platforms/wenxin.py:4-6](file://backend/app/workers/platforms/wenxin.py#L4-L6)
**章节来源**
- [backend/app/workers/citation_engine.py:1-309](file://backend/app/workers/citation_engine.py#L1-L309)
- [backend/app/workers/scheduler.py:1-95](file://backend/app/workers/scheduler.py#L1-L95)
- [backend/app/config.py:1-17](file://backend/app/config.py#L1-L17)
- [backend/app/workers/platforms/kimi.py:1-206](file://backend/app/workers/platforms/kimi.py#L1-L206)
- [backend/app/workers/platforms/wenxin.py:1-205](file://backend/app/workers/platforms/wenxin.py#L1-L205)
## 性能考虑
- 浏览器复用：避免每次查询都启动/关闭浏览器，减少冷启动开销。
- 稳定性检测阈值：合理设置“连续稳定”次数与轮询间隔，平衡准确性和延迟。
- 指数退避：在重试时采用指数退避，降低平台压力并提升成功率。
- 数据库批处理：批量写入引用记录与任务状态，减少IO往返。
- 超时与并发：为页面导航、元素等待与响应稳定检测设置合理超时，避免长时间阻塞。
- 缓存与预热：可在进程启动时预热部分资源（如Playwright浏览器），缩短首次查询耗时。
（本节为通用建议，不直接分析具体文件）
## 故障排查指南
- 浏览器相关
- 现象：启动浏览器失败或找不到输入框。
- 排查：确认已安装 Playwright 浏览器；检查平台URL可达性；核对页面选择器是否随平台更新而变更。
- 参考实现：Kimi/Wenxin 适配器在启动失败时抛出明确提示，需按提示执行安装命令。
- 超时与不稳定
- 现象：页面操作超时或回复未稳定。
- 排查：适当提高等待超时与稳定检测阈值；检查网络环境与平台负载。
- 参考实现：适配器内对超时与异常进行捕获并记录日志。
- 品牌匹配
- 现象：匹配结果不符合预期。
- 排查：调整别名列表、提高模糊匹配阈值或优化候选词提取逻辑。
- 参考实现：测试用例覆盖精确、别名、模糊与无匹配场景。
- 调度与状态
- 现象：查询未按时执行或状态异常。
- 排查：检查调度器是否启动、数据库连接与时区设置、Query 的 next_query_at 是否正确更新。
- 前端展示
- 现象：平台图表标签显示异常。
- 排查：确认前端平台映射与后端平台键一致。
**章节来源**
- [backend/app/workers/platforms/kimi.py:27-31](file://backend/app/workers/platforms/kimi.py#L27-L31)
- [backend/app/workers/platforms/kimi.py:87-88](file://backend/app/workers/platforms/kimi.py#L87-L88)
- [backend/app/workers/platforms/kimi.py:116-118](file://backend/app/workers/platforms/kimi.py#L116-L118)
- [backend/app/workers/platforms/wenxin.py:27-31](file://backend/app/workers/platforms/wenxin.py#L27-L31)
- [backend/app/workers/platforms/wenxin.py:86-87](file://backend/app/workers/platforms/wenxin.py#L86-L87)
- [backend/app/workers/platforms/wenxin.py:114-116](file://backend/app/workers/platforms/wenxin.py#L114-L116)
- [tests/test_citation_engine.py:6-53](file://tests/test_citation_engine.py#L6-L53)
- [backend/app/workers/scheduler.py:30-40](file://backend/app/workers/scheduler.py#L30-L40)
- [backend/app/workers/citation_engine.py:229-232](file://backend/app/workers/citation_engine.py#L229-L232)
- [frontend/lib/platforms.ts:1-18](file://frontend/lib/platforms.ts#L1-L18)
## 结论
通过继承 BasePlatformAdapter 并遵循本文提供的实现规范与最佳实践，可以快速、安全地为系统接入新的AI平台。对于浏览器驱动型平台，重点在于稳定的选择器策略与资源管理；对于API型平台，重点在于健壮的错误处理与配置管理。配合引擎的品牌检测能力与调度器的自动化执行，可构建高可用的跨平台引用检测体系。
## 附录
### 新平台接入步骤清单
- 继承基类并实现必需方法
- 在 workers/platforms 下新建适配器文件，继承 BasePlatformAdapter。
- 实现 query 与可选的 close。
- 设置 platform_name 与 platform_url。
- 注册到引擎
- 在 CitationEngine 的平台字典中注册新适配器实例。
- 配置与密钥
- 在 Settings 中添加必要的配置项（如API密钥、基础URL）。
- 前端集成
- 在前端 lib/platforms.ts 中添加平台键与中文标签。
- 如需展示统计，确保后端返回的数据结构与前端图表组件兼容。
- 测试与验证
- 编写单元测试覆盖品牌匹配与竞争品牌检测逻辑。
- 进行端到端测试，验证调度器触发、引擎执行与数据库写入。
- 性能与稳定性
- 评估并优化超时、重试与稳定检测策略。
- 监控日志与错误指标，持续改进。
（本节为流程性说明，不直接分析具体文件）
Reference in New Issue View Git Blame Copy Permalink