# iScene-python-backend

**Repository Path**: A564/i-scene-python-backend

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-23
- **Last Updated**: 2025-11-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多模态RAG系统

一个支持多模态文件上传和智能问答的RAG（检索增强生成）系统，支持PDF、PPT、DOCX、图片、CSV、视频等文件的批量处理。

## 功能特性

- 🚀 **多模态支持**: 支持文本、图片、视频等多种文件格式
- 📁 **批量上传**: 支持单文件和批量文件上传
- 🔄 **异步处理**: 使用Celery进行后台异步向量化处理
- 🎯 **两路召回**: 文本向量召回和图片向量召回分离
- 📊 **实时监控**: Celery任务状态实时监控
- 🔍 **知识溯源**: 返回使用的知识库文件和相关信息
- 🌐 **RESTful API**: 完整的REST API接口

## 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   文件上传API    │    │   RAG问答API    │    │   Celery Worker │
│   (Port 8000)   │    │   (Port 8001)   │    │   (后台处理)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   Milvus DB     │
                    │  (向量数据库)    │
                    └─────────────────┘
```

## 支持的文件格式

| 文件类型 | 扩展名 | 处理方式 |
|---------|--------|----------|
| 文档 | .pdf, .docx, .pptx | 提取文本 + 图片 |
| 图片 | .jpg, .jpeg, .png, .bmp, .gif | 多模态向量化 |
| 视频 | .mp4, .avi, .mov, .mkv | 提取关键帧 |
| 表格 | .csv | 文本化处理 |
| 文本 | .txt, .md | 直接处理 |

## 安装部署

### 1. 环境要求

- Python 3.8+
- Redis
- Milvus 2.3+

### 2. 安装依赖

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

### 3. 配置设置

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

```python
# Milvus数据库配置
MILVUS_HOST = "your_milvus_host"
MILVUS_PORT = "your_milvus_port"

# 阿里云配置
ALIYUN_OSS_ACCESS_KEY_ID = "your_access_key"
ALIYUN_OSS_ACCESS_KEY_SECRET = "your_secret_key"

# 百炼RAG配置
BAILIAN_API_KEY = "your_api_key"

# 模型配置
EMBEDDING_MODEL = 'text-embedding-v4'
MULTIMODAL_EMBEDDING_MODEL = 'multimodal-embedding-v1'
```

### 4. 启动服务

#### 方式一：一键启动（推荐）

```bash
python start_services.py
```

#### 方式二：分步启动

```bash
# 1. 启动Redis
redis-server

# 2. 启动Celery Worker
celery -A celery_app worker --loglevel=info --concurrency=4

# 3. 启动Celery Monitor（可选）
celery -A celery_app flower --port=5555

# 4. 启动文件上传API
python upload_api.py

# 5. 启动RAG问答API
python multimodal_rag_api.py
```

## API接口文档

### 文件上传API (Port 8000)

#### 1. 单文件上传
```http
POST /upload/single
Content-Type: multipart/form-data

file: [文件]
```

#### 2. 批量文件上传
```http
POST /upload/batch
Content-Type: multipart/form-data

files: [文件1, 文件2, ...]
```

#### 3. 通过路径上传
```http
POST /upload/paths
Content-Type: application/json

{
  "file_paths": ["/path/to/file1.pdf", "/path/to/file2.jpg"],
  "description": "批量上传描述"
}
```

#### 4. 查询任务状态
```http
GET /task/{task_id}
```

### RAG问答API (Port 8001)

#### 1. 问答接口
```http
POST /ask
Content-Type: application/json

{
  "question": "你的问题",
  "conversation_id": "会话ID（可选）",
  "include_images": true,
  "top_k": 10
}
```

#### 2. 流式问答接口
```http
POST /ask_stream
Content-Type: application/json

{
  "question": "你的问题",
  "include_images": true,
  "top_k": 10
}
```

#### 3. 获取知识库统计
```http
GET /stats
```

## 使用示例

### 1. 上传文件

```python
import requests

# 单文件上传
with open('document.pdf', 'rb') as f:
    files = {'file': f}
    response = requests.post('http://localhost:8000/upload/single', files=files)
    task_id = response.json()['task_id']

# 查询处理状态
status = requests.get(f'http://localhost:8000/task/{task_id}').json()
print(f"处理状态: {status['status']}")
```

### 2. 问答查询

```python
import requests

# 发送问题
question_data = {
    "question": "请介绍一下人工智能的发展历程",
    "include_images": True,
    "top_k": 5
}

response = requests.post('http://localhost:8001/ask', json=question_data)
result = response.json()

print(f"答案: {result['answer']}")
print(f"使用的知识库文件: {result['knowledge_files']}")
print(f"文本来源: {len(result['text_sources'])} 个")
print(f"图片来源: {len(result['image_sources'])} 个")
```

## 监控和管理

### Celery Monitor
访问 http://localhost:5555 查看任务执行状态和性能监控。

### 健康检查
```bash
# 检查文件上传API
curl http://localhost:8000/health

# 检查RAG问答API
curl http://localhost:8001/health
```

## 配置说明

### 文件上传配置
- `MAX_FILE_SIZE`: 最大文件大小（默认100MB）
- `UPLOAD_FOLDER`: 文件上传目录
- `ALLOWED_EXTENSIONS`: 支持的文件格式

### 向量化配置
- `CHUNK_SIZE`: 文本分块大小
- `CHUNK_OVERLAP`: 文本分块重叠大小
- `TOP_K`: 召回数量
- `SIMILARITY_THRESHOLD`: 相似度阈值

### Celery配置
- `CELERY_BROKER_URL`: Redis连接地址
- `CELERY_RESULT_BACKEND`: 结果存储地址
- 并发数：默认4个worker进程

## 故障排除

### 常见问题

1. **Milvus连接失败**
   - 检查Milvus服务是否启动
   - 验证连接配置是否正确

2. **Celery任务失败**
   - 检查Redis服务状态
   - 查看Celery Worker日志

3. **文件上传失败**
   - 检查文件大小是否超限
   - 验证文件格式是否支持

4. **向量化失败**
   - 检查模型文件是否下载完成
   - 验证GPU内存是否充足

### 日志查看

```bash
# Celery Worker日志
celery -A celery_app worker --loglevel=debug

# API服务日志
tail -f logs/api.log
```

## 性能优化

1. **增加并发数**: 调整Celery Worker的并发数
2. **GPU加速**: 使用GPU进行向量化计算
3. **缓存优化**: 配置Redis缓存策略
4. **数据库优化**: 调整Milvus索引参数

## 扩展开发

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

1. 在 `config.py` 中添加文件扩展名
2. 在 `tasks.py` 中实现文件处理函数
3. 更新文档加载器

### 集成新的向量模型

1. 更新 `config.py` 中的模型配置
2. 修改 `tasks.py` 中的向量化逻辑
3. 测试模型兼容性

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！