forked from fangtianchen/algonotes_rag
222 lines
11 KiB
Markdown
222 lines
11 KiB
Markdown
# 🧠 AlgoNotes RAG - 个人算法竞赛笔记智能助手
|
||
|
||
|
||
|
||
|
||
|
||
|
||
> 🎯 **定位**：面向 OI/ICPC 等算法竞赛生的 **个人笔记外置大脑**。
|
||
> 基于 RAG + MCP 架构，实现个人题解/代码/推导笔记的语义检索、竞赛场景下的问答与结构化输出。
|
||
> 与公共题库系统形成互补，专注还原**个人认知路径**与**复健轨迹**。
|
||
|
||
---
|
||
|
||
## 📖 项目背景：从“算力奢侈品”到“个人外置大脑”
|
||
|
||
回到项目发起人（即笔者 fangtianchen）学习信息学奥赛（OI）的“前 AI 时代”，那时学习路径高度依赖博客笔记、碎片化题解与反复试错。那时，DeepSeek R1 尚未问世，GPT 等大语言模型对中学生而言仍是遥不可及的“算力奢侈品”。每一位选手都在黑暗中独自摸索：手写推导、整理错题、反复调试，知识沉淀缓慢且极易断层。笔者在经历了高三的题海与模考的挫折后，许多本可结构化的认知轨迹，最终散落在 cnblogs、洛谷提交记录与本地文件夹中，这让高考后复健算法准备 ICPC 遇到困难。
|
||
|
||
如今，AI 技术普惠与国产算力崛起正在重塑这一切。沐曦 GPU、Gitee.AI 等国产基础设施的成熟，让“每个人都能拥有专属 AI 助手”从愿景走向现实。然而，市面上的竞赛辅助工具多聚焦于“公共题库检索”或“通用代码生成”，却忽略了竞赛生最核心的资产——**个人在实战中沉淀的认知路径**。
|
||
|
||
**AlgoNotes RAG** 正是在此背景下诞生。它不追求替代人类的思考，而是致力于成为 OI/ICPC 选手的“私有外置大脑”：
|
||
|
||
- 🇨🇳 **全栈国产算力落地**：推理依赖沐曦 GPU + 开源模型（Qwen/DeepSeek），零国外商业 API 依赖
|
||
- 🔒 **隐私优先的个人知识库**：笔记本地解析、向量化与存储，数据不出域，支持离线演进
|
||
- 🧭 **懂你的竞赛语境**：内置代码习惯审查/复杂度推导等 Prompt，输出带溯源引用的结构化答案
|
||
- 🤝 **MCP / CLI 双接口**：增/删/改/查四类操作同时支持 MCP 协议与命令行工具，可无缝接入 Claude Code / OpenClaw / 各类 AI Agent 前端
|
||
|
||
本项目是国产 AI 算力在垂直教育场景的一次轻量级验证。我们以 MVP 闭环证明技术可行性，以开源姿态拥抱社区，希望向更多选手传递一个信念：在算法竞赛与个性化学习领域，中国开发者完全有能力用本土算力构建高质量工具。
|
||
|
||
> 从“算力奢侈品”到“普惠外置大脑”，变的是工具，不变的是对问题本质的追问与对代码的敬畏。
|
||
> *"Don't stop. Don't hide. Follow the light, and you'll find tomorrow."*
|
||
> —— 致每一位在调试中逼近真相的算法探索者，与国产 AI 生态共同前行的同路人。
|
||
|
||
---
|
||
|
||
## 📊 核心差异化：为什么需要它？
|
||
|
||
| 维度 | 公共题库知识图谱系统 (如 CPGraph) | 🌟 AlgoNotes RAG (本项目) |
|
||
| :--- | :--- | :--- |
|
||
| **数据源** | 网络题解 / 公开题库 | 用户私有笔记 (cnblogs / 洛谷 / 本地 Markdown) |
|
||
| **核心价值** | “找题”：相似推荐 / 题意查重 / 题单生成 | “懂我”：个人思路还原 / 代码习惯审查 / 复健进度追踪 |
|
||
| **技术架构** | Neo4j + FAISS 双层图向量库，部署重 | Chroma + SQLite + 文件系统三层轻量存储，`uv sync` 零依赖启动 |
|
||
| **交互范式** | 结构化实体检索 | 自然语言问答 + 溯源引用 + 竞赛语境 Prompt 约束 |
|
||
|
||
✅ **场景互补**：本项目不替代公共知识图谱，而是通过两者配合使用，以填补 **“个人碎片化知识管理”** 空白。适合高三后复健、省选/NOIP 备赛阶段的私有化认知加固。
|
||
|
||
---
|
||
|
||
## 🏗️ MVP 架构设计（v1.0 已实现）
|
||
|
||
当前版本聚焦 **可验证的核心闭环**，采用轻量级架构确保比赛周期内稳定交付：
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[原始笔记] --> B(Ingestion Pipeline)
|
||
B -->|1. 存原始文件| C[(data/files/)]
|
||
B -->|2. 记笔记索引| D[(data/sql_db/)]
|
||
B -->|3. 分块向量化| E[(data/chroma_db/)]
|
||
F[用户提问] --> G[RAG Agent]
|
||
G -->|1. 查询理解| G
|
||
G -->|2. 路由工具| H{工具选择}
|
||
H -->|search_notes| E
|
||
H -->|search_by_tags| D
|
||
H -->|get_file_content| C
|
||
E --> G
|
||
D --> G
|
||
C --> G
|
||
G -->|3. generation 后处理| I[重排序 + 去重]
|
||
I -->|4. 生成答案| J[答案 + 溯源引用]
|
||
```
|
||
|
||
| 模块 | 职责 | 实现方式 |
|
||
| :--- | :--- | :--- |
|
||
| 📥 **Ingestion Pipeline** | 解析原始笔记 → 存原始文件 → 记笔记索引 → 分块打标 → 向量化入库 | `MarkdownHeaderTextSplitter` 按标题分块 + `RecursiveCharacterTextSplitter` 大块二次分割 + 自动注入 `source`/`type`/`ingested_at` 元数据 + Chroma `add_documents()` |
|
||
| 💾 **三层存储** | 原始文件（`data/files/`）+ 关系索引（`data/sql_db/`）+ 向量库（`data/chroma_db/`） | 文件原样保留 + SQLite 记录文件名/时间/关键词 + Chroma 持久化 · [详见 STORE.md](docs/STORE.md) |
|
||
| 📝 **RAG AGENT** | 理解问题，基于知识库检索并重排序，生成竞赛友好答案，强制溯源引用，支持流式输出 | 系统提示词规定流程 + tools 传入 + `chain.stream()` |
|
||
| 📊 **Performance Log** | 记录全链路耗时、Token 消耗、显存占用、检索命中率 | `logging` 模块 + JSON Lines 格式 + LangSmith Trace 集成 + 自动计时器（`time.perf_counter()`） |
|
||
| 🌐 **MCP Server** | 暴露 ingest/update/delete/search 四类工具，供 AI 前端调用 | `src/mcp/` 模块，MCP 协议标准接口 |
|
||
| 📟 **CLI** | 命令行工具集，覆盖笔记管理、语义查询、交互问答、MCP 启动 | `scripts/` 模块，argparse + Textual TUI |
|
||
|
||
---
|
||
|
||
## 🚀 5分钟快速开始
|
||
|
||
### 1️⃣ 环境准备
|
||
|
||
```bash
|
||
git clone https://gitlink.org.cn/fangtianchen/algonotes_rag.git
|
||
cd algonotes_rag
|
||
uv sync
|
||
```
|
||
|
||
### 2️⃣ 配置沐曦算力 (Gitee.AI)
|
||
|
||
复制 `.env.example` 为 `.env`，填入 API Key，编辑 `config.toml`：
|
||
|
||
```toml
|
||
[llm]
|
||
model = "Qwen2.5-72B-Instruct" # 或 deepseek-V3，需要支持 function_call 的 llm
|
||
base_url = "https://ai.gitee.com/v1"
|
||
api_key = "your_api_key" # 不建议硬编码，建议引用 .env 中的变量
|
||
|
||
[embedding]
|
||
model = "Qwen/Qwen3-Embedding-8B"
|
||
base_url = "https://ai.gitee.com/v1"
|
||
api_key = "your_api_key"
|
||
```
|
||
|
||
> 💡 敏感信息不建议硬编码，可以在 `config.toml` 中使用 `${VAR}` 语法动态替换。
|
||
|
||
### 3️⃣ 使用 CLI 或运行 MCP 服务
|
||
|
||
使用本项目，运行本项目 MCP 服务的方法：
|
||
|
||
```bash
|
||
# 导入笔记（从本地目录）
|
||
algonotes ingest -i ./my_notes/
|
||
|
||
# 更新笔记
|
||
algonotes update fenwick.md --file ./updated_fenwick.md
|
||
|
||
# 删除笔记
|
||
algonotes delete fenwick.md
|
||
|
||
# 查询笔记
|
||
algonotes query list
|
||
|
||
# 交互式问答
|
||
algonotes chat
|
||
|
||
# 启动 MCP 服务（供 AI 前端调用）
|
||
algonotes mcp
|
||
```
|
||
|
||
运行公开题库知识图谱 MCP 服务：
|
||
|
||
- [CPGraph](https://github.com/MIC728/CPGraph)
|
||
- 或直接使用 [https://mcp.cpgraph.top/mcp](https://mcp.cpgraph.top/mcp)，见其[官网文档](https://cpgraph.top/docs/)
|
||
|
||
把两个 MCP 服务添加到你的 AI 前端（如 VS Code/Claude Code/Open Code/Codex），开始你的个人笔记管理之旅。
|
||
|
||
---
|
||
|
||
## 🤖 MCP 服务封装（比赛核心交付）
|
||
|
||
项目内置标准 MCP Server，按逻辑分类暴露以下四类工具供 AI Agent 调用（每类下可注册多个具体工具，具体见 mcp 文档）：
|
||
|
||
| 架构模块 | MCP 工具分类 | 职责边界 | 前端 AI 调用时机 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| 📥 **Ingestion Pipeline** | `ingest` | 原始文本 → 存 `data/files/` → 记索引到 `data/sql_db/` → 分块/打标 → 入库 `data/chroma_db/` | 用户导入新笔记时触发 |
|
||
| 📥 **Ingestion Pipeline** | `update` | 定位旧笔记 → 覆盖文件/索引 → 删除旧向量 → 重新分块入库 | 用户修改推导过程、补充边界提示后触发 |
|
||
| 📥 **Ingestion Pipeline** | `delete` | 从三层存储中同步删除文件/索引/向量 | 用户清理过期笔记、误导入内容后触发 |
|
||
| 🧠 **RAG AGENT** | `search`/`ask`/`show`/`list`/`export` | 语义搜索 / RAG 问答 / 查看原文 / 列出笔记 / 导出笔记（不修改存储层） | 用户提问、检索、查看、导出时触发 |
|
||
|
||
CLI 的使用方法与其类似，具体见文档。
|
||
|
||
---
|
||
|
||
## 📈 性能与验证数据
|
||
|
||
全程基于 **沐曦 GPU (Gitee.AI)** 真实调用，内置自动化日志收集，使用 LangSmith 观测数据：
|
||
|
||
| 指标 | 实测值 (v1.0) | 记录方式 |
|
||
| :--- | :--- | :--- |
|
||
| 检索延迟 | 待测试 | 待记录 |
|
||
| LLM 首字延迟 | 待测试 | 待记录 |
|
||
| 吞吐量 | 待测试 | 待记录 |
|
||
| 显存占用 | 待测试 | 待记录 |
|
||
|
||
> 📄 详细性能测试报告见 [`docs/PERFORMANCE_REPORT.md`](docs/PERFORMANCE_REPORT.md)
|
||
|
||
---
|
||
|
||
## 🗺️ Roadmap：从 MVP 到个人知识引擎
|
||
|
||
本项目采用 **分阶段交付** 策略，确保核心价值先行，架构能力持续演进：
|
||
|
||
| 阶段 | 核心功能 | 状态 | 价值跃迁 |
|
||
| :---: | :--- | :---: | :--- |
|
||
| **v1.0 (MVP)** | 笔记摄取 + 知识图谱搜索 → 混合检索 → RAG 问答闭环 + CLI / MCP 封装 | ✅ 已实现 | 证明技术可行性，满足比赛可运行要求 |
|
||
| **v2.0 (Personalization)** | TUI 交互界面、遗忘曲线、知识图谱可视化 | 规划中 | 从"问答工具"升级为"个人认知操作系统" |
|
||
|
||
> 📖 完整 Roadmap 详见 [`docs/ROADMAP.md`](docs/ROADMAP.md)
|
||
|
||
---
|
||
|
||
## 📚 文档目录
|
||
|
||
| 文档 | 说明 |
|
||
| ------ | ------ |
|
||
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 架构说明与模块职责 |
|
||
| [CONFIG.md](docs/CONFIG.md) | 配置文件说明 |
|
||
| [STORE.md](docs/STORE.md) | 三层存储详解 |
|
||
| [RAG.md](docs/RAG.md) | RAG 查询管线详解 |
|
||
| [ROADMAP.md](docs/ROADMAP.md) | 项目路线图 |
|
||
| [cli/README.md](docs/cli/README.md) | CLI 命令行工具 |
|
||
|
||
---
|
||
|
||
## 🤝 参考声明与合规说明
|
||
|
||
本项目严格遵守 **CCF 开源创新大赛** 规则，在以下方面参考了开源项目：
|
||
|
||
- 📖 参考 [CPGraph](https://github.com/MIC728/CPGraph) 的 MCP 工具定义范式、工作流拆解思路与领域建模方法。
|
||
- 🔧 **场景改造**：从“公共题库管理”转向“个人笔记私有化问答”。
|
||
- 🛠️ **功能扩展**：新增竞赛语境 Prompt 约束、代码规范审查模块、复健进度追踪接口。
|
||
- ⚖️ **架构简化**：由于个人笔记的结构相对简单，用 Chroma 向量库 + SQLite 索引 + 文件系统三层轻量存储替代 Neo4j 图数据库，降低部署门槛，确保比赛环境零依赖可运行。
|
||
|
||
本项目所有核心代码（摄取/检索/生成/MCP封装）均为原创实现，仅借鉴架构思想与接口契约。
|
||
|
||
---
|
||
|
||
## 📜 License
|
||
|
||
MIT License. 欢迎 Fork、Issue、PR。
|
||
竞赛生专属优化建议请直接提交 Issue，我们将优先排期。
|
||
|
||
---
|
||
|
||
## 📺 演示视频
|
||
|
||
待录制
|