X-Agents/teams/web/model-settings.md

Model Settings 需求文档

需求概述

Model Settings 页面用于管理 AI 模型配置，支持添加、编辑、删除和测试模型连接。

功能列表

1. 模型列表展示

展示已配置的模型列表，包含以下字段：

• Model Name（模型名称）
• Model Type（模型类型）：Chat / Embedding / Rerank / VLM
• API Endpoint（API 端点）
• Status（状态）：Active / Inactive

2. 添加新模型

点击 "Add New Model" 按钮，弹出表单包含以下字段：

• Model Name（必填）
• Model Type（必选）：Chat / Embedding / Rerank / VLM
• Provider（必选）：OpenAI / Ollama
• Model（必填）：模型名称，如 gpt-4o
• API Key（必填）
• Base URL（必填）
• API Endpoint（可选）

3. 测试连接

在添加模型表单中提供 "Test Connection" 按钮，用于验证模型连接是否可用。

4. 编辑模型

点击编辑按钮，弹出编辑表单，可修改模型信息。

5. 删除模型

点击删除按钮，确认后删除模型记录。

---

后端接口需求

1. 获取模型列表

接口地址： GET /api/models 或 GET /model/list

返回参数：

{
  "list": [
    {
      "id": "1",
      "name": "OpenAI",
      "model_type": "chat",
      "provider": "OpenAI",
      "model": "gpt-4o",
      "api_key": "sk-xxx",
      "base_url": "https://api.openai.com",
      "api_endpoint": "/v1/chat/completions",
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

2. 添加模型

接口地址： POST /api/models 或 POST /model/add

请求参数：

{
  "name": "OpenAI",
  "model_type": "chat",
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions"
}

返回参数：

{
  "id": "1",
  "name": "OpenAI",
  "model_type": "chat",
  ...
}

3. 更新模型

接口地址： PUT /api/models/{id} 或 PUT /model/{id}

请求参数：

{
  "name": "OpenAI Updated",
  "model_type": "chat",
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions",
  "status": "active"
}

4. 删除模型

接口地址： DELETE /api/models/{id} 或 DELETE /model/{id}

返回参数：

{
  "success": true
}

5. 测试连接

接口地址： POST /api/models/test 或 POST /model/test

请求参数：

{
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions"
}

返回参数：

{
  "success": true,
  "message": "Connection successful"
}

---

数据结构

Model 表结构（参考）

字段	类型	说明
id	string	主键 UUID
name	string	模型名称
model_type	string	模型类型：chat/embedding/rerank/vlm
provider	string	提供商：OpenAI/Ollama
model	string	模型标识
api_key	string	API 密钥（加密存储）
base_url	string	基础 URL
api_endpoint	string	API 端点路径
status	string	状态：active/inactive
created_at	datetime	创建时间
updated_at	datetime	更新时间

---

前端组件状态

表单数据 (newModelForm)

{
  name: string,
  apiKey: string,
  apiEndpoint: string,
  baseUrl: string,
  provider: string,
  model: string,
  modelType: string
}

模型类型选项 (modelTypeOptions)

• Chat
• Embedding
• Rerank
• VLM

提供商选项 (providerOptions)

• OpenAI
• Ollama