# 模型配置管理业务设计

## 概述

模型配置管理是一个多层级模型配置系统，支持平台级、项目级、用户级三个层级的模型配置。各级配置独立管理，模型列表累加可见，默认模型按优先级链确定。

## 核心业务规则

### 模型配置层级结构

```mermaid
graph TB
    subgraph Platform["平台级模型配置 (Platform Level)"]
        P1[配置者: 平台管理员]
        P2[可见性: 所有用户可见]
        P3[用途: 作为所有用户的基础模型池]
        P4[默认模型: 平台默认模型]
    end

    subgraph Project["项目级模型配置 (Project Level)"]
        Pr1[配置者: 项目管理员]
        Pr2[可见性: 仅项目成员可见]
        Pr3[用途: 项目专用模型, 覆盖平台默认]
        Pr4[默认模型: 项目默认模型]
    end

    subgraph User["用户级模型配置 (User Level)"]
        U1[配置者: 用户自己]
        U2[可见性: 仅自己可见]
        U3[用途: 用户自定义模型, 覆盖项目/平台默认]
        U4[默认模型: 个人默认模型]
    end

    Platform -->|继承| Project
    Project -->|继承| User
```

### 权限边界

- **完全隔离**：各级别只能管理本级别的模型配置
  - 平台管理员：只能管理平台级模型配置
  - 项目管理员：只能管理本项目模型配置
  - 普通用户：只能管理个人模型配置
- **不可干预**：平台管理员不可干预项目级或用户级模型配置
- **菜单可见性**：项目成员看不到"模型管理"菜单（仅项目管理员可见）
- **安全性**：模型调用由服务端统一处理，API密钥不暴露给前端

### 模型可见性规则

- **平台模型**：所有用户可见
- **项目模型**：仅项目成员可见
- **个人模型**：仅自己可见
- **跨项目隔离**：项目X的模型在项目Y内不可见
- **累加模式**：用户可选模型 = 平台模型 ∪ 当前项目模型 ∪ 个人模型

### 模型选择规则

#### 可选模型范围

用户在项目X内：
```
可选模型 = 平台模型 ∪ 项目X模型 ∪ 个人模型
```

#### 默认模型优先级链

新建对话时：
```
默认模型 = 个人默认 ∨ 项目默认 ∨ 平台默认
```

已有对话时：
```
使用模型 = 上次使用的模型
```

模型失效时：
```
回退到默认模型优先级链 → 个人默认 ∨ 项目默认 ∨ 平台默认
```

### 默认模型规则

- **自动设置**：新增第一个模型时，自动设为默认模型
- **删除规则**：
  - **平台级**：默认模型不允许直接删除，必须先将另一个模型设为默认，然后才能删除
  - **项目级**：允许删除默认模型，删除后该级别没有默认模型
  - **用户级**：允许删除默认模型，删除后该级别没有默认模型
- **配置数量**：各级别不限制模型配置数量
- **空列表处理**：没有任何模型时，用户可以新建对话，但对话输入框的模型下拉列表为空

### 跨项目对话隔离

对话列表按项目维度隔离：
- 在项目A的对话列表中，只能看到项目A的对话
- 切换到项目B后，在项目B的对话列表中只能看到项目B的对话
- 不同项目的对话互不可见

## 配置内容

### 配置字段

所有级别的模型配置包含相同的字段：

#### 基本信息
- 配置名称（必填）
- 配置类型（必填，新建时可选，编辑时只读）
  - OpenAI 兼容接口
  - 智算管理平台

#### API配置（根据类型不同）

**OpenAI 兼容接口**：
- API地址（必填）
- API密钥（必填，掩码显示）
- 模型名称（必填）

**智算管理平台**：
- API地址（必填）
- App ID（必填）
- App Secret（必填，掩码显示）

#### 参数配置（仅OpenAI兼容接口）
- Temperature（0-2，默认0.7）
- Max Tokens（1-128000，默认4096）
- Top P（0-1，默认0.9）

## 附录：常见问题

### 📋 模型可见性问题

#### 1. 用户在项目内能看到哪些模型？模型可见性有哪些规则？

用户在项目X内可见的模型采用累加模式：
```
可选模型 = 平台模型 ∪ 项目X模型 ∪ 个人模型
```

**可见性规则**：
- **跨项目隔离**：项目X的模型在项目Y内不可见
- **多项目差异**：用户在不同项目内看到的模型列表不同（平台模型和个人模型在所有项目可见，项目模型仅在本项目可见）
- **移出项目**：用户被移出项目后，项目模型从列表消失，但数据保留；重新加入后恢复可见
- **项目成员权限**：项目模型对所有成员可见，但只有管理员能管理，普通成员只能使用
- **模型下拉列表展示**：同名配置在模型下拉列表中会分组展示

### 🎯 默认模型问题

#### 2. 新增第一个模型时需要手动设为默认吗？

不需要。系统会自动将新增的第一个模型设为默认模型。各级别模型配置都遵循此规则：
- 平台新增第一个模型 → 自动设为平台默认
- 项目新增第一个模型 → 自动设为项目默认
- 用户新增第一个模型 → 自动设为个人默认

#### 3. 默认模型可以删除吗？

根据配置级别不同，删除规则不同：

- **平台级**：默认模型不允许直接删除，必须先将另一个模型设为默认，然后才能删除原来的默认模型

- **项目级**：允许删除默认模型，删除后该级别没有默认模型

- **用户级**：允许删除默认模型，删除后该级别没有默认模型

#### 4. 如果某个级别没有配置任何模型，会怎样？

如果某个级别没有配置任何模型，该级别的默认模型为空，系统会按优先级链继续向上查找：
- 用户没有个人模型 → 使用项目默认模型
- 项目没有项目模型 → 使用平台默认模型
- 如果平台也没有模型 → 用户可以新建对话，但对话输入框的模型下拉列表为空

#### 5. 项目管理员想更换项目默认模型，原来的默认模型会怎样？对已有对话有影响吗？

项目管理员将模型B设为新的默认模型后：
- 原默认模型A变为普通模型（is_default = false）
- 模型B变为新的默认模型（is_default = true）

原默认模型A不会被删除，仍然在项目模型列表中，项目成员可以继续使用。

已有对话不受影响，继续使用对话创建时选择的模型。

### ⚙️ 配置管理问题

#### 6. 平台管理员能编辑或删除项目级、用户级的模型配置吗？

不能。各级模型配置权限完全隔离：
- 平台管理员：只能管理平台级模型配置
- 项目管理员：只能管理本项目模型配置
- 用户：只能管理个人模型配置

平台管理员无法查看、编辑、删除项目级或用户级的模型配置，确保各级模型配置的独立性和安全性。

#### 7. 项目管理员能看到项目成员的个人模型配置吗？

不能。个人模型配置仅用户自己可见，项目管理员无法查看或管理项目成员的个人模型。

用户在项目内使用个人模型时，项目管理员只知道用户选择了某个模型，但无法查看模型的配置详情（如API密钥）。

#### 8. 编辑模型配置时，配置类型可以修改吗？

不可以。配置类型（OpenAI 兼容接口 / 智算管理平台）在新建时选择，保存后不可修改。

编辑模型配置时，配置类型字段为只读状态，只能修改其他字段（如API地址、密钥、参数等）。

如果需要更换配置类型，必须删除原模型配置，重新创建新模型配置。删除已被对话使用的模型配置后，该对话会失效并触发模型回退逻辑。

#### 9. 配置名称可以重复吗？

可以。配置名称仅用于展示和区分，不要求唯一性。同一个级别下可以有多个同名配置，但建议使用有区分度的名称便于管理。

系统通过配置ID唯一标识模型，不依赖名称唯一性。同名配置在模型下拉列表中会分组展示。

### 🔐 安全性问题

#### 10. 项目成员能看到项目模型的API密钥吗？

不能。项目成员看不到"模型管理"菜单，无法访问模型配置页面，因此无法查看API密钥。

只有项目管理员能查看和管理项目模型的配置详情（包括API密钥），且密钥在表单中默认掩码显示，需要点击显示按钮才能查看明文。

#### 11. 不同级别的模型配置，API密钥存储方式有区别吗？

没有区别。所有级别的模型配置，API密钥都存储在服务端数据库中，存储方式一致，安全级别一致。前端只知道模型ID，从未接触API密钥。

### ❓ 其他问题

#### 12. 用户在项目X内使用项目模型D创建对话，后来项目模型D被删除，用户继续这个对话时会使用哪个模型？

系统会自动切换到默认模型（按优先级链）：
```
个人默认 → 项目X默认 → 平台默认
```

用户打开对话时，系统检测到模型D已失效，自动切换并提示："原模型已失效，已切换为XXX"。后续新消息使用切换后的模型，历史消息保持不变。

#### 13. 用户在项目X内使用个人模型D创建对话，后来用户被移出项目X，个人模型D会被删除吗？

不会被删除。个人模型是用户级别的模型配置，跟着用户走，不会因为被移出项目就被删除。用户在其他项目仍然可以使用个人模型D。

*最后更新：2026-04-10*