# 模型目录快速开始

## 🎯 问题

之前模型名称是硬编码在前端代码中的，每次添加新模型都需要修改代码并重启服务。

## ✅ 解决方案

现在模型目录存储在 MongoDB 数据库中，可以通过前端界面或 API 动态管理。

## 🚀 快速开始

### 1. 初始化模型目录

在项目根目录执行：

```bash
python scripts/init_model_catalog.py
```

这会在数据库中创建默认的模型目录，包含 7 个厂家共 31 个模型。

### 2. 访问管理界面

1. 启动前端和后端服务
2. 访问：`http://localhost:3001`
3. 登录系统
4. 进入：**设置 → 系统配置 → 配置管理 → 模型目录**

### 3. 管理模型目录

#### 添加新模型

1. 点击对应厂家的"编辑"按钮
2. 点击"添加模型"
3. 填写：
   - **模型名称**：如 `qwen-2.5-72b`
   - **显示名称**：如 `Qwen 2.5 72B - 超大参数`
4. 点击"保存"

#### 添加新厂家

1. 点击"添加厂家模型目录"
2. 填写：
   - **厂家标识**：如 `mistral`
   - **厂家名称**：如 `Mistral AI`
3. 添加模型
4. 点击"保存"

## 📊 数据流程

```
┌──────────────────────────────────────────────────────────┐
│  1. 管理员维护模型目录                                      │
│     (设置 → 配置管理 → 模型目录)                           │
└────────────────┬─────────────────────────────────────────┘
                 │
                 ↓
┌──────────────────────────────────────────────────────────┐
│  2. 模型目录存储在 MongoDB                                 │
│     (model_catalog 集合)                                  │
└────────────────┬─────────────────────────────────────────┘
                 │
                 ↓
┌──────────────────────────────────────────────────────────┐
│  3. 用户添加大模型配置时                                    │
│     (设置 → 配置管理 → 大模型配置 → 添加)                  │
│     - 选择厂家                                            │
│     - 从模型目录中选择模型（或手动输入）                    │
│     - 配置参数（API密钥、温度等）                          │
└────────────────┬─────────────────────────────────────────┘
                 │
                 ↓
┌──────────────────────────────────────────────────────────┐
│  4. 用户配置保存到数据库                                    │
│     (system_configs.llm_configs)                          │
└──────────────────────────────────────────────────────────┘
```

## 🎨 界面预览

### 模型目录管理页面

```
┌─────────────────────────────────────────────────────────┐
│  模型目录管理                    [+ 添加厂家模型目录]      │
├─────────────────────────────────────────────────────────┤
│  厂家标识  │ 厂家名称  │ 模型数量 │ 模型列表  │ 操作      │
├─────────────────────────────────────────────────────────┤
│  dashscope │ 通义千问  │ 8个模型  │ Qwen...   │ 编辑 删除 │
│  openai    │ OpenAI   │ 5个模型  │ GPT-4...  │ 编辑 删除 │
│  google    │ Gemini   │ 4个模型  │ Gemini... │ 编辑 删除 │
└─────────────────────────────────────────────────────────┘
```

### 添加大模型配置（使用模型目录）

```
┌─────────────────────────────────────────────────────────┐
│  添加大模型配置                                           │
├─────────────────────────────────────────────────────────┤
│  厂家：        [通义千问 ▼]                              │
│                                                          │
│  模型名称：    [Qwen Turbo - 快速经济 ▼]                 │
│                ↑ 从模型目录自动加载                       │
│                💡 可以从列表中选择，也可以直接输入         │
│                                                          │
│  API密钥：     [sk-*********************]                │
│  最大Token：   [4000]                                    │
│  温度：        [0.7]                                     │
│                                                          │
│                                    [取消]  [保存]        │
└─────────────────────────────────────────────────────────┘
```

## 🔧 维护流程

### 当厂家发布新模型时

1. **访问模型目录管理页面**
2. **找到对应厂家，点击"编辑"**
3. **点击"添加模型"**
4. **填写模型信息**：
   ```
   模型名称：qwen-2.5-72b
   显示名称：Qwen 2.5 72B - 超大参数
   ```
5. **点击"保存"**
6. **完成！** 用户立即可以在添加配置时看到新模型

### 当模型被废弃时

1. **编辑对应的模型目录**
2. **修改显示名称**，添加"(已废弃)"标记：
   ```
   显示名称：Qwen Old Model (已废弃)
   ```
3. **保存**

## 📝 API 使用示例

### 获取模型目录

```bash
curl -X GET http://localhost:8000/api/config/model-catalog \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 添加新模型到目录

```bash
curl -X POST http://localhost:8000/api/config/model-catalog \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "dashscope",
    "provider_name": "通义千问",
    "models": [
      {
        "name": "qwen-turbo",
        "display_name": "Qwen Turbo - 快速经济"
      },
      {
        "name": "qwen-2.5-72b",
        "display_name": "Qwen 2.5 72B - 超大参数"
      }
    ]
  }'
```

## 🎉 优势

### 之前（硬编码）

❌ 添加新模型需要修改代码  
❌ 需要重启服务才能生效  
❌ 不支持通过界面管理  
❌ 维护困难

### 现在（数据库存储）

✅ 通过界面动态添加模型  
✅ 立即生效，无需重启  
✅ 支持前端界面管理  
✅ 易于维护和更新  
✅ 支持批量管理  
✅ 支持 API 操作

## 🔍 常见问题

### Q: 修改模型目录会影响现有配置吗？

**A:** 不会。模型目录只是提供可选列表，用户的实际配置独立存储在 `system_configs.llm_configs` 中。

### Q: 如果模型不在目录中，还能使用吗？

**A:** 可以。用户仍然可以手动输入任意模型名称，模型目录只是提供便利，不是强制约束。

### Q: 如何备份模型目录？

**A:** 可以通过 MongoDB 导出 `model_catalog` 集合：
```bash
mongoexport --db=tradingagents --collection=model_catalog --out=model_catalog_backup.json
```

### Q: 如何恢复模型目录？

**A:** 可以通过 MongoDB 导入：
```bash
mongoimport --db=tradingagents --collection=model_catalog --file=model_catalog_backup.json
```

或者重新运行初始化脚本：
```bash
python scripts/init_model_catalog.py
```

## 📚 相关文档

- [详细管理指南](./MODEL_CATALOG_MANAGEMENT.md) - 完整的功能说明和 API 文档
- [配置管理指南](./CONFIGURATION_GUIDE.md) - 系统配置管理
- [大模型配置说明](./LLM_CONFIGURATION.md) - 大模型配置详解

## 🚀 下一步

1. ✅ 运行初始化脚本
2. ✅ 访问管理界面
3. ✅ 尝试添加/编辑模型
4. ✅ 测试添加大模型配置时的体验

祝使用愉快！ 🎊

