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`

**返回参数：**
```json
{
  "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`

**请求参数：**
```json
{
  "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"
}
```

**返回参数：**
```json
{
  "id": "1",
  "name": "OpenAI",
  "model_type": "chat",
  ...
}
```

### 3. 更新模型

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

**请求参数：**
```json
{
  "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}`

**返回参数：**
```json
{
  "success": true
}
```

### 5. 测试连接

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

**请求参数：**
```json
{
  "provider": "OpenAI",
  "model": "gpt-4o",
  "api_key": "sk-xxx",
  "base_url": "https://api.openai.com",
  "api_endpoint": "/v1/chat/completions"
}
```

**返回参数：**
```json
{
  "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)
```typescript
{
  name: string,
  apiKey: string,
  apiEndpoint: string,
  baseUrl: string,
  provider: string,
  model: string,
  modelType: string
}
```

### 模型类型选项 (modelTypeOptions)
- Chat
- Embedding
- Rerank
- VLM

### 提供商选项 (providerOptions)
- OpenAI
- Ollama