# 模型服务功能实现文档

## 📋 概述

本文档记录了模型服务功能的完整实现，包括真实的API连接、模型获取和聊天功能。

**实现日期**: 2025-10-14  
**版本**: 1.0.1

---

## 🎯 实现功能

### ✅ 核心功能

#### 1. 真实API连接
- **HTTP请求**: 使用 Fetch API 进行实际的网络请求
- **多服务支持**: OpenAI、Claude、Gemini、Azure OpenAI、本地模型、自定义API
- **超时控制**: 10秒连接超时，避免长时间等待
- **错误处理**: 完整的错误捕获和用户友好的错误信息

#### 2. 服务管理
- **添加服务**: 配置服务名称、类型、URL、API密钥
- **编辑服务**: 修改现有服务配置
- **删除服务**: 移除不需要的服务
- **连接/断开**: 实时管理服务连接状态

#### 3. 模型获取
- **自动获取**: 连接成功后自动获取可用模型列表
- **格式适配**: 支持不同服务的API响应格式
- **实时显示**: 在UI中展示可用模型

#### 4. 状态管理
- **连接状态**: connected、disconnected、connecting、error
- **本地存储**: 自动保存和恢复服务配置
- **错误信息**: 详细的错误提示和诊断建议

---

## 🏗️ 技术架构

### 文件结构

```
web/src/
├── services/
│   └── modelServiceManager.ts     # 模型服务管理器
├── components/
│   └── ModelService.vue           # 模型服务UI组件
└── SimpleApp.vue                  # 主应用（已集成）
```

### 核心类：ModelServiceManager

**职责**:
- 管理所有模型服务实例
- 处理API连接和请求
- 格式转换和响应解析
- 单例模式，全局访问

**主要方法**:

```typescript
// 测试连接
async testConnection(service: ModelService): Promise<ApiResponse<{ models: string[] }>>

// 获取模型列表
private async fetchModels(service: ModelService): Promise<string[]>

// 发送聊天请求
async sendChatRequest(serviceId: string, messages: any[], model: string): Promise<ApiResponse<any>>

// 连接/断开服务
async connectService(serviceId: string): Promise<void>
disconnectService(serviceId: string): void
```

---

## 🔌 API 集成

### 1. OpenAI / 本地模型

**端点**: `{url}/models`  
**认证**: `Authorization: Bearer {apiKey}`

**响应格式**:
```json
{
  "data": [
    { "id": "gpt-4", "object": "model" },
    { "id": "gpt-3.5-turbo", "object": "model" }
  ]
}
```

**聊天端点**: `{url}/chat/completions`

---

### 2. Claude (Anthropic)

**端点**: 无公开模型列表API（使用预定义列表）  
**认证**: 
- `x-api-key: {apiKey}`
- `anthropic-version: 2023-06-01`

**预定义模型**:
- claude-3-5-sonnet-20241022
- claude-3-haiku-20240307
- claude-3-sonnet-20240229
- claude-3-opus-20240229

**聊天端点**: `{url}/messages`

**消息格式转换**:
```typescript
// OpenAI格式 → Claude格式
messages.filter(m => m.role !== 'system')
  .map(m => ({
    role: m.role === 'assistant' ? 'assistant' : 'user',
    content: m.content
  }))
```

---

### 3. Google Gemini

**端点**: `{url}/models?key={apiKey}`  
**认证**: URL参数传递

**响应格式**:
```json
{
  "models": [
    { "name": "models/gemini-pro" },
    { "name": "models/gemini-1.5-pro" }
  ]
}
```

**聊天端点**: `{url}/models/{model}:generateContent?key={apiKey}`

**消息格式转换**:
```typescript
messages.filter(m => m.role !== 'system')
  .map(m => ({
    role: m.role === 'assistant' ? 'model' : 'user',
    parts: [{ text: m.content }]
  }))
```

---

### 4. Azure OpenAI

**端点**: `{url}/openai/deployments?api-version=2023-12-01-preview`  
**认证**: `api-key: {apiKey}`

**响应格式**:
```json
{
  "data": [
    { "id": "gpt-4-deployment", "model": "gpt-4" },
    { "id": "gpt-35-turbo-deployment", "model": "gpt-3.5-turbo" }
  ]
}
```

**聊天端点**: `{url}/openai/deployments/{model}/chat/completions?api-version=2023-12-01-preview`

---

### 5. 自定义API

**端点**: `{url}/models`  
**认证**: 通过自定义配置 JSON 指定

**自定义配置示例**:
```json
{
  "headers": {
    "X-Custom-Auth": "token",
    "X-API-Version": "v1"
  },
  "timeout": 30000
}
```

**支持的响应格式**:
- `{ models: [...] }`
- `{ data: [...] }`
- `[...]` (数组格式)

---

## 💡 使用指南

### 添加服务

1. **点击"添加服务"按钮**
2. **填写配置信息**:
   - 服务名称：自定义名称
   - 服务类型：选择 OpenAI、Claude 等
   - 服务地址：API 端点 URL
   - API Key：服务密钥

3. **保存配置**

### 测试连接

1. **点击服务卡片上的"连接"按钮**
2. **系统将执行**:
   - 发送 HTTP 请求到模型列表端点
   - 验证 API 密钥
   - 获取可用模型
   - 显示测试结果

3. **查看结果**:
   - ✅ 成功：显示可用模型数量和列表
   - ❌ 失败：显示错误信息和诊断建议

### 管理服务

- **编辑**: 点击菜单 → 编辑
- **删除**: 点击菜单 → 删除
- **复制配置**: 点击菜单 → 复制配置
- **测试**: 点击菜单 → 测试连接

---

## 🛠️ 配置示例

### OpenAI

```json
{
  "name": "OpenAI GPT-4",
  "type": "openai",
  "url": "https://api.openai.com/v1",
  "apiKey": "sk-..."
}
```

### Claude

```json
{
  "name": "Claude 3",
  "type": "claude",
  "url": "https://api.anthropic.com/v1",
  "apiKey": "sk-ant-..."
}
```

### 本地 Ollama

```json
{
  "name": "本地 Ollama",
  "type": "local",
  "url": "http://localhost:11434/v1",
  "apiKey": "ollama"
}
```

### Azure OpenAI

```json
{
  "name": "Azure GPT-4",
  "type": "azure",
  "url": "https://your-resource.openai.azure.com",
  "apiKey": "your-azure-key"
}
```

---

## 🔍 错误处理

### 常见错误及解决方案

#### 1. 连接超时
**错误**: `连接超时`  
**原因**: 
- 网络问题
- 服务器响应慢
- URL 错误

**解决方案**:
- 检查网络连接
- 验证 URL 是否正确
- 尝试增加超时时间

---

#### 2. HTTP 401 未授权
**错误**: `HTTP 401: Unauthorized`  
**原因**: API 密钥无效或过期

**解决方案**:
- 检查 API 密钥是否正确
- 确认密钥未过期
- 重新生成新密钥

---

#### 3. HTTP 403 禁止访问
**错误**: `HTTP 403: Forbidden`  
**原因**: 
- API 密钥权限不足
- IP 限制
- 配额超限

**解决方案**:
- 检查 API 密钥权限
- 确认 IP 白名单
- 查看账户配额

---

#### 4. HTTP 404 未找到
**错误**: `HTTP 404: Not Found`  
**原因**: API 端点错误

**解决方案**:
- 检查 URL 格式
- 确认 API 版本
- 参考官方文档

---

#### 5. CORS 错误
**错误**: `Failed to fetch` 或 CORS 相关错误  
**原因**: 浏览器同源策略限制

**解决方案**:
- 使用代理服务器
- 配置 CORS 头
- 使用本地开发服务器

---

## 🎨 UI 组件

### ModelService.vue

**功能**:
- 服务列表展示
- 添加/编辑/删除服务
- 连接测试
- 模型列表显示

**状态指示**:
- 🟢 已连接 (绿色)
- 🔴 未连接 (红色)
- 🟡 连接中 (黄色)
- 🔴 错误 (红色)

**交互操作**:
- 点击连接按钮：切换连接状态
- 点击菜单：显示操作选项
- 点击编辑：打开编辑模态框
- 点击测试：执行连接测试

---

## 📊 数据存储

### localStorage 键

**键名**: `model-services`  
**格式**: JSON 数组

**示例数据**:
```json
[
  {
    "id": "1234567890",
    "name": "OpenAI",
    "type": "openai",
    "url": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "status": "connected",
    "models": ["gpt-4", "gpt-3.5-turbo"],
    "lastUsed": "2025-10-14T12:00:00.000Z"
  }
]
```

---

## 🔐 安全考虑

### API 密钥保护

1. **掩码显示**: UI 中只显示前后4位
2. **本地存储**: 密钥存储在浏览器 localStorage
3. **不发送到服务器**: 仅在浏览器中使用
4. **HTTPS**: 建议使用 HTTPS 连接

**注意事项**:
- ⚠️ localStorage 不是最安全的存储方式
- ⚠️ 不要在公共设备上保存密钥
- ⚠️ 定期更换 API 密钥
- ⚠️ 避免在代码中硬编码密钥

---

## 🚀 未来改进

### 短期计划
- [ ] 添加模型选择功能
- [ ] 实现聊天历史记录
- [ ] 支持流式响应
- [ ] 添加更多服务类型

### 长期计划
- [ ] 加密存储 API 密钥
- [ ] 多账户管理
- [ ] 使用统计和费用跟踪
- [ ] 批量导入/导出配置

---

## 📝 更新日志

### v1.0.1 - 2025-10-14

#### 新增功能
- ✅ 真实API连接实现
- ✅ 多服务类型支持 (OpenAI、Claude、Gemini、Azure、Local)
- ✅ 模型自动获取
- ✅ 连接状态管理
- ✅ 错误处理和诊断

#### 技术改进
- ✅ ModelServiceManager 单例类
- ✅ 类型安全的 TypeScript 实现
- ✅ 响应式 Vue 3 组件
- ✅ 本地存储持久化

#### UI优化
- ✅ 服务卡片布局
- ✅ 状态标签指示
- ✅ 测试连接模态框
- ✅ 错误信息展示

---

## 🤝 贡献

欢迎贡献代码和提出建议！

**联系方式**:
- GitHub Issues: [项目地址]
- Email: [联系邮箱]

---

## 📚 参考文档

- [OpenAI API 文档](https://platform.openai.com/docs/api-reference)
- [Claude API 文档](https://docs.anthropic.com/claude/reference)
- [Gemini API 文档](https://ai.google.dev/docs)
- [Azure OpenAI 文档](https://learn.microsoft.com/azure/ai-services/openai/)

---

**MCP Client Vue - 模型服务功能** 🚀