# personal-ai-knowledge

**Repository Path**: sunyu-gitee/personal-ai-knowledge

## Basic Information

- **Project Name**: personal-ai-knowledge
- **Description**: 本地部署的私人 AI 知识库：MinerU 解析   混合检索   流式问答
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拾见

本地部署的私人 AI 知识库系统：上传文档 → MinerU 解析 → 切片向量化 → 混合检索 → 带引用溯源的流式问答。

## 能力现状

| 模块         | 能力                                                                 |
| ------------ | -------------------------------------------------------------------- |
| 认证与权限   | JWT（Access + Refresh 轮换）；权限树（目录 / 菜单 / 按钮，含 `setting:write`）；角色-知识库三项能力位（查看 / 编辑 / 删除） |
| 动态菜单与路由 | 侧边栏与前端路由表都由后端下发（登录即返回），目录 / 菜单 / 按钮三级；菜单节点带 `path` 与 `component`，前端 `addRoute` 动态注册；角色勾选菜单树授权，勾按钮自动带父菜单；未授权地址落到 404；内置菜单不可删不可隐藏 |
| 知识库       | 创建、编辑、删除；按角色授权访问；管理员可见全部，未授权完全不可见   |
| 文档管理     | 上传（pdf/doc/docx/ppt/pptx/png/jpg/html/md/txt）、批量删除、批量重新解析、批量重建索引、状态轮询；向量删不掉则不删文档；管理员可清扫残留向量 |
| 文档解析     | MinerU 云 API / 本地服务双模式；md/txt/html 本地直通；Markdown 标题层级切片；启动时把中断文档标为失败 |
| 检索         | Query Rewrite（追问改写）→ 向量通道 + 关键词子串扫描 → RRF 融合 → Reranker 重排（全量候选） |
| 问答         | SSE 流式输出、思考过程实时显示、Markdown 渲染（标题/列表/表格/代码块）、打字机光标、引用卡片（文件名 / 页码 / 章节 / 相关性分数）；改写只影响检索 |
| 引用跳转     | 点引用打开原文抽屉，自动定位到对应段落并高亮                        |
| 会话         | 历史会话列表按时间分组（置顶/今天/昨天/7天内/30天内/更早）、置顶/取消置顶、消息持久化、单条与批量删除 |
| 用户与角色   | 用户 CRUD / 角色分配 / 重置密码；角色 CRUD / 菜单树勾选授权（页面权限 + 按钮权限）。只有 `admin` 内置：运行时旁路、不可改删、不走菜单/知识库授权表；其余角色自由配置，被占用的角色禁止删除 |
| 审计日志     | 登录成功/失败、授权变更、删除等敏感操作落库；系统管理下「审计日志」页查询（`audit:read`）；不含密码与 Token |
| 用量统计     | LLM / Embedding / Rerank 调用次数与 Token 落库；系统管理「用量统计」页汇总/明细；工作台底部近 7/30 天趋势图（同需 `usage:read`）；不计费单价 |
| 健康检查     | `GET /api/health` 探测 PostgreSQL / Qdrant（公开，运维探活）；异常返回 503 + JSON；完整连通性见系统设置（工作台不重复展示） |
| 系统设置     | 可视化配置：分组编辑热更新、业务密钥密文落库（不认 `.env`）、连通性探测、限流（登录失败 / 问答频率 / 超管旁路）；`setting:read` / `setting:write` |
| 限流         | 登录失败按 IP+用户名窗口计数；问答按用户每分钟次数（可关）；超管旁路可选；设置页热更新 |
| 前端界面     | 设计系统（tokens.css）、可折叠侧边栏与页签、工作台（顶栏摘要 + 分段入口 + 文档处理面板 + 底部用量趋势）、问答会话列表、系统设置（连通性 + 行内编辑）；Element Plus 按需 |

权限分两层。第一层是**菜单树**：目录 / 菜单（页面权限）/ 按钮（增删改查等权限点），
角色被授予哪些节点就拥有哪些权限码，勾了菜单才能进页面、勾了按钮才能做操作。
菜单节点同时是路由来源：`path` + `component` 决定页面地址与组件，登录时随 `routes` 一起下发，
前端按需注册，所以「加个菜单就等于加个页面」，不用改前端路由文件。
第二层是**角色-知识库授权**：决定「能对哪个库做」。

知识库权限**授予角色**，用户通过角色继承（多角色取并集），不提供按用户直接授权的入口。
管理员与知识库创建者绕过授权校验；其他用户只有在所属角色被授予 `can_read` 后才能看到该库，
被授予 `can_write` 才能上传与重建索引，被授予 `can_delete` 才能删除文档与知识库本身。
授权有两个入口：知识库页的「角色授权」和角色页的「知识库」。

## 技术栈

- 前端：Vue 3 + TypeScript + Element Plus（按需）+ Pinia + Vue Router + Vite 5 + markdown-it（npm）
- 后端：FastAPI + SQLAlchemy 2.0 + Alembic + Pydantic v2（uv，Python 3.13）
- 存储：PostgreSQL 16（含 pg_trgm）、Qdrant（COSINE，1024 维）
- 模型：OpenAI 兼容协议调用云端 LLM / Embedding / Reranker
- 解析：MinerU 云 API v4 或本地 `opendatalab/magicdoc` 服务

## 目录结构

```
personal-ai-knowledge/
├── frontend/        # Vue 3 前端（Element Plus 按需；模块组件在 views/*/components）
├── backend/         # FastAPI（api → services → repositories；migrations / tests）
├── mineru/          # MinerU 本地服务 Dockerfile
├── storage/         # originals / parsed / exports
├── docker/          # docker-compose.yml
├── docs/            # 文档索引
├── AGENTS.md        # AI / 新人工程约定（改代码前先读）
├── 编码规范.md      # 分层、命名、健壮性与前后端风格
├── 项目设计.md      # 完整设计文档（唯一权威）
├── 项目评估报告.md
├── .env.example     # 环境变量模板（不含真实密钥）
└── README.md
```

> 设计以 `项目设计.md` 为准；动手前读 `AGENTS.md`；写代码风格读 `编码规范.md`。

## 快速开始

### 1. 启动依赖服务
```bash
# 启动 PostgreSQL 与 Qdrant（MinerU 本地模式可选）
docker compose -f docker/docker-compose.yml up -d postgres qdrant
```

### 2. 配置环境变量
复制根目录下的 `.env.example` 为 `.env`，并填写必要配置：
- `POSTGRES_DSN`: 数据库连接串
- `LLM_API_KEY` / `EMBEDDING_API_KEY`: 模型 API Key
- `MINERU_TOKEN`: 如果使用云端解析模式

### 3. 数据库初始化 (二选一)

**方式 A：使用 Alembic 自动迁移 (推荐)**
```bash
cd backend
uv sync
uv run alembic upgrade head
```
后端启动时会自动写入种子数据（管理员账号、菜单树、默认角色）。

**方式 B：执行 SQL 脚本快速初始化**
如果你想直接通过 SQL 初始化（包含结构与初始数据）：
1. 手动创建数据库：`CREATE DATABASE kb;`
2. 在该库中执行 [init.sql](file:///d:/Personal%20AI%20Knowledge%20Base/backend/scripts/init.sql) 脚本。
   *该脚本已包含所有表结构、索引、初始数据以及 Alembic 版本同步。*

### 4. 启动应用
**后端**
```bash
cd backend
uv run uvicorn app.main:app --reload --port 8000
```
**前端**
```bash
cd frontend
npm install
npm run dev
```

### 5. 访问与登录
- **Web UI**: `http://localhost:5173`
- **初始管理员**: 由仓库根 `.env` 的 `INIT_ADMIN_USERNAME` / `INIT_ADMIN_PASSWORD` 决定（模板见 `.env.example`）。
- **注意**: 首次登录后请务必立即修改密码。

> PyCharm 用户：可直接右键运行 `backend/app/main.py`（已内置启动入口，关闭 reload 便于断点调试）；更推荐新建 Run Configuration 执行 `uv run uvicorn app.main:app --reload`。

### 包管理器

前端固定使用 **npm**：仓库提交 `package-lock.json`，`package.json` 已声明 `packageManager`。不要混用 pnpm / yarn，避免多套锁文件与 node_modules 结构冲突。

后端固定使用 **uv**：`pyproject.toml` + `uv.lock` + `.python-version`（3.13）。

## 环境变量要点

| 变量                        | 说明                                                       |
| --------------------------- | ---------------------------------------------------------- |
| `POSTGRES_DSN`              | PostgreSQL 连接串（`postgresql+psycopg://...`）             |
| `QDRANT_URL`                | 向量库地址（集合名固定为 `kb_chunks`）                      |
| `LLM_*`                     | 问答模型，OpenAI 兼容接口                                  |
| `EMBEDDING_*`               | 向量模型；`EMBEDDING_DIM=0` 自动探测真实维度                |
| `RERANKER_*`                | 重排模型；`RERANKER_BLEND_WEIGHT` 控制重排分与召回分的融合 |
| `RETRIEVAL_*`               | 混合检索：候选数、RRF 常数、关键词权重、抽词上限            |
| `QUERY_REWRITE_*`           | 检索前追问改写：开关与历史条数                              |
| `MINERU_MODE`               | `cloud` 走 mineru.net，`local` 走本地服务                   |
| `HTTP_TRUST_ENV`            | 是否读取系统代理；本地代理会中断 TLS 握手时置 `false`       |
| `DOCUMENT_WORKERS`          | 解析线程池并发数，默认 3                                    |

完整清单见 `.env.example`。

## 测试

```bash
cd backend
uv run pytest -q          # 142 passed
cd ../frontend
npx vue-tsc --noEmit && npm run build
```

## 待开发

- 运维深化（备份恢复、多 worker 配置广播）
- Agent 智能助手（LangGraph）
- 外部任务队列（当前用进程内线程池）；按 Token 日限额

## 文档

- `AGENTS.md` —— 工程约定：技术栈、目录地图、硬约束、已知坑、改动清单。**用 AI 改代码前先读**
- `项目设计.md` —— 架构、数据模型、接口、检索链路、模块状态（唯一权威）
- `编码规范.md` —— 分层职责、命名、错误处理、内聚耦合、前后端风格
- `docs/README.md` —— 文档索引与维护原则；行为变化后必须同步上述文档