# 模型健康检测功能实现文档

## 📋 功能概述

为模型服务页面添加了"健康检测"功能,可以对服务中的所有模型进行可用性测试,自动过滤不可用的模型。

## 🎯 功能特性

### 1. 健康检测
- **批量检测**: 自动测试服务中所有模型的可用性
- **实时进度**: 显示当前检测进度和正在测试的模型
- **详细结果**: 展示每个模型的健康状态、延迟时间和错误信息
- **自动过滤**: 检测完成后自动更新服务配置,只保留可用模型

### 2. 检测按钮
- **表单检测**: API Key 输入框旁边的"检测"按钮,用于添加/编辑服务时快速验证
- **健康检测**: 服务卡片下拉菜单中的"健康检测"选项,用于已配置服务的模型筛选

## 🔧 实现细节

### 后端服务 (`modelServiceManager.ts`)

#### 1. 单模型健康检测
```typescript
async testModelHealth(service: ModelService, modelId: string): Promise<{
  modelId: string
  available: boolean
  latency?: number
  error?: string
}>
```

**功能**:
- 发送最小测试请求 (消息: "hi")
- 记录响应延迟
- 捕获错误信息

**返回**:
- `modelId`: 模型ID
- `available`: 是否可用
- `latency`: 响应延迟(毫秒)
- `error`: 错误信息(如果失败)

#### 2. 批量健康检测
```typescript
async healthCheckAllModels(
  service: ModelService,
  onProgress?: (current: number, total: number, modelId: string) => void
): Promise<{
  availableModels: string[]
  unavailableModels: string[]
  results: Array<{...}>
}>
```

**功能**:
- 遍历所有模型进行测试
- 实时回调进度信息
- 添加200ms延迟避免请求过快
- 统计可用和不可用模型

**返回**:
- `availableModels`: 可用模型列表
- `unavailableModels`: 不可用模型列表
- `results`: 详细测试结果

### 前端组件 (`ModelService.vue`)

#### 1. 状态管理
```typescript
const healthCheckResult = reactive({
  status: 'idle' | 'checking' | 'success' | 'error',
  currentService: ModelService | null,
  progress: { current: 0, total: 0, modelId: '' },
  availableModels: string[],
  unavailableModels: string[],
  results: Array<{...}>
})
```

#### 2. 健康检测函数
```typescript
const healthCheckModels = async (service: ModelService) => {
  // 1. 显示检测模态框
  showHealthCheckModal.value = true
  healthCheckResult.status = 'checking'
  
  // 2. 执行批量检测
  const result = await modelServiceManager.healthCheckAllModels(
    service,
    (current, total, modelId) => {
      // 更新进度
      healthCheckResult.progress = { current, total, modelId }
    }
  )
  
  // 3. 更新服务配置
  service.models = result.availableModels
  saveServices()
  
  // 4. 显示结果
  healthCheckResult.status = 'success'
}
```

#### 3. UI 组件

**健康检测模态框**:
- **检测中状态**:
  - 加载动画
  - 进度条
  - 当前测试模型信息
  
- **完成状态**:
  - 汇总卡片 (可用/不可用数量)
  - 可用模型列表 (带延迟时间)
  - 不可用模型列表 (带错误信息)
  - 自动更新提示

## 📊 使用流程

### 1. 添加服务时检测
```
1. 点击"添加服务"
2. 填写服务信息
3. 点击 API Key 旁的"检测"按钮
4. 查看检测到的模型列表
5. 保存服务
```

### 2. 健康检测已有服务
```
1. 找到已配置的服务卡片
2. 点击右上角的"..."菜单
3. 选择"健康检测"
4. 等待检测完成
5. 查看详细结果
6. 自动更新为只包含可用模型
```

## 🎨 UI 设计

### 检测进度界面
```
┌─────────────────────────────────┐
│   模型健康检测                   │
├─────────────────────────────────┤
│                                 │
│         [Loading Spinner]        │
│     正在检测模型健康状态...      │
│                                 │
│     当前进度: 25 / 135          │
│     当前模型: qwen-max          │
│                                 │
│   ████████░░░░░░░░░░ 18.5%      │
│                                 │
└─────────────────────────────────┘
```

### 检测结果界面
```
┌─────────────────────────────────┐
│   模型健康检测                   │
├─────────────────────────────────┤
│              ✓                   │
│        健康检测完成              │
│                                 │
│  ┌──────────┐  ┌──────────┐    │
│  │    ✓     │  │    ✗     │    │
│  │   120    │  │    15    │    │
│  │ 可用模型  │  │不可用模型 │    │
│  └──────────┘  └──────────┘    │
│                                 │
│  ✓ 可用模型 (120)               │
│  [qwen-max 250ms] [gpt-4 180ms] │
│  [claude-3 320ms] ...           │
│                                 │
│  ✗ 不可用模型 (15)              │
│  [old-model] [deprecated] ...   │
│                                 │
│  ℹ️ 已自动更新服务配置,只保留    │
│     可用模型                     │
└─────────────────────────────────┘
```

## 💡 技术亮点

### 1. 进度追踪
- 实时更新检测进度
- 显示当前测试的模型
- 进度条可视化

### 2. 性能优化
- 添加200ms延迟避免过快请求
- 异步处理不阻塞UI
- 支持大量模型检测

### 3. 用户体验
- 清晰的状态反馈
- 详细的错误信息
- 自动保存检测结果

### 4. 数据统计
- 可用/不可用模型计数
- 响应延迟统计
- 错误原因记录

## 🔍 参考实现

本功能参考了 Cherry Studio 的健康检测功能:
- 位置: API 地址输入框旁边的"健康检测"按钮
- 功能: 测试所有模型并过滤不可用的

## 📝 注意事项

1. **测试时间**: 模型数量较多时检测时间较长
2. **API 限制**: 注意服务商的 API 调用频率限制
3. **网络稳定**: 需要稳定的网络连接
4. **自动更新**: 检测后会自动更新模型列表

## 🚀 未来优化

1. **并发检测**: 支持多模型并发测试(需控制并发数)
2. **缓存结果**: 缓存检测结果避免重复测试
3. **定时检测**: 支持定时自动健康检测
4. **通知提醒**: 检测完成后发送通知

## 📌 更新日志

**v1.0.0** (2025-10-14)
- ✅ 实现单模型健康检测
- ✅ 实现批量健康检测
- ✅ 添加进度追踪界面
- ✅ 添加详细结果展示
- ✅ 自动过滤不可用模型
- ✅ 集成到服务下拉菜单