yingge 4d40d54a85 提交		4 mesi fa
..
README.md	4d40d54a85 提交	4 mesi fa
design.md	4d40d54a85 提交	4 mesi fa

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 环境准备

安装Python 3.12
安装依赖：
```
pip install -r requirements.txt
```

配置环境变量：

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

4.2 运行HTTP服务

python -m api.hybrid_search_http

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

4.3 使用API

混合检索API

请求URL：/hybrid_search

请求方法：POST

请求体：

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

响应示例：

{
    "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

响应示例：

{
    "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 测试

运行单元测试：
```
python -m pytest test/ -v
```

运行特定测试：

python -m pytest test/test_http_hybrid_search.py -v

6.3 添加新功能

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

7. 示例代码

7.1 使用混合检索

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许可证。

README.md