☁️ 云尚 · RAG LearnLittle

云尚 是一款基于 RAG（检索增强生成） 的 AI 智能笔记助手。它以你的笔记为知识库，支持 ReAct / Plan-and-Execute 双 Agent 编排模式（共享同一套工具集）、深度思考、图片 / 视频多模态理解，并提供笔记模板、回收站、邮件发送、Token 用量追踪等完整工具链 —— 从记录知识到提取知识，一站式完成。

🎯 定位：本地优先的私人知识助手。支持 DashScope（阿里云百炼）与 Ollama（完全本地）双模型提供商一键切换。

🗨️ AI 对话	🧠 深度思考 / 多模态
📓 笔记管理	🗺️ Plan-and-Execute

• 后端：FastAPI + SQLAlchemy(async) + MySQL + Redis（会话缓存 / 流式缓冲）
• Agent 编排：LangChain / LangGraph，ReAct 与 Plan-and-Execute 双模式；ToolRegistry 统一管理 9 组内置工具 + MCP 动态工具，关键词路由按需加载
• 记忆：滑动窗口 + 里程碑摘要 + Redis 热缓存的三级压缩
• 检索：ChromaDB 向量库 + BM25 + CrossEncoder 重排序（BAAI/bge-reranker-v2-m3，AI 对话语义检索）；顶栏全局搜索走 MySQL FULLTEXT（ngram 分词）+ LIKE 兜底（启动时自动校验 Embedding 维度一致性）
• 模型层：DashScope（百炼）⇄ Ollama（本地）一键切换；Chat / Thinking / Embedding / Vision / Classifier / Plan 多模型组合
• 基础设施：APScheduler 定时任务（回收站清理、孤儿附件清理）、Langfuse 可观测性

# 克隆项目（仓库名 RAG_LearnLittleCode，克隆目录同名）
git clone https://github.com/qiaojoin586-droid/RAG_LearnLittleCode.git && cd RAG_LearnLittleCode

# 创建虚拟环境并安装依赖
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # macOS / Linux

pip install -r requirements.txt

# 配置环境变量
copy .env.example .env        # Windows
cp .env.example .env          # macOS / Linux

编辑 .env，至少填写：

# 模型提供商：dashscope（云）/ ollama（本地）
MODEL_PROVIDER=dashscope
DASHSCOPE_API_KEY=sk-xxxxxx

# 数据库
MYSQL_USER=root
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=raglearn

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# 邮件（可选，QQ 邮箱授权码，非登录密码；you_qq_email 替换为你的 QQ 邮箱）
SMTP_USERNAME=you_qq_email
SMTP_PASSWORD=your_smtp_auth_code

CREATE DATABASE raglearn CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

其他关键配置项（完整清单见 .env.example，共 59 项）：

🖥️ 选择 MODEL_PROVIDER=ollama（本地）时，需配置 OLLAMA_BASE_URL（默认 http://localhost:11434）、OLLAMA_CHAT_MODEL、OLLAMA_EMBED_MODEL，并确保本地已拉取对应模型；视觉附件还需 OLLAMA_VISION_MODEL。

python main.py
# 或 uvicorn main:app --reload

服务启动后：API 文档 → http://localhost:8000/docs（默认端口 8000）

cd front
npm install
npm run dev

浏览器访问 → http://localhost:5173

💡 首次运行提示：

• 重排序模型首次下载：BAAI/bge-reranker-v2-m3（约 1GB）需从 HuggingFace 下载。首次部署请临时设置 HF_HUB_OFFLINE=0，下载完成后可恢复离线模式
• 切换 Embedding 模型后需重建 ChromaDB 向量库：运行 python scripts/manual/migrate_embeddings_2560.py（无损重嵌：读出原文 → 重建集合 → 重新嵌入）；服务启动时会自动检查向量库与 Embedding 模型维度是否一致，不一致会给出明确修复指引
• 生产环境：APP_ENV=production、JWT_SECRET 必须为强随机值（启动强校验，公开默认值会拒绝启动）、LOG_LEVEL=INFO、LOG_FORMAT=json、CORS_ORIGINS 配置前端域名白名单（使用 * 时自动关闭凭据跨域）

cp .env.example .env          # 配置全部环境变量（JWT_SECRET 必填强随机值）
docker compose up -d --build
# 前端 http://localhost/（nginx 反代 /api，SSE 已禁用缓冲）
# 健康检查: GET /health（存活） /ready（就绪，含 MySQL/Redis 连通探测） /metrics（Prometheus）

要点：

• 数据库迁移：启动时 alembic upgrade head 自动执行（空库建表 / 遗留库自动 stamp）。新增模型后生成迁移：

  .venv/Scripts/python.exe -m alembic revision --autogenerate -m "描述"
  .venv/Scripts/python.exe -m alembic upgrade head

• 重排序模型：容器内需可访问本地模型缓存（默认 HF_HUB_OFFLINE=1）。把本机 ~/.cache/huggingface 拷到 ./huggingface_cache/（或设置 HF_CACHE_DIR），或在构建时 docker build --build-arg PRELOAD_MODELS=true .
• 端口：8000 仅为本机调试暴露，外部流量统一走前端 nginx（80）
• 单进程部署：多 worker/多实例前需先完成 Redis 化限流、scheduler 去重与 ChromaDB 多进程写冲突改造（见已知限制）
• 监控：/metrics 暴露 Prometheus 指标（HTTP 计数/耗时）；/ready 就绪探针检查后台初始化 + MySQL/Redis 连通性

所有业务路由统一前缀 /api/v1，完整交互文档见 Swagger → http://localhost:8000/docs

请求体字段：message（可空，为空时必须带 attachment_ids）· session_id · enable_thinking · idempotency_key · attachment_ids

系统行为可通过 config/ 下的 YAML 文件调优（无需改代码）：

prompts/ 目录存放 12 个 Agent 提示词文件，可直接编辑调优，如 main_prompt.txt（主 Agent，已声明 MCP 与外部 API 工具的使用规则）、plan_generation.txt（计划生成）、classify_complexity.txt（L2 分类）、rag_summarize.txt（RAG 摘要）等。

RAG_LearnLittleCode/          # 本地目录名可自由修改
├── main.py                  # FastAPI 入口（生命周期 / 中间件 / 路由注册）
├── app/
│   ├── core/                # 日志、异常处理、model_trace、scheduler
│   ├── db/                  # SQLAlchemy、Redis 客户端
│   ├── models/              # ORM 模型（用户 / 笔记 / 知识库 / 模板 / 工具审计）
│   ├── rag/                 # RAG 核心（向量库、检索、RagService、任务队列）
│   ├── routers/             # API 路由（chat / note / user / knowledge ...）
│   ├── services/            # 业务服务（笔记、邮件、用量、记忆压缩、模板）
│   ├── ai_service/          # Agent 编排（ReAct / Plan-Execute / 工具注册表 / MCP 管理器 / 流式输出 / 中间件）
│   ├── utils/               # 模型工厂、Prompt 加载、Token 估算
│   └── schemas/             # Pydantic 模型
├── config/                  # YAML 配置（agent / chroma / prompt / pricing）
├── front/                   # React 19 + Vite 前端
├── prompts/                 # Agent 系统提示词（main / plan / classify 等 12 个）
├── templates/               # 邮件 HTML 模板
├── data/                    # ChromaDB 持久化 + 用户附件（运行时生成）
├── logs/                    # 日志输出目录（运行时生成）
├── tests/eval/              # AI 对话黄金评测器
├── docs/                    # 架构图与升级设计方案
├── .env.example              # 环境变量模板（59 项，含完整注释）
└── requirements.txt

pip install -r requirements-dev.txt   # 开发/测试依赖（生产依赖见 requirements.txt）
python -m pytest tests/ -v            # SSRF 守卫 / JWT 强校验 / MCP 包装等纯逻辑测试

根目录旧调试脚本（test_*.py / repro_tmp.py 等）已移入 scripts/manual/，用途与处置建议见其 README；它们依赖真实 DB/LLM，不属于 CI 测试。

cd front
npm run lint      # eslint（typescript-eslint + react-hooks）
npm test          # vitest（SSE 解析器 / client 401 刷新）
npm run build     # tsc --noEmit + vite build（tsconfig 已开启 strict）

内置 AI 对话黄金评测器：读取 golden_cases.json，逐条调用 /chat/query（SSE 流式），按关键词判定 PASS/FAIL，覆盖对话、RAG、笔记、安全注入等分类：

.venv/Scripts/python.exe -X utf8 tests/eval/eval_runner.py [--base-url URL] [--interval 7] [--keep]

报告输出至 tests/eval/results/report_*.json。

• 流式 Token 统计：DashScope 兼容模式下流式响应的 usage 可能为 null，影响成本统计精度
• 多模态 + 深度思考：视觉模型不支持思考模式，上传附件时自动走视觉模型，二者不可组合
• 工具按需加载：default_groups 为全量加载兜底（关键词规则仅作加速），后续可改为纯按需加载以节省上下文窗口
• MCP 依赖本机环境：Tavily（npx）与 Fetch（uvx）MCP Server 需要 Node 环境与网络；任一 Server 连接失败自动降级跳过，不影响 Agent 主流程
• 邮件限流：send_email 限流为进程内滑动窗口（10 封 / 小时 / 用户），多进程部署需迁移至 Redis
• 回收站：笔记回收站最长保留 14 天，由定时任务自动彻底删除

• 后端：Python PEP 8，类与方法使用中文 docstring；按 routers / services / models / schemas / rag / ai_service 分层，新增能力先写 service 再挂路由
• 前端：TypeScript 严格模式（npm run build 即 tsc && vite build，构建前必须通过类型检查）；函数式组件 + hooks + Zustand 状态管理

• 分支：main 为稳定基线，新功能在独立分支开发（如 Agent），验证通过后合入
• 提交信息：中文一句话描述改动内容与动机，重要改动附编号（如 P2-3）
• 提交前运行 python -m pytest tests/、前端 npm run lint && npm test && npm run build 确认无回归（CI 会全量执行）

• config/agent.yaml 是 Agent 行为中枢：工具分组、关键词路由、各阶段超时、Token 预算、记忆压缩阈值、邮件限流均可在此调整，修改后重启服务生效
• prompts/*.txt 提示词可直接编辑，无需改代码
• 新增内置工具：在 app/ai_service/agent_tools.py 用 @tool 注册 → 加入 config/agent.yaml 的 tool_groups 与 tool_routing.keyword_rules → 用黄金评测器回归验证
• 新增 MCP 工具：在 config/agent.yaml 的 mcp_servers 添加 Server 配置，用 tools_include 白名单过滤暴露的工具（自动注册进 "mcp" 组，随 default_groups 加载）

• 待添加
• 系统架构图

MIT © 2026 Qoin

本项目基于 MIT 协议开源：允许自由使用、修改与分发，需保留版权声明。

🔗 仓库：RAG_LearnLittleCode · 📚 更多设计文档