微信公众号 RAG Agent 最终版 GitHub 文档

（已补全：项目目录、requirements.txt、Modelfile、Nginx反向代理、微信配置全流程、完整启动命令）

🚀 项目介绍

本项目是一个专为微信公众号设计的轻量智能对话Agent，基于 FastAPI + LangGraph + Ollama + FAISS 构建，支持：

• 大模型闲聊（一句话短回答，适配微信场景）
• RAG 知识库检索
• 日期类接口调用（每日一句）
• 微信重试缓存机制：彻底解决公众号5秒超时问题，无需客服消息，100%保证消息送达
• Nginx 反向代理，适配公网部署

核心优势：2核4G服务器即可稳定运行，纯CPU推理，无GPU依赖，零客服消息次数占用。

📁 项目目录结构

wechat_agent_ai/
├── rag/                          # RAG 知识库模块
│   ├── faiss_index/              # FAISS 向量索引文件（向量化后生成）
│   ├── models--Qwen--Qwen3-Embedding-0.6B/  # 通义千问嵌入模型
│   ├── data_vectorization.py    # 知识库向量化脚本（生成FAISS索引）
│   ├── iciba_data_multi.json    # 每日一句备用数据
│   └── rag_data_retrieval.py    # RAG 检索测试脚本
├── main.py                       # 主程序（微信接口+Agent+重试缓存核心逻辑）
├── main_1.py                     # 历史版本/备用代码
├── test_local.py                 # 本地测试脚本（无需微信，直接测试Agent功能）
├── requirements.txt              # 项目依赖清单（一键安装）
├── Modelfile                     # Ollama 自定义模型配置文件
├── dockerfile                    # Docker 构建文件（可选）
├── start.sh                      # 启动脚本
├── .dockerignore                 # Docker 忽略文件
└── README.md                     # 本说明文档

目录说明

📦 环境安装（通过 requirements.txt 一键部署）

1. 前置依赖

• 系统：Ubuntu 20.04+（推荐）
• Python：3.8+
• 服务器：2核4G及以上，开放80端口（Nginx反向代理用）

2. 安装 Ollama（大模型运行环境）

# 一键安装 Ollama
curl https://ollama.com/install.sh | sh

# 拉取基础模型（qwen2:0.5b 超轻量，适配2核4G）
ollama pull qwen2:0.5b-instruct-q2_K

3. 构建自定义 Ollama 模型（Modelfile）

# 创建 Modelfile（适配微信的短回答模型）
tee Modelfile <<EOF
FROM qwen2:0.5b-instruct-q2_K
PARAMETER num_ctx 512
PARAMETER num_predict 64
PARAMETER temperature 0.1
PARAMETER top_p 0.7
PARAMETER num_thread 2
SYSTEM "直接回答，一句话。"
EOF

# 构建自定义模型 my-qwen
ollama create my-qwen -f Modelfile

# 测试模型（验证是否正常）
ollama run my-qwen "你好"

4. 一键安装 Python 依赖（requirements.txt）

# 1. 创建并激活虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate

# 2. 一键安装所有依赖
pip install -r requirements.txt

requirements.txt 完整内容

fastapi==0.110.0
uvicorn==0.28.0
langchain==0.2.0
langgraph==0.0.56
langchain-ollama==0.1.0
langchain-huggingface==0.1.0
langchain-community==0.2.0
faiss-cpu==1.8.0
requests==2.31.0
python-dotenv==1.0.1
huggingface-hub==0.23.0

⚙️ 核心配置说明

1. main.py 核心配置

修改 main.py 中的「线上配置」部分，替换为自己的信息：

# ===================== 【线上配置】 =====================
WECHAT_TOKEN = "wechat_rag_agent_2026"  # 与微信公众号配置的Token完全一致
WECHAT_ORIGIN_ID = "gh_cfbff1593cc5"    # 公众号原始ID（后台「设置与开发」→「基本配置」查看）

EMBEDDING_PATH = "./rag/models--Qwen--Qwen3-Embedding-0.6B/snapshots/c54f2e6e80b2d7b7de06f51cec4959f6b3e03418"
FAISS_INDEX_DIR = "./rag/faiss_index"  # FAISS 向量索引目录
LLM_MODEL = "my-qwen"  # 自定义Ollama模型名称（与Modelfile构建的一致）
OLLAMA_HOST = "http://localhost:11434"

# 缓存过期时间：30秒（仅覆盖微信重试窗口期，超时自动清空）
CACHE_EXPIRE_SECONDS = 30
# ========================================================

2. Nginx 反向代理配置（关键！适配微信公网访问）

1. 安装 Nginx

sudo apt update && sudo apt install nginx -y

2. 创建反向代理配置文件

sudo tee /etc/nginx/sites-available/wechat_agent <<EOF
server {
    listen 80;
    server_name 你的服务器公网IP;  # 替换为你的服务器IP（与微信配置的URL一致）

    # 👇 微信公众号接口反向代理（核心配置）
    location /wechat {
        proxy_pass http://127.0.0.1:8080/wechat;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_read_timeout 60s;  # 适配微信超时，避免代理断开
    }
}
EOF

3. 启用配置并重启 Nginx

# 启用配置
sudo ln -s /etc/nginx/sites-available/wechat_agent /etc/nginx/sites-enabled/

# 校验配置是否正确
sudo nginx -t

# 重启 Nginx 生效
sudo systemctl restart nginx

🚀 完整服务启动命令（直接复制运行）

以下命令包含「关闭旧进程→启动Ollama→预加载模型→启动FastAPI」，一键完成服务部署，确保运行稳定：

source venv/bin/activate
pkill -9 ollama
pkill -9 uvicorn
fuser -k 8080/tcp
OLLAMA_CPU_THREADS=2 OLLAMA_LOAD_MODEL_AT_START=true nohup ollama serve > ollama.log 2>&1 &
ollama run my-qwen "/bye"
nohup uvicorn main:app --host 0.0.0.0 --port 8080 --workers 1 > wechat.log 2>&1 

命令说明：

• 前3行：关闭旧的Ollama、uvicorn进程，释放8080端口，避免端口占用冲突
• 第4行：2核满负载启动Ollama，启动时预加载模型，彻底消除冷启动耗时
• 第5行：预加载my-qwen模型，进一步加速第一次请求响应
• 第6行：启动FastAPI服务，监听所有IP（0.0.0.0），适配Nginx反向代理，1个worker避免资源竞争

查看服务状态（确认启动成功）：

ps -ef | grep ollama
ps -ef | grep uvicorn

📱 微信公众号配置（与截图完全对应）

1. 配置信息（后台「微信开发者平台」→「公众号」->「消息」）

2. 配置校验

提交配置后，微信会自动校验URL有效性，校验通过后即可启用，公众号即可正常接收用户消息并自动回复。

🧠 核心逻辑说明

1. 重试缓存机制（解决微信5秒超时）

• 微信公众号被动回复官方建议超时5秒，超时会自动重试同一条消息（MsgId 不变）
• 第一次请求：调用AI生成回复，写入内存缓存（有效期30秒，仅绑定当前MsgId）
• 微信重试：第二次请求命中缓存，0.2秒内直接返回，确保用户100%收到
• 新消息触发：MsgId 变化时，自动清空所有缓存，避免重复回答
• 过期清理：每次请求自动清理30秒以上的过期缓存，无内存泄漏

2. 意图识别路由（LangGraph 工作流）

📝 日志查看与问题排查

1. 日志查看命令

# 查看FastAPI/微信消息日志（核心日志）
tail -f wechat.log

# 查看Ollama模型日志
tail -f ollama.log

# 查看Nginx代理日志
tail -f /var/log/nginx/access.log

2. 常见问题排查

（1）微信消息收不到

• 检查服务器安全组，确认80端口已开放（Nginx监听80，微信仅支持80/443端口）
• 确认Nginx配置正确，proxy_pass 指向 127.0.0.1:8080/wechat
• 查看wechat.log，确认AI调用、缓存逻辑正常
• 检查微信Token与代码配置完全一致

（2）回复速度慢

• 确认Ollama启动时添加OLLAMA_CPU_THREADS=2，2核满负载运行
• 确认Modelfile中num_thread=2，充分利用CPU
• 执行预加载模型命令（启动命令第5行），消除冷启动耗时

（3）重复回答

• 查看日志中「缓存清理」记录，确认新消息MsgId变化时缓存已清空
• 缓存有效期30秒，超时自动清理，重启FastAPI可手动清空所有缓存

🛑 服务停止命令

# 停止Ollama和FastAPI服务
pkill -9 ollama uvicorn

# 释放8080端口
fuser -k 8080/tcp

# 停止Nginx（如需）
sudo systemctl stop nginx

📌 注意事项

• 服务器重启后，需重新执行「完整服务启动命令」（复制即可运行），可配置开机自启避免手动操作
• Ollama模型建议使用0.5B级别的量化模型（如qwen2:0.5b-instruct-q2_K），避免CPU负载过高导致卡顿
• 微信公众号仅支持80/443端口，必须通过Nginx反向代理8080端口，否则无法完成URL校验
• 缓存仅用于接住微信重试，有效期30秒，无内存占用风险，无需手动清理
• 正式环境建议配置HTTPS（Let's Encrypt免费证书），使用443端口，提升安全性并避免微信接口限制
• 启动命令中--host 0.0.0.0表示监听所有公网IP，配合Nginx反向代理可实现公网访问，无需修改其他配置
• 若出现端口占用，可再次执行fuser -k 8080/tcp释放端口，重新启动服务