# 方案：校园 AI 代理层（AI Proxy Gateway）

> 编写日期：2026-09-04　状态：立项草案（待实现）
> 定位：在「端（学生 / 本地小模型）」与「云（DeepSeek 等 LLM API）」之间加一层 **AI 代理网关**——
> "端云协同"的第三层。开发工作（代码/实验/数据）全部落在本目录 `AI代理功能开发/`。

---

## 0. 一页速览

- **商业模式 = API 差价 + 缓存收益**。代理持有上游主 key（如 DeepSeek），学生持代理 key；
  学生按明牌单价/包月付费，代理按实际混合成本向上游结算。
- **关键洞察**：校园场景问题高度重复（同课程、同作业、同考点）→ 通过"网关语义缓存直答 +
  请求前缀整形"把上游**缓存命中价输入**的占比做到极高（上游缓存命中价通常为未命中价的 1/4～1/10，
  以官网最新价目为准），而计费按未命中口径 → 差值即毛利。
- **校园网提供基础设施**：托管、带宽、内网可达零成本；本地小模型层可跑在校内机器 → 近零成本兜底层。
- **北极星指标**：综合缓存命中率 `h = h_g + h_p`（网关语义缓存命中 + 上游前缀缓存命中）与
  毛利/千次请求。

## 1. 架构

```
学生（校园网内；Web / SDK / 任意 OpenAI 兼容客户端）
   │  ① 代理 key（学生凭据，非上游 key）
   ▼
┌─ 校园 AI 代理网关（本目录开发）──────────────────────┐
│ ② 鉴权 / 配额 / 限流（学生账户、代理 key 签发注销）      │
│ ③ 缓存栈 L0：语义缓存直答（命中 = 上游成本 0，全毛利）    │
│          L1：前缀整形（统一 system + 课程资料前置，      │
│              用户问题永远在末尾 → 上游前缀缓存高命中）     │
│ ④ 计量计费账本（usage / prompt_cache_hit_tokens 分账）  │
│ ⑤ 多价位调度（复用 model_pool：local / budget / premium）│
└──────────────────┬─────────────────────────┘
                   ▼ ⑥ 上游主 key（env / config/settings.json 注入，绝不入库）
            云端 API（DeepSeek 等；前缀缓存自动生效）
```

## 2. 缓存经济学（"赚缓存钱"的原理）

上游对**前缀缓存命中**的输入 token 计价通常为未命中价的 1/4～1/10（比例随上游版本变动，
以官网最新价目为准）。代理有三个牟利杠杆，按毛利从高到低：

1. **L0 语义缓存直答**：同义问题直接复用历史答案，上游成本为 0，毛利率 100%；
2. **L1 前缀整形**：所有请求强制统一前缀结构（固定 system 模板 + 课程资料/RAG 内容前置 +
   用户问题置末），使上游自动前缀缓存命中率大幅上升，输入成本降至命中价；
3. **计费口径差**：学生按明牌价计费，代理按实际混合成本结算。

毛利公式（输入部分，示意）：

```
cost_in = (1 − h_g − h_p) · P_miss + h_p · P_hit      （h_g：网关直答命中率，h_p：上游前缀命中率）
收入    = P_sale · tokens
```

校园场景 `h` 高的三个理由：课件/题库做共享前缀（同一门课几百人同前缀）、考试周问题重复率极高、
班级级 system 模板天然统一。

## 2.5 经济性测算（2026-09-04，讨论"官方价 5 折"定价）

**价格锚点**（DeepSeek 2026 分时价，每 1M tokens，[官方价目](https://api-docs.deepseek.com/zh-cn/quick_start/pricing)）：
输入未命中 空闲 ¥1.5 / 高峰 ¥3.0（Flash 档）；输入命中低至 ¥0.025–0.1（≈未命中价 **1/30**）；
输出 空闲 ¥4.5 起 / 高峰 ¥9 起。

**命中率规划值**（校园集中域）：
h_g 网关语义缓存 保守 15% / 中性 25% / 考试周 40–50%；
h_p 上游前缀命中（token 加权，前缀整形后）保守 30% / 中性 50% / 乐观 65%。
综合输入命中率：保守 40% / 中性 63% / 考试周 79%。
独有优势：前缀缓存挂在主 key 账号下 → **全校请求共享同一缓存池**（学生各自持 key 做不到）。

**单请求模型**（3K 输入含 1.5K 共享前缀 + 0.8K 输出，高峰）：
令 o = 输出成本/输入未命中成本 = 0.8；r = 命中/未命中 = 1/30。
统一 5 折收入 = 0.5(1+o)；差异化（输入 5 折、输出 8 折）收入 = 0.5 + 0.8o。
免上游率 h₀ = h_g + 本地分流率（model_pool local 档）。

| 场景 | h₀ | 统一 5 折毛利 | 输入 5 折/输出 8 折 |
|---|---|---|---|
| 保守 | 20% | **−34%** | −6%（近打平） |
| 中性 | 40% | +12% | **+31%** |
| 考试周 | 55% | +41% | +54% |

盈亏平衡 h₀：统一 5 折 ≈ 32%；差异化 ≈ **13%**。

**结论**：① 全线统一 5 折结构性危险——输出 token 固定亏 50%，缓存利润补不平；
**推荐"输入 5 折 / 输出 8 折"差异化定价**。② 杠杆排序：差异化定价 > 本地分流 > h_g 语义缓存
> 空闲时段调度（成本直接半价）> h_p 前缀整形。③ 规模：300 活跃用户问答场景月毛利仅数百元；
**放大器 = 编程智能体闭环**（单任务 tokens 为问答 30–50 倍，本系统消费本网关，月毛利可上 2000–5000 元）。

### 2.6 规模化测算（2026-09-04：5000 活跃用户 + 学校采纳情景）

**用量假设（制度性流量：课程绑定 + 校赛指定，非自然增长）**：
活跃 5000；DAU 平时 30%（1500）/ 高峰周 50%（2500）；人均日请求 12/18；40 教学周 ≈ **650 万请求/年**；
画像：问答 3.5K in + 0.8K out；智能体任务 50K in + 10K out。

**商业运营账**（差异化定价，缓存按规模校准：问答段 h_g 30–40%、智能体段 5–15%）：

| 情景 | 构成 | 年收入 | 年净利 |
|---|---|---|---|
| S1 纯问答 | agent 占 0 | ≈¥5.7 万 | ≈¥1.7 万（30%） |
| S2 +10% 智能体 | 校赛试点+编程课 | ≈¥12.8 万 | ≈¥2.9 万（23%） |
| S3 +20% 智能体+竞赛按量 | 完整高位优势 | ≈¥20 万+竞赛经费 | ≈¥6 万+竞赛毛利 |

**学校采纳模式对比（关键结论：差价是副产品，平台采购才是规模答案）**：

| 模式 | 收入形式 | 首年收益 | 风险 |
|---|---|---|---|
| C1 纯转售 | 差价+缓存 | 净利 ¥3–6 万 | 转售合规 + 上游调价（2026 已涨 57–214%） |
| **C2 学校采购（推荐）** | 建设立项 ¥10–20 万 + 年度服务费 ¥3–10 万 + 竞赛按量 | **¥15–35 万** | 项目制回款 |
| C3 混合 | 学校平台 + 学生增值付费 | 介于两者 | 定价需校批 |

C2 附带收益：合规消解（学校主体采购上游商用授权）、不垫资不担调价（按流水抽成/年费）、
软著+论文+奖项+校级平台经历。

**两条风险红线**：① 上游调价生死线 → model_pool 多供应商路由为生存设计；
② 学校自建私有化为最大替代 → 护城河 = 软件层（缓存整形/计费/交流文本/智能体平台），即毕设系统本身。

### 2.7 增补（2026-09-04）：C 端客户端 + 商用批量采购对模型的修正

**两个新变量**：① llama.cpp 推理在 C 端——免费客户端（即本毕设端侧系统，捆绑 llama.cpp）
分发给学生，本地推理用学生硬件，学校本地层硬件成本归零；客户端**限制使用学校代理**
（学号登录换 key、不暴露 base_url、按 key 限流计费）。② 上游 key 走商用批量采购，
采购价为个人牌价 d 折（具体折扣商务洽谈，用敏感性覆盖）。

**统一 5 折敏感性矩阵**（毛利占收入比；r=1/30、o=0.8）：

| 场景 | h₀ | d=1.0 | d=0.9 | d=0.8 | d=0.7 | d=0.6 |
|---|---|---|---|---|---|---|
| 保守 | 20% | −34% | −16% | −7% | +6% | +19% |
| 中性 | 40% | +12% | +21% | +30% | +39% | +47% |
| 考试周 | 55% | +41% | +49% | +53% | +59% | +65% |

盈亏平衡采购折扣：保守 d<7.5 折 / 中性 d<8.5 折 / 考试周 d<9.6 折。
**结论**：商用采购 ≤9 折时统一 5 折在中性场景 +21% 以上，可行；差异化定价（输入 5 折/输出 8 折）
降级为上游调价时的保险杠杆。5000 人年账（中性 d=0.8）：商业净利约 3–5 万，学校采购（C2）仍为收益主体。

**C 端客户端的边界（诚实评估）**：llama.cpp 开源，技术上无法阻止学生自装直连——
锁定的是统一体验/计费合规/学校背书（默认通道），不是防破解。端侧缓存越强打代理流量越少，
对学校上游配额是省、对代理毛利中性偏负；客户端免费层能力边界（本地档位/上下文长度）
是与学校对齐的定价杠杆。商用合同以学校主体签订 → 转售合规与备案红线基本消解。

## 3. 与现有系统的复用映射

| 代理层需要 | 现有资产 | 改造量 |
|---|---|---|
| 多价位上游池 | `gateway/model_pool.py`（local/budget/premium） | 复用 |
| 语义缓存 | `router_system/cache.py`（L1 精确 + L2 n-gram） | 可选升 embedding |
| token 计量分账 | `V2Stats.by_model` | 补 cache_hit 维度 |
| 学生账户/配额 | `review.py` 的 sqlite 模式 | 新建 `billing.py` |
| 流式网关 | v3 SSE 基建 | 透传上游 SSE |
| 滥用兜底 | ReviewQueue 思路 + 限流 | 复用思想 |

## 3.5 技术选型与实现架构（实现 agent 按此执行，细化 §4）

**总原则**：不换语言、不加服务、不动 `router_system/`。被否选项：Go/Rust 独立服务（丢全部复用，
校园负载用不上）、Nginx/OpenResty+Lua（写不了 AI 感知逻辑）、Envoy/Kong/Cloudflare AI Gateway
（运维重/出内网）。**结论：Python 3.14 + FastAPI APIRouter 挂现有 app**——峰值 45K 请求/日
≈ 1.6 req/s、瞬时 30–50 路流式，单进程 uvicorn 足够。

**请求链路**：鉴权（代理 key 哈希存储→令牌桶限流→余额熔断）→ 桶识别+规范化序列化 →
L0 两级缓存（精确哈希→语义向量 cosine≥0.92，命中即成本 0 照常计费）→ Singleflight 合并 →
前缀整形（canonical system+课程资料置顶、问题置末）→ model_pool 派发（local→budget→premium，
首 token 前才可 failover）→ 流式 tee（转发+累积）→ 回写账本/缓存/指标。

**模块落点 `gateway/proxy/`（6 模块）**：
`auth.py`（key 签发/注销、令牌桶、日/并发上限）、`ledger.py`（sqlite WAL：students/proxy_keys/
usage_ledger/semcache 四表；request_id 幂等；余额预扣-结算）、`normalizer.py`（桶识别、规范化、
前缀整形器）、`semcache.py`（两级缓存+singleflight+TTL/版本失效+int8 向量 LRU 30 万条≈300MB）、
`upstream.py`（派发+usage 归一化+流式转发）、`pricing.py`（miss/hit/out 三价×峰谷系数；可注入时钟）。

**usage 归一化**：DeepSeek `prompt_cache_hit_tokens`；OpenAI 兼容 `prompt_tokens_details.cached_tokens`；
Anthropic `cache_read_input_tokens`。流式须带 `stream_options.include_usage`；断连按已收 usage 计，
否则估算且不缓存。

**缓存感知技术清单（12 条）**：① 规范化序列化（稳定键序、剔易变字段）② 前缀钉扎（资料置顶问题置末
→ 上游 1/30 价命中）③ 桶作用域+版本失效（资料更新=版本+1）④ 两级缓存（复用 cache.py L1/L2 骨架，
L2 升级 embedding）⑤ 向量 int8+LRU ⑥ Singleflight 合并 ⑦ 空闲时段队列（非交互任务 off-peak 半价）
⑧ 前缀预热（max_tokens=1 廉价调用）⑨ 上游命中遥测回灌校准阈值 ⑩ L0 只缓存单轮（多轮靠上游前缀
自然命中，防上下文污染）⑪ 失败不缓存 ⑫ model_pool 补 hit_price 字段按命中价选上游。

**接入现有项目五步**：① `gateway/proxy/` 包 + `include_router`，router_system 零改动（缓存算法
直接 import）；② `config/settings.json` 加 `proxy` 段（桶/价格表/限流/allow_proxy），主 key 走 env；
③ `webapp/src/views/ProxyView.vue` 三卡片（key 管理/用量查询/命中率-毛利看板）+ `npm run build`；
④ `data/proxy.sqlite3`（gitignore 已含 data/）；⑤ 任务登记《任务拆解与执行计划.md》代理层节
（T-P1 上游客户端+usage 归一化 / T-P2 鉴权账本 / T-P3 流式透传 / T-P4 整形器 / T-P5 语义缓存 /
T-P6 计价 / T-P7 前端页 / T-P8 200 并发压测），AGENTS.md 文档地图补一行；测试资源隔离清单追加
proxy.sqlite3。

**性能定案与逃生通道（2026-09-04 补充）**：代理为 I/O 密集型流式转发（重计算全部在 C 侧：
llama.cpp 推理/embedding、numpy 检索、sqlite、hashlib），Python 代理开销 1–3ms/请求，
占端到端延迟 <0.5%，峰值负载 <10% 单核——**确定用 Python**。硬性对策：向量检索必须
numpy/hnswlib 且限定课程桶内；embedding 必须走 llama-server 端点（禁止 torch 在代理内推理）。
**性能预算（T-P8 压测验收）**：代理附加 P99 ≤50ms、进程内存 ≤1GB、单核 ≥50 req/s；
超标才启动数据面（透传+精确缓存）换 Go/Envoy 的局部手术——控制面/数据面分层 + 状态全外置
sqlite 保证该手术成本可控。减轻硬件消耗的优先级：缓存命中率设计 ≫ 本地模型量化 ≫ 空闲调度
≫ 代理语言（换 Go 仅省 ~150MB 内存）。

## 4. MVP 任务分解（供实现 agent 按序执行）

> **执行版已细化**：文件清单、DDL、接口签名、API 契约、逐任务验收见
> **《实施方案_代理层与缓存层.md》**（T-P0…T-P8，约 12 工作日）。本节 P1–P5 为摘要，以执行版为准。

> 约束：主 key 只从环境变量 / `config/settings.json` 读取（该文件已 gitignore），
> 任何代码、示例、测试中**不得出现真实凭据字面量**。

| # | 任务 | 验收 |
|---|---|---|
| P1 | 透传网关：`/proxy/v1/chat/completions`（OpenAI 兼容、流式透传） | curl 可用；流式与非流式均通 |
| P2 | 计量计费：解析上游 usage（含 `prompt_cache_hit_tokens`）；sqlite 账本；欠额熔断 | 每请求成本/收入可查；欠额请求被拒 |
| P3 | 缓存栈：前缀整形器 + L0 语义缓存接入；命中率埋点 | 埋点输出 h_g、h_p、假想直连成本对比 |
| P4 | 账号配额：代理 key 签发/注销、额度、限流 | key 生命周期可管理；限流生效 |
| P5 | 看板：命中率/毛利/用量视图（复用 MetricsView 模式） | 三卡片可见 |

**端到端验收基线**：构造 ≥200 条校园模拟请求（重复/同义变体占 ≥50%），`h_g + h_p ≥ 50%`，
在合理定价表下毛利为正。

## 5. 合规与风险（实现前必读）

1. **转售授权**：向上游 API 的转售/多租户使用可能受其服务条款限制，真实收费运营前必须确认
   上游商用/分销政策；个人 key 转售存在封号风险。
2. **备案要求**：面向不特定公众提供生成式 AI 服务在国内需完成备案；校内限定人群合规负担小——
   **从校内试点起步**。
3. **主 key 安全**：仅存 env / `config/settings.json`；代码、文档、测试零字面量。
4. **缓存正确性**：语义缓存必须带 TTL 与失效策略，并按课程/时间分桶隔离——资料更新后旧答案
   不能续用；作业场景"相似题 ≠ 可复用答案"。
5. **竞争**：学生自有 key、免费额度是替代品；定价锚定"便利性 + 稳定供给"，不锚定成本。

## 6. 实验设计（论文/答辩素材）

- **E-P1 命中率-毛利曲线**：模拟 500 条校园请求（重复率 0% / 30% / 60% 三档），
  测 h_g、h_p、混合成本、毛利率三组数字。
- **E-P2 前缀整形 A/B**：整形 vs 不整形的上游 `prompt_cache_hit_tokens` 对比——
  证明"缓存钱"是设计出来的，不是碰运气。
- **E-P3 语义缓存质量**：L0 直答复用的正确性抽检（分桶/TTL 策略对照）。

**推理引擎选型（2026-09-04 定案）**：客户端（C 端）**llama.cpp，无悬念**——学生 Windows 本机
只有它能单文件零依赖运行（vLLM 仅 Linux + CUDA + torch 数 GB）。校端**默认 llama.cpp**：
本地层峰值并发 10–50 路，`--parallel` 足够；`--cache-reuse`/KV 量化与交流文本协议已耦合并经
E1 验证；与客户端同运行时同打包，不破坏"干净环境 20 分钟"验收。**vLLM = 条件启用的部署选项**，
不是替换——它说 OpenAI 兼容协议，启用即 model_pool 加一个端点条目（零代码）。触发条件
（三条同时满足）：学校提供 Linux GPU 服务器（16GB+ 显存）+ 本地层持续并发 >50–100 路 +
本地层 token 占比成为吞吐瓶颈。推理引擎是可替换端点而非架构承诺；D1（只捆绑 llama.cpp
上游二进制）约束客户端分发件，不限制服务端池子的上游类型。

## 7. 与毕业设计主命题的关系

不改变已定命题《基于端云协同的编程智能体系统设计与实现》。本方向作为扩展章/答辩亮点：
**代理层 = 端侧基础设施的规模化形态**（从单机端侧到校园级端侧），核心贡献是
"缓存感知的 LLM 代理网关"——命中率和毛利曲线都是可量化、可复现的系统贡献。