473 lines
9.1 KiB
Markdown
473 lines
9.1 KiB
Markdown
# 模型服务功能实现文档
|
||
|
||
## 📋 概述
|
||
|
||
本文档记录了模型服务功能的完整实现，包括真实的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 - 模型服务功能** 🚀
|