niuniu/lijiaoqiao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
upload/2026-03-26-sync
lijiaoqiao/docs/supply_detailed_design_v1_2026-03-18.md

645 lines
23 KiB
Markdown
Raw Permalink Normal View History

chore: initial public snapshot for github upload
2026-03-26 20:06:14 +08:00
# 用户供应LLM功能 - 完整详细设计（补充版）
> 本文档对"用户分享LLM供应"功能进行完整详细的设计补充，包括安全机制、账单记录等完整内容。
---
## 1. 功能架构
### 1.1 整体架构
```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 供应侧功能完整架构 │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 供应方侧（User A） │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 账号挂载 │ │ 套餐发布 │ │ 收益查看 │ │ 提现 │ │ │
│ │ │ 模块 │ │ 模块 │ │ 模块 │ │ 模块 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 平台核心层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 账号验证 │ │ 套餐管理 │ │ 调度引擎 │ │ 计费引擎 │ │ │
│ │ │ 服务 │ │ 服务 │ │ │ │ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 风控服务 │ │ 合规检测 │ │ 通知服务 │ │ 审计服务 │ │ │
│ │ │ │ │ 服务 │ │ │ │ │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ 需求方侧（User B） │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 套餐选购 │ │ 调用API │ │ 使用账单 │ │ 消耗统计 │ │ │
│ │ │ 模块 │ │ 模块 │ │ 模块 │ │ 模块 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
```
---
## 2. 安全机制详细设计
### 2.1 账号安全
#### 2.1.1 账号挂载安全流程
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 账号挂载安全验证流程 │
└─────────────────────────────────────────────────────────────────────────────┘
步骤1: 用户提交账号
│
▼
步骤2: 账号格式校验
│ ├── API Key 格式检查
│ ├── OAuth 授权链接生成
│ └── 格式不合格 → 拒绝
▼
步骤3: 账号有效性验证
│ ├── 调用供应商 API 验证账号可用
│ ├── 获取账号基本信息
│ └── 验证失败 → 拒绝
▼
步骤4: 额度查询
│ ├── 获取当前剩余额度
│ ├── 记录额度快照
│ └── 额度不足 → 警告
▼
步骤5: ToS 合规检查
│ ├── 检查供应商 ToS 是否允许共享
│ ├── 检查账号类型是否合规
│ └── 不合规 → 拒绝
▼
步骤6: 风险评估
│ ├── 账号历史行为分析
│ ├── 异常检测
│ └── 高风险 → 人工审核
▼
步骤7: 加密存储
│ ├── 使用 KMS 加密
│ ├── 生成账号唯一标识
│ └── 存储到数据库
▼
步骤8: 通知用户
├── 挂载成功/失败通知
└── 后续操作指引
```
#### 2.1.2 账号存储安全
| 安全措施 | 说明 | 实现 |
|----------|------|------|
| **加密存储** | API Key 必须加密存储 | AES-256-GCM 加密 |
| **KMS 集成** | 使用密钥管理服务 | AWS KMS / 自建 |
| **字段级加密** | 敏感字段单独加密 | 密钥ID + 密文 |
| **访问控制** | 最小权限原则 | RBAC 控制 |
| **审计日志** | 所有访问记录日志 | 操作人 + 时间 + IP |
| **禁止导出** | 禁止明文导出 Key | 脱敏展示 |
#### 2.1.3 凭证边界强制约束
1. 供应方上游凭证仅由平台密态托管（KMS + 字段级加密）。
2. 需求方只允许使用平台签发凭证调用统一入口。
3. 平台禁止向需求方返回供应方上游凭证（API/控制台/导出均不允许）。
### 2.2 调用安全
#### 2.2.1 请求验证流程
```
请求进入
│
▼
┌─────────────────┐
│ 1. API Key 验证 │ ──▶ 无效 → 401 Unauthorized
└────────┬────────┘
│
▼
┌─────────────────┐
│ 2. 套餐有效性 │ ──▶ 过期/售罄 → 403 Forbidden
└────────┬────────┘
│
▼
┌─────────────────┐
│ 3. 额度检查 │ ──▶ 额度不足 → 402 Payment Required
└────────┬────────┘
│
▼
┌─────────────────┐
│ 4. 风控检查 │ ──▶ 风险拦截 → 429 Too Many Requests
└────────┬────────┘
│
▼
┌─────────────────┐
│ 5. ToS 合规 │ ──▶ 违规拦截 → 403 Forbidden
└────────┬────────┘
│
▼
转发到上游
```
#### 2.2.2 安全防护措施
| 防护项 | 说明 | 配置 |
|--------|------|------|
| **IP 白名单** | 限制调用来源 IP | 可配置 |
| **Referer 校验** | 限制调用来源域名 | 可配置 |
| **调用频率限制** | RPM/TPM 限制 | 按套餐配置 |
| **并发限制** | 同时请求数限制 | 按套餐配置 |
| **模型限制** | 可用模型白名单 | 按套餐配置 |
| **额度预警** | 额度低于阈值告警 | 可配置 |
### 2.3 防欺诈机制
#### 2.3.1 欺诈检测规则
| 规则 | 描述 | 动作 |
|------|------|------|
| **额度异常消耗** | 单日消耗 > 平均3倍 | 告警 + 审核 |
| **短时间大量调用** | 1分钟内 > 100次 | 限流 + 审核 |
| **新账号高额使用** | 注册24h内使用 > $100 | 审核 |
| **跨地区调用** | IP 地区突然变化 | 告警 |
| **模式异常** | 调用模式偏离历史 | 告警 |
| **账号共享检测** | 多 IP 同时使用 | 封禁 + 审核 |
#### 2.3.2 保证金机制
| 供应方类型 | 保证金要求 | 退还条件 |
|------------|------------|----------|
| 个人 | ¥500 | 最后一笔交易30天后无异常 |
| 企业 | ¥5,000 | 最后一笔交易90天后无异常 |
**扣除场景**：
- 欺诈行为
- 账号封禁导致需求方损失
- 恶意套现
---
## 3. 账单与记录详细设计
### 3.1 数据模型
执行口径说明（重要）：
1. 本节内联 SQL 用于逻辑模型说明，不作为生产执行脚本。
2. 生产执行 DDL 以 `sql/postgresql/supply_schema_v1.sql` 为唯一脚本来源（PostgreSQL 方言）。
3. 若内联示意与执行脚本冲突，以执行脚本为准。
#### 3.1.1 供应方账号表
执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_accounts`）。
关键字段：
1. 基础：`id/user_id/platform/account_type/status`。
2. 凭证：`encrypted_credentials/key_id`（仅密态托管）。
3. 风控：`risk_level/risk_score/is_frozen`。
4. 审计：`created_at/updated_at/created_by/updated_by`。
#### 3.1.2 供应套餐表
执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_packages`）。
关键字段：
1. 关联：`supply_account_id/user_id/platform/model`。
2. 定价：`price_per_1m_input/price_per_1m_output`。
3. 额度：`total_quota/available_quota/sold_quota/reserved_quota`。
4. 状态：`draft/active/paused/sold_out/expired`。
#### 3.1.3 订单表
执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_orders`）。
关键字段：
1. 订单主键：`id/order_no`。
2. 交易信息：`buyer_user_id/supplier_user_id/supply_package_id`。
3. 金额信息：`total_amount/platform_fee/supplier_earnings`。
4. 状态：`pending/paid/using/expired/refunded`。
#### 3.1.4 使用记录表（详细到每一次调用）
执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_usage_records`）。
关键字段：
1. 追踪主键：`request_id/upstream_request_id/order_id`。
2. 模型维度：`platform/model/endpoint`。
3. 计费维度：`request_tokens/response_tokens/total_tokens/total_cost`。
4. 响应维度：`response_status/latency_ms/success`。
#### 3.1.5 供应方收益表
执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_earnings`）。
关键字段：
1. 收益类型：`usage/bonus/refund`。
2. 资金状态：`pending/available/withdrawn/frozen`。
3. 金额字段：`amount/available_amount/frozen_amount/withdrawn_amount`。
#### 3.1.6 结算记录表
执行 DDL：`sql/postgresql/supply_schema_v1.sql`（表：`supply_settlements`）。
关键字段：
1. 结算状态：`pending/processing/completed/failed`。
2. 金额字段：`total_amount/fee_amount/net_amount`。
3. 周期字段：`period_start/period_end`。
### 3.2 账单查询API
#### 3.2.1 供应方账单API
```yaml
# 供应方账单查询
GET /api/v1/supplier/billing
Query Parameters:
- start_date: string (可选) 开始日期 YYYY-MM-DD
- end_date: string (可选) 结束日期 YYYY-MM-DD
- page: int (可选) 页码
- page_size: int (可选) 每页数量
Response:
{
"data": {
"period": {
"start": "2026-03-01",
"end": "2026-03-31"
},
"summary": {
"total_revenue": 12500.00, # 总收入
"total_orders": 156, # 订单数
"total_usage": 500000000, # 总tokens
"total_requests": 15800, # 总请求数
"avg_success_rate": 99.2, # 平均成功率
"platform_fee": 1875.00, # 平台服务费
"net_earnings": 10625.00 # 净收益
},
"by_platform": [
{
"platform": "openai",
"revenue": 8000.00,
"orders": 100,
"tokens": 320000000,
"success_rate": 99.5
},
{
"platform": "anthropic",
"revenue": 4500.00,
"orders": 56,
"tokens": 180000000,
"success_rate": 98.8
}
],
"by_model": [...],
"trend": [...]
},
"pagination": {...}
}
```
#### 3.2.2 需求方账单API
```yaml
# 需求方账单查询
GET /api/v1/consumer/billing
Response:
{
"data": {
"balance": {
"total_paid": 5000.00, # 已支付总额
"total_used": 3200.00, # 已使用
"remaining": 1800.00, # 剩余
"frozen": 0.00 # 冻结
},
"usage": {
"this_month": {
"tokens": 120000000,
"cost": 960.00,
"requests": 5200
},
"by_platform": [...],
"by_model": [...]
},
"orders": [...]
}
}
```
### 3.3 详细使用记录
```yaml
# 详细使用记录查询
GET /api/v1/consumer/usage-records
Query Parameters:
- start_date: string
- end_date: string
- platform: string (可选)
- model: string (可选)
- success: boolean (可选)
- page: int
- page_size: int
Response:
{
"data": [
{
"id": 1001,
"request_id": "req_abc123",
"order_id": 500,
"platform": "openai",
"model": "gpt-4o",
"endpoint": "/v1/chat/completions",
"tokens": {
"input": 1500,
"output": 800,
"total": 2300
},
"cost": {
"input": 0.0075, # $7.5/1M
"output": 0.032, # $32/1M
"total": 0.0395 # $0.0395
},
"latency_ms": 1250,
"status": "success",
"timestamp": "2026-03-18T10:30:00Z"
}
],
"pagination": {...}
}
```
---
## 4. 完整业务流程
### 4.1 供应方完整流程
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 供应方完整业务流程 │
└─────────────────────────────────────────────────────────────────────────────┘
1. 入驻认证
├── 注册账号
├── 实名认证 (个人/企业)
└── 缴纳保证金
│
▼
2. 账号挂载
├── 选择供应商
├── 选择认证方式 (API Key / OAuth)
├── 提交凭证
├── 平台验证 (有效性/额度/ToS)
└── 通过 → 激活账号
│
▼
3. 套餐发布
├── 选择要共享的模型
├── 设置配额 (全部/部分额度)
├── 设置售价
├── 设置有效期
└── 上架销售
│
▼
4. 日常运营
├── 监控账号状态
├── 查看订单通知
├── 处理异常 (如有)
└── 收益查看
│
▼
5. 收益结算
├── 收益累积 (T+7 可提现)
├── 申请提现
├── 平台审核
└── 到账
```
### 4.2 需求方完整流程
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 需求方完整业务流程 │
└─────────────────────────────────────────────────────────────────────────────┘
1. 浏览选购
├── 浏览可用套餐
├── 按供应商/模型筛选
├── 查看套餐详情 (额度/价格/评价)
└── 选择购买
│
▼
2. 下单购买
├── 选择配额数量
├── 确认价格
├── 选择支付方式
└── 支付成功
│
▼
3. 获取凭证
├── 获取平台 API Key（平台签发）
├── 不返回供应方上游凭证
├── 配置使用限制
└── 开始使用
│
▼
4. 使用API
├── 调用统一API
├── 实时扣减配额
├── 查看使用统计
└── 配额不足 → 续费
│
▼
5. 账单管理
├── 查看使用明细
├── 下载账单
└── 对账
```
---
## 5. 调度策略
### 5.1 请求调度流程
```
请求进入 (指定模型: gpt-4o)
│
▼
查找可用套餐 (gpt-4o + 有剩余配额 + 正常状态)
│
├── 多个套餐可用
│ │
│ ▼
│ 选择策略:
│ 1. 最低价格优先
│ 2. 负载均衡 (选择负载最低)
│ 3. 轮询
│ 4. 供应商偏好
│ │
│ ▼
│ 选择最优套餐
│
└── 单个套餐可用 → 使用该套餐
│
▼
检查套餐配额 (足够? → 继续; 不足? → 拒绝)
│
▼
检查账户状态 (正常? → 继续; 异常? → 拒绝)
│
▼
转发到上游供应商
│
▼
获取响应
│
▼
记录使用记录
│
├── 更新订单剩余配额
├── 更新套餐已售配额
├── 计算费用
└── 更新供应方收益
│
▼
返回响应给需求方
```
### 5.2 调度策略配置
| 策略 | 说明 | 适用场景 |
|------|------|----------|
| **最低价格** | 选择售价最低的套餐 | 成本优先 |
| **负载均衡** | 选择负载最低的套餐 | 性能优先 |
| **轮询** | 依次选择各套餐 | 公平使用 |
| **供应商偏好** | 优先特定供应商 | 稳定性优先 |
| **混合** | 综合考虑价格/负载/偏好 | 默认 |
---
## 6. 监控与告警
### 6.1 监控指标
#### 6.1.1 供应方监控
| 指标 | 说明 | 告警阈值 |
|------|------|----------|
| 账号可用率 | 账号正常比例 | < 99% |
| 成功率 | 请求成功率 | < 95% |
| 平均延迟 | 平均响应时间 | > 5000ms |
| 配额消耗速度 | 配额日消耗比例 | > 80%/天 |
| 异常请求比例 | 失败请求比例 | > 10% |
| 收益异常 | 收益突增/突降 | 偏离 > 50% |
#### 6.1.2 套餐监控
| 指标 | 说明 | 告警阈值 |
|------|------|----------|
| 剩余配额 | 可用配额 | < 10% |
| 订单量 | 新增订单 | 突降 > 30% |
| 评分 | 用户评分 | < 4.0 |
| 投诉 | 用户投诉 | > 3次/周 |
### 6.2 告警通知
| 告警类型 | 通知对象 | 通知方式 |
|----------|----------|----------|
| 账号异常 | 供应方 | 站内信/邮件 |
| 配额不足 | 供应方 | 站内信/短信 |
| 收益到账 | 供应方 | 站内信/邮件 |
| 异常订单 | 平台运营 | 邮件/短信 |
| ToS 违规 | 平台运营 | 邮件 |
---
## 7. 报表导出
### 7.1 供应方报表
| 报表 | 内容 | 格式 |
|------|------|------|
| 账单汇总 | 收入/订单/费用 | CSV/Excel |
| 使用明细 | 每笔调用详情 | CSV/Excel |
| 账户流水 | 收益/提现/冻结 | CSV/Excel |
| 对账单 | 平台与供应方对账 | PDF |
### 7.2 需求方报表
| 报表 | 内容 | 格式 |
|------|------|------|
| 消费账单 | 消费汇总 | CSV/Excel |
| 使用明细 | 调用明细 | CSV/Excel |
| 成本分析 | 按模型/部门分析 | PDF |
---
## 8. 数据统计SQL示例
### 8.1 供应方收入统计
```sql
SELECT
sa.user_id,
u.username,
sa.platform,
SUM(sur.total_cost) as total_revenue,
SUM(sur.total_cost) * :platform_fee_rate as platform_fee,
SUM(sur.total_cost) * :supplier_settlement_rate as supplier_earnings,
COUNT(DISTINCT sur.order_id) as order_count,
SUM(sur.total_tokens) as total_tokens,
AVG(sur.success) as avg_success_rate
FROM supply_usage_records sur
JOIN supply_accounts sa ON sur.supply_account_id = sa.id
JOIN users u ON sa.user_id = u.id
WHERE sur.created_at >= '2026-03-01' AND sur.created_at < '2026-04-01'
GROUP BY sa.user_id, u.username, sa.platform
ORDER BY total_revenue DESC;
```
### 8.2 套餐消耗统计
```sql
SELECT
sp.id as package_id,
sp.model,
sp.platform,
sp.total_quota,
sp.available_quota,
sp.sold_quota,
(sp.sold_quota / sp.total_quota * 100) as sold_rate,
COUNT(DISTINCT so.id) as order_count,
SUM(sur.total_cost) as total_revenue,
AVG(sur.latency_ms) as avg_latency,
AVG(sur.success) as success_rate
FROM supply_packages sp
LEFT JOIN supply_orders so ON sp.id = so.supply_package_id
LEFT JOIN supply_usage_records sur
ON sur.supply_account_id = sp.supply_account_id
AND sur.model = sp.model
WHERE sp.created_at >= '2026-03-01'
GROUP BY sp.id, sp.model, sp.platform, sp.total_quota, sp.available_quota, sp.sold_quota
ORDER BY total_revenue DESC;
```
---
**文档状态**：完整详细设计（已补 PostgreSQL 执行口径与 SQL 示例修正）
**关联文档**：
- `supply_side_product_design_v1_2026-03-18.md`
- `supply_feature_technical_analysis_v1_2026-03-18.md`
Reference in New Issue Copy Permalink