fischer
/
geo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
geo/.qoder/repowiki/zh/content/扩展与定制/第三方集成.md

24 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/api/auth.py](file://backend/app/api/auth.py) - [backend/app/services/auth.py](file://backend/app/services/auth.py) - [backend/app/api/queries.py](file://backend/app/api/queries.py) - [backend/app/models/user.py](file://backend/app/models/user.py) - [backend/app/models/query.py](file://backend/app/models/query.py) - [backend/app/models/query_task.py](file://backend/app/models/query_task.py) - [backend/app/config.py](file://backend/app/config.py) - [backend/app/database.py](file://backend/app/database.py) - [backend/alembic/versions/488d0bd5ab01_initial_migration.py](file://backend/alembic/versions/488d0bd5ab01_initial_migration.py) - [backend/app/schemas/auth.py](file://backend/app/schemas/auth.py)

目录

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

简介

本指南面向需要在 GEO 平台上集成新的第三方能力的开发者，覆盖以下主题：

  • 新 AI 平台接入：适配器接口实现、平台认证配置与查询逻辑适配
  • 新数据库支持：SQLAlchemy 模型扩展、迁移脚本编写与连接配置
  • 新认证方式集成：OAuth 提供商配置、JWT 令牌处理与权限系统扩展
  • 插件系统使用：插件注册机制、生命周期管理与错误处理
  • 实战示例与常见问题解决方案

项目结构

后端采用 FastAPI + SQLAlchemy Async + APScheduler 的架构，核心模块如下：

  • workers：爬虫式 AI 平台适配器与引用检测引擎、定时调度器
  • api：FastAPI 路由层，负责请求入口与权限校验
  • services：业务服务层，封装认证、查询等核心逻辑
  • models/schemas：数据模型与请求/响应模型
  • database/config：数据库连接与配置
  • alembic：数据库迁移工具
graph TB
subgraph "API 层"
RAuth["路由: 认证 /api/auth/*"]
RQueries["路由: 查询 /api/queries/*"]
end
subgraph "服务层"
SAuth["服务: 认证"]
SQuery["服务: 查询"]
end
subgraph "工作器"
CE["引擎: 引用检测"]
SCH["调度器: 定时任务"]
ADP["适配器: AI 平台"]
end
subgraph "数据层"
DB["数据库: Async Engine"]
MUser["模型: User"]
MQuery["模型: Query"]
MTask["模型: QueryTask"]
end
RAuth --> SAuth
RQueries --> SQuery
SQuery --> CE
SCH --> CE
CE --> ADP
SAuth --> DB
SQuery --> DB
CE --> DB
DB --> MUser
DB --> MQuery
DB --> MTask

图表来源

章节来源

核心组件

  • 适配器接口与具体实现：统一的 AI 平台查询接口，内置 Kimi 与文心一言适配器
  • 引用检测引擎：对平台返回内容进行品牌引用检测与竞争品牌识别
  • 定时调度器：基于 APScheduler 的周期性查询任务调度
  • 认证与权限：基于 JWT 的用户认证与权限控制
  • 数据模型与迁移：基于 SQLAlchemy Async 的模型与 Alembic 迁移

章节来源

架构总览

下图展示从 API 请求到定时任务执行、再到 AI 平台查询与结果入库的整体流程。

sequenceDiagram
participant Client as "客户端"
participant API as "FastAPI 路由"
participant Service as "业务服务"
participant Scheduler as "定时调度器"
participant Engine as "引用检测引擎"
participant Adapter as "AI 平台适配器"
participant DB as "数据库"
Client->>API : "登录/注册/查询请求"
API->>Service : "认证/授权/业务处理"
Service->>DB : "读写模型数据"
Note over Scheduler : "定时触发"
Scheduler->>Engine : "执行到期查询"
Engine->>Adapter : "调用平台查询"
Adapter-->>Engine : "返回原始响应"
Engine->>DB : "写入引用记录/任务状态"
Engine-->>Scheduler : "更新查询时间"

图表来源

详细组件分析

组件A：AI 平台适配器体系

  • 接口设计：抽象基类定义统一的平台名称、URL 与查询接口
  • 具体实现：Kimi 与文心一言适配器均继承基类，实现稳定的页面交互与响应等待逻辑
  • 错误处理：重试机制、指数退避、超时处理与资源清理
  • 扩展建议：新增平台时，遵循相同接口与错误处理模式
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
}
BasePlatformAdapter <|-- KimiAdapter
BasePlatformAdapter <|-- WenxinAdapter

图表来源

章节来源

组件B：引用检测引擎与查询任务

  • 引擎职责：遍历查询配置的平台，执行查询与品牌匹配，记录结果与任务状态
  • 品牌匹配：精确/别名/模糊匹配，并提取置信度与上下文片段
  • 竞争品牌检测：基于预设品牌库识别文本中的竞品
  • 任务管理：为每个查询与平台维护独立的任务记录，支持失败重试与状态追踪
flowchart TD
Start(["开始执行查询"]) --> Init["初始化 BrandMatcher 与平台列表"]
Init --> Loop{"遍历平台"}
Loop --> |执行| Single["执行单平台查询"]
Single --> Detect["品牌匹配与竞品检测"]
Detect --> Record["写入引用记录与任务状态"]
Record --> Next{"还有平台？"}
Next --> |是| Loop
Next --> |否| Update["更新查询下次执行时间"]
Update --> End(["结束"])

图表来源

章节来源

组件C：定时调度器

  • 触发策略：每小时检查一次到期查询
  • 执行流程：定位状态为 active 且 next_query_at 已到达的查询，委派引擎执行
  • 生命周期：启动/关闭时清理资源，优雅退出
sequenceDiagram
participant Timer as "APScheduler"
participant Scheduler as "QueryScheduler"
participant DB as "数据库"
participant Engine as "CitationEngine"
Timer->>Scheduler : "定时触发"
Scheduler->>DB : "查询到期的 Query"
DB-->>Scheduler : "返回待执行查询集合"
loop "逐条执行"
Scheduler->>Engine : "execute_query(query)"
Engine-->>Scheduler : "返回引用记录"
end

图表来源

章节来源

组件D：认证与权限系统

  • 用户模型：包含邮箱、密码哈希、计划与配额等字段
  • 登录/注册：服务层进行密码哈希与校验，生成 JWT
  • 路由保护：通过依赖注入获取当前用户，实现基于角色的访问控制
  • 权限扩展：可基于用户计划与配额限制查询频率与数量
sequenceDiagram
participant Client as "客户端"
participant API as "认证路由"
participant Service as "认证服务"
participant DB as "数据库"
Client->>API : "POST /api/auth/login"
API->>Service : "authenticate_user(email, password)"
Service->>DB : "查询用户并校验密码"
DB-->>Service : "返回用户信息"
Service-->>API : "生成 JWT"
API-->>Client : "返回 TokenResponse"

图表来源

章节来源

组件E：数据库模型与迁移

  • 模型关系：User 与 Query、Subscription；Query 与 CitationRecord、QueryTask
  • 字段设计：JSONB 存储平台列表与别名，UUID 主键，索引优化查询
  • 迁移脚本：初始版本包含 users、queries、citation_records、query_tasks、subscriptions 表及索引
erDiagram
USERS {
uuid id PK
string email UK
string password_hash
string name
string plan
int max_queries
boolean is_active
timestamp created_at
timestamp updated_at
}
QUERIES {
uuid id PK
uuid user_id FK
string keyword
string target_brand
jsonb brand_aliases
jsonb platforms
string frequency
string status
timestamp last_queried_at
timestamp next_query_at
timestamp created_at
timestamp updated_at
}
QUERY_TASKS {
uuid id PK
uuid query_id FK
string platform
string status
text error_message
timestamp scheduled_at
timestamp started_at
timestamp completed_at
}
CITATION_RECORDS {
uuid id PK
uuid query_id FK
string platform
boolean cited
int citation_position
text citation_text
jsonb competitor_brands
text raw_response
timestamp queried_at
}
SUBSCRIPTIONS {
uuid id PK
uuid user_id FK
string plan
string status
date start_date
date end_date
numeric amount
string payment_method
string payment_id
timestamp created_at
}
USERS ||--o{ QUERIES : "拥有"
USERS ||--o{ SUBSCRIPTIONS : "拥有"
QUERIES ||--o{ QUERY_TASKS : "包含"
QUERIES ||--o{ CITATION_RECORDS : "产生"

图表来源

章节来源

依赖分析

  • 组件耦合：引擎依赖适配器接口；调度器依赖引擎；API 依赖服务层；服务层依赖数据库
  • 外部依赖：FastAPI、SQLAlchemy Async、APScheduler、Pydantic、JWTS、Passlib、Playwright
  • 配置集中：数据库 URL、Redis URL、JWT 秘钥与过期时间、平台 API Key 等集中于配置类
graph LR
APIAuth["API: 认证"] --> SAuth["服务: 认证"]
APIQueries["API: 查询"] --> SQuery["服务: 查询"]
SQuery --> CE["引擎: 引用检测"]
SCH["调度器: 定时任务"] --> CE
CE --> ADP["适配器: AI 平台"]
SAuth --> DB["数据库: Async Engine"]
SQuery --> DB
CE --> DB
DB --> CFG["配置: Settings"]

图表来源

章节来源

性能考虑

  • 引擎并发：适配器查询采用异步与重试策略，避免阻塞；建议在高并发场景下增加适配器池与限流
  • 数据库索引：对查询表的关键字段建立索引，减少调度器扫描成本
  • 缓存策略：可引入 Redis 缓存热点查询结果与任务状态
  • 超时与退避：适配器已内置超时与指数退避，建议结合平台限速策略调整重试参数

故障排查指南

章节来源

结论

本指南提供了 GEO 平台集成第三方能力的系统化方法论与实践路径。通过适配器接口与引擎解耦、定时调度与任务状态管理、认证与权限控制以及数据库模型与迁移规范，开发者可以快速、安全地扩展平台能力。建议在生产环境中结合缓存、限流与监控进一步完善整体稳定性与可观测性。

附录

新 AI 平台接入流程（步骤清单）

章节来源

新数据库支持（步骤清单）

章节来源

新认证方式集成（步骤清单）

章节来源

插件系统使用指南（概念性说明）

章节来源