RagFlow_Plugs/VectorDB_GUIDE.md

向量数据库使用指南

1. 配置说明

在 .env 文件中添加以下配置，用于选择和配置向量数据库：

# 向量数据库配置
VECTOR_DB_TYPE=es  # 可选值: es, infinity

# Infinity向量数据库配置
INFINITY_HOST=localhost
INFINITY_PORT=23810
INFINITY_USER=admin
INFINITY_PASSWORD=admin

2. 基本使用

2.1 获取向量数据库实例

from services.utils.vector_db import VectorDBFactory

# 根据配置获取向量数据库实例
vector_db = VectorDBFactory.get_vector_db()

2.2 创建索引

# 创建索引
index_name = "test_index"
mappings = {
    "properties": {
        "content": {
            "type": "text"
        },
        "vector_768_vec": {
            "type": "dense_vector",
            "dims": 768,
            "similarity": "cosine"
        }
    }
}

vector_db.create_index(index_name, mappings)

2.3 插入文档

# 插入单个文档
document = {
    "content": "这是一个测试文档",
    "vector_768_vec": [0.1] * 768,
    "metadata": {
        "title": "测试文档",
        "category": "test"
    }
}

vector_db.insert_document(index_name, document, id="1")

# 批量插入文档
documents = [
    {
        "content": f"批量测试文档 {i}",
        "vector_768_vec": [0.1] * 768,
        "metadata": {
            "title": f"批量测试文档 {i}",
            "category": "test"
        }
    }
    for i in range(5)
]

vector_db.bulk_insert(index_name, documents)

2.4 向量检索

# 向量检索
query_vector = [0.1] * 768
result = vector_db.vector_search(
    index_name,
    vector_field="vector_768_vec",
    vector=query_vector,
    size=10
)

2.5 混合检索

# 混合检索（文本+向量）
result = vector_db.hybrid_search(
    index_name,
    text_query="测试",
    vector_field="vector_768_vec",
    vector=query_vector,
    size=10,
    text_weight=0.5,  # 文本检索权重
    vector_weight=0.5  # 向量检索权重
)

2.6 关闭连接

# 关闭连接
vector_db.close()

3. 切换向量数据库

3.1 通过环境变量切换

修改 .env 文件中的 VECTOR_DB_TYPE 配置：

# 使用Elasticsearch
VECTOR_DB_TYPE=es

# 使用Infinity
VECTOR_DB_TYPE=infinity

3.2 在代码中动态切换

# 注意：这种方式不推荐，建议通过环境变量配置
from services.utils.vector_db import ElasticsearchVectorDB, InfinityVectorDB

# 直接创建特定类型的向量数据库实例
es_db = ElasticsearchVectorDB()
infinity_db = InfinityVectorDB()

4. 集成到现有代码

4.1 替换原有的ES连接

原代码：

from services.utils.es_conn import ESConnection

# 初始化ES连接
es = ESConnection()

新代码：

from services.utils.vector_db import VectorDBFactory

# 初始化向量数据库连接（根据配置自动选择）
vector_db = VectorDBFactory.get_vector_db()

4.2 替换向量检索逻辑

原代码：

result = es.hybrid_search(
    index_name, 
    text_query="测试", 
    vector_field="vector_768_vec", 
    vector=vector,
    size=10
)

新代码：

result = vector_db.hybrid_search(
    index_name, 
    text_query="测试", 
    vector_field="vector_768_vec", 
    vector=vector,
    size=10
)

5. 注意事项

1. 依赖问题：

   • 使用 Elasticsearch 时，确保已安装 elasticsearch==8.11.1
   • 使用 Infinity 时，需要注意 infinity-emb 和 huggingface_hub 的版本兼容问题
     • 推荐：huggingface_hub==0.21.4
     • 安装命令：pip install huggingface_hub==0.21.4

2. 配置问题：

   • 确保 .env 文件中的配置正确
   • 确保向量数据库服务已启动并可访问

3. 性能问题：

   • 对于大规模数据，建议使用批量操作
   • 调整向量检索的 size 参数以平衡性能和结果数量

4. 迁移问题：

   • 从一种向量数据库迁移到另一种时，需要重新创建索引和导入数据
   • 不同向量数据库的映射和查询语法可能有所不同

6. 扩展新的向量数据库

要添加对新的向量数据库的支持，需要：

1. 创建一个新的类，继承自 VectorDBBase
2. 实现所有抽象方法
3. 在 VectorDBFactory.get_vector_db() 方法中添加新的类型判断

示例：

class NewVectorDB(VectorDBBase):
    def create_index(self, index_name: str, mappings: Dict[str, Any] = None) -> bool:
        # 实现创建索引逻辑
        pass
    
    # 实现其他方法...

# 在 VectorDBFactory.get_vector_db() 中添加
if vector_db_type == "new":
    return NewVectorDB()

7. 故障排除

7.1 Elasticsearch 连接超时

• 检查 Elasticsearch 服务是否正在运行
• 检查 .env 文件中的 ES_HOST 配置是否正确
• 检查防火墙设置，确保 Elasticsearch 端口可访问

7.2 Infinity 依赖错误

• 尝试安装兼容版本的 huggingface_hub：pip install huggingface_hub==0.21.4
• 检查 Infinity 服务是否正在运行
• 检查 .env 文件中的 Infinity 配置是否正确

7.3 向量检索返回空结果

• 检查索引是否已创建
• 检查文档是否已成功插入
• 检查向量字段名是否正确
• 检查查询向量的维度是否与索引中存储的向量维度一致