773 lines
25 KiB
Markdown
773 lines
25 KiB
Markdown
# MaiBot 动作激活系统使用指南
|
||
|
||
## 概述
|
||
|
||
MaiBot 的动作激活系统采用**双激活类型架构**，为Focus模式和Normal模式分别提供最优的激活策略。
|
||
|
||
**系统已集成四大核心特性：**
|
||
- 🎯 **双激活类型**：Focus模式智能化，Normal模式高性能
|
||
- 🚀 **并行判定**：多个LLM判定任务并行执行
|
||
- 💾 **智能缓存**：相同上下文的判定结果缓存复用
|
||
- ⚡ **并行动作**：支持与回复同时执行的动作
|
||
|
||
## 双激活类型系统 🆕
|
||
|
||
### 系统设计理念
|
||
|
||
**Focus模式**：智能优先
|
||
- 支持复杂的LLM判定
|
||
- 提供精确的上下文理解
|
||
- 适合需要深度分析的场景
|
||
|
||
**Normal模式**：性能优先
|
||
- 使用快速的关键词匹配
|
||
- 采用简单的随机触发
|
||
- 确保快速响应用户
|
||
|
||
### 核心属性配置
|
||
|
||
```python
|
||
from src.chat.focus_chat.planners.actions.base_action import BaseAction, register_action, ActionActivationType
|
||
from src.chat.chat_mode import ChatMode
|
||
|
||
@register_action
|
||
class MyAction(BaseAction):
|
||
action_name = "my_action"
|
||
action_description = "我的动作描述"
|
||
|
||
# 双激活类型配置
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE # Focus模式使用智能判定
|
||
normal_activation_type = ActionActivationType.KEYWORD # Normal模式使用关键词
|
||
activation_keywords = ["关键词1", "关键词2", "keyword"]
|
||
keyword_case_sensitive = False
|
||
|
||
# 模式启用控制
|
||
mode_enable = ChatMode.ALL # 支持的聊天模式
|
||
|
||
# 并行执行控制
|
||
parallel_action = False # 是否与回复并行执行
|
||
|
||
# 插件系统控制
|
||
enable_plugin = True # 是否启用此插件
|
||
```
|
||
|
||
## 激活类型详解
|
||
|
||
### 1. ALWAYS - 总是激活
|
||
**用途**：基础必需动作，始终可用
|
||
```python
|
||
focus_activation_type = ActionActivationType.ALWAYS
|
||
normal_activation_type = ActionActivationType.ALWAYS
|
||
```
|
||
**示例**：`reply_action`, `no_reply_action`
|
||
|
||
### 2. RANDOM - 随机激活
|
||
**用途**：增加不可预测性和趣味性
|
||
```python
|
||
focus_activation_type = ActionActivationType.RANDOM
|
||
normal_activation_type = ActionActivationType.RANDOM
|
||
random_activation_probability = 0.2 # 20%概率激活
|
||
```
|
||
**示例**：`vtb_action` (表情动作)
|
||
|
||
### 3. LLM_JUDGE - LLM智能判定
|
||
**用途**：需要上下文理解的复杂判定
|
||
```python
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
# 注意：Normal模式使用LLM_JUDGE会产生性能警告
|
||
normal_activation_type = ActionActivationType.KEYWORD # 推荐在Normal模式使用KEYWORD
|
||
```
|
||
**优化特性**：
|
||
- ⚡ **直接判定**：直接进行LLM判定，减少复杂度
|
||
- 🚀 **并行执行**：多个LLM判定同时进行
|
||
- 💾 **结果缓存**：相同上下文复用结果（30秒有效期）
|
||
|
||
### 4. KEYWORD - 关键词触发
|
||
**用途**：精确命令式触发
|
||
```python
|
||
focus_activation_type = ActionActivationType.KEYWORD
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["画", "画图", "生成图片", "draw"]
|
||
keyword_case_sensitive = False # 不区分大小写
|
||
```
|
||
**示例**：`pic_action`, `mute_action`
|
||
|
||
## 模式启用控制 (ChatMode)
|
||
|
||
### 模式类型
|
||
```python
|
||
from src.chat.chat_mode import ChatMode
|
||
|
||
# 在所有模式下启用
|
||
mode_enable = ChatMode.ALL # 默认值
|
||
|
||
# 仅在Focus模式启用
|
||
mode_enable = ChatMode.FOCUS
|
||
|
||
# 仅在Normal模式启用
|
||
mode_enable = ChatMode.NORMAL
|
||
```
|
||
|
||
### 使用场景建议
|
||
- **ChatMode.ALL**: 通用功能（如回复、图片生成）
|
||
- **ChatMode.FOCUS**: 需要深度理解的智能功能
|
||
- **ChatMode.NORMAL**: 快速响应的基础功能
|
||
|
||
## 并行动作系统 🆕
|
||
|
||
### 概念说明
|
||
```python
|
||
# 并行动作：与回复生成同时执行
|
||
parallel_action = True # 不会阻止回复，提升用户体验
|
||
|
||
# 串行动作：替代回复生成（传统行为）
|
||
parallel_action = False # 默认值，动作执行时不生成回复
|
||
```
|
||
|
||
### 适用场景
|
||
**并行动作 (parallel_action = True)**:
|
||
- 情感表达（表情、动作）
|
||
- 状态变更（禁言、设置）
|
||
- 辅助功能（TTS播报）
|
||
|
||
**串行动作 (parallel_action = False)**:
|
||
- 内容生成（图片、文档）
|
||
- 搜索查询
|
||
- 需要完整注意力的操作
|
||
|
||
### 实际案例
|
||
```python
|
||
@register_action
|
||
class MuteAction(PluginAction):
|
||
action_name = "mute_action"
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["禁言", "mute", "ban", "silence"]
|
||
parallel_action = True # 禁言的同时还可以回复确认信息
|
||
|
||
@register_action
|
||
class PicAction(PluginAction):
|
||
action_name = "pic_action"
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["画", "绘制", "生成图片", "画图", "draw", "paint"]
|
||
parallel_action = False # 专注于图片生成，不同时回复
|
||
```
|
||
|
||
## 推荐配置模式
|
||
|
||
### 模式1：智能自适应（推荐）
|
||
```python
|
||
# Focus模式智能判定，Normal模式快速触发
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["相关", "关键词", "英文keyword"]
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False # 根据具体需求调整
|
||
```
|
||
|
||
### 模式2：统一关键词
|
||
```python
|
||
# 两个模式都使用关键词，确保行为一致
|
||
focus_activation_type = ActionActivationType.KEYWORD
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["画", "图片", "生成"]
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False
|
||
```
|
||
|
||
### 模式3：Focus专享功能
|
||
```python
|
||
# 仅在Focus模式启用的高级功能
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.ALWAYS # 不会生效
|
||
mode_enable = ChatMode.FOCUS
|
||
parallel_action = False
|
||
```
|
||
|
||
### 模式4：随机娱乐功能
|
||
```python
|
||
# 增加趣味性的随机功能
|
||
focus_activation_type = ActionActivationType.RANDOM
|
||
normal_activation_type = ActionActivationType.RANDOM
|
||
random_activation_probability = 0.08 # 8%概率
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = True # 通常与回复并行
|
||
```
|
||
|
||
## 性能优化详解
|
||
|
||
### 并行判定机制
|
||
```python
|
||
# 自动将多个LLM判定任务并行执行
|
||
async def _process_llm_judge_actions_parallel(self, llm_judge_actions, ...):
|
||
tasks = [self._llm_judge_action(name, info, ...) for name, info in llm_judge_actions.items()]
|
||
results = await asyncio.gather(*tasks, return_exceptions=True)
|
||
```
|
||
|
||
**优势**：
|
||
- 多个LLM判定同时进行，显著减少总耗时
|
||
- 异常处理确保单个失败不影响整体
|
||
- 自动负载均衡
|
||
|
||
### 智能缓存系统
|
||
```python
|
||
# 基于上下文哈希的缓存机制
|
||
cache_key = f"{action_name}_{context_hash}"
|
||
if cache_key in self._llm_judge_cache:
|
||
return cached_result # 直接返回缓存结果
|
||
```
|
||
|
||
**特性**：
|
||
- 30秒缓存有效期
|
||
- MD5哈希确保上下文一致性
|
||
- 自动清理过期缓存
|
||
- 命中率优化：相同聊天上下文的重复判定
|
||
|
||
### 分层判定架构
|
||
|
||
#### 第一层：智能动态过滤
|
||
```python
|
||
def _pre_filter_llm_actions(self, llm_judge_actions, observed_messages_str, ...):
|
||
# 动态收集所有KEYWORD类型actions的关键词
|
||
all_keyword_actions = self.action_manager.get_registered_actions()
|
||
collected_keywords = {}
|
||
|
||
for action_name, action_info in all_keyword_actions.items():
|
||
if action_info.get("activation_type") == "KEYWORD":
|
||
keywords = action_info.get("activation_keywords", [])
|
||
if keywords:
|
||
collected_keywords[action_name] = [kw.lower() for kw in keywords]
|
||
|
||
# 基于实际配置进行智能过滤
|
||
for action_name, action_info in llm_judge_actions.items():
|
||
# 策略1: 避免与KEYWORD类型重复
|
||
# 策略2: 基于action描述进行语义相关性检查
|
||
# 策略3: 保留核心actions
|
||
```
|
||
|
||
**智能过滤策略**：
|
||
- **动态关键词收集**：从各个action的实际配置中收集关键词，无硬编码
|
||
- **重复避免机制**：如果存在对应的KEYWORD触发action，优先使用KEYWORD
|
||
- **语义相关性检查**：基于action描述和消息内容进行智能匹配
|
||
- **长度与复杂度匹配**：短消息自动排除复杂operations
|
||
- **核心action保护**：确保reply/no_reply等基础action始终可用
|
||
|
||
#### 第二层：LLM精确判定
|
||
通过第一层过滤后的动作才进入LLM判定，大幅减少：
|
||
- LLM调用次数
|
||
- 总处理时间
|
||
- API成本
|
||
|
||
## HFC流程级并行化优化 🆕
|
||
|
||
### 三阶段并行架构
|
||
|
||
除了动作激活系统内部的优化，整个HFC（HeartFocus Chat）流程也实现了并行化：
|
||
|
||
```python
|
||
# 在 heartFC_chat.py 中的优化
|
||
if global_config.focus_chat.parallel_processing:
|
||
# 并行执行调整动作、回忆和处理器阶段
|
||
with Timer("并行调整动作、回忆和处理", cycle_timers):
|
||
async def modify_actions_task():
|
||
await self.action_modifier.modify_actions(observations=self.observations)
|
||
await self.action_observation.observe()
|
||
self.observations.append(self.action_observation)
|
||
return True
|
||
|
||
# 创建三个并行任务
|
||
action_modify_task = asyncio.create_task(modify_actions_task())
|
||
memory_task = asyncio.create_task(self.memory_activator.activate_memory(self.observations))
|
||
processor_task = asyncio.create_task(self._process_processors(self.observations, []))
|
||
|
||
# 等待三个任务完成
|
||
_, running_memorys, (all_plan_info, processor_time_costs) = await asyncio.gather(
|
||
action_modify_task, memory_task, processor_task
|
||
)
|
||
```
|
||
|
||
### 并行化阶段说明
|
||
|
||
**1. 调整动作阶段（Action Modifier）**
|
||
- 执行动作激活系统的智能判定
|
||
- 包含并行LLM判定和缓存
|
||
- 更新可用动作列表
|
||
|
||
**2. 回忆激活阶段（Memory Activator）**
|
||
- 根据当前观察激活相关记忆
|
||
- 检索历史对话和上下文信息
|
||
- 为规划器提供背景知识
|
||
|
||
**3. 信息处理器阶段（Processors）**
|
||
- 处理观察信息，提取关键特征
|
||
- 生成结构化的计划信息
|
||
- 为规划器提供决策依据
|
||
|
||
### 性能提升效果
|
||
|
||
**理论提升**：
|
||
- 原串行执行：500ms + 800ms + 1000ms = 2300ms
|
||
- 现并行执行：max(500ms, 800ms, 1000ms) = 1000ms
|
||
- **性能提升：2.3x**
|
||
|
||
**实际效果**：
|
||
- 显著减少每个HFC循环的总耗时
|
||
- 提高机器人响应速度
|
||
- 优化用户体验
|
||
|
||
### 配置控制
|
||
|
||
通过配置文件控制是否启用并行处理：
|
||
```yaml
|
||
focus_chat:
|
||
parallel_processing: true # 启用并行处理
|
||
```
|
||
|
||
**建议设置**：
|
||
- **生产环境**：启用（`true`）- 获得最佳性能
|
||
- **调试环境**：可选择禁用（`false`）- 便于问题定位
|
||
|
||
## 使用示例
|
||
|
||
### 定义新的动作类
|
||
|
||
```python
|
||
from src.chat.focus_chat.planners.actions.plugin_action import PluginAction, register_action, ActionActivationType
|
||
from src.chat.chat_mode import ChatMode
|
||
|
||
@register_action
|
||
class MyAction(PluginAction):
|
||
action_name = "my_action"
|
||
action_description = "我的自定义动作"
|
||
|
||
# 双激活类型配置
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["自定义", "触发", "custom"]
|
||
|
||
# 模式和并行控制
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False
|
||
enable_plugin = True
|
||
|
||
async def process(self):
|
||
# 动作执行逻辑
|
||
pass
|
||
```
|
||
|
||
### 关键词触发动作
|
||
```python
|
||
@register_action
|
||
class SearchAction(PluginAction):
|
||
action_name = "search_action"
|
||
focus_activation_type = ActionActivationType.KEYWORD
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["搜索", "查找", "什么是", "search", "find"]
|
||
keyword_case_sensitive = False
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False
|
||
```
|
||
|
||
### 随机触发动作
|
||
```python
|
||
@register_action
|
||
class SurpriseAction(PluginAction):
|
||
action_name = "surprise_action"
|
||
focus_activation_type = ActionActivationType.RANDOM
|
||
normal_activation_type = ActionActivationType.RANDOM
|
||
random_activation_probability = 0.1 # 10%概率
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = True # 惊喜动作与回复并行
|
||
```
|
||
|
||
### Focus专享智能动作
|
||
```python
|
||
@register_action
|
||
class AdvancedAnalysisAction(PluginAction):
|
||
action_name = "advanced_analysis"
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.ALWAYS # 不会生效
|
||
mode_enable = ChatMode.FOCUS # 仅Focus模式
|
||
parallel_action = False
|
||
```
|
||
|
||
## 现有插件的配置示例
|
||
|
||
### MuteAction (禁言动作)
|
||
```python
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["禁言", "mute", "ban", "silence"]
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = True # 可以与回复同时进行
|
||
```
|
||
|
||
### PicAction (图片生成)
|
||
```python
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["画", "绘制", "生成图片", "画图", "draw", "paint", "图片生成"]
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False # 专注生成，不同时回复
|
||
```
|
||
|
||
### VTBAction (虚拟主播表情)
|
||
```python
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.RANDOM
|
||
random_activation_probability = 0.08
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False # 替代文字回复
|
||
```
|
||
|
||
## 性能监控
|
||
|
||
### 实时性能指标
|
||
```python
|
||
# 自动记录的性能指标
|
||
logger.debug(f"激活判定：{before_count} -> {after_count} actions")
|
||
logger.debug(f"并行LLM判定完成，耗时: {duration:.2f}s")
|
||
logger.debug(f"使用缓存结果 {action_name}: {'激活' if result else '未激活'}")
|
||
logger.debug(f"清理了 {count} 个过期缓存条目")
|
||
logger.debug(f"并行调整动作、回忆和处理完成，耗时: {duration:.2f}s")
|
||
```
|
||
|
||
### 性能优化建议
|
||
1. **合理配置缓存时间**：根据聊天活跃度调整 `_cache_expiry_time`
|
||
2. **优化过滤规则**：根据实际使用情况调整 `_quick_filter_keywords`
|
||
3. **监控并行效果**：关注 `asyncio.gather` 的执行时间
|
||
4. **缓存命中率**：监控缓存使用情况，优化策略
|
||
5. **启用流程并行化**：确保 `parallel_processing` 配置为 `true`
|
||
6. **激活类型选择**：Normal模式优先使用KEYWORD，避免LLM_JUDGE
|
||
|
||
## 迁移指南 ⚠️
|
||
|
||
### 重大变更说明
|
||
**旧的 `action_activation_type` 属性已被移除**，必须更新为新的双激活类型系统。
|
||
|
||
### 快速迁移步骤
|
||
|
||
#### 第一步：更新基本属性
|
||
```python
|
||
# 旧的配置（已废弃）❌
|
||
class OldAction(BaseAction):
|
||
action_activation_type = ActionActivationType.LLM_JUDGE
|
||
|
||
# 新的配置（必须使用）✅
|
||
class NewAction(BaseAction):
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["相关", "关键词"]
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False
|
||
enable_plugin = True
|
||
```
|
||
|
||
#### 第二步：根据原类型选择对应策略
|
||
```python
|
||
# 原来是 ALWAYS
|
||
focus_activation_type = ActionActivationType.ALWAYS
|
||
normal_activation_type = ActionActivationType.ALWAYS
|
||
|
||
# 原来是 LLM_JUDGE
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD # 添加关键词
|
||
activation_keywords = ["需要", "添加", "关键词"]
|
||
|
||
# 原来是 KEYWORD
|
||
focus_activation_type = ActionActivationType.KEYWORD
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
# 保持原有的 activation_keywords
|
||
|
||
# 原来是 RANDOM
|
||
focus_activation_type = ActionActivationType.RANDOM
|
||
normal_activation_type = ActionActivationType.RANDOM
|
||
# 保持原有的 random_activation_probability
|
||
```
|
||
|
||
#### 第三步：配置新功能
|
||
```python
|
||
# 添加模式控制
|
||
mode_enable = ChatMode.ALL # 或 ChatMode.FOCUS / ChatMode.NORMAL
|
||
|
||
# 添加并行控制
|
||
parallel_action = False # 根据动作特性选择True/False
|
||
|
||
# 添加插件控制
|
||
enable_plugin = True # 是否启用此插件
|
||
```
|
||
|
||
### 批量迁移脚本
|
||
可以创建以下脚本来帮助批量迁移：
|
||
|
||
```python
|
||
# migrate_actions.py
|
||
import os
|
||
import re
|
||
|
||
def migrate_action_file(filepath):
|
||
with open(filepath, 'r', encoding='utf-8') as f:
|
||
content = f.read()
|
||
|
||
# 替换 action_activation_type
|
||
if 'action_activation_type = ActionActivationType.ALWAYS' in content:
|
||
content = content.replace(
|
||
'action_activation_type = ActionActivationType.ALWAYS',
|
||
'focus_activation_type = ActionActivationType.ALWAYS\n normal_activation_type = ActionActivationType.ALWAYS'
|
||
)
|
||
elif 'action_activation_type = ActionActivationType.LLM_JUDGE' in content:
|
||
content = content.replace(
|
||
'action_activation_type = ActionActivationType.LLM_JUDGE',
|
||
'focus_activation_type = ActionActivationType.LLM_JUDGE\n normal_activation_type = ActionActivationType.KEYWORD\n activation_keywords = ["需要", "添加", "关键词"] # TODO: 配置合适的关键词'
|
||
)
|
||
# ... 其他替换逻辑
|
||
|
||
# 添加新属性
|
||
if 'mode_enable' not in content:
|
||
# 在class定义后添加新属性
|
||
# ...
|
||
|
||
with open(filepath, 'w', encoding='utf-8') as f:
|
||
f.write(content)
|
||
|
||
# 使用示例
|
||
migrate_action_file('src/plugins/your_plugin/actions/your_action.py')
|
||
```
|
||
|
||
## 测试验证
|
||
|
||
运行动作激活优化测试：
|
||
```bash
|
||
python test_action_activation_optimized.py
|
||
```
|
||
|
||
运行HFC并行化测试：
|
||
```bash
|
||
python test_parallel_optimization.py
|
||
```
|
||
|
||
测试内容包括：
|
||
- ✅ 双激活类型功能验证
|
||
- ✅ 并行处理功能验证
|
||
- ✅ 缓存机制效果测试
|
||
- ✅ 分层判定规则验证
|
||
- ✅ 性能对比分析
|
||
- ✅ HFC流程并行化效果
|
||
- ✅ 多循环平均性能测试
|
||
- ✅ 并行动作系统验证
|
||
- ✅ 迁移兼容性测试
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 激活类型选择
|
||
- **ALWAYS**：reply, no_reply 等基础动作
|
||
- **LLM_JUDGE**：需要智能判断的复杂动作（建议仅用于Focus模式）
|
||
- **KEYWORD**：明确的命令式动作（推荐在Normal模式使用）
|
||
- **RANDOM**：增趣动作，低概率触发
|
||
|
||
### 2. 双模式配置策略
|
||
- **智能自适应**：Focus用LLM_JUDGE，Normal用KEYWORD
|
||
- **性能优先**：两个模式都用KEYWORD或RANDOM
|
||
- **功能分离**：某些功能仅在特定模式启用
|
||
|
||
### 3. 并行动作使用建议
|
||
- **parallel_action = True**：辅助性、非内容生成类动作
|
||
- **parallel_action = False**：主要内容生成、需要完整注意力的动作
|
||
|
||
### 4. LLM判定提示词编写
|
||
- 明确描述激活条件和排除条件
|
||
- 避免模糊的描述
|
||
- 考虑边界情况
|
||
- 保持简洁明了
|
||
|
||
### 5. 关键词设置
|
||
- 包含同义词和英文对应词
|
||
- 考虑用户的不同表达习惯
|
||
- 避免过于宽泛的关键词
|
||
- 根据实际使用调整
|
||
|
||
### 6. 性能优化
|
||
- 定期监控处理时间
|
||
- 根据使用模式调整缓存策略
|
||
- 优化激活判定逻辑
|
||
- 平衡准确性和性能
|
||
- **启用并行处理配置**
|
||
- **Normal模式避免使用LLM_JUDGE**
|
||
|
||
### 7. 并行化最佳实践
|
||
- 在生产环境启用 `parallel_processing`
|
||
- 监控并行阶段的执行时间
|
||
- 确保各阶段的独立性
|
||
- 避免共享状态导致的竞争条件
|
||
|
||
## 总结
|
||
|
||
优化后的动作激活系统通过**五层优化策略**，实现了全方位的性能提升：
|
||
|
||
### 第一层：双激活类型系统
|
||
- **Focus模式**：智能化优先，支持复杂LLM判定
|
||
- **Normal模式**：性能优先，使用快速关键词匹配
|
||
- **模式自适应**：根据聊天模式选择最优策略
|
||
|
||
### 第二层：动作激活内部优化
|
||
- **并行判定**：多个LLM判定任务并行执行
|
||
- **智能缓存**：相同上下文的判定结果缓存复用
|
||
- **分层判定**：快速过滤 + 精确判定的两层架构
|
||
|
||
### 第三层：并行动作系统
|
||
- **并行执行**：支持动作与回复同时进行
|
||
- **用户体验**：减少等待时间，提升交互流畅性
|
||
- **灵活控制**：每个动作可独立配置并行行为
|
||
|
||
### 第四层：HFC流程级并行化
|
||
- **三阶段并行**：调整动作、回忆、处理器同时执行
|
||
- **性能提升**：2.3x 理论加速比
|
||
- **配置控制**：可根据环境灵活开启/关闭
|
||
|
||
### 第五层：插件系统增强
|
||
- **enable_plugin**：精确控制插件启用状态
|
||
- **mode_enable**：支持模式级别的功能控制
|
||
- **向后兼容**：平滑迁移旧系统配置
|
||
|
||
### 综合效果
|
||
- **响应速度**：显著提升机器人反应速度
|
||
- **成本优化**：减少不必要的LLM调用
|
||
- **智能决策**：双激活类型覆盖所有场景
|
||
- **用户体验**：更快速、更智能的交互
|
||
- **灵活配置**：精细化的功能控制
|
||
|
||
**总性能提升预估：4-6x**
|
||
- 双激活类型系统：1.5x (Normal模式优化)
|
||
- 动作激活内部优化：1.5-2x
|
||
- HFC流程并行化：2.3x
|
||
- 并行动作系统：额外30-50%提升
|
||
- 缓存和过滤优化：额外20-30%提升
|
||
|
||
这使得MaiBot能够更快速、更智能地响应用户需求，同时提供灵活的配置选项以适应不同的使用场景，实现了卓越的交互体验。
|
||
|
||
## 如何为Action添加激活类型
|
||
|
||
### 对于普通Action
|
||
|
||
```python
|
||
from src.chat.focus_chat.planners.actions.base_action import BaseAction, register_action, ActionActivationType
|
||
from src.chat.chat_mode import ChatMode
|
||
|
||
@register_action
|
||
class YourAction(BaseAction):
|
||
action_name = "your_action"
|
||
action_description = "你的动作描述"
|
||
|
||
# 双激活类型配置
|
||
focus_activation_type = ActionActivationType.LLM_JUDGE
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["关键词1", "关键词2", "keyword"]
|
||
keyword_case_sensitive = False
|
||
|
||
# 新增属性
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = False
|
||
enable_plugin = True
|
||
|
||
# ... 其他代码
|
||
```
|
||
|
||
### 对于插件Action
|
||
|
||
```python
|
||
from src.chat.focus_chat.planners.actions.plugin_action import PluginAction, register_action, ActionActivationType
|
||
from src.chat.chat_mode import ChatMode
|
||
|
||
@register_action
|
||
class YourPluginAction(PluginAction):
|
||
action_name = "your_plugin_action"
|
||
action_description = "你的插件动作描述"
|
||
|
||
# 双激活类型配置
|
||
focus_activation_type = ActionActivationType.KEYWORD
|
||
normal_activation_type = ActionActivationType.KEYWORD
|
||
activation_keywords = ["触发词1", "trigger", "启动"]
|
||
keyword_case_sensitive = False
|
||
|
||
# 新增属性
|
||
mode_enable = ChatMode.ALL
|
||
parallel_action = True # 与回复并行执行
|
||
enable_plugin = True
|
||
|
||
# ... 其他代码
|
||
```
|
||
|
||
## 工作流程
|
||
|
||
1. **ActionModifier处理**: 在planner运行前，ActionModifier会遍历所有注册的动作
|
||
2. **模式检查**: 根据当前聊天模式（Focus/Normal）和action的mode_enable进行过滤
|
||
3. **激活类型判断**: 根据当前模式选择对应的激活类型（focus_activation_type或normal_activation_type）
|
||
4. **激活决策**:
|
||
- ALWAYS: 直接激活
|
||
- RANDOM: 根据概率随机决定
|
||
- LLM_JUDGE: 调用小模型判定（Normal模式会警告）
|
||
- KEYWORD: 检测关键词匹配
|
||
5. **并行性检查**: 根据parallel_action决定是否与回复并行
|
||
6. **结果收集**: 收集所有激活的动作供planner使用
|
||
|
||
## 配置建议
|
||
|
||
### 双激活类型策略选择
|
||
- **智能自适应（推荐）**: Focus用LLM_JUDGE，Normal用KEYWORD
|
||
- **性能优先**: 两个模式都用KEYWORD或RANDOM
|
||
- **功能专享**: 某些高级功能仅在Focus模式启用
|
||
|
||
### LLM判定提示词编写
|
||
- 明确指出激活条件和不激活条件
|
||
- 使用简单清晰的语言
|
||
- 避免过于复杂的逻辑判断
|
||
|
||
### 随机概率设置
|
||
- 核心功能: 不建议使用随机
|
||
- 娱乐功能: 0.1-0.3 (10%-30%)
|
||
- 辅助功能: 0.05-0.2 (5%-20%)
|
||
|
||
### 关键词设计
|
||
- 包含常用的同义词和变体
|
||
- 考虑中英文兼容
|
||
- 避免过于宽泛的词汇
|
||
- 测试关键词的覆盖率
|
||
|
||
### 性能考虑
|
||
- LLM判定会增加响应时间，适度使用
|
||
- 关键词检测性能最好，推荐优先使用
|
||
- Normal模式避免使用LLM_JUDGE
|
||
- 建议优先级：KEYWORD > ALWAYS > RANDOM > LLM_JUDGE
|
||
|
||
## 调试和测试
|
||
|
||
使用提供的测试脚本验证激活类型系统：
|
||
|
||
```bash
|
||
python test_action_activation.py
|
||
```
|
||
|
||
该脚本会显示：
|
||
- 所有注册动作的双激活类型配置
|
||
- 模拟不同模式下的激活结果
|
||
- 并行动作系统的工作状态
|
||
- 帮助验证配置是否正确
|
||
|
||
## 注意事项
|
||
|
||
1. **重大变更**: `action_activation_type` 已被移除，必须使用双激活类型
|
||
2. **向后兼容**: 系统不再兼容旧的单一激活类型配置
|
||
3. **错误处理**: LLM判定失败时默认不激活该动作
|
||
4. **性能警告**: Normal模式使用LLM_JUDGE会产生警告
|
||
5. **日志记录**: 系统会记录激活决策过程，便于调试
|
||
6. **性能影响**: LLM判定会略微增加响应时间
|
||
|
||
## 未来扩展
|
||
|
||
系统设计支持未来添加更多激活类型和功能，如：
|
||
- 基于时间的激活
|
||
- 基于用户权限的激活
|
||
- 基于群组设置的激活
|
||
- 基于对话历史的激活
|
||
- 基于情感状态的激活 |