Personal Notes Assistant

个人笔记助手是一套基于 RAG（检索增强生成）与 MCP（Model Context Protocol）的本地知识管理服务。它可以摄取 PDF、Markdown 和文本资料，将内容切分、向量化并建立索引，再通过混合检索、重排和大语言模型生成带上下文的回答。

项目适合用于整理个人学习资料、工作文档、读书笔记与长期知识库。核心组件均可通过配置替换，既可以在本地运行，也可以接入 OpenAI、Azure OpenAI、Ollama 等服务。

核心能力

• 文档摄取：解析文档、切分内容、补充元数据并写入向量库。
• 混合检索：结合 Dense Embedding、BM25、RRF Fusion 与可选重排器。
• 多模态处理：通过 Vision LLM 为文档图片生成描述，让图片信息参与检索。
• MCP 工具：提供知识查询、集合列表和文档摘要接口，方便 AI 客户端调用。
• 可视化管理：使用 Streamlit 查看数据、摄取任务、查询链路和评估结果。
• 质量评估：支持 Ragas、自定义指标和 Golden Test Set 回归测试。
• 可观测性：记录摄取与查询过程中的阶段状态、耗时和错误信息。

项目结构

personal-notes-assistant/
├── config/              # 服务、模型与提示词配置
├── data/                # 本地索引、数据库和文档数据
├── logs/                # 运行与评估日志
├── scripts/             # 摄取、查询、评估和仪表盘脚本
├── src/
│   ├── core/            # 查询、响应、配置与链路追踪
│   ├── ingestion/       # 文档摄取流水线
│   ├── libs/            # 模型、检索、存储等可插拔实现
│   ├── mcp_server/      # MCP 服务与工具
│   └── observability/   # 仪表盘和评估模块
├── tests/               # 单元、集成和端到端测试
├── main.py              # MCP 服务入口
└── pyproject.toml       # Python 项目配置

环境要求

• Python 3.10 或更高版本
• 至少一种可用的 LLM 与 Embedding 服务
• Windows、macOS 或 Linux

安装

python -m venv .venv

Windows：

.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

macOS / Linux：

source .venv/bin/activate
pip install -e ".[dev]"

根据实际使用的模型服务，在 config/settings.yaml 中选择提供商，并通过环境变量配置对应凭据。不要把真实密钥写入仓库。

使用方法

摄取文档：

python scripts/ingest.py <文档路径>

查询个人知识库：

python scripts/query.py "你的问题"

启动 MCP 服务：

python main.py

启动管理仪表盘：

python scripts/start_dashboard.py

运行测试：

pytest

运行不依赖真实模型服务的快速测试：

pytest tests/unit -m "not llm"

MCP 工具

工具	用途
query_knowledge_hub	检索个人知识库并生成回答
list_collections	查看已有知识集合
get_document_summary	获取指定文档摘要

配置说明

主要配置文件为 config/settings.yaml，包括：

• LLM、Vision LLM 与 Embedding 提供商
• 文档切分和元数据增强策略
• Dense、BM25、RRF 与重排参数
• Chroma 等存储后端
• 日志、链路追踪和评估选项

修改配置后建议先摄取少量文档，再通过命令行查询和仪表盘检查结果。

安全与数据说明

• data/ 与 logs/ 可能包含个人文档、索引和查询记录，请按需要加入备份或清理策略。
• 使用云端模型时，文档片段可能发送给相应服务商；敏感资料建议使用本地模型。
• 示例凭据文件仅用于说明字段，真实密钥应保存在环境变量或密钥管理工具中。

许可证

本项目采用 MIT License。