# personal_knowledge_base_server

**Repository Path**: qfxtime/personal_knowledge_base_server

## Basic Information

- **Project Name**: personal_knowledge_base_server
- **Description**: 企业级知识库出尝试，只实现必要功能，用来学习和实践
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-21
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Personal Knowledge Base Server

> 企业级 RAG 个人知识库问答服务，基于 FastAPI + LangChain + LangGraph + 向量库构建。

---

## 📌 项目介绍

本项目实现了一个完整的 **检索增强生成（Retrieval-Augmented Generation, RAG）** 知识库服务，支持：

- 📄 **多格式文档上传与解析** — PDF / Word / Markdown / TXT
- 🔪 **智能文本分片** — 递归字符分割 / 语义分割
- 🧠 **向量索引与检索** — 支持 Chroma / PGVector 等多种向量库
- 💬 **基础 RAG 问答** — 检索 + Prompt 组装 + LLM 生成
- 🤖 **LangGraph Agent 智能问答** — 查询改写 → 检索 → 生成的有状态图编排
- 🚀 **RESTful API** — FastAPI 对外提供统一接口

---

## 🗂 目录结构

```
personal_knowledge_base_server/
├── app/                           # 业务主包
│   ├── __init__.py
│   ├── main.py                    # FastAPI 入口，uvicorn 启动
│   ├── config/                    # 配置模块
│   │   ├── settings.py            # 全局配置（pydantic-settings 读 .env）
│   │   └── constants.py           # 静态常量（后缀、大小限制、日志级别）
│   ├── api/                       # HTTP 接口层
│   │   ├── upload_api.py          # 文档上传
│   │   ├── knowledge_api.py       # 知识库管理（列表/删除）
│   │   └── chat_api.py            # RAG 问答 / Agent 问答
│   ├── document_loader/           # 文档解析
│   │   ├── base_loader.py         # 抽象基类 BaseLoader
│   │   ├── pdf_loader.py
│   │   ├── word_loader.py
│   │   └── markdown_loader.py
│   ├── splitter/                  # 文本分片
│   │   ├── text_splitter.py       # RecursiveCharacterTextSplitter
│   │   └── semantic_splitter.py   # 语义分割
│   ├── embeddings/                # 向量化
│   │   ├── base_embedding.py
│   │   └── embedding_factory.py   # 工厂函数，支持切换模型
│   ├── vector_store/              # 向量库交互
│   │   ├── base_store.py
│   │   └── vector_factory.py
│   ├── retrieval/                 # 检索 + 重排
│   │   ├── retriever.py
│   │   └── reranker.py
│   ├── rag/                       # RAG 核心链路
│   │   ├── prompt_template.py
│   │   └── rag_chain.py
│   ├── agent/                     # LangGraph Agent
│   │   ├── state.py               # AgentState TypedDict
│   │   ├── graph_builder.py       # StateGraph 构建
│   │   └── nodes/                 # 各节点实现
│   └── common/                    # 公共工具
│       ├── exceptions.py          # 自定义业务异常
│       └── utils.py               # md5、文件后缀、路径穿越防护
├── tests/                         # pytest 单元测试
├── static/upload/                 # 上传文件临时存储
├── data/                          # 本地缓存 / 测试向量库
├── logs/                          # 日志
├── .env                           # 环境变量（不提交 Git）
└── requirements.txt
```

---

## 🧰 环境准备

### 1. Python 版本

```
Python 3.10+
```

### 2. 创建虚拟环境（推荐）

```bash
python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置 `.env`

在项目根目录创建 `.env` 文件（**不要提交到 Git**）：

```env
# ===== LLM =====
LLM_BASE_URL=https://api.deepseek.com
LLM_API_KEY=sk-xxxxxxxxxxxxxxxx
LLM_MODEL=deepseek-chat

# ===== Embedding =====
EMBEDDING_MODEL=text-embedding-v2
EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
EMBEDDING_API_KEY=sk-xxxxxxxxxxxxxxxx

# ===== Vector Store =====
VECTOR_DB_TYPE=chroma          # chroma / pgvector
VECTOR_DB_HOST=localhost
VECTOR_DB_PORT=8000

# ===== Splitter =====
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

# ===== Retrieval =====
TOP_K=4
```

---

## 🚀 启动方式

### 开发模式（热重载）

```bash
python -m app.main
# 等价于
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 生产模式

```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
```

启动后访问：

- 接口文档（Swagger UI）：<http://localhost:8000/docs>
- 健康检查：<http://localhost:8000/>

### 运行测试

```bash
pytest -v
```

---

## 📡 API 接口说明

### 1. 文档上传

`POST /document/upload`

上传文档，自动解析 → 分片 → 向量化 → 入库。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | UploadFile | ✅ | 支持 `.pdf` `.docx` `.doc` `.md` `.txt` |

### 2. 知识库管理

**`GET /knowledge/list`**

查询已入库文档列表。

**`DELETE /knowledge/delete`**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| doc_id | str | ✅ | 要删除的文档 ID |

### 3. 问答接口

**`POST /chat/rag`** — 基础 RAG 问答

```json
{
  "query": "如何初始化 LangGraph？"
}
```

**`POST /chat/agent`** — Agent 智能问答（会先改写 query 再检索）

```json
{
  "query": "帮我总结一下今天会议讨论了什么",
  "rewrite": true
}
```

### 4. 健康检查

`GET /`

```json
{
  "status": "ok",
  "service": "personal_knowledge_base_server"
}
```

---

## 🧪 典型调用链

```
用户上传 PDF
  → upload_api (校验 + 保存)
  → PdfLoader (pypdf 解析)
  → TextSplitter (分片)
  → EmbeddingFactory (向量化)
  → VectorStoreFactory (写入 Chroma/PGVector)

用户发起问答
  → chat_api
  → [基础 RAG]  retriever → reranker → prompt → LLM
  → [Agent]     StateGraph
                    ├─ query_rewrite_node (LLM 改写)
                    ├─ retrieve_node      (向量检索)
                    └─ answer_node        (LLM 生成)
```

---

## 📄 License

MIT