feat(v2): T14 README v2 改写（架构/快速开始/指标）
This commit is contained in:
tzt
@@ -0,0 +1,47 @@
|
|||||||
|
# AGENTS.md — Agent 仓库导读
|
||||||
|
|
||||||
|
> 面向在此仓库工作的 AI Agent。人类开发者也可参考。
|
||||||
|
|
||||||
|
## 当前权威规划（先读这个）
|
||||||
|
|
||||||
|
**《实现方案_v2_端云协同LLM协作系统.md》**（仓库根目录）是当前唯一权威实施方案：
|
||||||
|
大模型（API）任务分析/决策/终审 ＋ 小模型（本地 llama.cpp）实现/自验证 ＋「交流文本」结构化共享工作区 ＋ 人工检验队列。
|
||||||
|
|
||||||
|
- 实现前必读其第 3 节（不得推翻的设计决策 D1–D11）与第 8 节（工程规约）。
|
||||||
|
- 任务按其第 7 节 T1–T14 顺序执行；每完成一个任务，在《任务拆解与执行计划.md》登记一行。
|
||||||
|
- v1 的 L0 专家系统内核**不删除**，保留为 legacy 路由（`POST /chat/legacy`）与离线降级模式；
|
||||||
|
v1 测试套件（126 项）必须保持全绿。
|
||||||
|
|
||||||
|
## 环境事实
|
||||||
|
|
||||||
|
- Windows 11，shell 为 Git Bash；Python venv 在 `.venv`（Python 3.14）。
|
||||||
|
- 测试：`.venv/Scripts/python.exe -m pytest tests -q`（基线 126 passed，2026-08-30）。
|
||||||
|
- 运行 demo / 评测 / 网关的命令见 README「快速开始」。
|
||||||
|
|
||||||
|
## 硬性约束（违反即返工）
|
||||||
|
|
||||||
|
1. `router_system/` 核心包零第三方依赖（纯标准库）；`runtime/`、`gateway/` 可用
|
||||||
|
httpx / fastapi / pydantic / uvicorn；新增任何依赖需说明理由并登记 requirements*.txt。
|
||||||
|
2. 所有 LLM 结构化输出必须过 JSON Schema 校验；解析失败重试一次后降级，禁止带病继续。
|
||||||
|
3. Architect（大模型 API）输入永不包含工件全文，只用锚点＋片段（方案 5.1 / D7）。
|
||||||
|
4. 一切 LLM 调用在测试中用 `httpx.MockTransport` 注入，测试不依赖真实模型或 API key。
|
||||||
|
5. 不修改 llama.cpp 源码；只捆绑上游 release 二进制（`bin/`，gitignore）。
|
||||||
|
6. Windows 兼容：`pathlib` 路径、CLI 出口 UTF-8 reconfigure（先例 `scripts/eval.py`）、
|
||||||
|
子进程 terminate→kill 兜底。
|
||||||
|
7. 金额敏感：API 调用必须计量并受 `api_token_cap` 熔断约束。
|
||||||
|
|
||||||
|
## 代码风格
|
||||||
|
|
||||||
|
- 中文 docstring；配置构造用 `build_xxx(cfg)` 工厂；与现有文件排版/命名一致。
|
||||||
|
- 每任务一个 commit，格式 `feat(v2): Tn 描述`。
|
||||||
|
|
||||||
|
## 文档地图
|
||||||
|
|
||||||
|
| 文档 | 用途 |
|
||||||
|
|---|---|
|
||||||
|
| 实现方案_v2_端云协同LLM协作系统.md | **当前权威规划**（架构/协议/任务分解/实验设计） |
|
||||||
|
| 任务拆解与执行计划.md | 任务状态登记表（v1 历史任务 + v2 新任务追加处） |
|
||||||
|
| 实现方案_多专业小模型+路由模型.md | v1 方案（已被 v2 取代方向，作历史参考） |
|
||||||
|
| 可行性调研与落地实现路线报告.md | v1 期可行性论证（历史参考） |
|
||||||
|
| research/2026_papers_survey.md | 文献调研（LLM 路由/级联/验证器） |
|
||||||
|
| research/routerarena/01_results_and_gap_analysis.md | v1 实测数据（74.4% 准确率、68.9% 升级率——v2 转向依据） |
|
||||||
@@ -1,125 +1,140 @@
|
|||||||
# 多专业小模型 + 路由模型系统（MVP）
|
# 端云协同 LLM 协作系统（v2）
|
||||||
|
|
||||||
用「轻量分类路由器 + 专业小模型池 + 质量控制器(Judge) + 大模型回退」在限定条件下替代单一通用大模型，
|
大模型（API，Architect）做任务分析/决策/终审 ＋ 本地小模型（llama.cpp，Worker）做实现/自验证，
|
||||||
实现 **成本降低 80%+、延迟可控** 的目标。本仓库是《实现方案_多专业小模型+路由模型.md》的第一阶段落地。
|
两者通过**「交流文本」**（一份 schema 约束的结构化 JSON 共享工作区）交接，互不共享内部状态，
|
||||||
|
另有人工检验队列作为第三协作者。目标是：在端到端质量不降的前提下，把大模型 API token 消耗相对
|
||||||
|
「全量上下文」方案下降 **≥80%**（北极星指标）。
|
||||||
|
|
||||||
## ✨ 当前能力（2026-08-12 已跑通）
|
> v1 的 L0 专家系统内核保留为 **legacy 路由**（`POST /chat/legacy`）与离线降级模式，不删除；126 项 v1 测试保持全绿。
|
||||||
|
|
||||||
- ✅ 零依赖 mock 全链路可运行：缓存 → 分类 → 专家 → Judge → 回退
|
---
|
||||||
- ✅ 5 领域意图分类（code / math / legal / medical / general），规则分类器准确率 **100%**（15 条评测样例）
|
|
||||||
- ✅ 两阶段缓存（L1 精确 + L2 语义 n-gram，零依赖），评测缓存命中率 **40%**
|
|
||||||
- ✅ 质量控制器（Judge）自动评估输出并触发升级，升级率 **20%**（命中第二阶段验收线）
|
|
||||||
- ✅ FastAPI 网关：`/chat` `/health` `/metrics`，20 项单元测试全部通过
|
|
||||||
- ✅ 可选接入真实模型：HuggingFace 小模型（`type: hf`）或 OpenAI 兼容 API（`type: api`）
|
|
||||||
|
|
||||||
## 🚀 快速开始
|
## ✨ 当前能力（2026-08-30 已落地）
|
||||||
|
|
||||||
```powershell
|
- ✅ **交流文本协议**（`router_system/workspace.py`）：schema 校验、锚点寻址（`a://file#L12-18`）、rollup 压缩、双渲染函数（Architect ≤1200 token / Worker ≤8K token）、状态机、前缀稳定性（T10）
|
||||||
# 1. 创建虚拟环境并安装依赖（核心 router_system 零依赖，网关/测试需要轻量依赖）
|
- ✅ **ArchitectClient**（`architect.py`）：DeepSeek JSON 约束输出，失败回喂重写一次，token 计量，预算熔断
|
||||||
C:\Python314\python.exe -m venv .venv
|
- ✅ **WorkerLoop + 接地验证**（`worker.py` / `verifier.py`）：实现→自验证（代码沙箱 > facts 对照 > 结构检查）→自修≤2→issue
|
||||||
.venv\Scripts\python.exe -m pip install -r requirements.txt
|
- ✅ **CollaborativePipeline 编排**（`pipeline.py`）：快路径 → brief → 协作循环 → 终审 → 交付，双护栏熔断
|
||||||
|
- ✅ **运维层**（`runtime/`）：三档硬件检测（gpu12/gpu8/cpu）+ llama-server 进程管理（启停/健康/重启）
|
||||||
|
- ✅ **网关 v2**（`gateway/api.py`）：`/chat`（v2）、`/chat/legacy`（v1）、`/runs/{id}/workspace`、`/runs/{id}/artifacts/{name}`、`/review/queue`、`POST /review/{id}`、`/metrics`（含 v2 统计）
|
||||||
|
- ✅ **人工检验队列**（`review.py`）：sqlite 队列、抽样 + safety 强制入队、verdict/correction 回写
|
||||||
|
- ✅ **打包分发**（`scripts/setup_runtime.py`）：llama-server + GGUF 下载（断点续传/大小校验）
|
||||||
|
- ✅ **E1 token 经济学实验**（`scripts/bench_tokens.py` → `research/v2_experiments/`）
|
||||||
|
- ✅ **测试**：**228 项全绿**（含 v1 legacy 126 项 + v2 新模块）
|
||||||
|
|
||||||
# 2. 运行演示（mock 模式，离线可跑）
|
---
|
||||||
.venv\Scripts\python.exe scripts/demo.py
|
|
||||||
|
|
||||||
# 3. 迷你评估（分类准确率 / 升级率 / 缓存命中率）
|
|
||||||
.venv\Scripts\python.exe scripts/eval.py --repeat 2
|
|
||||||
|
|
||||||
# 4. 运行单元测试
|
|
||||||
.venv\Scripts\python.exe -m pytest tests -v
|
|
||||||
|
|
||||||
# 5. 启动 API 网关
|
|
||||||
.venv\Scripts\python.exe scripts/serve.py --port 8000
|
|
||||||
# 停止：.venv\Scripts\python.exe scripts/serve.py --stop
|
|
||||||
|
|
||||||
# 6. 调用接口
|
|
||||||
curl http://127.0.0.1:8000/health
|
|
||||||
curl -X POST http://127.0.0.1:8000/chat -H "Content-Type: application/json" -d '{"query":"用 Python 写一个快速排序函数"}'
|
|
||||||
curl http://127.0.0.1:8000/metrics
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🏗️ 架构
|
## 🏗️ 架构
|
||||||
|
|
||||||
```
|
```
|
||||||
用户查询
|
用户 query
|
||||||
│
|
│
|
||||||
▼
|
▼
|
||||||
┌───────────────────┐ ┌──────────────────┐
|
[快路径] Worker 直答 + 自验证通过？──是──▶ 直接返回（省 API 钱）
|
||||||
│ RouterCache 缓存 │───▶│ 命中 → 直接返回 │
|
│ 否
|
||||||
│ (L1精确 / L2语义) │ └──────────────────┘
|
|
||||||
└─────────┬─────────┘
|
|
||||||
▼ 未命中
|
|
||||||
┌───────────────────┐ 低置信度(<0.60) ┌──────────────────┐
|
|
||||||
│ 分类路由器 │ ───────────────▶ │ 大模型回退 │
|
|
||||||
│ RuleClassifier / │ │ Mock / DeepSeek │
|
|
||||||
│ HuggingFace │ └──────────────────┘
|
|
||||||
└─────────┬─────────┘
|
|
||||||
▼ 高置信度
|
|
||||||
┌───────────────────┐
|
|
||||||
│ 专家模型池 │ code/math/legal/medical/general
|
|
||||||
│ Mock / HF / API │
|
|
||||||
└─────────┬─────────┘
|
|
||||||
▼
|
▼
|
||||||
┌───────────────────┐ 质量分<0.70 ┌──────────────────┐
|
[Architect·API·一次] brief（goal/constraints/acceptance/plan/tags）写入 交流文本
|
||||||
│ Judge 质量控制器 │ ────────────▶ │ 升级大模型回退 │
|
│
|
||||||
│ Rule / LLM-as-Judge│ └──────────────────┘
|
▼
|
||||||
└───────────────────┘
|
┌─────────── 协作循环（护栏：rounds_cap / api_token_cap 熔断）───────────┐
|
||||||
|
│ [Worker·本地] 读 brief+当前步 → 实现 → 接地验证 → 通过→progress；失败自修≤2→issue │
|
||||||
|
│ [Architect·API·按需] 读 issues → decide → 修订 plan / 兜底代做 │
|
||||||
|
└──────────────────────────────────────────────────────────────────────┘
|
||||||
|
│ 全步 done
|
||||||
|
▼
|
||||||
|
[Architect·API·一次] final_review → done / 打回
|
||||||
|
▼
|
||||||
|
交付 + 入人工检验队列（抽样 / safety 强制）
|
||||||
```
|
```
|
||||||
|
|
||||||
一次请求的完整路由轨迹示例：
|
**核心经济学**：贵的一方（API）少读少写（每次输入 ≤1200 token 压缩摘要），便宜的一方（本地）多读多干。
|
||||||
|
|
||||||
```
|
---
|
||||||
cache:miss -> classify:code@0.95/hard -> expert:expert-code -> judge:0.96
|
|
||||||
cache:miss -> classify:general@0.50/easy -> direct_fallback
|
## 🚀 快速开始
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# 1. 虚拟环境 + 依赖
|
||||||
|
C:\Python314\python.exe -m venv .venv
|
||||||
|
.venv\Scripts\python.exe -m pip install -r requirements.txt
|
||||||
|
|
||||||
|
# 2. 跑测试（v1 legacy 126 + v2 新模块 = 228）
|
||||||
|
.venv\Scripts\python.exe -m pytest tests -q
|
||||||
|
|
||||||
|
# 3. （可选）准备本地运行时：下载 llama-server 二进制 + GGUF 模型
|
||||||
|
.venv\Scripts\python.exe scripts/setup_runtime.py
|
||||||
|
|
||||||
|
# 4. 启动网关（v2 /chat 默认走 mock worker，无需 API key/模型即可演示）
|
||||||
|
.venv\Scripts\python.exe scripts/serve.py --port 8000
|
||||||
|
|
||||||
|
# 5. 调用
|
||||||
|
curl http://127.0.0.1:8000/health
|
||||||
|
curl -X POST http://127.0.0.1:8000/chat -H "Content-Type: application/json" -d '{"query":"用 Python 写一个快速排序"}'
|
||||||
|
curl -X POST http://127.0.0.1:8000/chat/legacy -H "Content-Type: application/json" -d '{"query":"基金定投的收益率怎么计算"}'
|
||||||
|
curl http://127.0.0.1:8000/metrics
|
||||||
|
|
||||||
|
# 6. E1 token 经济学实验（本地确定性测量）
|
||||||
|
.venv\Scripts\python.exe scripts/bench_tokens.py
|
||||||
```
|
```
|
||||||
|
|
||||||
## ⚙️ 配置（config/config.yaml）
|
> 无 API key / 无本地模型时，`/chat` 走快路径（mock Worker）或本地降级，不崩溃。
|
||||||
|
|
||||||
默认全 mock（零依赖离线）。接入真实模型只需改 `type`：
|
---
|
||||||
|
|
||||||
| 组件 | 当前 | 可切换 | 说明 |
|
## ⚙️ 配置（config/config.yaml v2 段）
|
||||||
|------|------|--------|------|
|
|
||||||
| classifier | `rule` | `hf` | 正式环境建议训练 BERT 级分类器（94-97%） |
|
|
||||||
| experts.* | `mock` | `hf` / `api` | HF 小模型或 OpenAI 兼容 API |
|
|
||||||
| judge | `rule` | `llm` | LLM-as-Judge |
|
|
||||||
| fallback | `mock` | `api` | 设置 `DEEPSEEK_API_KEY` 环境变量 |
|
|
||||||
|
|
||||||
关键阈值：
|
| 段 | 关键项 | 说明 |
|
||||||
- `low_confidence_threshold: 0.60` —— 分类置信度低于此值直接走大模型
|
|----|--------|------|
|
||||||
- `judge_fallback_threshold: 0.70` —— Judge 质量分低于此值升级大模型
|
| `runtime` | binary / model / port / hw_profile / tiers | llama-server 二进制、GGUF、三档硬件模板 |
|
||||||
|
| `architect` | model / base_url / api_key_env | 大模型（默认 DeepSeek），`DEEPSEEK_API_KEY` |
|
||||||
|
| `worker` | backend(mock|llama_server) / max_fix_attempts | 小模型后端与自修次数 |
|
||||||
|
| `pipeline` | fast_path / rounds_cap / api_token_cap / breach_policy | 快路径、双护栏熔断、兜底策略 |
|
||||||
|
| `review` | queue_db / sample_rate / force_tags | 人工检验抽样 |
|
||||||
|
|
||||||
## 📂 目录结构
|
---
|
||||||
|
|
||||||
|
## 📂 目录结构（v2 新增）
|
||||||
|
|
||||||
```
|
```
|
||||||
├── router_system/ # 核心（零依赖纯标准库）
|
├── router_system/
|
||||||
│ ├── classifier.py # 意图分类器（规则 / HF）
|
│ ├── workspace.py ★ 交流文本协议（核心）
|
||||||
│ ├── difficulty.py # 难度估计
|
│ ├── architect.py 大模型客户端（brief/decide/final_review）
|
||||||
│ ├── experts.py # 专家池（Mock / HF / API）
|
│ ├── worker.py 小模型实现/自验证循环
|
||||||
│ ├── judge.py # 质量控制器
|
│ ├── verifier.py 接地验证（代码沙箱/facts/结构）
|
||||||
│ ├── fallback.py # 大模型回退
|
│ ├── pipeline.py 协作管线编排
|
||||||
│ ├── cache.py # 两阶段缓存
|
│ ├── review.py 人工检验队列
|
||||||
│ ├── router.py # 主路由
|
│ └── v2stats.py token 计量与聚合
|
||||||
│ └── stats.py # 指标
|
├── runtime/ 运维层（hw_profile / llama_server 进程管理）
|
||||||
├── gateway/api.py # FastAPI 网关
|
├── gateway/api.py v2 + v1 legacy 端点
|
||||||
├── scripts/ # demo / eval / serve / train_classifier
|
├── scripts/
|
||||||
├── tests/ # 20 项单元测试
|
│ ├── setup_runtime.py 下载运行时/模型
|
||||||
├── config/config.yaml # 配置
|
│ └── bench_tokens.py E1 实验
|
||||||
└── research/ # 论文调研
|
├── eval/v2_sample.json 实验数据集
|
||||||
|
└── research/v2_experiments/ E1 结果与实验规划
|
||||||
```
|
```
|
||||||
|
|
||||||
## 📊 验收指标对照（实现方案 5.1/5.2）
|
---
|
||||||
|
|
||||||
| 指标 | 目标 | 当前（mock 评测） |
|
## 📊 指标（v2）
|
||||||
|------|------|------------------|
|
|
||||||
| 分类准确率 | ≥95%（正式） | 100%（15 条样例） |
|
|
||||||
| 升级率（fallback rate） | ≤20% | 20% |
|
|
||||||
| 缓存命中率 | ≥30% | 40% |
|
|
||||||
| 端到端延迟 | < 大模型 1.5× | mock 下 ~10-16ms |
|
|
||||||
|
|
||||||
## 🔜 下一步（对照实现方案）
|
| 指标 | 值 | 说明 |
|
||||||
|
|------|----|------|
|
||||||
|
| 测试 | **228 passed** | v1 legacy 126 + v2 新模块 |
|
||||||
|
| E1 token 下降（A2 交流文本 vs A1 全量） | **~61%**（本地确定性测量） | 真实缓存计费下目标 ≥80%（`--live` 待确认） |
|
||||||
|
| 稳定前缀可命中 | ~99% 的 A2 输入 | 配合 `--cache-reuse` 进一步降成本 |
|
||||||
|
| 快路径 / 熔断 / 回合 | /metrics v2 统计 | V2Stats 实时聚合 |
|
||||||
|
|
||||||
1. 接入真实小模型：`pip install -r requirements-ml.txt`，`experts.*.type` 改 `hf`
|
---
|
||||||
2. 训练 BERT 级分类器替代规则分类器（`scripts/train_classifier.py` 流水线骨架）
|
|
||||||
3. 用 RouterArena（[GitHub](https://github.com/RouteWorks/RouterArena)）标准化评测路由质量
|
## 🔜 下一步
|
||||||
4. 接入 DeepSeek 等大模型 API 作为真实回退层
|
|
||||||
5. 语义缓存升级为 embedding 检索（当前为 n-gram 轻量方案）
|
1. **`--live` 接入真实链路**：安装 runtime（`setup_runtime.py`）+ 设置 `DEEPSEEK_API_KEY`，跑 E1 主实验确认 ≥80% 北极星（`scripts/bench_tokens.py --live`）。
|
||||||
|
2. **E2–E5 跑数**：端到端质量 / 协作健康度 / KV 量化曲线 / 验证器 P/R（见 `research/v2_experiments/README.md`）。
|
||||||
|
3. 用 RouterArena 协议化评测 v2 端到端质量。
|
||||||
|
4. 写 v2 论文（`research/paper/`）。
|
||||||
|
|
||||||
|
## 📌 环境备忘（T1）
|
||||||
|
|
||||||
|
- Windows 11 + Git Bash；venv 在 `.venv`（Python 3.14）。
|
||||||
|
- 测试命令：`.venv/Scripts/python.exe -m pytest tests -q`。
|
||||||
|
- `bin/`、`models/`、`data/`、`runs/` 已 gitignore（运行时产物不入库）。
|
||||||
|
|||||||
+1
-1
@@ -80,4 +80,4 @@ P0 完成后的能力：干净的后端抽象 + 可量化的评测 + 可追溯
|
|||||||
| T11 | 打包分发 setup_runtime.py | ✅ 完成 | T11 |
|
| T11 | 打包分发 setup_runtime.py | ✅ 完成 | T11 |
|
||||||
| T12 | 实验脚本 bench_tokens.py + 数据集 | ✅ 完成 | T12 |
|
| T12 | 实验脚本 bench_tokens.py + 数据集 | ✅ 完成 | T12 |
|
||||||
| T13 | E1 本地跑数完成（E2–E5 待 live 接入） | ✅ 完成 | T13 |
|
| T13 | E1 本地跑数完成（E2–E5 待 live 接入） | ✅ 完成 | T13 |
|
||||||
| T14 | 文档收口（README v2 改写） | ⬜ | |
|
| T14 | 文档收口（README v2 改写） | ✅ 完成 | T14 |
|
||||||
|
|||||||
Reference in New Issue
Block a user