# 个人笔记助手

个人笔记助手是一套基于 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 回归测试。
- 可观测性：记录摄取与查询过程中的阶段状态、耗时和错误信息。

## 项目结构

```text
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

## 安装

```bash
python -m venv .venv
```

Windows：

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

macOS / Linux：

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

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

## 使用方法

摄取文档：

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

查询个人知识库：

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

启动 MCP 服务：

```bash
python main.py
```

启动管理仪表盘：

```bash
python scripts/start_dashboard.py
```

运行测试：

```bash
pytest
```

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

```bash
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。