# LocalRag

**Repository Path**: lyDevelop/local-rag

## Basic Information

- **Project Name**: LocalRag
- **Description**: 基于RAG（Retrieval-Augmented Generation）的本地知识库系统，支持多格式文档的上传、解析、检索和问答。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LocalRAG - 本地知识库系统

基于RAG（Retrieval-Augmented Generation）的本地知识库系统，支持多格式文档的上传、解析、检索和问答。

## 功能特性

- 支持多种文档格式：PDF、DOCX、TXT、Markdown、HTML
- 智能文本分块（支持中文）
- 向量检索 + Rerank重排序
- 多知识库管理
- 文档去重（MD5）
- 完整的REST API
- 健康检查和监控

## 技术栈

- **Web框架**: FastAPI
- **向量数据库**: ChromaDB
- **Embedding模型**: BAAI/bge-m3（HTTP API）
- **Reranker模型**: BAAI/bge-reranker-v2-m3（HTTP API）
- **元数据存储**: SQLite
- **日志**: Loguru

## 目录结构

```
rag/
├── app.py              # FastAPI主应用
├── config.py           # 配置管理
├── database.py         # SQLite数据库
├── embedding.py        # Embedding API客户端
├── reranker.py         # Reranker API客户端
├── parser.py           # 文件解析器
├── chunk.py            # 文本分块
├── vector_store.py     # ChromaDB向量存储
├── models.py           # 数据模型
├── utils.py            # 工具函数
├── requirements.txt    # 依赖
├── .env.example        # 环境变量示例
├── start.sh            # 启动脚本
├── routers/            # API路由
│   ├── upload.py
│   ├── search.py
│   ├── document.py
│   └── collection.py
├── services/           # 业务服务
│   ├── ingest_service.py
│   ├── retrieve_service.py
│   ├── rerank_service.py
│   └── rag_service.py
├── schemas/            # Pydantic模型
│   ├── request.py
│   └── response.py
├── data/               # 数据目录
│   ├── upload/
│   ├── chroma/
│   └── rag.db
└── tests/              # 测试
```

## 快速开始

### 1. 环境要求

- Python >= 3.11
- Embedding API服务（http://localhost:8000/embedding）
- Reranker API服务（http://localhost:8001/rerank）

### 2. 安装

```bash
# 克隆项目
cd rag

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

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

# 配置环境变量
cp .env.example .env
# 编辑.env文件配置相关参数
```

### 3. 启动服务

```bash
# 方式1: 使用启动脚本（推荐）
./start.sh

# 方式2: 直接运行
python app.py
```

服务将在 http://localhost:8080 启动

### 4. 访问API文档

打开浏览器访问: http://localhost:8080/docs

## API接口

### 健康检查

```bash
curl http://localhost:8080/health
```

### 创建知识库

```bash
curl -X POST http://localhost:8080/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "技术文档",
    "description": "技术相关的文档知识库"
  }'
```

### 上传文件

```bash
curl -X POST http://localhost:8080/upload \
  -F "file=@./example.pdf" \
  -F "collection_id=知识库ID"
```

### 搜索文档

```bash
curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "什么是机器学习？",
    "top_k": 5,
    "use_rerank": true
  }'
```

### 获取文档列表

```bash
curl http://localhost:8080/document?collection_id=知识库ID&page=1&page_size=10
```

### 删除文档

```bash
curl -X DELETE http://localhost:8080/document/{文档ID}
```

### 获取知识库列表

```bash
curl http://localhost:8080/collections/s
```

### 删除知识库

```bash
curl -X DELETE http://localhost:8080/collections/{知识库ID}
```

## 配置说明

在`.env`文件中配置以下参数：

```bash
# Embedding API地址
EMBEDDING_API=http://localhost:8000/embedding

# Reranker API地址
RERANK_API=http://localhost:8001/rerank

# ChromaDB数据目录
CHROMA_PATH=./data/chroma

# SQLite数据库路径
SQLITE_PATH=./data/rag.db

# 分块大小（字符数）
CHUNK_SIZE=500

# 分块重叠大小
CHUNK_OVERLAP=100

# 向量检索返回数量
TOP_K=20

# Rerank后返回数量
RERANK_TOP_K=5

# 服务器地址
HOST=0.0.0.0

# 服务器端口
PORT=8080
```

## RAG流程

```
文档上传流程:
上传文件 → 解析文档 → 文本分块 → 获取Embedding → 存储到ChromaDB → 保存元数据到SQLite

查询流程:
用户查询 → 获取Query Embedding → ChromaDB检索 → TopK结果 → Rerank重排序 → 返回TopN结果
```

## 注意事项

1. 需要预先启动Embedding API服务和Reranker API服务
2. 首次运行会自动创建数据库和数据目录
3. 支持文档去重，相同MD5的文档会被跳过
4. 删除知识库会同时删除其下的所有文档

## License

MIT License