# Bug修复：知识库模型配置错误

## 问题描述

客户报告了以下问题：
1. **知识库显示10个文件，但查询时只返回2个文件**
2. **第四张图报错**：`HTTP状态码错误: 404, body={"error":{"message":"Unsupported model 'gte-rerank-v2' for OpenAI compatibility mode","type":"invalid_request_error","param":null,"code":"model_not_supported"}}`

## 根本原因

客户**错误地将 Rerank 模型名称填到了 Embedding 模型字段**：
- **Embedding 模型**字段填写了：`gte-rerank-v2`（这是一个Rerank模型！）
- **Rerank 模型**字段填写了：`qwen3-rerank`（正确）

正确的配置应该是：
- **Embedding 模型**：`text-embedding-v4` 或 `text-embedding-v3` 等向量化模型
- **Rerank 模型**：`qwen3-rerank` 或 `gte-rerank-v2` 等重排序模型

### 为什么会导致只返回2个文件？

1. 系统在重建知识库索引时调用 Embedding API 失败（因为 `gte-rerank-v2` 不是有效的 Embedding 模型）
2. 向量索引为空或不完整
3. 查询时向量检索失败，系统降级使用关键词检索
4. Rerank 步骤也受到影响，最终只返回了部分结果

## 修复方案

### 1. 后端配置验证 (config/types.go)

添加了两个验证函数：
- `isRerankModelName()` - 识别 Rerank 模型名称
- `isEmbeddingModelName()` - 识别 Embedding 模型名称

在 `ApplyDefaults()` 函数中自动检测和修正错误配置：

```go
// 检测用户是否错误地将 Rerank 模型填到了 Embedding 模型字段
if isRerankModelName(c.AutoReplyConfig.Retrieval.EmbeddingModel) {
    c.AutoReplyConfig.Retrieval.EmbeddingModel = defaultAuto.Retrieval.EmbeddingModel
}

// 检测用户是否错误地将 Embedding 模型填到了 Rerank 模型字段
if isEmbeddingModelName(c.AutoReplyConfig.Retrieval.RerankModel) {
    c.AutoReplyConfig.Retrieval.RerankModel = defaultAuto.Retrieval.RerankModel
}
```

### 2. 改进错误提示 (helper/auto_reply_retrieval.go)

在 `callDashScopeEmbeddings()` 函数中添加更友好的错误信息：

```go
if strings.Contains(strings.ToLower(errMsg), "unsupported model") &&
   strings.Contains(strings.ToLower(errMsg), "rerank") {
    return nil, fmt.Errorf("Embedding模型配置错误：'%s' 是一个Rerank模型，不是Embedding模型。请使用 text-embedding-v4 或 text-embedding-v3 等Embedding模型", retrievalCfg.EmbeddingModel)
}
```

### 3. 前端UI优化 (frontend/src/components/AutoReply.vue)

#### 3.1 添加说明文本

在模型配置输入框下方添加提示：

```vue
<label>
  <span>Embedding 模型</span>
  <input v-model="form.retrieval.embeddingModel" placeholder="text-embedding-v4">
  <small style="color: #666; font-size: 12px; margin-top: 4px; display: block;">
    用于文本向量化，例如：text-embedding-v4, text-embedding-v3
  </small>
</label>

<label>
  <span>Rerank 模型</span>
  <input v-model="form.retrieval.rerankModel" placeholder="qwen3-rerank">
  <small style="color: #666; font-size: 12px; margin-top: 4px; display: block;">
    用于结果重排序，例如：qwen3-rerank, gte-rerank-v2
  </small>
</label>
```

#### 3.2 添加前端验证

在保存配置前进行验证：

```javascript
function validateModelConfig() {
  if (!form.retrieval) return null

  const embeddingModel = String(form.retrieval.embeddingModel || '').trim().toLowerCase()
  const rerankModel = String(form.retrieval.rerankModel || '').trim().toLowerCase()

  // 检测 Embedding 模型字段是否填写了 Rerank 模型
  if (embeddingModel && (embeddingModel.includes('rerank') || ...)) {
    return `配置错误：Embedding 模型字段不能填写 Rerank 模型...`
  }

  // 检测 Rerank 模型字段是否填写了 Embedding 模型
  if (rerankModel && (rerankModel.includes('embedding') || ...)) {
    return `配置错误：Rerank 模型字段不能填写 Embedding 模型...`
  }

  return null
}
```

## 测试验证

创建了完整的单元测试 (`types_test.go`)：
- `TestIsRerankModelName` - 验证 Rerank 模型识别
- `TestIsEmbeddingModelName` - 验证 Embedding 模型识别
- `TestApplyDefaultsFixesWrongModelConfig` - 验证自动修正功能
- `TestApplyDefaultsFixesWrongRerankConfig` - 验证反向错误修正

所有测试通过✓

## 使用指南

### 正确的模型配置

#### Embedding 模型（用于文本向量化）
- `text-embedding-v4` ✓
- `text-embedding-v3` ✓
- `bge-large-zh` ✓
- `gte-large` ✓

#### Rerank 模型（用于结果重排序）
- `qwen3-rerank` ✓
- `gte-rerank-v2` ✓
- `bge-rerank-large` ✓

### 常见错误配置

❌ **错误示例**：
```json
{
  "embeddingModel": "gte-rerank-v2",  // 错误：这是Rerank模型
  "rerankModel": "qwen3-rerank"
}
```

✓ **正确配置**：
```json
{
  "embeddingModel": "text-embedding-v4",  // 正确：Embedding模型
  "rerankModel": "qwen3-rerank"           // 正确：Rerank模型
}
```

## 如何告知客户

1. 更新到新版本后，系统会自动检测并修正错误的模型配置
2. 如果配置被自动修正，建议在"知识库"模块点击"重建索引"按钮
3. 新版本的UI会显示每个模型字段的用途和示例，避免混淆

## 影响范围

- 影响范围：使用混合检索模式的所有用户
- 严重程度：高（导致知识库检索失败）
- 修复方式：自动修正 + 用户友好提示
- 兼容性：向后兼容，不影响正确配置的用户

## 相关文件

- `config/types.go` - 配置验证逻辑
- `helper/auto_reply_retrieval.go` - 错误提示改进
- `frontend/src/components/AutoReply.vue` - 前端UI和验证
- `types_test.go` - 单元测试