Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
289 lines (210 loc) · 6.95 KB

SETUP_GUIDE.md

File metadata and controls

289 lines (210 loc) · 6.95 KB
Raw

Memory System Deployment - Setup Guide

✅ 部署状态

已完成组件

组件 状态 访问地址 说明
Neo4j ✅ 运行中 http://localhost:7474 图数据库 (时序知识图)
Qdrant ✅ 运行中 http://localhost:6333 向量存储
Redis ✅ 运行中 localhost:6379 会话缓存
项目代码 ✅ 已创建 memory-app/ 完整实现

等待中组件

组件 状态 说明
Ollama ✅ 已完成 (8.96GB) 本地 LLM 和嵌入模型

📋 安装步骤

1. 安装 Python 依赖

cd memory-system-deploy/memory-app

# 方式一：使用 requirements.txt (推荐)
pip install -r requirements.txt

# 方式二：逐个安装核心依赖
pip install python-dotenv
pip install neo4j
pip install qdrant-client
pip install redis
pip install sentence-transformers

注意: 如果网络较慢，可以使用国内镜像：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 配置环境变量

cd memory-app
cp .env.example .env

.env 文件已包含所有默认配置，无需修改即可使用。

3. 启动服务 (如未运行)

cd memory-system-deploy
docker-compose up -d

检查服务状态：

docker ps

预期输出应包含：

  • memory-neo4j
  • memory-qdrant
  • memory-redis
  • memory-ollama (下载完成后)

4. 验证 Neo4j 连接

Neo4j 需要 30-60 秒启动时间。

访问 http://localhost:7474

  • 用户名: neo4j
  • 密码: memoryPassword123

如果显示 unhealthy，等待后重试：

docker logs memory-neo4j
docker ps

5. 运行示例程序

cd memory-app
python example_usage.py

🏗️ 系统架构

┌─────────────────────────────────────────────┐
│         你的 Agent 应用                       │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│      IntegratedMemorySystem                  │
│  (memory_systems skill 实现)                 │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────────┐  ┌──────────────┐        │
│  │ Session      │  │ Vector Store │        │
│  │ Memory       │  │ (Qdrant)     │        │
│  │ (Redis)      │  │              │        │
│  └──────────────┘  └──────────────┘        │
│                                             │
│  ┌──────────────────────────────────┐      │
│  │ Temporal Knowledge Graph         │      │
│  │ (Neo4j)                          │      │
│  └──────────────────────────────────┘      │
└─────────────────────────────────────────────┘

🚀 快速开始代码

基础用法

import asyncio
from memory_system import get_memory_system

async def main():
    # 初始化
    memory = await get_memory_system()

    # 开始会话
    memory.start_session("user_session_123")

    # 存储事实
    await memory.store_fact(
        fact="用户喜欢使用 Python 开发",
        entity="user_123"
    )

    # 语义检索
    results = await memory.retrieve_memories(
        query="编程语言偏好",
        limit=5
    )

    for result in results:
        print(f"[{result['score']:.2f}] {result['text']}")

asyncio.run(main())

实体关系追踪

await memory.store_fact(
    fact="Alice 在 TechCorp 工作",
    entity="alice",
    relationships=[
        {"type": "WORKS_AT", "target": "techcorp"}
    ]
)

# 查询实体上下文
context = await memory.get_entity_history("alice")
print(context)

时序查询

from datetime import datetime, timedelta

# 查询某个时间点的状态
past_time = datetime.now() - timedelta(days=30)
results = await memory.graph.query_at_time(
    query="MATCH (e:Entity)-[r:WORKS_AT]->(c:Company) RETURN e, r, c",
    query_time=past_time
)

📊 性能指标 (基于 DMR Benchmark)

架构 准确率 延迟 适用场景
时序知识图 94.8% 2.58s 复杂关系推理
GraphRAG 75-85% 可变 知识密集型任务
Vector RAG 60-70% 快速 文档检索

🔧 故障排除

Neo4j 无法启动

症状: memory-neo4j 显示 unhealthy

解决方案:

# 查看日志
docker logs memory-neo4j

# 等待 30-60 秒后检查
docker ps

# 如果持续失败，重启容器
docker restart memory-neo4j

端口冲突

症状: Error: port is already allocated

解决方案: 编辑 docker-compose.yml 修改端口映射

Python 包安装失败

症状: 网络超时

解决方案:

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 或手动安装
pip install python-dotenv neo4j qdrant-client redis sentence-transformers

📈 后续步骤

1. 集成 Ollama (可选)

Ollama 下载完成后，启动服务：

docker-compose up -d ollama

下载嵌入模型：

docker exec memory-ollama ollama pull nomic-embed-text
docker exec memory-ollama ollama pull llama3.2

2. 自定义配置

编辑 .env 文件：

# 调整会话时长
MEMORY_MAX_SESSION_DURATION=7200

# 启用内存整合
MEMORY_CONSOLIDATION_INTERVAL=43200

3. 监控和调优

📚 参考文档

✅ 验收检查清单

完成以下步骤确认系统就绪：

  • 所有 Docker 容器运行中 (docker ps)
  • Neo4j 可以访问 (http://localhost:7474)
  • Python 依赖已安装
  • .env 文件已创建
  • example_usage.py 可以运行
  • 无错误日志输出

完成以上步骤后，你的 memory system 就可以集成到 agent 应用了！