# shopi-rag

**Repository Path**: caigxx/shopi-rag

## Basic Information

- **Project Name**: shopi-rag
- **Description**: No description available
- **Primary Language**: Python
- **License**: AFL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG API 系统

基于 GPUStack 和本地模型的 RAG (Retrieval-Augmented Generation) REST API 系统

## 项目结构

```
shopi/
├── app/                           # 应用主目录
│   ├── config/                    # 配置模块
│   │   ├── __init__.py
│   │   └── settings.py           # 应用配置
│   ├── models/                    # 数据模型层
│   │   ├── __init__.py
│   │   └── schemas.py            # Pydantic 模型
│   ├── controllers/               # API 控制器层
│   │   ├── __init__.py
│   │   └── api.py                # API 路由
│   ├── services/                  # 业务逻辑层
│   │   ├── __init__.py
│   │   ├── llm_service.py        # LLM 服务
│   │   └── rag_service.py        # RAG 服务
│   ├── vector_store/              # 向量存储层
│   │   ├── __init__.py
│   │   └── store.py              # 向量数据库
│   ├── utils/                     # 工具模块
│   │   ├── __init__.py
│   │   └── logger.py             # 日志工具
│   └── main.py                    # FastAPI 应用入口
├── .env                           # 环境变量配置
├── main.py                        # 启动脚本
├── test_api.py                    # API 测试脚本
├── requirements.txt               # Python 依赖
└── start.bat                      # Windows 启动脚本
```

## 技术栈

- **Web 框架**: FastAPI
- **向量数据库**: ChromaDB
- **嵌入模型**: sentence-transformers
- **LLM 客户端**: GPUStack API (qwen3-coder-30b)
- **HTTP 客户端**: httpx

## 安装依赖

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

## 配置

编辑 `.env` 文件配置 GPUStack 和其他参数：

```env
# GPUStack LLM 服务配置
GPUSTACK_API_KEY=your_api_key
GPUSTACK_API_ENDPOINT=http://192.168.37.220/v1
GPUSTACK_MODEL=qwen3-coder-30b-a3b-instruct-1m-q5_k_s

# 向量数据库配置
VECTOR_DB_PATH=./vector_db
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

# RAG 配置
MAX_CONTEXT_LENGTH=4096
TOP_K=5
SIMILARITY_THRESHOLD=0.5
```

## 启动服务

### 方法 1: 使用 Python
```bash
python main.py
```

### 方法 2: 使用启动脚本 (Windows)
```bash
start.bat
```

### 方法 3: 使用 uvicorn
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

服务启动后访问：
- API 文档：http://localhost:8000/docs
- 备用文档：http://localhost:8000/redoc

## API 接口

### 1. 健康检查
```bash
GET /api/v1/health
```

### 2. RAG 查询
```bash
POST /api/v1/query
{
  "query": "你的问题",
  "top_k": 5,
  "include_sources": true
}
```

### 3. RAG 聊天
```bash
POST /api/v1/chat
{
  "messages": [
    {"role": "user", "content": "你好"}
  ],
  "use_rag": true,
  "top_k": 5
}
```

### 4. 添加文档
```bash
POST /api/v1/documents
{
  "content": "文档内容",
  "metadata": {"key": "value"}
}
```

### 5. 批量添加文档
```bash
POST /api/v1/documents/batch
{
  "documents": [
    {"content": "文档 1", "metadata": {}},
    {"content": "文档 2", "metadata": {}}
  ]
}
```

### 6. 删除文档
```bash
DELETE /api/v1/documents/{doc_id}
```

### 7. 清空所有文档
```bash
DELETE /api/v1/documents
```

### 8. 获取文档数量
```bash
GET /api/v1/documents/count
```

## 测试

### 方法 1: 运行测试脚本
```bash
python test_api.py
```

### 方法 2: 使用 Web 界面（推荐）
```bash
# 启动 Web 服务
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 或使用 Windows 批处理
web.bat
```

然后访问：http://localhost:8000

**Web 界面功能**：
- ✅ 智能对话（支持 RAG 检索）
- ✅ 文档上传（TXT、PDF）
- ✅ 文本知识添加
- ✅ 知识块管理（查看、编辑、搜索）
- ✅ 系统设置配置

### 方法 3: 使用命令行聊天

#### 选项 A: 独立聊天客户端（无需启动服务）
```bash
# 直接运行
python chat_direct.py

# 或使用 Windows 批处理
chat_direct.bat
```

**特点**：
- ✅ 无需启动 8000 端口服务
- ✅ 直接调用 GPUStack API
- ✅ 支持连续对话
- ✅ 开箱即用

#### 选项 B: RAG 聊天客户端（需要知识库）
```bash
# 先启动服务器
python main.py

# 再运行聊天客户端
python chat_cli.py

# 或使用 Windows 批处理
chat.bat
```

**特点**：
- ✅ 支持知识库检索
- ✅ RAG 增强回答
- ✅ 文档管理
- ✅ 专业领域问答

## 架构说明

### REST 架构分层

1. **Controllers 层**: 处理 HTTP 请求和响应
2. **Services 层**: 实现业务逻辑
3. **Models 层**: 定义数据结构
4. **Vector Store 层**: 管理向量数据库

### RAG 工作流程

1. **索引阶段**:
   - 文档添加到向量数据库
   - 使用嵌入模型将文本转换为向量

2. **检索阶段**:
   - 用户查询转换为向量
   - 在向量数据库中搜索相似文档

3. **生成阶段**:
   - 将检索到的文档作为上下文
   - 调用 GPUStack LLM 生成答案

## 注意事项

1. **GPUStack 服务**: 确保 GPUStack 服务可访问（默认：http://192.168.37.220/v1）
2. **嵌入模型**: 首次运行会下载嵌入模型（需要网络连接），使用 HuggingFace 镜像源加速
3. **向量数据库**: 文件存储在 `./vector_db` 目录
4. **生产环境**: 建议关闭 DEBUG 模式，配置合适的 CORS 策略
5. **Windows 用户**: 使用 `start_with_mirror.bat` 启动可自动使用 HuggingFace 镜像源

## 常见问题

### Q: 查询/聊天接口返回 500 错误？
A: 这通常是因为 GPUStack 服务不可达。请检查：
- GPUStack 服务是否正在运行
- API 密钥是否正确
- 网络连接是否正常

### Q: 如何查看 API 文档？
A: 启动服务后访问 http://localhost:8000/docs

### Q: 如何清空向量数据库？
A: 删除 `./vector_db` 目录或调用 `DELETE /api/v1/documents` 接口