# 平台运营逻辑

***

## 一、总览

> TokenHub 是一条「渠道资产化管理」流水线：把上游 API 渠道按**入库 → 监控 → 评价 → 路由 → 转发**五个环节管理起来，用**多源竞争**的机制在保障稳定性的同时压低成本、放大毛利，最终向用户提供"稳定 + 便宜 + 可审计"的统一接入。

```
上游渠道
  │
  ▼
① 渠道入库     —— 供应商/类型/地址/密钥/模型映射/标签 登记
  │
  ▼
② 实时监控     —— 测试、余额、可用性、延迟、限额预警、系统健康
  │
  ▼
③ 量化评价     —— 成功率/延迟/吞吐/成本/限额 → 决定取舍与优先级
  │
  ▼
④ 纳入路由     —— 分组(性价比/高性能/自动) + 优先级 + 权重
  │
  ▼
⑤ 转发规则     —— 指定渠道→亲和性→优先级→重试降级→切分组
  │
  ▼
下游用户（一个 Key，统一计费）
```

***

## 二、渠道入库

### 2.1 基本概念

- **渠道（Channel）**＝一条可用的上游连接（含类型、地址、密钥、绑定模型）。
- **渠道类型（Type）**＝上游接入协议形态（DeepSeek、OpenRouter、硅基流动、自定义 Custom、多 Key 聚合等）。
- **供应商（Vendor）**＝模型/品牌的厂商维度，通过"模型"与渠道间接关联。
- 一个渠道可绑定多个模型；同一模型也可由多个渠道提供 → 形成**同类多渠道冗余**。

### 2.2 入库动作

1. **登记基本配置**：名称、类型、上游地址、API 密钥、分组归属（渠道编辑表单）。
2. **绑定模型 + 模型映射**：把上游模型名映射到平台统一模型名。
3. **拉取模型**：从上游自动拉取最新可用模型列表，减少手工维护。
4. **配置标签**：为渠道打运营治理类标签（如“高稳”“低价”“备用”），并支持**按标签批量操作**（批量改优先级/权重、批量启用/禁用）。
5. **多 Key 管理**：同一渠道下挂多个上游 Key，分摊额度、降低单 Key 耗尽风险。

### 2.3 入库即建立"运营档案"

每条渠道初始化：分组归属、优先级、权重、以及故障处理机制开关（见以下路由可靠性/渠道亲和性）。

***

## 三、实时监控

| 监控项      | 手段                  | 说明与配置位置                                                       |
| -------- | ------------------- | ------------------------------------------------------------- |
| 可用性 / 延迟 | **单渠道测试 / 批量测试**    | 发送测试请求验证转发，渠道列表/表格内操作                                         |
| 上游余额     | **余额查询**            | 拉取 OpenAI/DeepSeek/硅基流动/OpenRouter 等上游剩余额度                    |
| 失败自动处理   | **路由可靠性**           | 系统设置→模型→路由可靠性：定时渠道健康检查、失败状态码重试、按失败关键词/状态码自动禁用、达到阈值自动禁用，可配被动恢复 |
| 稳定性缓存    | **渠道亲和性**           | 系统设置→模型→渠道亲和性：同特征请求复用上次成功渠道（配置启用/成功切换/禁用保留/缓存条数/TTL/规则）       |
| 限额与频控    | **速率限制 / Token 限制** | 系统设置→安全→速率限制 / Token 限制（RP 限制配置在此）                            |
| 系统健康     | **告警 / 性能 / 日志**    | 系统设置→运维：告警（额度阈值等）、性能（GC/缓存/内存）、日志                             |
| 访问合规     | **GeoIP**           | 系统设置→运维→GeoIP：按客户端地区黑/白名单拦截                                   |

> 监控数据会采集入库（模型延时/TPS 等性能指标），作为评价与展示的数据底座。

***

## 四、量化评价

| 指标          | 来源            | 用途              |
| ----------- | ------------- | --------------- |
| 成功率         | 请求成败统计        | 判断稳定性，驱动自动禁用/降级 |
| 平均延迟        | 性能指标采集        | 判断响应速度          |
| 吞吐（TPS/RPM） | 性能指标采集        | 判断承载能力          |
| 成本          | 各渠道对同一模型的上游报价 | 判断毛利空间          |
| 限额/额度       | 上游余额与频控       | 决定是否保留在路由池      |

**评价输入定价策略（报价矩阵 + 收益率）：**

- 用**报价矩阵**（各渠道 × 各模型成本）掌握成本；
- 用**收益率**（目标利润率）反推用户价；
- 用"利润 > 0"判断渠道是否可入**性价比(CE)组**；
- 亏损组合自动剔除，盈利组合按利润排序 → **同模型内优先级/权重由利润驱动**。

> 作用：自动决定"哪条渠道优先、哪条兜底、哪条淘汰"，再把决策输入路由。定价/倍率在系统设置→计费、系统设置→模型（模型定价）中可配。

***

## 五、纳入路由

- **分组**（决定卖价与体验）：
  - **性价比（cost-effective）**：低倍率折扣组，需低成本上游才能在折扣下仍盈利；
  - **高性能（high-performance）**：高倍率溢价组，可接入更稳（或略贵）的渠道；
  - **自动（auto）**：非独立倍率，按预设顺序择优切换。
- **路由参数**（在渠道中配置）：
  - **优先级（Priority）**：数值越大越优先，分层兜底、防雪崩；
  - **权重（Weight）**：同优先级内决定被选概率；
  - **标签**：用于按标签批量改 schedule。

***

## 六、转发规则

```
用户请求（模型 + 分组）
  ├─ 1. Token 绑定了指定渠道？→ 直接用该渠道，跳过路由
  ├─ 2. 渠道亲和性命中？      → 复用上次成功渠道
  └─ 3. 正常路由选择
       ├─ 按模型名精确/规范化匹配
       ├─ 按请求路径过滤（部分高级渠道）
       ├─ 按优先级分层 → 同层按权重加权随机
       ├─ 失败 → 重试 → 降级到下一优先级
       └─ 全部失败 → 自动分组模式下切下一分组
```

### 容灾闭环

- 同组多渠道冗余 → 单渠道故障不中断；
- 优先级逐级降级 + 权重分流 → 高利润优先、兜底可用；
- 路由可靠性 → 自动隔离故障渠道 / 按状态码重试；
- 渠道亲和性 → 连续请求一致性与低延迟；
- 自动分组 → 性价比渠道全挂时切高性能渠道保可用。

### 计费闭环

- 用户看到统一价格（分组倍率决定实付）；
- 平台用低成本渠道赚差价、高稳定渠道保续费；
- auto 场景实付＝路由到的渠道所在分组的倍率。

***

## 七、全链路闭环 → 商业价值

| 关注点   | 机制支撑                               |
| ----- | ---------------------------------- |
| 稳定    | 多渠道冗余 + 亲和性 + 优先级降级 + 路由可靠性自动恢复    |
| 便宜    | 低成本渠道进性价比组 + 利润优先路由                |
| 可控    | 余额查询 + 频控 + 限额告警 + 日志审计 + GeoIP 合规 |
| 可扩展   | 新渠道入库即接入，路由/评价自动适配                 |
| 毛利最大化 | 报价矩阵 + 收益率 → 用户价与渠道编排同步最优化         |