# multi-model-notes-agent-professional

**Repository Path**: fy_group/multi-model-notes-agent-professional

## Basic Information

- **Project Name**: multi-model-notes-agent-professional
- **Description**: > 一个**零外部服务**、开箱即用的全栈 AI 笔记 + 私有知识库 + RAG 智能问答工作台。
> 适用于毕设答辩、商业化作品集展示、小型团队私有化部署与教学演示。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多模型智能协作笔记系统 · Professional Edition

> 一个**零外部服务**、开箱即用的全栈 AI 笔记 + 私有知识库 + RAG 智能问答工作台。
> 适用于毕设答辩、商业化作品集展示、小型团队私有化部署与教学演示。
>
> **当前版本**：v2.2.0  ·  **作者**：D.C.Y.  ·  **联系邮箱**：dcyyd_kcug@yeah.net

[![Python](https://img.shields.io/badge/Python-3.12-3776AB?logo=python&logoColor=white)](#-技术栈)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.116-009688?logo=fastapi&logoColor=white)](#-技术栈)
[![Vue](https://img.shields.io/badge/Vue-3.5-4FC08D?logo=vue.js&logoColor=white)](#-技术栈)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6?logo=typescript&logoColor=white)](#-技术栈)
[![Vite](https://img.shields.io/badge/Vite-6-646CFF?logo=vite&logoColor=white)](#-技术栈)
[![License](https://img.shields.io/badge/License-见仓库_LICENSE-555)](#-许可证)
[![Stars](https://img.shields.io/badge/PRs-welcome-brightgreen)](#-贡献)

---

## 📑 目录

- [✨ 核心能力](#-核心能力)
- [🏛️ 技术栈](#-技术栈)
- [🗂️ 目录结构](#-目录结构)
- [🚀 快速开始](#-快速开始)
- [🔑 默认管理员](#-默认管理员)
- [💾 数据保存位置](#-数据保存位置)
- [⚙️ 管理后台](#-管理后台)
- [🧠 AI 模型配置](#-ai-模型配置)
- [🔬 RAG 算法说明](#-rag-算法说明)
- [❓ 常见问题](#-常见问题)
- [🧪 自检](#-自检)
- [📚 项目文档](#-项目文档)
- [🤝 贡献](#-贡献)
- [📄 许可证](#-许可证)

---

## ✨ 核心能力

### 🧩 用户与权限
- JWT 用户注册 / 登录
- RBAC 权限分离：**管理员** / **普通用户**
- 专业化**管理后台**：系统概览、用户管理、系统配置、审计日志

### 🛠️ 配置与配额
- 后台**配置中心**：项目名称、版本、描述、AI 模型参数、RAG 参数、用户默认配额
- **智能用户空间分配**：存储空间、笔记数、文档数、每日 AI 请求数

### 📝 富文本笔记
- 基于 Tiptap 的现代化编辑器
- 任务列表、表格、代码块、引用、对齐、链接、文本高亮
- **自动保存** + 后台异步向量化

### 🤖 AI 能力
- 笔记 AI：**润色 / 续写 / 总结 / 翻译**，全场景 SSE 流式输出
- 知识库 AI：**RAG 智能问答**，SSE 打字机效果
- **双模型自动调度**：通义千问 ⇄ DeepSeek

### 📚 私有知识库
- 多格式上传：**PDF / Word / Markdown / TXT**
- 解析 → 切片 → 嵌入式 Chroma → 异步索引
- 按 `user_id` **强隔离**的向量空间

### 🧠 RAG 优化
- 结构化切片：标题识别 + 段落切分 + 句子切分 + overlap
- 词法 / 向量**混合重排**
- Prompt 严格约束：**只基于私有知识回答**

### 🎨 现代化 UI/UX
- **Naive UI + Tailwind CSS** 设计语言
- 亮 / 暗主题 + 跟随系统
- 中英文国际化（`vue-i18n`）
- 响应式三栏布局 + 拖拽式 Resizer

---

## 🏛️ 技术栈

### 后端
| 模块 | 选型 |
| --- | --- |
| Web 框架 | **FastAPI**（异步） |
| 服务器 | **Uvicorn** (`uvicorn[standard]`) |
| 数据校验 | **Pydantic v2 / pydantic-settings** |
| 数据库 | **SQLite 3** + `aiosqlite`（异步） |
| 鉴权 | `python-jose[cryptography]` JWT + **PBKDF2-SHA256** |
| LLM 编排 | **LangChain / LangChain Core** |
| 向量库 | **Chroma**（嵌入式持久化） |
| Embedding | **LocalHash / N-gram**（本地、零云端依赖） |
| 模型客户端 | OpenAI 兼容协议（`httpx` 流式） |
| 后台任务 | FastAPI `BackgroundTasks` |
| 文档解析 | `pypdf` / `python-docx` |

### 前端
| 模块 | 选型 |
| --- | --- |
| 框架 | **Vue 3**（Composition API + `<script setup lang="ts">`） |
| 语言 | **TypeScript 5.7** |
| 构建 | **Vite 6** |
| UI 库 | **Naive UI** + **Tailwind CSS** |
| 编辑器 | **Tiptap 2** |
| 状态管理 | **Pinia** |
| 国际化 | **vue-i18n** |
| SSE 客户端 | `fetch` + `ReadableStream`（原生） |

---

## 🗂️ 目录结构

```text
multi-model-notes-agent-professional/
├── backend/                          # FastAPI 后端
│   ├── main.py                       # 进程入口（uvicorn app.main:app）
│   ├── start-backend.py              # 一键启动脚本（py -3.12 -m venv .venv）
│   ├── tests_smoke.py                # 冒烟自检脚本
│   ├── requirements.txt
│   ├── .env.example
│   └── app/
│       ├── main.py                   # FastAPI 应用与生命周期
│       ├── deps.py                   # 鉴权依赖（get_current_user / require_admin）
│       ├── core/                     # 配置、安全、响应封装
│       ├── db/                       # SQLite 连接与 schema
│       ├── models/                   # Pydantic Schema
│       ├── ai/                       # 模型客户端、路由、Prompt
│       ├── retrieval/                # 切片、本地 Embedding、Chroma
│       ├── services/                 # 业务服务层
│       ├── routers/                  # 路由层
│       └── utils/                    # 工具（缓存、SSE、文件解析、文本）
├── frontend/                         # Vue 3 前端
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── tailwind.config.js
│   ├── start-frontend.py             # 一键启动脚本（pnpm i / pnpm dev）
│   └── src/
│       ├── main.ts
│       ├── App.vue
│       ├── style.css                 # 全局样式与设计 token
│       ├── api/                      # HTTP 客户端、SSE 客户端、类型
│       ├── components/               # 业务组件
│       ├── composables/              # 通用组合式函数
│       ├── i18n/                     # 国际化
│       ├── stores/                   # Pinia 状态
│       └── utils/                    # 通用工具
├── docs/                             # 项目文档（架构、API、部署、FAQ、变更记录）
├── test/                             # 演示数据（笔记 + 知识库 + 测试题）
├── .gitignore
└── README.md
```

---

## 🚀 快速开始

> **三步即可启动整套系统**：克隆 → 后端 → 前端

### 1. 克隆仓库

```bash
git clone <your-repo-url>
cd multi-model-notes-agent-professional
```

### 2. 启动后端（Python 3.12 · venv · pip）

> 项目已提供 `backend/start-backend.py` 一键脚本，会自动完成：
> `py -3.12 -m venv .venv` → 安装依赖 → 复制 `.env` → 启动 `python main.py`。

#### 🪟 Windows

```powershell
cd backend
py -3.12 -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
python main.py

# 也可一键：
python start-backend.py
```

#### 🍎 macOS / 🐧 Linux

```bash
cd backend
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python main.py

# 也可一键：
python3 start-backend.py
```

后端启动成功后会看到：

```text
INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.
```

- 后端服务：<http://localhost:8000>
- Swagger UI：<http://localhost:8000/docs>
- ReDoc：<http://localhost:8000/redoc>

### 3. 启动前端（Node ≥ 18 · pnpm）

> 强烈推荐使用 **pnpm**（仓库已提供 `pnpm-lock.yaml`），安装速度更快、磁盘占用更小。
> 项目提供 `frontend/start-frontend.py` 一键脚本。

```powershell
# 安装 pnpm（如未安装）
npm install -g pnpm

# 启动前端
cd frontend
pnpm install
pnpm dev
```

> Windows 用户也可执行 `python start-frontend.py` 一键完成「检测 pnpm → pnpm i → pnpm dev」。

前端启动成功后：

```text
  VITE v6.x.x  ready in xxx ms
  ➜  Local:   http://localhost:5173/
  ➜  Network: http://<your-ip>:5173/
```

打开浏览器访问 <http://localhost:5173> 即可。

### 📦 生产构建

```bash
# 后端：直接用 uvicorn / gunicorn 启动
cd backend
.venv\Scripts\activate            # macOS / Linux: source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 2

# 前端：构建静态资源后由 Nginx 托管
cd frontend
pnpm install
pnpm build                       # 输出到 frontend/dist/
pnpm preview                     # 本地预览生产产物
```

详细的生产部署方案参见 [`docs/DEPLOY.md`](docs/DEPLOY.md)。

---

## 🔑 默认管理员

首次启动时，系统会自动创建管理员账号：

```text
用户名：admin
密码：Admin@123456
邮箱：dcyyd_kcug@yeah.net
```

可在 `backend/.env` 中修改：

```env
ADMIN_USERNAME=admin
ADMIN_EMAIL=dcyyd_kcug@yeah.net
ADMIN_PASSWORD=Admin@123456
```

> ⚠️ 上线或答辩演示前，**必须**登录后通过管理后台修改默认密码。

---

## 💾 数据保存位置

所有数据全部本地持久化，**无需**安装 MySQL、PostgreSQL、Redis、Qdrant、Docker：

```text
backend/data/
├── app.db              # SQLite 数据库（用户、笔记、文档、配置、审计日志）
├── chroma/             # Chroma 本地向量库（嵌入式 HNSW + sqlite）
└── uploads/            # 用户上传文件
    └── user_<id>/
        ├── <uuid>.pdf
        ├── <uuid>.docx
        └── ...
```

> 备份只需打包 `backend/data/` 整个目录，恢复后无需任何数据库迁移。

---

## ⚙️ 管理后台

管理员登录后，顶部会出现 **「管理后台」** 入口。包含四大模块：

| 模块 | 功能 |
| --- | --- |
| **系统概览** | 用户数、笔记数、文档数、存储占用、向量切片总数、今日 AI 请求数 |
| **用户管理** | 角色、状态、空间配额、笔记配额、文档配额、每日 AI 配额、重置密码、删除用户 |
| **系统配置** | 项目元信息、AI 模型参数（千问 / DeepSeek）、RAG Top-K、切片大小、默认配额 |
| **审计日志** | 管理员修改配置、更新用户、重置密码、删除用户等操作记录 |

> 管理后台**不会**直接改写磁盘 `.env`，而是将运行时配置写入 SQLite 的 `system_configs` 表，启动时把 `.env` 作为初始默认值导入。

---

## 🧠 AI 模型配置

> 不配置 Key 也可体验完整链路与 SSE 打字机效果——系统会走「本地降级流式输出」。

如需真实模型输出，可通过任一方式配置：

### 方式一：环境变量（`backend/.env`）

```env
QWEN_API_KEY=你的通义千问Key
DEEPSEEK_API_KEY=你的DeepSeekKey
```

### 方式二：管理后台 → 系统配置

可在 UI 上修改以下键值（修改后立即生效）：

- `qwen_api_key` / `qwen_base_url` / `qwen_chat_model`
- `deepseek_api_key` / `deepseek_base_url` / `deepseek_chat_model`

### 双模型自动调度

`app/ai/model_router.py` 根据以下规则自动选择模型：

| 条件 | 偏好模型 |
| --- | --- |
| 文本长度 > 600 字 / 命中「推理 / 证明 / 代码 / 架构 / 算法 / 检索 / 调试」等关键词 | **DeepSeek** |
| 其他常规文本 | **通义千问** |
| 手动指定 `model=qwen` / `model=deepseek` | 用户选择优先 |

---

## 🔬 RAG 算法说明

系统实现纯本地 RAG 流水线：

```text
文档 / 笔记
  ↓
解析文本（pypdf / python-docx / 原生读取）
  ↓
结构化切片：标题识别 + 段落切分 + 句子切分 + overlap
  ↓
本地 Hash / N-gram Embedding（384 维）
  ↓
Chroma 持久化存储，metadata 写入 user_id
  ↓
提问时按 user_id 强过滤
  ↓
向量召回 Top-K × 4 候选
  ↓
词法 overlap 混合重排（向量 0.72 + 词法 0.28）
  ↓
Prompt 限制：只基于私有知识回答
  ↓
DeepSeek / Qwen SSE 流式回答
```

详细参数与调优指南参见 [`docs/RAG 问答怎么使用.md`](docs/RAG%20%E9%97%AE%E7%AD%94%E6%80%8E%E4%B9%88%E4%BD%BF%E7%94%A8.md)。

---

## ❓ 常见问题

### Q：需要安装 MySQL、Redis、Docker 吗？

**不需要**。项目采用「零外部服务」原则：SQLite + 嵌入式 Chroma + 内存缓存 + 本地文件系统。

### Q：必须用 Python 3.12 吗？

不是，但**推荐**。项目使用 `py -3.12 -m venv .venv` 创建虚拟环境（确保团队 / 部署环境一致）。3.10 / 3.11 / 3.12 均可运行；3.9 及以下不支持。

### Q：必须用 pnpm 吗？

不是。`npm install` / `pnpm install` / `yarn` 均可，仓库同时提供 `package-lock.json` 与 `pnpm-lock.yaml`。**推荐 pnpm**，更快速且磁盘占用更少。

### Q：为什么没配置 API Key 也能回答？

为了便于离线演示，未配置 `QWEN_API_KEY` / `DEEPSEEK_API_KEY` 时，系统会走**本地降级流式输出**（仍保留 SSE 打字机效果与「基于私有知识」Prompt 约束）。配置 Key 后自动切换为真实模型流式回答。

### Q：管理后台会修改 `.env` 吗？

**不会**。管理后台将运行时配置写入 SQLite 的 `system_configs` 表，启动时把 `.env` 作为初始默认值导入配置中心；用户可在线编辑、隐藏、标记为公开 / 私有。

更多问题与排查指南参见 [`docs/FAQ.md`](docs/FAQ.md)。

---

## 🧪 自检

### 后端语法与冒烟测试

```powershell
cd backend
py -3.12 -m compileall -q .
python tests_smoke.py
```

### 前端类型与构建检查

```powershell
cd frontend
pnpm install
pnpm build
```

`pnpm build` 包含两步：① `vue-tsc -b` 严格类型检查；② `vite build` 生产构建。

### 接口健康检查

```powershell
curl http://localhost:8000/api/health
# 期望: {"success":true,"message":"ok","data":{"status":"running",...}}
```

---

## 📚 项目文档

| 文档 | 内容 |
| --- | --- |
| 📘 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 基于 C4 模型的系统架构（系统上下文、容器、组件、数据流、安全） |
| 📗 [docs/API.md](docs/API.md) | 完整接口文档（路径、方法、参数、响应、错误码、curl 示例） |
| 📙 [docs/RAG 问答怎么使用.md](docs/RAG%20%E9%97%AE%E7%AD%94%E6%80%8E%E4%B9%88%E4%BD%BF%E7%94%A8.md) | RAG 智能问答使用教程（算法、参数、SSE、提问模板、故障排查） |
| 📕 [docs/DEPLOY.md](docs/DEPLOY.md) | 部署与环境配置（systemd + Nginx + HTTPS + 备份） |
| 📓 [docs/FAQ.md](docs/FAQ.md) | 8 大类共 49 个常见问题 |
| 🛠️ [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | 贡献指南（分支、Commit、PR、编码规范） |
| 🗒️ [docs/CHANGELOG.md](docs/CHANGELOG.md) | 版本变更记录（遵循 Keep a Changelog） |
| 🧭 [docs/docweaver-manifest.json](docs/docweaver-manifest.json) | 文档站点元信息（DocWeaver） |

---

## 🤝 贡献

欢迎 Issue 与 PR！请先阅读 [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) 了解：

- 分支策略（`main` / `develop` / `feature/*` / `fix/*`）
- Commit 规范（[Conventional Commits](https://www.conventionalcommits.org/)）
- PR 流程、代码规范、自检清单
- 安全披露渠道

---

## 📄 许可证

本项目遵循仓库根目录 `LICENSE` 文件所声明的许可证。提交代码即视为同意按该许可证授权。