# 向量数据库使用指南

## 1. 配置说明

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

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

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

## 2. 基本使用

### 2.1 获取向量数据库实例

```python
from services.utils.vector_db import VectorDBFactory

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

### 2.2 创建索引

```python
# 创建索引
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 插入文档

```python
# 插入单个文档
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 向量检索

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

### 2.5 混合检索

```python
# 混合检索（文本+向量）
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 关闭连接

```python
# 关闭连接
vector_db.close()
```

## 3. 切换向量数据库

### 3.1 通过环境变量切换

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

```env
# 使用Elasticsearch
VECTOR_DB_TYPE=es

# 使用Infinity
VECTOR_DB_TYPE=infinity
```

### 3.2 在代码中动态切换

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

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

## 4. 集成到现有代码

### 4.1 替换原有的ES连接

原代码：
```python
from services.utils.es_conn import ESConnection

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

新代码：
```python
from services.utils.vector_db import VectorDBFactory

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

### 4.2 替换向量检索逻辑

原代码：
```python
result = es.hybrid_search(
    index_name, 
    text_query="测试", 
    vector_field="vector_768_vec", 
    vector=vector,
    size=10
)
```

新代码：
```python
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()` 方法中添加新的类型判断

示例：

```python
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 向量检索返回空结果

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