Initial qiwei secondary development handoff

config/docs/BUG_FIX_MODEL_CONFIG.md

@@ -0,0 +1,169 @@
+# 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` - 单元测试