projectAIpopular/AI代理功能开发/方案_校园AI代理层.md

方案：校园 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，官方价目）： 输入未命中 空闲 ¥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. 方向评估：AI 网关 + 学习型路由（5000–20000 人情景，2026-09-05）

结论：2 万规模下难度路由从"省钱优化"升级为"容量必需"——纯云配额/峰值撑不住， 客户端舰队（学生本机 llama.cpp）即分布式本地推理层，容量随用户线性增长； 路由是把流量分配给该容量池的调度器。日请求 7–15 万、突发 50–150 req/s， 网关单进程（D-P9）经预算重测仍可承载。

共享 Embedding 底座 = 网关语义服务化：/v1/embeddings（llama-server 挂 BGE-m3 / Qwen3-Embedding-0.6B，0.6B 短文本 ~15ms，CPU 即可）+ /v1/route（难度/域/建议路径）。 客户端路由决策同调此 API → 全校一套 Embedding/分类器/策略，改进一次全校生效。 同一底座喂养：语义缓存 L2 升级（T-P6 预留 M3 选项）、RAG 分块、滥用检测、审计抽样。

难度分级的路线修正（关键）：不预测文本固有难度（弱信号，《The Routing Plateau》）， 预测升级概率——标签由网关结果观测自动产生（本地答→验证过→"本地可答"）， v2 验证器 + 审计队列即标签工厂；阈值用 Conformal Cascade（调研文献 2607.25018）校准， 控制 P(需升级|路由本地) ≤ α（教育场景保守优先）。分类器两步走：线性探针（numpy，微秒级） 起步 → 线性不够再上 LoRA heads（注意：per-request LoRA 需 vLLM——即上一节 vLLM 条件启用的 触发项之一，专职分类服务实例）；E-G2 实验裁决（AUC 对比）。

语义分析器与执行逻辑映射（2026-09-05 澄清定稿）：共享 Embedding 底座 + 轻量分类器（LoRA 可选） = 语义分析器（独立组件），职责 = 输出任务难度档位 → 档位选择执行逻辑（而非只选模型）： 简单 → 本地小模型直答；复杂 → 完整四阶段管线（云大模型理解 = Architect.brief → 本地大模型构建+检测 = WorkerLoop → 云大模型解决检测出的问题 = issues/decide 升级回路 → 云端大模型检查代码 = final_review） ——即已实现的 v2 CollaborativePipeline，语义分析器是其入口分流器（升级现有快路径启发式判定； 本地进程内直调，客户端/代理经网关 /v1/route，三方共用）。建议三档：简单/中等/复杂—— 中等 = 单次云端（或本地大模型）直答，跳过四阶段管线的 3 次云端往返（帕累托中段是流量大头， 该档分流效率决定整体经济性）；置信度不足默认中等。难度标签 = 管线充分性观测 （"简单 = 本地直答验证通过且无升级"），与上文升级概率预测同一定义；误分级非对称已由 升级回路兜底（简单→失败→升级；复杂→多付一次 brief，方向安全）。 执行版：《实施方案_语义分析器与三级分级.md》（T-G0–G8，三级规格/DDL/接口/晋升门，约 11 工作日）。

2 万规模网关补强：hnswlib 按课程桶分区 ANN（sqlite 全表扫到顶）；账本 100ms 批量刷盘； 降级阶梯写死（Embedding 挂→退 n-gram+规则；分类器挂→保守全云）；T-P8 预算按 2 万口径重测。

分阶段（每步独立有用）：0 代理+缓存（T-P0..P8）→ 1 /v1/embeddings 只采集不决策 → 2 线性 head shadow mode（预测不动流量，比对一致率）→ 3 正式路由+conformal 校准+升级回路 （复用 v2 验证器/审计队列；用户可见"端侧/云端"来源 + 一键升级重答）→ 4 可选 LoRA（vLLM）。

与主命题的关系（叙事闭环）：v1 规则路由（74.4% 失败教训）→ v2 端云协作（核心系统）→ 平台级学习型路由回归 （真实流量 + 结果标签 + 共形校准 + 生产验证器）。 守门线：① 结果驱动标签，不用文本难度；② shadow 先行 + 降级阶梯；③ conformal 保守阈值保教育质量。

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

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