gavin/map-client-vue

Fork 0

Files

douboer 4f5eea604e update at 2025-10-14 21:52:11

2025-10-14 21:52:11 +08:00

9.1 KiB

Raw Blame History

模型服务功能实现文档

📋 概述

本文档记录了模型服务功能的完整实现，包括真实的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连接和请求
格式转换和响应解析
单例模式，全局访问

主要方法:

// 测试连接
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}

响应格式:

{
  "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

消息格式转换:

// 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参数传递

响应格式:

{
  "models": [
    { "name": "models/gemini-pro" },
    { "name": "models/gemini-1.5-pro" }
  ]
}

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

消息格式转换:

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}

响应格式:

{
  "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 指定

自定义配置示例:

{
  "headers": {
    "X-Custom-Auth": "token",
    "X-API-Version": "v1"
  },
  "timeout": 30000
}

支持的响应格式:

{ models: [...] }
{ data: [...] }
[...] (数组格式)

💡 使用指南

添加服务

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

测试连接

点击服务卡片上的"连接"按钮
系统将执行:
- 发送 HTTP 请求到模型列表端点
- 验证 API 密钥
- 获取可用模型
- 显示测试结果
查看结果:
- ✅ 成功：显示可用模型数量和列表
- ❌ 失败：显示错误信息和诊断建议

管理服务

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

🛠️ 配置示例

OpenAI

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

Claude

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

本地 Ollama

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

Azure OpenAI

{
  "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 数组

示例数据:

[
  {
    "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 密钥保护

掩码显示: UI 中只显示前后4位
本地存储: 密钥存储在浏览器 localStorage
不发送到服务器: 仅在浏览器中使用
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: [联系邮箱]

📚 参考文档

MCP Client Vue - 模型服务功能 🚀

9.1 KiB Raw Blame History Unescape Escape

模型服务功能实现文档

📋 概述

🎯 实现功能

✅ 核心功能

1. 真实API连接

2. 服务管理

3. 模型获取

4. 状态管理

🏗️ 技术架构

文件结构

核心类：ModelServiceManager

🔌 API 集成

1. OpenAI / 本地模型

2. Claude (Anthropic)

3. Google Gemini

4. Azure OpenAI

5. 自定义API

💡 使用指南

添加服务

测试连接

管理服务

🛠️ 配置示例

OpenAI

Claude

本地 Ollama

Azure OpenAI

🔍 错误处理

常见错误及解决方案

1. 连接超时

2. HTTP 401 未授权

3. HTTP 403 禁止访问

4. HTTP 404 未找到

5. CORS 错误

🎨 UI 组件

ModelService.vue

📊 数据存储

localStorage 键

🔐 安全考虑

API 密钥保护

🚀 未来改进

短期计划

长期计划

📝 更新日志

v1.0.1 - 2025-10-14

新增功能

技术改进

UI优化

🤝 贡献

📚 参考文档

9.1 KiB

Raw Blame History