160 lines
4.5 KiB
Markdown
160 lines
4.5 KiB
Markdown
# Memory Bank 设计与实现文档
|
||
|
||
## 概述
|
||
|
||
Memory Bank 是 稷下学宫AI辩论系统 的核心组件之一，旨在为每个AI智能体（八仙）提供持久化的记忆能力。通过集成不同的后端实现（如 Google Vertex AI Memory Bank 和 Cloudflare AutoRAG），系统能够灵活地存储、检索和利用智能体在辩论过程中积累的知识和经验。
|
||
|
||
## 架构设计
|
||
|
||
### 核心抽象
|
||
|
||
系统通过 `MemoryBankProtocol` 定义了记忆银行的通用接口，确保了不同后端实现的可替换性。
|
||
|
||
```python
|
||
@runtime_checkable
|
||
class MemoryBankProtocol(Protocol):
|
||
async def create_memory_bank(self, agent_name: str, display_name: Optional[str] = None) -> str: ...
|
||
|
||
async def add_memory(
|
||
self,
|
||
agent_name: str,
|
||
content: str,
|
||
memory_type: str = "conversation",
|
||
debate_topic: str = "",
|
||
metadata: Optional[Dict[str, Any]] = None,
|
||
) -> str: ...
|
||
|
||
async def search_memories(
|
||
self,
|
||
agent_name: str,
|
||
query: str,
|
||
memory_type: Optional[str] = None,
|
||
limit: int = 10,
|
||
) -> List[Dict[str, Any]]: ...
|
||
|
||
async def get_agent_context(self, agent_name: str, debate_topic: str) -> str: ...
|
||
|
||
async def save_debate_session(
|
||
self,
|
||
debate_topic: str,
|
||
participants: List[str],
|
||
conversation_history: List[Dict[str, str]],
|
||
outcomes: Optional[Dict[str, Any]] = None,
|
||
) -> None: ...
|
||
```
|
||
|
||
### 工厂模式
|
||
|
||
通过 `get_memory_backend` 工厂函数，系统可以根据配置动态选择合适的记忆后端实现。
|
||
|
||
```python
|
||
def get_memory_backend(prefer: Optional[str] = None) -> MemoryBankProtocol:
|
||
# 根据环境变量 JIXIA_MEMORY_BACKEND 选择后端
|
||
# 支持 "vertex" 和 "cloudflare"
|
||
...
|
||
```
|
||
|
||
## 后端实现
|
||
|
||
### Vertex AI Memory Bank
|
||
|
||
基于 Google Vertex AI 的 Memory Bank 服务实现。
|
||
|
||
**特点**:
|
||
- 与 Google Cloud 生态系统深度集成
|
||
- 提供企业级的安全性和可靠性
|
||
- 支持复杂的元数据过滤和查询
|
||
|
||
**配置**:
|
||
- `GOOGLE_API_KEY`: Google API 密钥
|
||
- `GOOGLE_CLOUD_PROJECT_ID`: Google Cloud 项目ID
|
||
- `GOOGLE_CLOUD_LOCATION`: 部署区域 (默认 us-central1)
|
||
|
||
### Cloudflare AutoRAG
|
||
|
||
基于 Cloudflare Vectorize 和 Workers AI 实现的向量检索增强生成方案。
|
||
|
||
**特点**:
|
||
- 全球分布的边缘计算网络
|
||
- 成本效益高，适合中小型项目
|
||
- 易于部署和扩展
|
||
|
||
**配置**:
|
||
- `CLOUDFLARE_ACCOUNT_ID`: Cloudflare 账户ID
|
||
- `CLOUDFLARE_API_TOKEN`: 具有 Vectorize 和 Workers AI 权限的 API 令牌
|
||
|
||
## 使用指南
|
||
|
||
### 初始化记忆银行
|
||
|
||
```python
|
||
from src.jixia.memory.factory import get_memory_backend
|
||
|
||
# 根据环境变量自动选择后端
|
||
memory_bank = get_memory_backend()
|
||
|
||
# 或者显式指定后端
|
||
memory_bank = get_memory_backend(prefer="cloudflare")
|
||
```
|
||
|
||
### 为智能体创建记忆空间
|
||
|
||
```python
|
||
# 为吕洞宾创建记忆银行/空间
|
||
await memory_bank.create_memory_bank("lvdongbin")
|
||
```
|
||
|
||
### 添加记忆
|
||
|
||
```python
|
||
await memory_bank.add_memory(
|
||
agent_name="lvdongbin",
|
||
content="倾向于使用DCF模型评估科技股的内在价值",
|
||
memory_type="preference",
|
||
debate_topic="TSLA投资分析"
|
||
)
|
||
```
|
||
|
||
### 搜索记忆
|
||
|
||
```python
|
||
memories = await memory_bank.search_memories(
|
||
agent_name="lvdongbin",
|
||
query="TSLA",
|
||
memory_type="preference"
|
||
)
|
||
```
|
||
|
||
### 获取上下文
|
||
|
||
```python
|
||
context = await memory_bank.get_agent_context("lvdongbin", "TSLA投资分析")
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
1. **合理分类记忆类型**:
|
||
- `conversation`: 记录对话历史，用于上下文理解和连贯性。
|
||
- `preference`: 存储智能体的偏好和倾向，指导决策过程。
|
||
- `knowledge`: 积累专业知识和数据，提升分析深度。
|
||
- `strategy`: 总结辩论策略和战术，优化表现。
|
||
|
||
2. **定期维护记忆**:
|
||
- 实施记忆的定期清理和归档策略，避免信息过载。
|
||
- 通过 `save_debate_session` 方法系统性地保存重要辩论会话。
|
||
|
||
3. **优化搜索查询**:
|
||
- 使用具体、明确的查询词以提高搜索相关性。
|
||
- 结合 `memory_type` 过滤器缩小搜索范围。
|
||
|
||
4. **错误处理**:
|
||
- 在生产环境中，务必对所有异步操作进行适当的错误处理和重试机制。
|
||
|
||
## 未来扩展
|
||
|
||
1. **混合后端支持**: 允许同时使用多个后端，根据数据类型或访问模式进行路由。
|
||
2. **记忆压缩与摘要**: 自动对长篇记忆进行摘要，提高检索效率。
|
||
3. **情感分析**: 为记忆添加情感标签，丰富检索维度。
|
||
|
||
---
|
||
*此文档旨在为开发者提供 Memory Bank 模块的全面技术参考* |