# kb-practice

**Repository Path**: ai_code_stu/kb-practice

## Basic Information

- **Project Name**: kb-practice
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 个人知识库系统

基于 BGE-M3 和 DeepSeek 的个人知识库系统，支持文档搜索和网络搜索。

## 功能特性

- 📚 **文档搜索**: 支持多种文档格式（PDF、Word、Markdown、TXT）
- 🌐 **网络搜索**: 集成 DuckDuckGo 搜索引擎
- 🧠 **智能路由**: 自动识别用户意图，选择最佳搜索策略
- 🔍 **向量检索**: 基于 BGE-M3 的语义搜索
- 📊 **重排序**: 使用 DeepSeek-R1 进行结果重排序
- 🚀 **FastAPI**: 高性能 RESTful API
- 🎨 **Gradio**: 友好的 Web 界面

## 技术栈

- **Python 3.13**
- **FastAPI**: Web API 框架
- **Gradio**: Web 界面框架
- **Faiss**: 向量数据库
- **Sentence Transformers**: BGE-M3 嵌入模型
- **DuckDuckGo**: 网络搜索
- **PyMuPDF**: PDF 解析
- **python-docx**: Word 文档解析

## 项目结构

```
kb-practice/
├── src/
│   ├── api/              # FastAPI 接口
│   ├── config.py         # 配置文件
│   ├── main.py          # 主启动脚本
│   ├── models/          # 模型管理
│   ├── processing/      # 文档处理
│   ├── search/          # 搜索模块
│   ├── storage/         # 存储模块
│   └── ui/              # 用户界面
├── config.py            # 配置文件
├── requirements.txt     # 依赖列表
└── README.md           # 项目说明
```

## 安装依赖

```bash
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows

# 安装依赖
uv pip install -r requirements.txt
```

## 配置

编辑 `config.py` 文件，配置以下参数：

```python
# 模型配置
EMBEDDING_MODEL = "BAAI/bge-m3"
RERANKER_MODEL = "deepseek-ai/deepseek-r1-7b"
LLM_MODEL = "deepseek-ai/deepseek-r1-7b"

# 服务配置
API_HOST = "0.0.0.0"
API_PORT = 8000
GRADIO_PORT = 7860

# 向量数据库配置
FAISS_INDEX_PATH = "data/index.faiss"
FAISS_DIM = 1024
TOP_K = 10

# 文档处理配置
CHUNK_SIZE = 512
CHUNK_OVERLAP = 50
```

## 启动服务

### 方式一：使用启动脚本

```bash
python src/main.py
```

### 方式二：分别启动

```bash
# 启动 API 服务
uvicorn src.api.main:app --host 0.0.0.0 --port 8000

# 启动 Gradio 界面
python src/ui/gradio_app.py
```

## 使用方法

### 1. 上传文档

通过 Gradio 界面或 API 上传文档：

```bash
# 通过 API 上传
curl -X POST "http://localhost:8000/documents/upload" \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/your/document.pdf"}'
```

### 2. 搜索文档

```bash
# 智能搜索
curl -X POST "http://localhost:8000/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "如何使用 Python 进行数据分析", "top_k": 10}'
```

### 3. 网络搜索

```bash
# 网络搜索
curl -X POST "http://localhost:8000/search/web" \
  -H "Content-Type: application/json" \
  -d '{"query": "Python 数据分析教程", "top_k": 10}'
```

## API 接口

### 搜索接口

- `POST /search`: 智能搜索
- `POST /search/document`: 文档搜索
- `POST /search/web`: 网络搜索

### 文档管理

- `POST /documents/upload`: 上传单个文档
- `POST /documents/upload/batch`: 批量上传文档
- `GET /documents/list`: 列出所有文档
- `DELETE /documents/{document_id}`: 删除文档

### 索引管理

- `POST /index/clear`: 清空索引
- `GET /stats`: 获取统计信息

## Web 界面

启动后访问以下地址：

- **API 文档**: http://localhost:8000/docs
- **Gradio 界面**: http://localhost:7860

## 性能优化

1. **模型缓存**: 模型会自动下载并缓存到本地
2. **向量索引**: 使用 Faiss 进行高效的向量检索
3. **异步处理**: 支持异步文档上传和处理
4. **批量操作**: 支持批量文档上传

## 故障排除

### 常见问题

1. **模型下载慢**: 可以设置代理或使用国内镜像
2. **内存不足**: 调整 CHUNK_SIZE 和 TOP_K 参数
3. **端口冲突**: 修改配置文件中的端口号

### 日志

日志文件位于 `logs/kb_system.log`，可以查看详细的运行信息。

## 开发

### 添加新的文档格式支持

在 `src/processing/parser.py` 中添加新的解析器：

```python
def parse_new_format(file_path: Path) -> Optional[Dict[str, str]]:
    """解析新格式文档"""
    # 实现解析逻辑
    return document
```

### 添加新的搜索源

在 `src/search/` 目录下创建新的搜索模块，实现搜索接口。

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！