RAG/docs/code_retrieve_optimization.md

# 代码检索模块性能调优文档

## 1. 存储结构设计

### 1.1 核心设计原则
```
向量化文本: func_desc (函数描述，语义丰富)
元数据存储: func_body (完整函数代码，供问答使用)
```

### 1.2 存储格式
```python
Document(
    text=func_desc,           # 用于 embedding 的文本
    metadata={
        "func_body": "...",   # 完整函数代码（核心）
        "func_name": "...",
        "file_path": "...",
        "repo_id": "...",
        # ... 其他元数据
    }
)
```

## 2. 检索性能优化

### 2.1 Top-K 参数调优

| 场景 | 推荐 top_k | 说明 |
|------|-----------|------|
| 精确查找特定函数 | 3-5 | 减少噪声，提高精确度 |
| 探索性查询 | 10-15 | 获取更多上下文 |
| 复杂问题 | 20+ | 需要多个函数协作回答 |

### 2.2 元数据过滤

**优势**：在向量检索前过滤，减少计算量

```python
# 按仓库过滤
results = code_retrieve(query, repo_id="git_https___gitee_com_xxx")

# 按函数名精确查找
results = code_retrieve(query, func_name="push")
```

**性能提升**：
- 无过滤：全库扫描 O(N)
- 有过滤：仅扫描子集 O(M)，M << N

### 2.3 Embedding 模型选择

| 模型 | 维度 | 速度 | 适用场景 |
|------|------|------|----------|
| nomic-embed-text | 768 | 快 | 通用代码检索 |
| qwen3-embedding | 768 | 中等 | 中文代码理解 |
| text-embedding-3 | 1536 | 慢 | 高精度需求 |

## 3. 检索质量优化

### 3.1 函数描述生成策略

当前实现：
```python
def generate_func_desc(func_info):
    parts = []
    # 1. 函数类型和名称
    if func_info.get("class_name"):
        parts.append(f"{func_info['class_name']}类的{func_info['func_name']}方法")
    else:
        parts.append(f"{func_info['func_name']}函数")
    
    # 2. 参数信息
    if params:
        parts.append(f"接收参数: {', '.join(param_str)}")
    
    # 3. 返回值
    if return_type:
        parts.append(f"返回类型: {return_type}")
    
    # 4. 文档字符串
    if docstring:
        parts.append(f"功能描述: {docstring}")
    
    return ". ".join(parts)
```

**优化建议**：
1. **添加函数调用关系**："调用 xx 函数"
2. **添加代码复杂度**："包含 xx 行代码"
3. **添加关键 API**："使用 requests 库"

### 3.2 相似度阈值

```python
# 过滤低质量结果
MIN_SIMILARITY_SCORE = 0.5

results = [r for r in results if r['score'] >= MIN_SIMILARITY_SCORE]
```

### 3.3 结果重排序

```python
def rerank_results(results, query):
    """
    基于额外特征重排序：
    1. 函数名匹配度
    2. 文档字符串相关性
    3. 代码长度适中度
    """
    for r in results:
        # 函数名完全匹配加分
        if query.lower() in r['func_name'].lower():
            r['score'] += 0.2
        
        # 有文档字符串加分
        if r['docstring']:
            r['score'] += 0.1
    
    return sorted(results, key=lambda x: x['score'], reverse=True)
```

## 4. 增量同步优化

### 4.1 变更检测

```python
def detect_changes(repo_path, last_sync_time):
    """
    只检测变更的文件，避免全量扫描
    """
    changed_files = []
    for file in get_tracked_files(repo_path):
        if get_file_mtime(file) > last_sync_time:
            changed_files.append(file)
    return changed_files
```

### 4.2 增量更新策略

1. **新增函数**：直接添加
2. **修改函数**：更新 embedding 和 metadata
3. **删除函数**：从向量库删除

## 5. 性能监控指标

### 5.1 关键指标

| 指标 | 目标值 | 监控方式 |
|------|--------|----------|
| 检索延迟 | < 500ms | 日志记录 |
| 准确率@5 | > 80% | 人工评估 |
| 覆盖率 | > 95% | 自动化测试 |
| 存储空间 | < 10GB | 系统监控 |

### 5.2 日志记录

```python
logger.info(f"[CodeRetrieve] 查询: '{query}', 找到 {len(results)} 个结果, 耗时 {elapsed_time:.2f}s")
```

## 6. 最佳实践

### 6.1 查询优化

**好的查询**：
- "push 函数的功能是什么"
- "如何处理 GitHub issue"
- "webhook.py 中的 run 方法"

**差的查询**：
- "代码"（太宽泛）
- "问题"（无针对性）
- "怎么写"（不明确）

### 6.2 索引维护

1. **定期重建索引**：每月一次
2. **清理孤立文档**：每周检查
3. **监控存储增长**：设置告警

## 7. 故障排查

### 7.1 检索不到结果

1. 检查向量库是否为空
2. 检查 embedding 模型是否正常
3. 检查查询文本是否有效

### 7.2 结果质量差

1. 检查 func_desc 生成质量
2. 调整 top_k 参数
3. 考虑更换 embedding 模型

### 7.3 性能下降

1. 检查 ChromaDB 连接
2. 检查 embedding 服务负载
3. 考虑增加缓存层