# Ragflow_plugs 项目文档

## 1. 项目概述

Ragflow_plugs是一个基于RAG（检索增强生成）技术的多模态混合检索系统，支持文本和图像的联合检索，并提供灵活的HTTP API服务。该系统旨在为智能应用提供高效、准确的多模态信息检索能力。

## 2. 目录结构

```
├── agent/             # 智能代理模块
├── api/               # HTTP API服务模块
├── book/              # 示例文档和输出目录
├── conf/              # 配置文件
├── doc/               # 项目文档
├── model/             # 模型相关模块
├── parser/            # 文档解析模块
├── test/              # 测试文件
├── utils/             # 工具模块
├── workflow/          # 工作流管理模块
├── .env               # 环境变量配置
├── .env.example       # 环境变量示例
├── requirements.txt   # 项目依赖
└── __init__.py        # 项目初始化
```

## 3. 核心功能

### 3.1 多模态嵌入生成

- 支持文本和图像的联合嵌入生成
- 兼容多种AI模型API
- 提供统一的嵌入接口

### 3.2 混合检索

- 结合文本检索和向量检索
- 支持灵活的检索参数配置
- 提供准确的检索结果

### 3.3 HTTP API服务

- 提供RESTful API
- 支持请求参数验证
- 提供统一的响应格式

### 3.4 文档处理

- 支持PDF文档解析
- 支持图像提取和处理

### 3.5 向量数据库集成

- 与Infinity向量数据库无缝集成
- 支持向量存储和检索

## 4. 快速开始

### 4.1 环境准备

1. 安装Python 3.12
2. 安装依赖：

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

3. 配置环境变量：

```bash
cp .env.example .env
# 编辑.env文件，配置API密钥和其他参数
```

### 4.2 运行HTTP服务

```bash
python -m api.hybrid_search_http
```

服务将在 `http://0.0.0.0:18001` 上运行。

### 4.3 使用API

#### 混合检索API

**请求URL**：`/hybrid_search`

**请求方法**：POST

**请求体**：

```json
{
    "text_query": "文本查询",
    "image": "图片URL或base64编码",
    "topn": 2
}
```

**响应示例**：

```json
{
    "success": true,
    "message": "混合检索成功",
    "output": [
        {
            "file_name": "文件名",
            "page_number": 1,
            "content": "内容",
            "image_path": "图片路径",
            "dataset_id": "数据集ID",
            "document_id": "文档ID",
            "_similarity": 0.95
        }
    ],
    "total": 1
}
```

#### 健康检查API

**请求URL**：`/health`

**请求方法**：GET

**响应示例**：

```json
{
    "status": "ok",
    "message": "混合检索HTTP服务正常运行"
}
```

## 5. 配置说明

### 5.1 模型配置

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| MULTIMODAL_EMBEDDING_MODEL_NAME | 多模态嵌入模型名称 | qwen-vl-plus |
| DASHSCOPE_API_KEY | DashScope API密钥 | - |
| SILICONFLOW_API_KEY | SiliconFlow API密钥 | - |

### 5.2 向量数据库配置

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| INFINITY_HOST | Infinity数据库地址 | http://localhost:23820 |
| INFINITY_DATABASE | Infinity数据库名称 | image_db |
| INFINITY_TABLE_NAME | Infinity表名称 | - |

## 6. 开发指南

### 6.1 代码风格

- 遵循PEP 8代码风格
- 使用类型注解
- 编写清晰的文档字符串

### 6.2 测试

- 运行单元测试：

```bash
python -m pytest test/ -v
```

- 运行特定测试：

```bash
python -m pytest test/test_http_hybrid_search.py -v
```

### 6.3 添加新功能

1. 在相应的模块目录下创建新文件
2. 实现新功能
3. 编写测试用例
4. 更新文档

## 7. 示例代码

### 7.1 使用混合检索

```python
from utils.infinity_util import InfinityVectorDB
from model.multimodal_embedding import Embedding
from conf.config import ModelConfig

# 初始化向量数据库
vector_db = InfinityVectorDB()

# 初始化嵌入模型
embedding_model = Embedding(
    model_name=ModelConfig.get_multimodal_embedding_model_name(),
    api_key=ModelConfig.get_dashscope_api_key()
)

# 生成多模态嵌入
text_query = "文本查询"
image = Image.open("image.jpg")
embedding = embedding_model.get_multimodal_embedding(text_query, image)

# 执行混合检索
result = vector_db.hybrid_search(
    index_name="index_name",
    match_method="dense",
    vector_field="vector_field",
    query_vector=embedding,
    element_type="float",
    metric_type="cosine",
    topn=2,
    text_query=text_query,
    text_field="content"
)

print(result)
```

## 8. 常见问题

### 8.1 嵌入生成失败

- 检查API密钥是否正确
- 检查网络连接
- 检查模型名称是否正确

### 8.2 检索结果不准确

- 检查向量数据库配置
- 检查嵌入模型配置
- 调整检索参数

### 8.3 HTTP服务无法启动

- 检查端口是否被占用
- 检查配置文件是否正确
- 检查依赖是否安装完整

## 9. 联系方式

如有问题或建议，请联系项目负责人。

## 10. 版本历史

- v1.0.0：初始版本，支持多模态混合检索和HTTP API服务

## 11. 许可证

本项目采用MIT许可证。