# LLM 多提供商配置管理 重构 PRD

> **版本**: v1.0
> **日期**: 2026-05-09
> **状态**: 📝 待评审

---

## 一、背景与动机

### 1.1 现状分析

当前 `/admin/settings` 页面采用**按调用协议（Anthropic / OpenAI）硬编码**的方式管理 LLM 配置：

| 层 | 文件 | 现状 |
|---|---|---|
| 存储 | settings.py | 12 个 `llm.*` key，按协议前缀分组 |
| 服务 | settings.py | `get_llm_config()` 硬编码两套，`get_active_provider_config()` 用 if/else 分支 |
| 调用 | llm.py | `chat_completion()` 按 `config["provider"]` 分发到 `_call_anthropic` / `_call_openai` |
| 路由 | admin.py | POST 接收 12 个独立 Form 字段 |
| 前端 | settings.html | 两张固定的 provider-card，点击切换 |

### 1.2 缺失的能力

| 场景 | 当前行为 | 期望行为 |
|------|----------|----------|
| 临时切换到另一个提供商 | 手动改 URL + Key + 模型名（3 个字段） | 一键切换 |
| 切换回来 | 再手动改 3 个字段 | 一键切换 |
| 某提供商同时支持两种协议 | 无法在一个配置下管理 | 同一提供商下可混合不同协议的模型 |
| 添加新的提供商 | 只能在 Anthropic 或 OpenAI 二选一 | 自定义添加任意数量的提供商 |

### 1.3 用户核心诉求

> "我配置了提供商 A 的模型，想暂时换用提供商 B，目前只能改 URL 和 Key，改了之后模型名称又对不上了。切回来又要再改一次。"

本质：**从"单套配置"变成"多套配置方案"的管理方式。**

---

## 二、功能定义

### 2.1 功能描述

将 LLM 设置从"按协议管理两套固定配置"重构为"按提供商管理多套自定义配置方案"。

核心变化：
- **提供商（Profile）**：用户自定义的配置方案，包含名称、URL、API Key
- **模型**：每个提供商下可配置多个模型，每个模型指定调用协议（anthropic / openai）
- **全局参数**：temperature、max_tokens、timeout 等保持全局，不随提供商切换

### 2.2 用户故事

1. 作为管理员，我想保存多套 LLM 提供商配置，这样我可以快速在不同提供商之间切换，而不用每次手动改多个字段
2. 作为管理员，我想给每个模型指定调用协议（Anthropic / OpenAI 兼容），这样同一个提供商下可以混合使用不同协议的模型
3. 作为管理员，我想保留现有的配置数据，升级后自动迁移，不需要重新配置

### 2.3 交互设计

#### 页面布局

```
┌─────────────────────────────────────────────────────────────────┐
│ LLM 设置                                              [返回管理] │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─ 提供商列表 ────┐  ┌─ 编辑区 ──────────────────────────────┐ │
│  │                 │  │                                       │ │
│  │ 🔵 我的 Claude  │  │  名称:     [我的 Claude          ]    │ │
│  │ ○ DeepSeek      │  │  Base URL: [https://api.anthropic...] │ │
│  │ ○ 本地 Ollama   │  │  API Key:  [sk-ant-...] [👁] [测试]   │ │
│  │                 │  │                                       │ │
│  │ [+ 新建提供商]   │  │  ┌─ 模型列表 ─────────────────────┐  │ │
│  │                 │  │  │ claude-sonnet-4  Claude 4 Sonnet │  │ │
│  │                 │  │  │   协议: [anthropic ▾]            │  │ │
│  │                 │  │  │ claude-opus-4    Claude 4 Opus   │  │ │
│  │                 │  │  │   协议: [anthropic ▾]            │  │ │
│  │                 │  │  │                                  │  │ │
│  │                 │  │  │ [+ 添加模型]            [删除当前] │  │ │
│  │                 │  │  └──────────────────────────────────┘  │ │
│  │                 │  │                                       │ │
│  │                 │  │  [保存提供商]     [删除提供商]          │ │
│  └─────────────────┘  └───────────────────────────────────────┘ │
│                                                                 │
│  ┌─ 全局参数 ──────────────────────────────────────────────────┐ │
│  │  Temperature: [0.7]   Max Tokens: [8000]   Timeout: [120s] │ │
│  │  速率限制:    [10] 次/分钟          [60] 次/小时             │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                 │
│                                              [保存全局参数]      │
└─────────────────────────────────────────────────────────────────┘
```

#### 交互流程

1. **切换提供商**：点击左侧列表中的提供商卡片 → 右侧编辑区显示该提供商的配置
2. **新建提供商**：点击 `[+ 新建提供商]` → 创建空配置 → 自动选中 → 右侧可编辑
3. **删除提供商**：点击 `[删除提供商]` → 确认弹窗 → 删除并切换到列表第一项（不允许删除最后一个）
4. **添加模型**：在模型列表点击 `[+ 添加模型]` → 新增一行，协议默认 openai
5. **删除模型**：点击模型行的 `×` 按钮
6. **测试连接**：使用当前编辑区的 URL + Key + 第一个模型发起测试请求
7. **保存**：提供商配置和全局参数分开保存，各自有独立的保存按钮

### 2.4 API 设计

#### GET /admin/settings

返回设置页面，传入：
- `profiles`: 所有配置方案列表
- `active_profile_id`: 当前激活的方案 ID
- `global_config`: 全局参数（temperature, max_tokens, timeout, rate_limit）

#### POST /admin/settings/save-profiles

保存提供商配置。

**请求体**（Form）：
```
csrf_token: string
active_profile_id: string          # 当前激活的方案 ID
profiles_json: string              # JSON 序列化的方案列表
```

**profiles_json 结构**：
```json
[
  {
    "id": "prof_1715234567_abc",
    "name": "我的 Claude",
    "base_url": "https://api.anthropic.com",
    "api_key": "sk-ant-...",
    "models": [
      {
        "id": "claude-sonnet-4-20250514",
        "alias": "Claude 4 Sonnet",
        "protocol": "anthropic"
      },
      {
        "id": "gpt-4o",
        "alias": "GPT-4o",
        "protocol": "openai"
      }
    ],
    "default_model_index": 0
  }
]
```

**校验规则**：
- `name` 必填，最长 50 字符
- `base_url` 必填，必须以 `http://` 或 `https://` 开头
- `api_key` 可选（某些本地模型不需要）
- `models` 至少有一个模型
- 每个模型的 `id` 必填，`protocol` 必须是 `anthropic` 或 `openai`
- `profiles` 不能为空（至少保留一个方案）

**成功响应**：302 重定向到 `/admin/settings?success=1`

**错误响应**：302 重定向到 `/admin/settings?error={message}`

#### POST /admin/settings/save-global

保存全局参数。

**请求体**（Form）：
```
csrf_token: string
temperature: float (0-2)
max_output_tokens: int (256-200000)
request_timeout: int (10-600)
rate_limit_per_minute: int (1-1000)
rate_limit_per_hour: int (1-10000)
```

#### POST /admin/settings/test-connection（可选增强）

测试提供商连接。

**请求体**（JSON）：
```json
{
  "base_url": "https://api.anthropic.com",
  "api_key": "sk-ant-...",
  "model_id": "claude-sonnet-4-20250514",
  "protocol": "anthropic"
}
```

**响应**：
```json
// 成功
{"success": true, "model": "claude-sonnet-4-20250514", "latency_ms": 1200}

// 失败
{"success": false, "error": "Invalid API key"}
```

### 2.5 数据模型

**不新建表**，继续使用现有的 `settings` key-value 表。

#### 存储结构

| Key | Value | 说明 |
|-----|-------|------|
| `llm.active_profile_id` | `"prof_xxx"` | 当前激活的方案 ID |
| `llm.profiles` | `JSON array` | 所有方案的 JSON 序列化 |
| `llm.temperature` | `"0.7"` | 全局默认 temperature |
| `llm.max_output_tokens` | `"8000"` | 全局默认最大输出 tokens |
| `llm.request_timeout` | `"120"` | 全局默认请求超时（秒） |
| `llm.rate_limit_per_minute` | `"10"` | 每分钟速率限制 |
| `llm.rate_limit_per_hour` | `"60"` | 每小时速率限制 |

#### Profile 数据结构

```json
{
  "id": "prof_1715234567_abc",
  "name": "我的 Claude",
  "base_url": "https://api.anthropic.com",
  "api_key": "sk-ant-...",
  "models": [
    {
      "id": "claude-sonnet-4-20250514",
      "alias": "Claude 4 Sonnet",
      "protocol": "anthropic"
    }
  ],
  "default_model_index": 0
}
```

字段说明：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | string | 自动生成 | 格式 `prof_{timestamp}_{random}` |
| name | string | ✅ | 用户自定义名称，最长 50 字符 |
| base_url | string | ✅ | API 端点地址 |
| api_key | string | ❌ | API 密钥（本地模型可为空） |
| models | array | ✅ | 模型列表，至少 1 个 |
| models[].id | string | ✅ | 模型 ID，用于 API 调用 |
| models[].alias | string | ❌ | 显示别名 |
| models[].protocol | string | ✅ | `"anthropic"` 或 `"openai"` |
| default_model_index | int | ❌ | 默认模型的索引，默认 0 |

#### 向后兼容迁移

在 `init_db()` 中检测旧 key 存在时自动转换：

```python
def _migrate_llm_profiles(cursor):
    """将旧的按协议存储的配置迁移到新的 profile 格式"""
    cursor.execute(
        "SELECT key, value FROM settings "
        "WHERE key LIKE 'llm.anthropic_%' OR key LIKE 'llm.openai_%' "
        "OR key = 'llm.active_provider'"
    )
    old = {row["key"]: row["value"] for row in cursor.fetchall()}

    if not old:
        return  # 已迁移或全新安装

    # 检查是否已经迁移过
    cursor.execute("SELECT 1 FROM settings WHERE key = 'llm.profiles'")
    if cursor.fetchone():
        return

    profiles = []
    import time, json

    # 迁移 Anthropic 配置
    if old.get("llm.anthropic_api_key") or old.get("llm.anthropic_base_url"):
        models = json.loads(old.get("llm.anthropic_models_json", "[]"))
        profiles.append({
            "id": f"prof_{int(time.time())}_anthropic",
            "name": "Anthropic",
            "base_url": old.get("llm.anthropic_base_url", "https://api.anthropic.com"),
            "api_key": old.get("llm.anthropic_api_key", ""),
            "models": [{"id": m["id"], "alias": m.get("alias", ""), "protocol": "anthropic"} for m in models] or [
                {"id": "claude-sonnet-4-20250514", "alias": "Claude 4 Sonnet", "protocol": "anthropic"}
            ],
            "default_model_index": 0,
        })

    # 迁移 OpenAI 配置
    if old.get("llm.openai_api_key") or old.get("llm.openai_base_url"):
        models = json.loads(old.get("llm.openai_models_json", "[]"))
        profiles.append({
            "id": f"prof_{int(time.time())}_openai",
            "name": "OpenAI 兼容",
            "base_url": old.get("llm.openai_base_url", "https://api.openai.com/v1"),
            "api_key": old.get("llm.openai_api_key", ""),
            "models": [{"id": m["id"], "alias": m.get("alias", ""), "protocol": "openai"} for m in models] or [
                {"id": "gpt-4o", "alias": "GPT-4o", "protocol": "openai"}
            ],
            "default_model_index": 0,
        })

    if not profiles:
        return

    # 确定激活的方案
    active_provider = old.get("llm.active_provider", "anthropic")
    active_profile = next(
        (p for p in profiles if any(m["protocol"] == active_provider for m in p["models"])),
        profiles[0]
    )

    # 写入新格式
    cursor.execute(
        "INSERT OR REPLACE INTO settings (key, value, updated_at) VALUES (?, ?, datetime('now'))",
        ("llm.profiles", json.dumps(profiles, ensure_ascii=False))
    )
    cursor.execute(
        "INSERT OR REPLACE INTO settings (key, value, updated_at) VALUES (?, ?, datetime('now'))",
        ("llm.active_profile_id", active_profile["id"])
    )

    # 清理旧 key
    old_keys = [
        "llm.active_provider",
        "llm.anthropic_base_url", "llm.anthropic_api_key", "llm.anthropic_models_json",
        "llm.openai_base_url", "llm.openai_api_key", "llm.openai_models_json",
    ]
    for key in old_keys:
        cursor.execute("DELETE FROM settings WHERE key = ?", (key,))
```

### 2.6 安全与限制

| 项目 | 策略 |
|------|------|
| 认证 | 需登录 + `prompt.entry.view_admin` 权限查看，`prompt.entry.edit_any` 权限修改 |
| CSRF | 所有 POST 请求验证 CSRF token |
| API Key 存储 | 明文存储在 SQLite（与现有行为一致，后续可考虑加密） |
| 速率限制 | POST 接口 20 次/分钟（与现有行为一致） |
| 输入校验 | URL 格式、temperature 范围、token 范围等 |
| 最少方案数 | 不允许删除最后一个方案，至少保留一个 |

---

## 三、技术方案

### 3.1 架构变更

```
改动前:
  settings.html → POST 12个字段 → admin.py → update_settings(12个key)
                                              → get_llm_config() 硬编码两套
                                              → get_active_provider_config() if/else
                                              → llm.py 按 provider 分发

改动后:
  settings.html → POST profiles_json + global_params
                → admin.py → save_profiles() / save_global_params()
                → settings.py → get_active_profile() 动态获取
                              → get_active_provider_config() 从 profile 构建
                              → llm.py 不变（仍按 config["provider"] 分发）
```

### 3.2 文件改动清单

| 文件 | 改动 | 说明 |
|------|------|------|
| `prompt/src/services/settings.py` | **中** | 新增 `get_all_profiles()`, `get_active_profile()`, `save_profiles()`；重构 `get_active_provider_config()`；保留 `get_llm_config()` 只返回全局参数 |
| `prompt/src/services/db.py` | **小** | `init_db()` 末尾加迁移函数调用 |
| `prompt/src/routes/admin.py` | **中** | settings 路由改为接收 `profiles_json`；新增 test-connection 路由 |
| `prompt/templates/admin/settings.html` | **大** | 完全重写：左侧列表 + 右侧编辑区 + 模型列表动态增删 |
| `prompt/src/services/llm.py` | **不动** | 只看 `config["provider"]`，不感知 profile 概念 |
| `prompt/src/services/rate_limiter.py` | **不动** | 读全局 rate_limit |

### 3.3 settings.py 核心函数

```python
import json
import time
import secrets

def get_all_profiles() -> list[dict]:
    """获取所有配置方案"""
    raw = get_setting("llm.profiles") or "[]"
    try:
        profiles = json.loads(raw)
        return profiles if isinstance(profiles, list) else []
    except json.JSONDecodeError:
        return []


def get_active_profile() -> dict | None:
    """获取当前激活的配置方案"""
    profiles = get_all_profiles()
    if not profiles:
        return None
    active_id = get_setting("llm.active_profile_id")
    return next((p for p in profiles if p["id"] == active_id), profiles[0])


def save_profiles(profiles: list[dict], active_id: str) -> bool:
    """保存所有配置方案"""
    return update_setting("llm.profiles", json.dumps(profiles, ensure_ascii=False)) \
        and update_setting("llm.active_profile_id", active_id)


def generate_profile_id() -> str:
    """生成方案 ID"""
    ts = int(time.time())
    rand = secrets.token_hex(4)
    return f"prof_{ts}_{rand}"


def get_active_provider_config() -> dict:
    """从当前 profile 构建调用配置（返回格式不变，llm.py 无需改动）"""
    profile = get_active_profile()
    if not profile:
        raise LLMError("没有配置任何 LLM 提供商", "config_error")

    models = profile.get("models", [])
    default_idx = profile.get("default_model_index", 0)

    # 获取全局参数
    global_config = get_llm_config()

    return {
        "provider": models[default_idx]["protocol"] if models and default_idx < len(models) else "openai",
        "base_url": profile["base_url"],
        "api_key": profile.get("api_key", ""),
        "default_model": models[default_idx]["id"] if models and default_idx < len(models) else "",
        "available_models": [m["id"] for m in models],
        "temperature": global_config["temperature"],
        "max_output_tokens": global_config["max_output_tokens"],
        "request_timeout": global_config["request_timeout"],
    }
```

### 3.4 前端实现要点

1. **提供商列表**：用 JS 动态渲染，点击切换编辑目标
2. **模型列表**：每个模型行包含 model_id、alias、protocol 下拉框
3. **表单提交**：用隐藏字段 `profiles_json` 存储 JSON，JS 在 submit 前序列化
4. **测试连接**：AJAX 请求，显示成功/失败结果
5. **新建/删除**：纯前端操作，保存时一起提交

---

## 四、优先级与排期

| 阶段 | 内容 | 预计时间 | 依赖 |
|------|------|----------|------|
| P0 | settings.py：新增 profile CRUD 函数 | 0.5h | 无 |
| P0 | db.py：迁移逻辑 | 0.5h | P0 settings.py |
| P0 | admin.py：重写 settings 路由 | 1h | P0 settings.py |
| P0 | settings.html：重写前端 | 3h | P0 admin.py |
| P1 | 测试连接 API（AJAX） | 0.5h | P0 |
| P1 | 迁移测试 + 功能测试 | 1h | P0 |
| **总计** | | **6.5h** | |

---

## 五、技术风险与决策点

### 5.1 决策记录

| 决策点 | 选项 | 选择 | 理由 |
|--------|------|------|------|
| 存储方式 | A: JSON 单字段 / B: 新建表 | A | 不改表结构，迁移简单，对这个项目规模足够 |
| 参数粒度 | A: 全局 / B: 方案级 / C: 模型级 | A | 大多数用户切换提供商时不需要改参数，减少复杂度 |
| 协议位置 | A: 方案级 / B: 模型级 | B | 支持同一提供商下混合不同协议的模型 |
| 速率限制 | A: 全局 / B: 方案级 | A | 安全措施，不应随提供商切换 |
| llm.py | A: 改 / B: 不改 | B | `get_active_provider_config()` 返回格式不变，隔离变更 |

### 5.2 技术风险

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| 迁移逻辑丢失旧数据 | 🔴 高 | 迁移前备份，迁移函数幂等（INSERT OR IGNORE） |
| JSON 过大（100+ 方案） | 🟢 低 | 实际场景不可能超过 10 个方案 |
| 并发编辑竞态 | 🟢 低 | 单管理员场景，SQLite 写锁保护 |
| 前端 JSON 序列化错误 | 🟡 中 | 提交前校验 JSON 结构，错误时阻止提交并提示 |

---

## 六、附录

### A. 相关文件清单

| 文件 | 作用 |
|------|------|
| `prompt/src/services/settings.py` | 设置服务，核心改动 |
| `prompt/src/services/db.py` | 数据库初始化，加迁移 |
| `prompt/src/services/llm.py` | LLM 调用层，不改动 |
| `prompt/src/services/rate_limiter.py` | 速率限制，不改动 |
| `prompt/src/routes/admin.py` | 管理路由，改动 |
| `prompt/templates/admin/settings.html` | 设置页面，重写 |
| `prompt/src/config.py` | 配置，不改动 |

### B. 旧配置迁移映射

| 旧 Key | 迁移到 |
|--------|--------|
| `llm.active_provider` | `llm.active_profile_id`（通过匹配 protocol） |
| `llm.anthropic_base_url` | profiles[0].base_url |
| `llm.anthropic_api_key` | profiles[0].api_key |
| `llm.anthropic_models_json` | profiles[0].models（每个 model 加 protocol="anthropic"） |
| `llm.openai_base_url` | profiles[1].base_url |
| `llm.openai_api_key` | profiles[1].api_key |
| `llm.openai_models_json` | profiles[1].models（每个 model 加 protocol="openai"） |
| `llm.temperature` | 保持不变（全局参数） |
| `llm.max_output_tokens` | 保持不变（全局参数） |
| `llm.request_timeout` | 保持不变（全局参数） |
| `llm.rate_limit_per_minute` | 保持不变（全局参数） |
| `llm.rate_limit_per_hour` | 保持不变（全局参数） |