# 知识库向量索引配置

## 概述

本文档描述知识库的向量索引配置和检索策略。

## 向量存储架构

```
文档摄入流程：
文档上传 → Parser解析 → Chunker分块 → Embedder向量化 → 向量数据库存储

检索流程：
用户查询 → Embedder向量化 → 向量检索 → 混合排序 → 返回结果
```

## 嵌入模型配置

### Embedder服务

位置：`backend/app/services/knowledge/embedder.py`

| 配置项 | 环境变量 | 说明 |
|--------|----------|------|
| OpenAI嵌入 | OPENAI_API_KEY | 使用OpenAI text-embedding-ada-002 |
| 本地嵌入 | LOCAL_EMBEDDING_MODEL | 本地模型路径 |
| 批处理大小 | EMBEDDING_BATCH_SIZE | 默认20 |

### 支持的嵌入模型

| 模型 | 维度 | 说明 |
|------|------|------|
| text-embedding-ada-002 | 1536 | OpenAI官方模型 |
| text-embedding-3-small | 1536 | OpenAI新模型 |
| text-embedding-3-large | 3072 | OpenAI高性能模型 |
| m3e-base | 768 | 中文嵌入模型 |

### 向量维度

- OpenAI Ada: 1536维
- M3E: 768维

## 分块策略

### RecursiveChunker (默认)

```python
RecursiveChunker.STRATEGY = ChunkStrategy(
    name="recursive",
    description="优先按段落分割，过长时按句子分割",
    chunk_size=500,       # 块大小（字符数）
    chunk_overlap=50,     # 重叠大小
    min_chunk_size=50,    # 最小块大小
)
```

分割优先级：
1. `\n\n+` - 双换行（段落）
2. `\n` - 单换行
3. `[。！？!?]\s*` - 句子结束
4. `[,，;；]\s*` - 分句
5. `\s+` - 空格

### SemanticChunker

```python
SemanticChunker.STRATEGY = ChunkStrategy(
    name="semantic",
    description="根据语义边界自动分块",
    chunk_size=800,
    chunk_overlap=100,
    min_chunk_size=100,
)
```

语义边界模式：
- Markdown标题 `# ## ###`
- 中文标题 `【】`
- 章节标题 `第X章/第X条`
- 数字编号 `1. 2. 3.`

### FixedLengthChunker

```python
FixedLengthChunker.STRATEGY = ChunkStrategy(
    name="fixed",
    description="按固定长度强制分块",
    chunk_size=300,
    chunk_overlap=30,
    min_chunk_size=50,
)
```

## 检索配置

### HybridRetriever (混合检索器)

位置：`backend/app/services/knowledge/retriever.py`

支持两种检索方式：
1. **向量检索** - 基于语义相似度
2. **关键词检索** - 基于BM25

### 检索参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| top_k | 返回结果数 | 10 |
| similarity_threshold | 相似度阈值 | 0.7 |
| enable_rerank | 是否重排序 | true |
| enable_compression | 是否上下文压缩 | false |

### 增强检索 (EnhancedRAG)

位置：`backend/app/services/knowledge/enhanced_rag.py`

#### 重排序流程

```
1. 初始检索候选集 (top_k * 4)
2. 对每个候选计算与查询的相关性分数
3. 按相关性分数排序
4. 返回top_k结果
```

#### 上下文压缩

```
1. 计算当前context的token数
2. 如果超过max_context_tokens
3. 使用LLM提取与query相关的片段
4. 减少token消耗
```

## 向量数据库

当前实现使用数据库原生向量支持：

```sql
-- PostgreSQL + pgvector
CREATE TABLE knowledge_chunks (
    id UUID PRIMARY KEY,
    document_id UUID REFERENCES knowledge_documents(id),
    content TEXT,
    embedding VECTOR(1536),  -- 1536维向量
    chunk_index INTEGER,
    token_count INTEGER,
    extra_metadata JSONB
);
```

## 增量索引

位置：`backend/app/services/knowledge/incremental_index.py`

支持增量更新：
1. 新文档摄入时，只索引新增chunks
2. 删除文档时，删除对应chunks
3. 更新文档时，重新处理变化的chunks

## 性能优化

| 优化项 | 说明 |
|--------|------|
| 批处理嵌入 | 批量调用embedding API |
| 连接池 | 数据库连接复用 |
| 缓存 | 热门查询结果缓存 |
| 异步 | 使用asyncio提高并发 |

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| OPENAI_API_KEY | OpenAI API密钥 | - |
| KNOWLEDGE_EMBEDDING_MODEL | 嵌入模型 | text-embedding-ada-002 |
| KNOWLEDGE_VECTOR_DB | 向量数据库类型 | pgvector |
| EMBEDDING_BATCH_SIZE | 批处理大小 | 20 |
