170 lines
5.5 KiB
Markdown
170 lines
5.5 KiB
Markdown
# 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` - 单元测试
|