# rag-demo

**Repository Path**: bulua/rag-demo

## Basic Information

- **Project Name**: rag-demo
- **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-02-27
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 文档问答系统

基于检索增强生成（RAG）的智能文档问答系统，支持文档上传、智能分块、向量检索和 AI 对话。

## 功能特性

- 📄 **文档管理**：支持上传、查看和管理文档
- ✂️ **智能分块**：自动对文档进行语义分块
- 🔍 **向量检索**：基于 Embedding 的相似度检索
- 💬 **AI 对话**：支持流式输出和多轮对话
- 🛠️ **工具调用**：AI 可调用工具（如获取当前时间）

## 技术栈

### 后端
- **FastAPI** - 高性能异步 Web 框架
- **OpenAI Client** - 兼容 vLLM 的 LLM 调用
- **Sentence Transformers** - 文本 Embedding
- **Python 3.10+**

### 前端
- **Vue 3** - 渐进式 JavaScript 框架
- **TypeScript** - 类型安全的 JavaScript
- **Vite** - 快速构建工具

## 项目结构

```
rag-demo/
├── backend/                 # 后端服务
│   ├── app/
│   │   ├── api/            # API 路由
│   │   ├── models/         # 数据模型
│   │   ├── services/       # 业务服务
│   │   ├── main.py         # FastAPI 入口
│   │   └── config.py       # 配置管理
│   ├── uploads/            # 上传文件存储
│   ├── .env                # 环境变量（需自行创建）
│   ├── .env.example        # 环境变量示例
│   └── requirements.txt    # Python 依赖
│
├── frontend/               # 前端应用
│   ├── src/
│   │   ├── components/     # Vue 组件
│   │   ├── services/       # API 服务
│   │   ├── types/          # TypeScript 类型
│   │   └── App.vue         # 根组件
│   ├── package.json        # Node 依赖
│   └── vite.config.ts      # Vite 配置
│
└── openspec/               # OpenSpec 规范
    └── specs/              # 功能规格文档
```

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd rag-demo
```

### 2. 后端启动

```bash
cd backend

# 使用 uv 配置环境并启动
uv run --python 3.10 -m app.main

# 或开发模式（自动重载）
uv run --python 3.10 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

> **注意**：首次运行会自动创建虚拟环境并安装依赖。如需手动配置：
> ```bash
> # 创建虚拟环境
> uv venv --python 3.10
> 
> # 安装依赖
> uv pip install -r requirements.txt
> 
> # 配置环境变量
> cp .env.example .env
> # 编辑 .env 文件，填入你的 AI 服务配置
> ```

后端服务启动后访问：
- API 文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/api/v1/health

### 3. 前端启动

```bash
cd frontend

# 安装依赖
pnpm install
# 或 pnpm install

# 启动开发服务器
pnpm run dev
# 或 pnpm dev
```

前端访问地址：http://localhost:5173

## 配置说明

### 后端环境变量 (.env)

```env
# AI 服务配置（支持 vLLM/OpenAI 兼容接口）
AI_BASE_URL=http://your-ai-server:8004/v1
AI_API_KEY=your-api-key
AI_MODEL_NAME=your-model-name

# Embedding 服务配置
EMBEDDING_BASE_URL=http://your-embedding-server:8002/v1
EMBEDDING_MODEL_NAME=bge-large-zh-v1.5

# Rerank 服务配置
RERANK_BASE_URL=http://your-rerank-server:8003/v1/rerank
RERANK_MODEL_NAME=bge-reranker-large

# 服务器配置
HOST=0.0.0.0
PORT=8000
DEBUG=true

# 文件上传配置
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760

# 文档分块配置
CHUNK_SIZE=1000
CHUNK_OVERLAP=200
CHUNK_MIN_SIZE=256
CHUNK_MAX_SIZE=512
CHUNK_OVERLAP_SIZE=50
```

## API 接口

### 文件上传
```http
POST /api/v1/upload
Content-Type: multipart/form-data

file: <文件>
```

### AI 对话
```http
POST /api/v1/chat/stream
Content-Type: application/json

{
  "question": "你的问题",
  "file_ids": ["file-id-1"],
  "history": []
}
```

### 获取文件列表
```http
GET /api/v1/files
```

### 获取文件分块
```http
GET /api/v1/files/{file_id}/chunks
```

## 开发指南

### 添加新的 AI 工具

在 `backend/app/services/ai_service.py` 中添加：

1. 在 `TOOLS` 列表中定义工具 schema
2. 在 `_tool_handlers` 中注册工具处理函数

示例：
```python
def _get_current_time(self, format: str = "%Y-%m-%d %H:%M:%S") -> str:
    return datetime.now().strftime(format)
```

## 许可证

MIT License