WeChat RAG Agent

[!WARNING] 重要免责声明 / IMPORTANT DISCLAIMER

本项目仅供技术学习和研究之用，严禁用于任何商业或非法用途。 This project is for educational and research purposes ONLY. Commercial or illegal use is strictly prohibited.

微信聊天记录包含大量个人隐私信息。您在使用本项目时，必须承担所有数据安全和隐私泄露的风险。开发者不对任何数据丢失、泄露或滥用负责。 WeChat chat history contains extensive private information. By using this project, you assume all risks related to data security and privacy breaches. The developers are not responsible for any data loss, leakage, or misuse.

强烈建议您在完全隔离的本地环境中运行本项目，切勿将其部署在任何可公开访问的服务器上。 It is STRONGLY recommended that you run this project in a completely isolated, local environment. DO NOT deploy it on any publicly accessible server.

项目简介

WeChat RAG Agent 是一个基于检索增强生成（RAG）技术的微信聊天记录智能问答系统。通过向量化微信聊天记录，结合先进的大语言模型，为用户提供基于历史聊天内容的智能问答服务。

前端界面预览

现代化的聊天界面，支持实时流式回答和智能聊天记录检索

相关项目

• 后端API服务: wechat-rag-agent (本项目)
• 前端Web界面: wechat-rag-frontend - Next.js构建的现代化聊天界面
• 微信数据提取: chatlog-new - 微信聊天记录提取工具，fork自原项目chatlog

核心特性

• 🚀 高性能向量化处理：支持大规模微信聊天记录的并行向量化处理
• 🔍 智能检索增强：基于向量相似度搜索和重排序模型的精准内容检索
• ⚡ 实时流式问答：支持流式输出的自然语言问答体验
• 📈 增量同步机制：基于Redis的增量数据同步，避免重复处理
• 🎯 多AI提供商支持：支持多种向量化、重排序和语言模型提供商
• 🐳 容器化部署：Docker Compose一键部署，包含所有依赖服务
• 📊 实时进度监控：Server-Sent Events实时跟踪数据处理进度
• 🔧 模块化架构：清晰的三层架构设计，便于扩展和维护
• 🏭 工厂模式设计：支持多种嵌入、重排序和向量存储提供商
• 📝 时间查询解析：智能解析自然语言时间表达式

系统架构

模块结构

wechat-rag-agent/
├── agent-web/          # 主Web应用模块 (端口:8080) - 系统编排层
├── agent-datasync/     # 数据同步服务模块 - 向量化处理
├── agent-core/         # 核心RAG功能库 - 嵌入模型和查询处理
└── docker/            # Docker配置文件

模块依赖关系： - agent-web: 主应用，依赖 agent-core 和 agent-datasync - agent-datasync: 依赖 agent-core 进行嵌入向量化 - agent-core: 独立的共享库，无外部模块依赖

技术栈

• 后端框架：Spring Boot 3.5.3 + WebFlux (响应式编程)
• AI框架：LangChain4j 1.1.0
• 运行环境：Java 21
• 向量数据库：Elasticsearch 8.18.1 / Chroma
• 缓存存储：Redis 7.2
• 容器化：Docker + Docker Compose
• 监控：Spring Boot Actuator + Micrometer

架构图

数据同步流程

sequenceDiagram
    participant User as 用户
    participant WebApp as agent-web

(端口8080)
    participant DataSync as agent-datasync
    participant WeChatAPI as 微信API服务

(端口5030)
    participant Embedding as SiliconFlow

(向量化)
    participant VectorDB as Elasticsearch
    participant Redis as Redis

(状态管理)

    User->>WebApp: POST /api/vectorization/chatlog/stream
    WebApp->>DataSync: 调用ChatlogVectorService
    DataSync->>WeChatAPI: 分页请求聊天记录
    WeChatAPI-->>DataSync: 返回聊天记录
    DataSync->>DataSync: 并行处理(4线程)
    DataSync->>Embedding: 批量文本向量化(50条/批)
    Embedding-->>DataSync: 返回向量
    DataSync->>VectorDB: 存储文档和向量
    DataSync->>Redis: 更新同步检查点
    DataSync-->>WebApp: 返回处理进度
    WebApp-->>User: SSE流式推送进度

智能问答流程

sequenceDiagram
    participant User as 用户
    participant WebApp as agent-web
    participant Core as agent-core
    participant QueryParser as QueryParser

(查询解析)
    participant TimeParser as TimeParser

(时间解析)
    participant Embedding as SiliconFlow

(向量化)
    participant VectorDB as Elasticsearch
    participant Reranker as SiliconFlow

(重排序)
    participant LLM as OpenRouter

(大语言模型)

    User->>WebApp: GET /api/chat?question=...
    WebApp->>Core: 调用Assistant
    Core->>QueryParser: 解析查询意图
    Core->>TimeParser: 解析时间表达式
    Core->>Embedding: 向量化用户问题
    Embedding-->>Core: 返回问题向量
    Core->>VectorDB: 向量相似度搜索
    VectorDB-->>Core: 返回相关文档
    Core->>Reranker: 重排序文档
    Reranker-->>Core: 返回优化后的文档
    Core->>LLM: 构建增强Prompt
    LLM-->>Core: 返回最终答案
    Core-->>WebApp: 返回结构化响应
    WebApp-->>User: 流式响应答案

快速开始

前置条件

1. Docker & Docker Compose：版本20.0+
2. Git：用于克隆项目
3. 微信API服务 fork修改版：确保提前运行HTTP服务(端口5030)以及数据解密
4. API密钥：
5. OpenRouter API密钥 (用于大语言模型)
6. SiliconFlow API密钥 (用于向量化和重排序)

安装步骤

1. 克隆项目

git clone https://github.com/WechatRagAgent/agent
cd agent

2. 配置环境变量

创建环境配置文件：

cd docker/ && cp .env.example .env

编辑 .env 文件，添加您的API密钥：

# ============= AI服务密钥 =============
# 用于解析问题
# 推荐OpenRouter API密钥 (获取地址：https://openrouter.ai/keys)
RAG_PARSE_MODEL_API_KEY=your_openrouter_api_key

# 用于向量化模型和重排序模型服务
# 推荐SiliconFlow API密钥 (获取地址：https://cloud.siliconflow.cn/me/account/ak)
RAG_EMBEDDING_API_KEY=your_siliconflow_api_key
RAG_RERANK_API_KEY=your_siliconflow_api_key

3. 启动服务

确保在docker目录下执行

# 启动所有服务 (首次启动需要下载镜像，请耐心等待)
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f wechat-rag-agent

4. 验证部署

检查服务健康状态：

# 检查应用健康状态
curl http://localhost:8080/actuator/health

# 检查Elasticsearch
curl http://localhost:9200/_cluster/health

# 检查Redis
docker exec redis redis-cli ping

如果所有服务都正常运行，您应该看到类似以下的响应：

{
  "status": "UP",
  "components": {
    "elasticsearch": {"status": "UP"},
    "redis": {"status": "UP"}
  }
}

API 使用指南

1. 数据同步API

开始向量化处理

curl -X POST "http://localhost:8080/api/vectorization/chatlog/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "talker": "好友昵称",
    "time": "2024-01-01~2024-01-31"
  }'

支持的时间格式： - 单日：2024-01-01 - 时间范围：2024-01-01~2024-01-31

该接口返回Server-Sent Events (SSE) 流，实时推送处理进度：

data: {"taskId":"uuid","status":"PROCESSING","processedCount":150,"totalCount":1000,"progress":0.15}
data: {"taskId":"uuid","status":"COMPLETED","processedCount":1000,"totalCount":1000,"progress":1.0}

清理已完成任务

curl -X DELETE "http://localhost:8080/api/vectorization/progress/{taskId}"

2. 聊天API

curl -G "http://localhost:8080/api/chat" \
  --data-urlencode "question=总结一下最近的工作安排" \
  --data-urlencode "modelName=google/gemini-2.5-flash" \
  --data-urlencode "apiKey=your-openrouter-api-key"
  -H "Accept: text/event-stream"

返回格式兼容OpenAI格式，支持流式输出。

3. 系统监控API

# 健康检查
curl http://localhost:8080/actuator/health

# 系统指标
curl http://localhost:8080/actuator/metrics

# Prometheus指标
curl http://localhost:8080/actuator/prometheus

本地开发

开发环境要求

• Java 21+
• Maven 3.8+
• Elasticsearch 8.18.1
• Redis 7.2+

启动开发环境

1. 启动基础设施

# 仅启动依赖的基础设施服务
docker-compose up -d elasticsearch redis kibana

2. 构建项目

# 编译整个项目
mvn clean compile

# 打包项目
mvn clean package -DskipTests

3. 运行应用

# 运行主应用 (推荐 - 包含完整功能)
mvn spring-boot:run -pl agent-web

# 可选：单独运行数据同步服务进行测试
mvn spring-boot:run -pl agent-datasync

注意：推荐运行 agent-web 模块，它整合了所有功能并提供完整的REST API。

4. 开发环境配置

修改配置文件(application.yml)中的API密钥和服务地址。

运行测试

# 运行所有测试
mvn test

# 运行特定模块测试
mvn test -pl agent-core

配置说明

核心配置项

项目使用Spring Boot的配置管理，主要配置文件为 application.yml：

# 服务器配置
server:
  port: 8080

# Redis配置
spring:
  data:
    redis:
      host: localhost
      port: 6379

# 微信API配置
wechat:
  chatlog:
    base-url: http://127.0.0.1:5030

# RAG相关配置
rag:
  # 大语言模型配置
  parse-model:
    api-key: your-openrouter-api-key
    model: google/gemini-2.5-flash

  # 向量化模型配置
  embedding:
    provider: siliconflow
    model: BAAI/bge-m3
    api-key: your-siliconflow-api-key
    base-url: https://api.siliconflow.cn/v1

  # 重排序模型配置
  rerank:
    provider: siliconflow
    model: BAAI/bge-reranker-v2-m3
    api-key: your-siliconflow-api-key
    base-url: https://api.siliconflow.cn/v1

  # 向量数据库配置
  vector-store:
    provider: elasticsearch  # 或 chroma
    url: http://localhost:9200
    collection-name: wechat_chatlog

支持的提供商

向量化模型提供商 (rag.embedding.provider)

• siliconflow: SiliconFlow平台 (推荐，支持BAAI/bge-m3等模型)
• huggingface: HuggingFace Hub (支持大部分开源模型)
• local: 本地模型服务 (自建API兼容服务)

重排序模型提供商 (rag.rerank.provider)

• siliconflow: SiliconFlow平台 (推荐，支持BAAI/bge-reranker-v2-m3)
• local: 本地重排序模型 (自建重排序服务)

向量数据库提供商 (rag.vector-store.provider)

• elasticsearch: Elasticsearch (生产推荐，支持复杂查询)
• chroma: Chroma (开发友好，轻量级部署)

大语言模型提供商 (rag.parse-model)

• OpenRouter: 多模型聚合平台，支持 Google Gemini, OpenAI GPT 等

故障排除

常见问题

1. 容器启动失败

问题：docker-compose up 执行失败

解决方案：

# 检查Docker服务状态
systemctl status docker

# 检查端口占用
netstat -tulpn | grep -E "(8080|9200|6379)"

# 清理Docker资源
docker system prune -f
docker-compose down --volumes

2. API密钥错误

问题：401 Unauthorized 或向量化失败

解决方案： - 确认OpenRouter和SiliconFlow API密钥的有效性 - 检查API密钥是否正确配置在环境变量中 - 验证API账户余额是否充足

3. 微信API服务连接失败

问题：Connection refused 错误

解决方案：

# 检查微信API服务是否运行
curl http://localhost:5030/health

# 检查Docker网络配置
docker network ls
docker network inspect wechat-rag_default

4. Elasticsearch连接问题

问题：向量存储操作失败

解决方案：

# 检查Elasticsearch状态
curl http://localhost:9200/_cluster/health?pretty

# 查看Elasticsearch日志
docker-compose logs elasticsearch

# 重启Elasticsearch服务
docker-compose restart elasticsearch

5. 内存不足

问题：容器因内存不足被杀死

解决方案：

# 调整Docker Compose中的内存限制
# 编辑 docker-compose.yml
services:
  elasticsearch:
    environment:
      - "ES_JAVA_OPTS=-Xms2g -Xmx2g"  # 增加内存分配

日志查看

# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f wechat-rag-agent
docker-compose logs -f elasticsearch
docker-compose logs -f redis

# 查看应用日志文件
tail -f logs/application.log

贡献指南

我们欢迎社区贡献！请遵循以下指南：

如何贡献

1. Fork 项目到您的GitHub账户
2. 创建功能分支：git checkout -b feature/your-feature-name
3. 提交更改：git commit -am 'Add some feature'
4. 推送分支：git push origin feature/your-feature-name
5. 创建Pull Request

代码规范

• 遵循Java代码规范和Spring Boot最佳实践
• 使用Lombok减少样板代码
• 编写有意义的提交信息
• 添加适当的单元测试
• 更新相关文档

报告问题

在Issues页面报告问题时，请提供：

• 详细的问题描述
• 重现步骤
• 环境信息 (OS、Java版本、Docker版本)
• 相关的错误日志

路线图

已完成 ✅

• [x] 三模块清晰架构设计 (agent-web, agent-datasync, agent-core)
• [x] 多AI提供商支持 (SiliconFlow, HuggingFace, OpenRouter)
• [x] Redis增量同步机制
• [x] 时间表达式智能解析
• [x] 实时进度监控 (SSE)
• [x] 响应式并行处理

计划中 🚧

• [ ] 支持更多向量数据库 (Pinecone, Weaviate)
• [ ] 集成更多AI模型提供商 (Azure OpenAI, Claude)
• [ ] 优化大规模数据处理性能

许可证

本项目采用 MIT License 开源许可证。

致谢

感谢以下开源项目和服务：

• LangChain4j - Java版本的LangChain
• Spring Boot - 应用框架
• Elasticsearch - 向量搜索引擎
• OpenRouter - AI模型API聚合服务
• SiliconFlow - 向量化和重排序服务
• chatlog - 微信聊天记录提取工具

免责声明 (再次强调)

⚠️ 请再次注意：

1. 隐私保护：本项目处理的微信聊天记录包含极其敏感的个人隐私信息，使用前请确保充分理解相关风险。

2. 本地运行：强烈建议仅在本地隔离环境中运行，不要将包含真实聊天数据的服务暴露到公网。

3. 合规使用：请确保您的使用方式符合当地法律法规和微信用户协议。

4. 数据安全：开发者不对任何数据泄露、丢失或滥用承担责任。

5. 学习目的：本项目仅供技术学习和研究使用，禁止用于任何商业用途。

---

如果此项目对您有帮助，请给我们一个 ⭐ Star！

_{Built with ❤️ for learning and research purposes only}