忆语 (YiYu) - 智能对话记忆系统

忆语 (YiYu)

基于 LangGraph、本地 Qdrant 向量数据库、Mem0、本地嵌入模型和 LangSmith 的智能对话记忆系统,具备跨会话记忆功能和完整的对话流程追踪。

✨ 特性

🚀 快速预览

Web界面

• 🧠 智能记忆: 跨会话对话记忆管理
• 👥 多用户支持: 独立的用户记忆空间
• 🔍 语义搜索: 基于M3E向量的智能检索
• 📊 实时追踪: LangSmith完整的对话监控

🏗️ 技术架构

核心对话架构

LangGraph (对话状态管理)
 ↓
Mem0 (记忆管理)
 ↓
HuggingFace M3E-Base (本地嵌入模型)
 ↓
Qdrant (本地向量数据库)
 ↓
ModelScope DeepSeek-V3.1 (LLM对话)
 ↓
LangSmith (对话流程追踪和调试)

用户管理架构

应用启动
 ↓
扫描 Qdrant 向量数据库
 ↓
提取已有用户ID列表
 ↓
分类用户 (数据库用户/本地用户)
 ↓
加载到 Streamlit Session State
 ↓
提供用户界面管理
 ↓
动态创建/删除用户

🚀 快速开始

1. 环境准备

# 克隆项目
git clone <your-repo-url>
cd 忆语-YiYu # 或 EasyMemGraph
# 创建 Python 3.11 虚拟环境
python3.11 -m venv venv
# 激活虚拟环境
source venv/bin/activate # Linux/macOS
# 或 venv\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt

2. 配置环境变量

# 复制环境变量模板
cp .env.example .env
# 编辑 .env 文件,填入您的配置
# 必须配置 MODELSCOPE_API_KEY 和 LANGCHAIN_API_KEY

# 必须配置的参数
MODELSCOPE_API_KEY=your-modelscope-api-key-here
LANGCHAIN_API_KEY=your-langsmith-api-key-here
# 其他推荐配置
EMBEDDING_MODEL=moka-ai/m3e-base # 本地嵌入模型
EMBEDDING_DIMS=768 # 向量维度
LANGCHAIN_PROJECT=YiYu # LangSmith 项目名称

3. 启动 Qdrant 服务

# 自动设置 Qdrant (推荐)
python setup_qdrant.py
# 或手动启动 Docker 容器
docker run -d --name qdrant-memory-agent \
 -p 6333:6333 -p 6334:6334 \
 -v $(pwd)/qdrant_storage:/qdrant/storage \
 qdrant/qdrant:latest

4. 创建 LangSmith 项目(可选)

# 自动创建 YiYu 项目
python create_project.py
# 或使用交互式设置工具
python setup_langsmith_project.py

5. 启动对话机器人

选项1: 命令行界面

python memory_agent.py

选项2: Web界面 (推荐)

streamlit run app.py

📁 项目结构

忆语 (YiYu)/
├── 📄 app.py # Streamlit Web应用主文件 (智能用户管理)
├── 📄 memory_agent.py # 主对话代理 (带 LangSmith 追踪)
├── 📄 config.py # 统一配置管理
├── 📄 setup_qdrant.py # Qdrant 向量数据库设置脚本
├── 📄 langsmith_debug.py # LangSmith 调试和监控工具
├── 📄 setup_langsmith_project.py # LangSmith 项目设置工具
├── 📄 requirements.txt # 依赖包列表 (含 streamlit)
├── 📄 .env.example # 环境变量配置模板
├── 📄 README.md # 项目完整文档
├── 📄 CLAUDE.md # 开发环境指南
├── 📄 qdrant_storage/ # Qdrant 本地存储目录
├── 📄 .gitignore # Git忽略文件
└── 📄 LICENSE # MIT许可证

📊 项目统计

⚙️ 配置说明

环境变量配置

模型配置

🎯 使用示例

Web界面使用 (推荐)

streamlit run app.py

👥 智能用户管理功能

🆔 用户类型

📊 用户统计信息

🚀 用户操作

命令行界面

python memory_agent.py

程序化调用

from memory_agent import run_conversation
# 单次对话
response = run_conversation("你好,我想了解一下你的功能", "user123")
# 多轮对话 (跨会话记忆)
response1 = run_conversation("我叫张三,喜欢编程和AI", "user123")
response2 = run_conversation("你还记得我的名字和爱好吗?", "user123") # 会记住之前的对话

测试项目

# 运行完整测试套件 (含 LangSmith 验证)
python test_agent.py
# 测试内容包括:
# - 基本自我介绍和记忆存储
# - 跨会话记忆检索
# - 用户隔离验证
# - 偏好记忆功能
# - LangSmith 追踪数据验证
# - 调试工具功能测试

🔧 开发指南

核心设计原则

用户管理系统架构

# 用户扫描流程
def scan_existing_users() -> set:
 """从Qdrant扫描已有用户"""
 - 连接到Qdrant向量数据库
 - 批量扫描所有记录
 - 提取user_id字段
 - 返回唯一用户集合
# 用户统计流程
def get_user_statistics(user_id: str) -> Dict:
 """获取用户详细统计"""
 - 查询用户记忆数量
 - 获取最后活跃时间
 - 统计对话次数
 - 返回用户画像信息

记忆系统架构

# 记忆存储格式
interaction = [
 {
 "role": "user",
 "content": "用户输入内容"
 },
 {
 "role": "assistant",
 "content": "AI回应内容"
 }
]
# 记忆检索配置
memories = memory.search(
 query=user_message,
 user_id=user_id,
 limit=5 # 返回最相关的5条记忆
)

🛠️ 故障排除

常见问题

日志查看

📝 API 参考

Config 配置类

from config import Config
# 获取完整的 Mem0 配置
mem0_config = Config.get_mem0_config()
# 获取 LLM 配置 (魔搭 API)
llm_config = Config.get_model_config()
# 获取嵌入配置 (本地 M3E-Base)
embedding_config = Config.get_embedding_config()
# 获取 Qdrant 配置
qdrant_config = Config.get_qdrant_config()

对话代理

from memory_agent import run_conversation
# 单次对话
response = run_conversation("你好", "user_id")
# 带记忆的多轮对话
response1 = run_conversation("我叫张三,是程序员", "user_id")
response2 = run_conversation("你还记得我的职业吗?", "user_id")

记忆管理

from mem0 import Memory
from config import Config
# 初始化记忆系统
memory = Memory.from_config(Config.get_mem0_config())
# 搜索用户记忆
memories = memory.search("查询内容", user_id="user_id")
# 查看记忆结果
if memories and 'results' in memories:
 for mem in memories['results']:
 print(f"记忆: {mem['memory']}")

LangSmith 调试工具

# 查看运行记录
python langsmith_debug.py list --limit 10
# 查看特定运行详情
python langsmith_debug.py details --run-id <run-id>
# 性能分析
python langsmith_debug.py performance --hours 24
# 测试对话并追踪
python langsmith_debug.py test --input "测试消息" --user-id test_user
# 实时监控运行
python langsmith_debug.py monitor --duration 5
# 创建或切换 LangSmith 项目
python create_project.py

🎯 性能特性

系统性能指标

扩展性考虑

🔒 安全性

🤝 贡献指南

开发要求

提交流程

📄 许可证

🙏 致谢

🔗 相关链接

⭐ 如果这个项目对您有帮助,请给我们一个 Star!

GitHub stars GitHub forks GitHub issues

🔧 维护者: brightbird 📅 最后更新: 2025年10月 📦 版本: v1.0