map-client-vue/MODEL_HEALTH_CHECK.md

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

📋 功能概述

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

🎯 功能特性

1. 健康检测

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

2. 检测按钮

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

🔧 实现细节

后端服务 (modelServiceManager.ts)

1. 单模型健康检测

async testModelHealth(service: ModelService, modelId: string): Promise<{
  modelId: string
  available: boolean
  latency?: number
  error?: string
}>

功能:

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

返回:

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

2. 批量健康检测

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. 状态管理

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

2. 健康检测函数

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)

• ✅ 实现单模型健康检测
• ✅ 实现批量健康检测
• ✅ 添加进度追踪界面
• ✅ 添加详细结果展示
• ✅ 自动过滤不可用模型
• ✅ 集成到服务下拉菜单