150 lines
4.9 KiB
Markdown
150 lines
4.9 KiB
Markdown
# 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. 改进日志输出，更容易定位配置问题
|