# memobase

**Repository Path**: luorient/memobase

## Basic Information

- **Project Name**: memobase
- **Description**: 本系统旨在通过 RAG（检索增强生成）技术，构建个人知识库，将分散的技术文档、开发规范整合为可检索的知识资源
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-26
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 忆库 MemoBase

基于检索增强生成（RAG）技术的个人知识库系统，用于管理技术文档、开发规范，并提供智能问答功能。

## 功能特性

- 📄 **文档管理**：支持 PDF、Word、Markdown 格式文档上传和管理
- 🔍 **知识库检索**：基于向量数据库的语义检索
- 🤖 **AI 问答**：基于智谱 AI 的智能问答
- 🌐 **网页爬取**：支持从指定网站爬取内容
- 📊 **统计分析**：知识库统计和搜索历史
- 🏷️ **分类标签**：文档分类和标签管理
- 📝 **版本管理**：文档版本控制和回滚
- 📤 **结果导出**：支持 Markdown 格式导出

## 技术栈

- **后端框架**：FastAPI
- **数据库**：SQLite + SQLAlchemy
- **向量数据库**：Chroma
- **LLM**：智谱 AI（GLM-4）
- **文档解析**：PyPDF2、python-docx
- **网页爬取**：BeautifulSoup + Readability
- **嵌入模型**：sentence-transformers（中文模型）

## 项目结构

```
memobase/
├── app/
│   ├── api/              # API 路由
│   │   ├── documents.py  # 文档管理 API
│   │   ├── search.py     # 知识库检索 API
│   │   ├── categories.py # 分类和标签管理 API
│   │   ├── crawl.py      # 网页爬取 API
│   │   └── statistics.py # 统计和配置 API
│   ├── core/             # 核心模块
│   │   ├── config.py     # 配置管理
│   │   └── database.py   # 数据库连接
│   ├── models/           # 数据库模型
│   │   └── database.py   # SQLAlchemy 模型
│   ├── schemas/          # Pydantic schemas
│   │   └── schemas.py    # 请求和响应模型
│   ├── services/         # 业务服务
│   │   ├── document_parser.py  # 文档解析服务
│   │   ├── vector_service.py   # 向量化服务
│   │   └── llm_service.py      # LLM 服务
│   └── utils/            # 工具函数
│       └── init_db.py    # 数据库初始化
├── data/                 # 数据目录
│   ├── uploads/          # 上传文件
│   ├── chroma/           # 向量数据库
│   ├── modelscope_cache/ # 模型缓存
│   └── rag_system.db     # SQLite 数据库
├── docs/                 # 文档目录
│   ├── CHINA_NETWORK_SOLUTION.md
│   ├── DOWNLOAD_GUIDE.md
│   └── MODEL_DOWNLOAD_GUIDE.md
├── logs/                 # 日志目录
├── scripts/              # 工具脚本
│   ├── check_*.py        # 检查脚本
│   ├── reindex_*.py      # 重新索引脚本
│   ├── reset_*.py        # 重置脚本
│   ├── download_model_modelscope.py
│   └── init_project.py
├── memobase-front/       # 前端项目
│   ├── public/           # 静态资源
│   ├── src/              # 源代码
│   │   ├── assets/       # 资源文件
│   │   ├── components/   # 组件
│   │   ├── pages/        # 页面
│   │   ├── services/     # API 服务
│   │   ├── styles/       # 样式
│   │   └── utils/        # 工具函数
│   └── package.json
├── main.py               # 应用入口
├── start.py              # 启动脚本
├── start.bat             # Windows 启动脚本
├── requirements.txt      # 依赖列表
├── .env                  # 环境变量
└── .env.example          # 环境变量示例
```

## 快速开始

### 1. 环境要求

- Python 3.9+
- Node.js 16+ (前端)
- npm 或 yarn (前端)
- pip

### 2. 安装后端依赖

```bash
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 3. 安装前端依赖

```bash
cd memobase-front
npm install
```

### 4. 配置环境变量

复制 `.env.example` 为 `.env` 并修改配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置智谱 AI API Key：

```env
ZHIPUAI_API_KEY=your_api_key_here
ZHIPUAI_MODEL=glm-4.5-air
```

### 5. 下载模型（可选）

如果需要使用向量检索功能，需要下载嵌入模型。推荐使用 ModelScope：

```bash
pip install modelscope
python scripts/download_model_modelscope.py
```

或者禁用向量服务（仅使用关键词检索）：

在 `.env` 文件中设置：
```env
ENABLE_VECTOR_SERVICE=False
```

### 6. 启动应用

**方式一：使用启动脚本（推荐）**

Windows:
```bash
start.bat
```

Linux/Mac:
```bash
python start.py
```

**方式二：分别启动后端和前端**

启动后端：
```bash
python main.py
```

启动前端（新开一个终端）：
```bash
cd memobase-front
npm run dev
```

### 7. 访问应用

- 前端界面：`http://localhost:5173`
- 后端 API：`http://localhost:8000`
- API 文档：`http://localhost:8000/docs`

## API 接口

### 文档管理

- `POST /api/documents/upload` - 上传文档
- `GET /api/documents` - 查询文档列表
- `GET /api/documents/{document_id}` - 查询文档详情
- `PUT /api/documents/{document_id}` - 编辑文档
- `DELETE /api/documents/{document_id}` - 删除文档
- `GET /api/documents/{document_id}/versions` - 查询文档版本
- `POST /api/documents/{document_id}/versions/{version_id}/rollback` - 回滚文档版本

### 知识库检索

- `POST /api/search` - 知识库检索
- `POST /api/qa` - AI 问答

### 分类和标签管理

- `GET /api/categories` - 查询分类列表
- `POST /api/categories` - 创建分类
- `PUT /api/categories/{category_id}` - 编辑分类
- `DELETE /api/categories/{category_id}` - 删除分类
- `GET /api/tags` - 查询标签列表
- `POST /api/tags` - 创建标签
- `DELETE /api/tags/{tag_id}` - 删除标签

### 网页爬取

- `POST /api/crawl` - 网页爬取

### 统计和配置

- `GET /api/statistics` - 查询知识库统计
- `GET /api/search-history` - 查询搜索历史
- `DELETE /api/search-history` - 清空搜索历史
- `GET /api/configurations` - 查询配置
- `PUT /api/configurations` - 更新配置
- `POST /api/export` - 结果导出

## 工具脚本

项目提供了一些实用工具脚本，位于 `scripts/` 目录：

### 检查脚本

- `check_doc_11.py` - 检查特定文档的数据
- `check_document_content.py` - 检查文档内容
- `check_documents.py` - 检查所有文档
- `check_vector_data.py` - 检查向量数据
- `check_vector_db_all.py` - 检查向量数据库

### 重新索引脚本

- `reindex_doc_11.py` - 重新索引特定文档
- `reindex_documents.py` - 重新索引所有文档

### 重置脚本

- `reset_and_reindex.py` - 重置并重新索引所有数据
- `reset_database.py` - 重置数据库

### 其他工具

- `download_model_modelscope.py` - 从 ModelScope 下载模型
- `init_project.py` - 初始化项目

使用方法：
```bash
python scripts/<脚本名>.py
```

## 开发指南

### 运行测试

```bash
pytest tests/
```

### 代码规范

- 遵循 PEP 8 代码规范
- 使用类型注解
- 添加函数和类注释
- 使用 loguru 记录日志

### 数据库迁移

如需修改数据库结构，请更新 `app/models/database.py` 中的模型定义，然后运行：

```bash
python scripts/reset_database.py
```

**注意**：这将清空所有数据，请谨慎操作！

### 前端开发

前端使用 React + TypeScript + Vite 开发：

```bash
cd memobase-front

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview
```

### 日志查看

应用运行时，日志会输出到：
- 控制台（实时查看）
- `logs/app.log` 文件（持久化存储）

日志按天轮转，默认保留30天。

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `DATABASE_URL` | 数据库连接 URL | `sqlite+aiosqlite:///./data/rag_system.db` |
| `VECTOR_DB_PATH` | 向量数据库路径 | `./data/chroma` |
| `ZHIPUAI_API_KEY` | 智谱 AI API Key | - |
| `ZHIPUAI_MODEL` | LLM 模型名称 | `glm-4` |
| `UPLOAD_DIR` | 文件上传目录 | `./data/uploads` |
| `MAX_FILE_SIZE` | 最大文件大小（字节） | `52428800` (50MB) |
| `CRAWL_WHITELIST` | 爬取白名单（逗号分隔） | `docs.python.org,developer.mozilla.org` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
| `LOG_DIR` | 日志目录 | `./logs` |
| `API_HOST` | API 主机地址 | `0.0.0.0` |
| `API_PORT` | API 端口 | `8000` |
| `ENABLE_VECTOR_SERVICE` | 是否启用向量服务 | `True` |
| `EMBEDDING_MODEL_NAME` | 嵌入模型名称 | `shibing624/text2vec-base-chinese` |
| `CHUNK_SIZE` | 文档分块大小（字符） | `1000` |
| `TOP_K` | 检索返回结果数量 | `5` |
| `SIMILARITY_THRESHOLD` | 相似度阈值 | `0.5` |

### 前端配置

前端配置文件位于 `memobase-front/src/config/constants.ts`，可以修改以下配置：

```typescript
export const API_BASE_URL = 'http://localhost:8000'
export const APP_NAME = '忆库 MemoBase'
export const APP_VERSION = '1.0.0'
```

## 相关文档

更多详细文档请参考：

- [网络解决方案](docs/CHINA_NETWORK_SOLUTION.md) - 中国大陆网络环境配置
- [下载指南](docs/DOWNLOAD_GUIDE.md) - 模型和依赖下载指南
- [模型下载指南](docs/MODEL_DOWNLOAD_GUIDE.md) - 嵌入模型下载详细说明

## 常见问题

### 1. 向量化失败

**问题**：上传文档后向量化失败

**解决方案**：
- 检查是否正确安装了 sentence-transformers：
```bash
pip install sentence-transformers
```
- 确保已下载嵌入模型：
```bash
python scripts/download_model_modelscope.py
```
- 或者禁用向量服务，使用关键词检索：
在 `.env` 文件中设置 `ENABLE_VECTOR_SERVICE=False`

### 2. LLM 调用失败

**问题**：AI 问答功能无法使用

**解决方案**：
- 确保智谱 AI API Key 已正确配置在 `.env` 文件中
- 检查 API Key 是否有效且有足够的配额
- 查看日志文件 `logs/app.log` 获取详细错误信息

### 3. 网页爬取失败

**问题**：无法爬取网页内容

**解决方案**：
- 检查目标域名是否在白名单中
- 在 `.env` 文件中修改 `CRAWL_WHITELIST` 配置
- 确保网络连接正常
- 某些网站可能有反爬虫机制，可能需要调整爬取策略

### 4. 前端无法连接后端

**问题**：前端页面显示连接错误

**解决方案**：
- 确保后端服务已启动（运行在 http://localhost:8000）
- 检查 `memobase-front/src/services/api.ts` 中的 API 地址配置
- 检查浏览器控制台是否有 CORS 错误

### 5. 模型下载失败

**问题**：无法下载嵌入模型

**解决方案**：
- 使用 ModelScope 下载（推荐）：
```bash
pip install modelscope
python scripts/download_model_modelscope.py
```
- 参考文档 `docs/MODEL_DOWNLOAD_GUIDE.md` 获取更多下载方式
- 配置网络代理（如果在中国大陆）

### 6. 数据库错误

**问题**：启动时出现数据库相关错误

**解决方案**：
- 删除数据库文件重新初始化：
```bash
python scripts/reset_database.py
```
- 检查 `data` 目录是否有写入权限

### 7. 端口被占用

**问题**：启动时提示端口已被占用

**解决方案**：
- 修改 `.env` 文件中的 `API_PORT` 配置
- 或停止占用端口的进程：
```bash
# Windows
netstat -ano | findstr :8000
taskkill /PID <进程ID> /F

# Linux/Mac
lsof -ti:8000 | xargs kill -9
```

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！