503 lines
16 KiB
Markdown
503 lines
16 KiB
Markdown
# GEO 平台 - AI Agent 框架设计
|
||
|
||
## 概述
|
||
|
||
GEO 平台的 AI Agent 框架是系统的核心智能层，负责执行各种需要 AI 能力的业务任务。框架采用模块化、可插拔的设计，支持 Agent 的动态注册、任务分发和状态管理。
|
||
|
||
本文档定义 Agent 框架的整体架构、核心组件和通信机制。
|
||
|
||
## Agent 列表
|
||
|
||
### CitationDetector（引用检测 Agent）
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| **职责** | 解析 AI 平台响应，识别其中是否包含品牌引用 |
|
||
| **输入** | AI 平台原始响应文本、品牌名称列表、竞品名称列表 |
|
||
| **输出** | 引用检测结果（引用/未引用/竞品引用）、引用片段、置信度评分 |
|
||
| **核心能力** | 自然语言理解、实体识别、引用关系判定 |
|
||
| **触发方式** | 查询任务完成后自动触发 |
|
||
| **优先级** | P0 |
|
||
|
||
**处理流程**：
|
||
```
|
||
接收响应文本 ──▶ 文本预处理 ──▶ 品牌实体识别 ──▶ 引用关系判定
|
||
│
|
||
▼
|
||
竞品引用检测 ──▶ 置信度评估
|
||
│
|
||
▼
|
||
结果格式化 ──▶ 上报结果
|
||
```
|
||
|
||
**引用类型判定**：
|
||
| 类型 | 判定标准 | 置信度权重 |
|
||
|------|----------|------------|
|
||
| `direct_quote` | 品牌名被直接提及并作为信息来源 | 高 |
|
||
| `indirect_reference` | 品牌信息被提及但未明确标注来源 | 中 |
|
||
| `no_reference` | 品牌完全未被提及 | 确定 |
|
||
| `competitor_reference` | 竞品被引用而品牌未被引用 | 高 |
|
||
|
||
### ContentGenerator（内容生成 Agent）
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| **职责** | 根据策略和规则生成 GEO 优化的内容资产 |
|
||
| **输入** | 内容主题、规则库配置、品牌素材、参考数据 |
|
||
| **输出** | GEO 优化内容（文章/问答/指南等）、内容元数据 |
|
||
| **核心能力** | 创意写作、SEO/GEO 优化、多风格适配 |
|
||
| **触发方式** | 用户手动触发或按排期自动触发 |
|
||
| **优先级** | P0 |
|
||
|
||
**处理流程**：
|
||
```
|
||
接收生成任务 ──▶ 需求分析 ──▶ 素材收集 ──▶ 大纲生成
|
||
│
|
||
▼
|
||
内容撰写 ──▶ GEO 优化处理
|
||
│
|
||
▼
|
||
自检校验 ──▶ 输出结果
|
||
```
|
||
|
||
**内容类型支持**：
|
||
| 类型 | 说明 | 适用场景 |
|
||
|------|------|----------|
|
||
| `article` | 长篇文章（800-2000 字） | 深度行业内容 |
|
||
| `qa` | 问答对 | 常见品牌问题 |
|
||
| `guide` | 操作指南 | 产品使用场景 |
|
||
| `comparison` | 对比分析 | 竞品对抗 |
|
||
| `data_report` | 数据报告 | 行业研究 |
|
||
|
||
### RuleChecker（规则检查 Agent）
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| **职责** | 检查内容是否符合规则库中的约束条件 |
|
||
| **输入** | 待检查内容、规则库配置 |
|
||
| **输出** | 检查结果（通过/不通过）、问题列表、改进建议 |
|
||
| **核心能力** | 规则引擎、内容质量评估、语义分析 |
|
||
| **触发方式** | ContentGenerator 生成后自动触发，或手动触发 |
|
||
| **优先级** | P0 |
|
||
|
||
**检查维度**：
|
||
| 维度 | 说明 | 示例规则 |
|
||
|------|------|----------|
|
||
| `keyword_coverage` | 关键词覆盖度 | 必须包含核心关键词 |
|
||
| `readability` | 可读性评分 | Flesch 阅读 ease 分数 |
|
||
| `tone_consistency` | 语气一致性 | 保持专业、客观语气 |
|
||
| `length_compliance` | 长度合规 | 符合目标平台偏好长度 |
|
||
| `fact_accuracy` | 事实准确性 | 品牌信息准确无误 |
|
||
| `geo_optimization` | GEO 优化度 | 符合 GEO 最佳实践 |
|
||
|
||
### CompetitorAnalyzer（竞品分析 Agent）
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| **职责** | 分析竞品的 GEO 表现和策略 |
|
||
| **输入** | 竞品名称、查询结果、引用数据 |
|
||
| **输出** | 竞品分析报告、SWOT 分析、策略建议 |
|
||
| **核心能力** | 竞品数据对比、模式识别、策略推断 |
|
||
| **触发方式** | 诊断分析流程中自动触发 |
|
||
| **优先级** | P1 |
|
||
|
||
**分析维度**：
|
||
| 维度 | 说明 |
|
||
|------|------|
|
||
| `citation_share` | 竞品引用份额占比 |
|
||
| `platform_presence` | 各平台出现频率 |
|
||
| `content_pattern` | 竞品被引用的内容模式 |
|
||
| `strength_weakness` | 竞品的优劣势分析 |
|
||
| `strategy_inference` | 推测竞品的 GEO 策略 |
|
||
|
||
### PerformanceTracker（性能追踪 Agent）
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| **职责** | 持续追踪品牌 GEO 表现，计算 KPI，检测异常 |
|
||
| **输入** | 历史引用数据、当前查询结果、KPI 配置 |
|
||
| **输出** | KPI 计算结果、趋势分析、异常告警、优化建议 |
|
||
| **核心能力** | 时间序列分析、趋势预测、异常检测 |
|
||
| **触发方式** | 按设定周期自动执行 |
|
||
| **优先级** | P1 |
|
||
|
||
**追踪指标**：
|
||
| 指标 | 计算方式 | 更新频率 |
|
||
|------|----------|----------|
|
||
| `citation_rate` | 被引用查询数 / 总查询数 | 每日 |
|
||
| `avg_confidence` | 引用记录置信度平均值 | 每次查询 |
|
||
| `platform_coverage` | 已覆盖平台数 / 目标平台数 | 每周 |
|
||
| `ranking_position` | 品牌在引用中的平均排名 | 每周 |
|
||
| `competitor_gap` | 品牌引用率 - 竞品平均引用率 | 每周 |
|
||
|
||
## 通信协议
|
||
|
||
### Agent 间通信模型
|
||
|
||
GEO 平台 Agent 之间采用 **基于 Redis 消息队列的异步通信协议**。
|
||
|
||
```
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ Agent A │◀────▶│ Redis │◀────▶│ Agent B │
|
||
│ (Producer) │ │ Queue │ │ (Consumer) │
|
||
└─────────────┘ └──────┬──────┘ └─────────────┘
|
||
│
|
||
┌──────▼──────┐
|
||
│ Registry │
|
||
│ (Hash Map) │
|
||
└─────────────┘
|
||
```
|
||
|
||
### 消息格式规范
|
||
|
||
```python
|
||
class AgentMessage:
|
||
"""Agent 间通信消息标准格式"""
|
||
|
||
message_id: str # UUID，消息唯一标识
|
||
timestamp: datetime # ISO 8601 格式时间戳
|
||
sender: str # 发送方 Agent 名称
|
||
recipient: str # 接收方 Agent 名称，或 "broadcast"
|
||
message_type: str # 消息类型
|
||
correlation_id: str # 关联 ID，用于追踪请求-响应链路
|
||
reply_to: str # 回复目标 Agent
|
||
payload: dict # 消息负载数据
|
||
ttl: int # 消息存活时间（秒），默认 300
|
||
```
|
||
|
||
**消息类型（message_type）**：
|
||
| 类型 | 说明 | 使用场景 |
|
||
|------|------|----------|
|
||
| `task_request` | 任务请求 | Agent A 请求 Agent B 执行任务 |
|
||
| `task_result` | 任务结果 | Agent B 返回任务执行结果 |
|
||
| `status_update` | 状态更新 | Agent 上报自身状态变化 |
|
||
| `heartbeat` | 心跳 | Agent 定期发送健康信号 |
|
||
| `config_update` | 配置更新 | 通知 Agent 配置变更 |
|
||
| `error_report` | 错误报告 | Agent 报告执行错误 |
|
||
|
||
### 消息负载（payload）规范
|
||
|
||
```python
|
||
class TaskPayload:
|
||
"""任务请求/结果负载"""
|
||
|
||
task_id: str # 任务唯一标识
|
||
task_type: str # 任务类型
|
||
parameters: dict # 任务参数
|
||
data: dict # 输入/输出数据
|
||
priority: int # 优先级 1-10，默认 5
|
||
deadline: datetime # 截止时间（可选）
|
||
retry_count: int # 已重试次数
|
||
max_retries: int # 最大重试次数
|
||
```
|
||
|
||
### 通信模式
|
||
|
||
#### 1. 点对点模式（Point-to-Point）
|
||
|
||
```
|
||
Agent A ──task_request──▶ Queue ──▶ Agent B
|
||
Agent A ◀──task_result─── Queue ◀── Agent B
|
||
```
|
||
|
||
- 每个 Agent 有专属的输入队列
|
||
- 任务按轮询方式分配
|
||
- 适用于明确的任务分配场景
|
||
|
||
#### 2. 发布/订阅模式（Pub/Sub）
|
||
|
||
```
|
||
Agent A ──config_update──▶ Topic
|
||
│
|
||
┌───────────────┼───────────────┐
|
||
▼ ▼ ▼
|
||
Agent B Agent C Agent D
|
||
```
|
||
|
||
- 使用 Redis Pub/Sub 频道
|
||
- 适用于配置变更、状态广播
|
||
|
||
#### 3. 工作流模式（Workflow）
|
||
|
||
```
|
||
┌────────────┐ ┌────────────┐ ┌────────────┐
|
||
│ QueryTask │───▶│ Citation │───▶│ Report │
|
||
│ Completed │ │ Detector │ │ Generator │
|
||
└────────────┘ └────────────┘ └────────────┘
|
||
```
|
||
|
||
- 基于事件驱动的工作流编排
|
||
- 使用 correlation_id 串联整个工作流
|
||
- 支持并行和串行执行
|
||
|
||
## 注册机制
|
||
|
||
### Agent 注册流程
|
||
|
||
```
|
||
Agent 启动
|
||
│
|
||
▼
|
||
读取配置（能力声明、资源需求、版本信息）
|
||
│
|
||
▼
|
||
连接 Redis
|
||
│
|
||
▼
|
||
向 Registry 注册
|
||
│
|
||
▼
|
||
创建专属输入队列
|
||
│
|
||
▼
|
||
启动心跳定时器
|
||
│
|
||
▼
|
||
开始监听任务
|
||
```
|
||
|
||
### Registry 数据结构
|
||
|
||
```python
|
||
# Redis Hash: agent:registry:{agent_name}
|
||
{
|
||
"name": "CitationDetector",
|
||
"version": "1.0.0",
|
||
"capabilities": "[\"citation_detect\", \"entity_recognition\"]",
|
||
"status": "online", # online / busy / offline
|
||
"queue_name": "agent:citation_detector",
|
||
"registered_at": "2026-01-01T00:00:00Z",
|
||
"last_heartbeat": "2026-01-01T00:01:00Z",
|
||
"current_task": "task_123", # 当前执行任务 ID，空闲时为 null
|
||
"concurrency": 5, # 最大并发数
|
||
"load": 0.6 # 当前负载 0-1
|
||
}
|
||
```
|
||
|
||
### 服务发现
|
||
|
||
```python
|
||
# 获取所有在线 Agent
|
||
agents = redis.hgetall("agent:registry:*")
|
||
online_agents = [a for a in agents if a.status == "online"]
|
||
|
||
# 按能力筛选 Agent
|
||
capable_agents = [a for a in online_agents if "citation_detect" in a.capabilities]
|
||
|
||
# 选择负载最低的 Agent
|
||
selected = min(capable_agents, key=lambda a: a.load)
|
||
```
|
||
|
||
## 任务分发
|
||
|
||
### 分发策略
|
||
|
||
| 策略 | 说明 | 适用场景 |
|
||
|------|------|----------|
|
||
| `round_robin` | 轮询分配 | 同类型 Agent 负载均衡 |
|
||
| `least_load` | 最低负载优先 | 不同 Agent 性能差异时 |
|
||
| `capability_match` | 能力匹配 | 需要特定能力的任务 |
|
||
| `priority_queue` | 优先级队列 | 任务有明确优先级差异 |
|
||
| `sticky` | 粘性分配 | 需要上下文连续性的任务 |
|
||
|
||
### 任务分发流程
|
||
|
||
```
|
||
任务提交
|
||
│
|
||
▼
|
||
解析任务类型 ──▶ 确定所需能力
|
||
│
|
||
▼
|
||
查询 Registry ──▶ 筛选可用 Agent
|
||
│
|
||
▼
|
||
应用分发策略 ──▶ 选择目标 Agent
|
||
│
|
||
▼
|
||
序列化消息 ──▶ 写入目标队列
|
||
│
|
||
▼
|
||
更新任务状态 ──▶ 等待结果
|
||
```
|
||
|
||
### 任务状态机
|
||
|
||
```
|
||
┌──────────┐ 提交任务 ┌──────────┐
|
||
│ PENDING │───────────────▶│ QUEUED │
|
||
└──────────┘ └─────┬────┘
|
||
│ 入队
|
||
▼
|
||
┌──────────┐
|
||
开始执行│ RUNNING │
|
||
┌───────┤ │
|
||
│ └─────┬────┘
|
||
│ │
|
||
执行成功 执行失败
|
||
│ │
|
||
▼ ▼
|
||
┌──────────┐ ┌──────────┐
|
||
│COMPLETED │ │ FAILED │
|
||
└──────────┘ └─────┬────┘
|
||
│
|
||
重试次数 < 最大重试
|
||
│
|
||
▼
|
||
┌──────────┐
|
||
│ RETRY │
|
||
└────┬─────┘
|
||
│ 重新入队
|
||
└────▶ QUEUED
|
||
```
|
||
|
||
## 状态上报
|
||
|
||
### 上报内容
|
||
|
||
每个 Agent 需要定期上报以下状态信息：
|
||
|
||
| 字段 | 说明 | 上报频率 |
|
||
|------|------|----------|
|
||
| `status` | 当前状态 | 每次变化 + 心跳 |
|
||
| `current_task` | 正在执行的任务 | 每次变化 |
|
||
| `load` | 当前负载 0-1 | 心跳时 |
|
||
| `queue_depth` | 待处理任务数 | 心跳时 |
|
||
| `processed_count` | 已处理任务总数 | 心跳时 |
|
||
| `error_count` | 错误次数 | 心跳时 |
|
||
| `avg_process_time` | 平均处理时间 | 心跳时 |
|
||
|
||
### 心跳机制
|
||
|
||
```python
|
||
# 心跳间隔：30 秒
|
||
HEARTBEAT_INTERVAL = 30
|
||
|
||
# 心跳超时判定：90 秒（3 个心跳周期）
|
||
HEARTBEAT_TIMEOUT = 90
|
||
|
||
# 心跳消息格式
|
||
heartbeat_message = {
|
||
"message_type": "heartbeat",
|
||
"sender": "CitationDetector",
|
||
"timestamp": "2026-01-01T00:01:00Z",
|
||
"payload": {
|
||
"status": "online",
|
||
"load": 0.4,
|
||
"queue_depth": 2,
|
||
"processed_count": 150,
|
||
"error_count": 3,
|
||
"avg_process_time": 2.5
|
||
}
|
||
}
|
||
```
|
||
|
||
### 状态监控
|
||
|
||
- Registry 定期检查 Agent 心跳超时
|
||
- 超时 Agent 自动标记为 `offline`
|
||
- 正在执行的任务自动重新分发
|
||
- 管理员可通过 Dashboard 查看 Agent 状态
|
||
|
||
## 配置管理
|
||
|
||
### 配置层级
|
||
|
||
| 层级 | 说明 | 优先级 |
|
||
|------|------|--------|
|
||
| `system_default` | 系统默认配置 | 最低 |
|
||
| `tenant_config` | 租户级配置（覆盖默认） | 中 |
|
||
| `agent_override` | Agent 本地配置（覆盖租户） | 最高 |
|
||
|
||
### 配置项
|
||
|
||
```python
|
||
class AgentConfig:
|
||
"""Agent 配置项"""
|
||
|
||
# 通用配置
|
||
max_concurrency: int = 5 # 最大并发数
|
||
task_timeout: int = 300 # 任务超时时间（秒）
|
||
retry_policy: str = "exponential" # 重试策略
|
||
max_retries: int = 3 # 最大重试次数
|
||
|
||
# CitationDetector 专用
|
||
confidence_threshold: float = 0.7 # 置信度阈值
|
||
enable_semantic_analysis: bool = True
|
||
|
||
# ContentGenerator 专用
|
||
default_content_length: int = 1500
|
||
content_styles: List[str] = ["professional", "casual", "technical"]
|
||
|
||
# RuleChecker 专用
|
||
strict_mode: bool = False
|
||
custom_rules: List[dict] = []
|
||
```
|
||
|
||
### 动态配置更新
|
||
|
||
```
|
||
管理员更新配置
|
||
│
|
||
▼
|
||
写入 Redis 配置存储
|
||
│
|
||
▼
|
||
发布 config_update 消息
|
||
│
|
||
▼
|
||
各 Agent 接收消息
|
||
│
|
||
▼
|
||
Agent 热重载配置（无需重启）
|
||
```
|
||
|
||
## 管理功能需求
|
||
|
||
### Agent Dashboard
|
||
|
||
管理员需要通过 Dashboard 监控和管理所有 Agent：
|
||
|
||
| 功能 | 说明 | 优先级 |
|
||
|------|------|--------|
|
||
| Agent 列表 | 查看所有已注册 Agent 的状态 | P0 |
|
||
| 实时状态看板 | 展示 Agent 在线状态、负载、任务数 | P0 |
|
||
| 任务队列监控 | 查看各队列的待处理任务数 | P0 |
|
||
| 任务执行日志 | 查看任务执行的详细日志 | P1 |
|
||
| 错误告警 | Agent 异常时发送告警通知 | P1 |
|
||
| 配置管理 | 在线修改 Agent 配置 | P1 |
|
||
| Agent 启停 | 远程启动或停止 Agent | P2 |
|
||
| 版本管理 | 查看和升级 Agent 版本 | P2 |
|
||
| 性能统计 | 查看 Agent 的性能指标和趋势 | P2 |
|
||
|
||
### Agent 日志规范
|
||
|
||
```python
|
||
# 日志格式
|
||
{
|
||
"timestamp": "2026-01-01T00:00:00Z",
|
||
"level": "INFO", # DEBUG / INFO / WARNING / ERROR
|
||
"agent": "CitationDetector",
|
||
"task_id": "task_123",
|
||
"message": "开始执行引用检测",
|
||
"metadata": {
|
||
"query_id": "q_456",
|
||
"brand": "ExampleBrand"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 错误处理
|
||
|
||
| 错误类型 | 处理方式 | 告警级别 |
|
||
|----------|----------|----------|
|
||
| 任务执行失败 | 自动重试，达到最大重试后标记失败 | Warning |
|
||
| Agent 心跳超时 | 标记离线，任务重新分发 | Error |
|
||
| 队列积压 | 触发弹性扩容或告警 | Warning |
|
||
| Agent 崩溃 | 自动重启（配合 supervisor） | Critical |
|
||
| 配置错误 | 拒绝加载，保持上次有效配置 | Error |
|
||
|
||
---
|
||
|
||
*本文档定义 GEO 平台的 AI Agent 框架设计，各 Agent 的具体实现算法和模型选型在模块指南中详细说明。*
|