Initial qiwei secondary development handoff

config/docs/BUG_FIX_SUMMARY.md

@@ -0,0 +1,149 @@
+# Bug修复总结
+
+## 客户问题
+客户反馈："我搞了10个MD文件进去，自动客服页面也显示有10个文件，但是一回到会话一问就出现只有两个，怎么回事，而且第四张图报错如图"
+
+## Bug分析
+
+### 表面现象
+1. 知识库页面显示：10个文件，389个片段 ✓
+2. AI查询时只能看到2个文件 ❌
+3. HTTP 404错误：`Unsupported model 'gte-rerank-v2' for OpenAI compatibility mode` ❌
+
+### 根本原因
+**客户将Rerank模型名称错误填到了Embedding模型字段！**
+
+从截图第四张可以看到客户的配置：
+- Embedding 模型：`gte-rerank-v2` ← **错误！这是Rerank模型**
+- Rerank 模型：`qwen3-rerank` ← 正确
+
+正确的应该是：
+- Embedding 模型：`text-embedding-v4` 或 `text-embedding-v3`
+- Rerank 模型：`gte-rerank-v2` 或 `qwen3-rerank`
+
+### 错误传播链
+```
+错误配置 (gte-rerank-v2 作为Embedding)
+    ↓
+Embedding API调用失败 (404: model not supported)
+    ↓
+向量索引构建失败/不完整
+    ↓
+查询时向量检索失败
+    ↓
+系统降级为关键词检索
+    ↓
+Rerank步骤受影响
+    ↓
+只返回部分结果（2个文件）
+```
+
+## 修复方案
+
+### 1. 后端自动修正 (config/types.go)
+- 新增 `isRerankModelName()` 函数识别Rerank模型
+- 新增 `isEmbeddingModelName()` 函数识别Embedding模型
+- 在 `ApplyDefaults()` 中自动检测并修正错误配置
+
+### 2. 错误提示改进 (helper/auto_reply_retrieval.go)
+- 在 `callDashScopeEmbeddings()` 中增加友好的错误提示
+- 明确告知用户配置了哪个错误的模型
+- 提示正确的模型选择
+
+### 3. 前端UI优化 (frontend/src/components/AutoReply.vue)
+- 添加说明文字："用于文本向量化，例如：text-embedding-v4, text-embedding-v3"
+- 添加说明文字："用于结果重排序，例如：qwen3-rerank, gte-rerank-v2"
+- 新增 `validateModelConfig()` 函数在保存前验证配置
+- 如果配置错误，保存时会显示友好的错误提示
+
+### 4. 测试覆盖 (types_test.go)
+- 测试Rerank模型识别准确性
+- 测试Embedding模型识别准确性
+- 测试自动修正功能
+- 所有测试通过 ✓
+
+## 修改的文件
+
+| 文件 | 修改内容 | 行数 |
+|------|---------|------|
+| `config/types.go` | 添加模型验证和自动修正逻辑 | +40 |
+| `helper/auto_reply_retrieval.go` | 改进错误提示信息 | +6 |
+| `frontend/src/components/AutoReply.vue` | 添加UI提示和前端验证 | +30 |
+| `types_test.go` | 添加单元测试 | +107 |
+| `docs/BUG_FIX_MODEL_CONFIG.md` | 详细修复文档 | new |
+| `docs/用户通知_知识库配置修复.md` | 用户通知文档 | new |
+
+## 测试结果
+
+```bash
+$ go test -v -run "TestIs|TestApplyDefaults"
+=== RUN   TestIsRerankModelName
+--- PASS: TestIsRerankModelName (0.00s)
+=== RUN   TestIsEmbeddingModelName
+--- PASS: TestIsEmbeddingModelName (0.00s)
+=== RUN   TestApplyDefaultsFixesWrongModelConfig
+--- PASS: TestApplyDefaultsFixesWrongModelConfig (0.00s)
+=== RUN   TestApplyDefaultsFixesWrongRerankConfig
+--- PASS: TestApplyDefaultsFixesWrongRerankConfig (0.00s)
+PASS
+ok  	qiweimanager/config	0.098s
+```
+
+## 用户操作指南
+
+### 立即解决方案
+告知客户：
+1. 打开"自动客服"→"知识库"模块
+2. 将"Embedding 模型"从 `gte-rerank-v2` 改为 `text-embedding-v4`
+3. 点击"保存配置"
+4. 点击"重建索引"按钮
+5. 等待重建完成（1-3分钟）
+6. 测试查询："现在知识库有哪些文件"
+
+### 长期解决方案
+1. 发布包含修复的新版本
+2. 系统会自动检测并修正错误配置
+3. 用户界面会显示清晰的说明文字
+4. 保存时会进行验证，防止再次配置错误
+
+## 预防措施
+
+### 已实施
+✅ 自动检测和修正错误配置
+✅ 更友好的错误提示
+✅ UI添加说明文字和示例
+✅ 保存前验证配置
+
+### 建议补充
+- [ ] 在文档中明确说明两种模型的区别
+- [ ] 在配置页面添加"推荐配置"按钮
+- [ ] 添加配置检查工具，一键诊断配置问题
+
+## 影响评估
+
+### 影响范围
+- 所有使用"混合检索 + 重排序"模式的用户
+- 估计影响5-10%的用户（基于此为配置错误）
+
+### 严重程度
+- **高** - 导致知识库检索功能完全失效
+
+### 修复效果
+- ✅ 后端自动修正：错误配置会被自动检测和修正
+- ✅ 前端验证：保存前阻止错误配置
+- ✅ 友好提示：明确告知用户问题和解决方案
+- ✅ 向后兼容：不影响配置正确的用户
+
+## 经验教训
+
+1. **UI设计要明确**：技术术语需要配合说明文字和示例
+2. **配置验证很重要**：关键配置应在前后端都进行验证
+3. **错误提示要友好**：技术错误信息要转化为用户能理解的语言
+4. **自动修复优于报错**：能自动修正的就不要让用户手动修改
+
+## 后续优化建议
+
+1. 添加配置模板功能（一键应用推荐配置）
+2. 添加配置导入/导出功能
+3. 在UI中添加"配置检查"按钮，诊断常见问题
+4. 改进日志输出，更容易定位配置问题