Initial qiwei secondary development handoff
This commit is contained in:
169
config/docs/BUG_FIX_MODEL_CONFIG.md
Normal file
169
config/docs/BUG_FIX_MODEL_CONFIG.md
Normal file
@@ -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` - 单元测试
|
||||
149
config/docs/BUG_FIX_SUMMARY.md
Normal file
149
config/docs/BUG_FIX_SUMMARY.md
Normal file
@@ -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. 改进日志输出，更容易定位配置问题
|
||||
101
config/docs/用户通知_知识库配置修复.md
Normal file
101
config/docs/用户通知_知识库配置修复.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# 知识库配置修复通知
|
||||
|
||||
## 问题说明
|
||||
|
||||
如果您遇到以下情况：
|
||||
- ✅ 知识库文件显示10个，但查询时AI只能看到2个
|
||||
- ✅ 知识库页面出现错误：`Unsupported model 'gte-rerank-v2' for OpenAI compatibility mode`
|
||||
|
||||
**这是因为模型配置填写错误导致的。**
|
||||
|
||||
## 问题原因
|
||||
|
||||
**Embedding 模型** 和 **Rerank 模型** 填写混淆了！
|
||||
|
||||
### 错误配置示例 ❌
|
||||
```
|
||||
Embedding 模型: gte-rerank-v2 ← 这是Rerank模型，填错了！
|
||||
Rerank 模型: qwen3-rerank ← 正确
|
||||
```
|
||||
|
||||
### 正确配置示例 ✓
|
||||
```
|
||||
Embedding 模型: text-embedding-v4 ← 正确：用于文本向量化
|
||||
Rerank 模型: qwen3-rerank ← 正确：用于结果重排序
|
||||
```
|
||||
|
||||
## 如何修复
|
||||
|
||||
### 方法1：自动修复（推荐）
|
||||
|
||||
更新到最新版本后：
|
||||
1. 系统会自动检测并修正错误配置
|
||||
2. 打开"自动客服"页面
|
||||
3. 进入"知识库"模块
|
||||
4. 点击"重建索引"按钮
|
||||
5. 等待重建完成（可能需要几分钟）
|
||||
|
||||
### 方法2：手动修复
|
||||
|
||||
1. 打开"自动客服"页面
|
||||
2. 进入"知识库"模块
|
||||
3. 找到模型配置区域
|
||||
4. 将 **Embedding 模型** 改为：`text-embedding-v4`
|
||||
5. 将 **Rerank 模型** 改为：`qwen3-rerank`（如果之前填写的是embedding模型）
|
||||
6. 点击"保存配置"
|
||||
7. 点击"重建索引"
|
||||
|
||||
## 模型选择指南
|
||||
|
||||
### Embedding 模型（文本向量化）
|
||||
推荐使用以下模型之一：
|
||||
- `text-embedding-v4` （推荐，512维）
|
||||
- `text-embedding-v3` （1024维）
|
||||
- `bge-large-zh`
|
||||
- `gte-large`
|
||||
|
||||
### Rerank 模型（结果重排序）
|
||||
推荐使用以下模型之一：
|
||||
- `qwen3-rerank` （推荐）
|
||||
- `gte-rerank-v2`
|
||||
- `bge-rerank-large`
|
||||
|
||||
## 新版本改进
|
||||
|
||||
最新版本包含以下改进：
|
||||
1. ✨ 自动检测并修正错误的模型配置
|
||||
2. ✨ 更友好的错误提示信息
|
||||
3. ✨ 输入框下方添加了说明文字和示例
|
||||
4. ✨ 保存前会验证配置是否正确
|
||||
|
||||
## 注意事项
|
||||
|
||||
⚠️ **不要将模型名称混淆**：
|
||||
- Embedding 模型通常包含 "embedding" 关键词
|
||||
- Rerank 模型通常包含 "rerank" 关键词
|
||||
|
||||
⚠️ **重建索引需要时间**：
|
||||
- 10个MD文件大约需要1-3分钟
|
||||
- 重建期间不影响正常使用
|
||||
- 重建完成后查询结果会更准确
|
||||
|
||||
## 验证修复
|
||||
|
||||
修复后，可以通过以下方式验证：
|
||||
|
||||
1. 查看"知识库"模块的状态
|
||||
- 知识文件数量应显示正确（如：10个）
|
||||
- 知识片段数量应显示正确（如：389个）
|
||||
- 向量片段数量应与知识片段相同或接近
|
||||
|
||||
2. 测试查询
|
||||
- 询问："现在知识库有哪些文件"
|
||||
- AI应该能列出所有10个文件
|
||||
- 不应再出现404错误
|
||||
|
||||
## 技术支持
|
||||
|
||||
如果按照以上步骤操作后问题仍未解决，请联系技术支持并提供：
|
||||
1. 错误截图
|
||||
2. 当前的模型配置截图
|
||||
3. 日志文件（Log目录下的最新日志）
|
||||
Reference in New Issue
Block a user