qiweimanager-master/config/docs/BUG_FIX_SUMMARY.md

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

测试结果

$ 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. 改进日志输出，更容易定位配置问题