贯穿项目：Hamauls Orion One Project Through All 17 Stages

总览

下面这张图是 Hamauls Orion 的目标态架构（第 17 阶段完成时的样子）。你在早期阶段只需要实现最下面一层的极小一部分，但它能让你始终知道「我现在做的这块，最终会嵌在哪里」。

text┌──────────────────────────────────────────────────────────────────────────┐
│  客户端层                                                                 │
│  React + TS 聊天界面 · 文档上传 · 引用溯源面板 · 工具调用可视化            │
│  协议：HTTP/2 + SSE（流式）                        ← 第 1、4 阶段           │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │ SSE / HTTP
┌───────────────────────────────▼──────────────────────────────────────────┐
│  接入层 Gateway（FastAPI）                                                │
│  鉴权 · 限流（按 token）· 超时预算 · 幂等键 · 熔断 · 背压 · 会话管理       │
│                                                    ← 第 4 阶段（M4）       │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │ gRPC（HTTP/2 + protobuf，内部 mTLS）
┌───────────────────────────────▼──────────────────────────────────────────┐
│  编排层 Orchestrator                                                      │
│  查询改写 · DAG 规划（拓扑排序）· 多 Agent 分工 · 工具路由 · 状态检查点    │
│                                                    ← 第 14 阶段（M14）      │
└───┬─────────────────┬──────────────────┬────────────────────┬────────────┘
    │                 │                  │                    │
┌───▼──────────┐ ┌────▼───────────┐ ┌────▼──────────┐ ┌───────▼──────────┐
│ 检索服务      │ │ 推理服务        │ │ 工具服务       │ │ 多模态服务        │
│ Retriever    │ │ Inference      │ │ ToolHub       │ │ Vision            │
│              │ │                │ │               │ │                   │
│ HNSW 向量    │ │ vLLM/SGLang    │ │ MCP servers   │ │ 版面分析 / OCR    │
│ BM25 倒排    │ │ 量化 / 投机解码 │ │ SQL 只读      │ │ VLM 问答          │
│ RRF 融合     │ │ 前缀缓存复用    │ │ 沙箱代码执行   │ │ 图像向量化        │
│ 交叉编码器重排│ │ KV 量化        │ │ 日历 / 邮件    │ │                   │
│ 上下文压缩    │ │                │ │               │ │                   │
│ ← 第 3、13   │ │ ← 第 8、9、10  │ │ ← 第 14       │ │ ← 第 11           │
└───┬──────────┘ └────┬───────────┘ └───────┬───────┘ └───────────────────┘
    │                 │                     │
┌───▼─────────────────▼─────────────────────▼──────────────────────────────┐
│  数据与模型层                                                             │
│  Postgres + pgvector（文档 / 元数据）· Redis（缓存 / 幂等键 / 队列）       │
│  对象存储（原始文件 / 权重）· 领域微调模型（LoRA 合并）                    │
│  ← 第 3、6、7、9 阶段                                                      │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │ OTel 全链路 trace + 指标
┌───────────────────────────────▼──────────────────────────────────────────┐
│  评测与安全层（第 15 阶段 · M15）                                          │
│  黄金评测集 · LLM-as-Judge · CI 回归门禁 · 输入注入检测 · 输出护栏         │
│  红队用例 · 可观测面板（TTFT / TPOT / 排队 / 成本）                        │
└──────────────────────────────────────────────────────────────────────────┘
        ↑ 部署层（第 16 阶段 · M16）：Docker → K8s → 灰度 → 压测 → 告警

一、仓库结构与模块划分

这份目录结构从第 1 阶段就建立，之后 16 个阶段只是往里填内容。早期不要为了「将来可能需要」而过度设计——先建目录与接口，实现可以留 TODO。

texthamauls-orion/
├── pyproject.toml / uv.lock / Makefile / README.md
├── configs/                      # 所有可调参数（hydra 风格，支持命令行覆盖）
│   ├── base.yaml
│   ├── train/{sft.yaml, dpo.yaml, grpo.yaml}
│   └── serving/{vllm.yaml, gateway.yaml}
├── src/hamauls_orion/
│   ├── core/                     # M1：配置、结构化日志、异常体系、通用类型
│   │   ├── settings.py           #   Pydantic Settings（环境变量注入）
│   │   ├── logging.py            #   structlog 配置，带 request_id 串联
│   │   └── errors.py             #   Retryable / Fatal 异常分层
│   ├── data/                     # M1、M6：数据管线与版本管理
│   │   ├── pipeline.py           #   并发调用 + 限流 + 断点续跑
│   │   ├── clean.py              #   polars 清洗、去重、质量报告
│   │   └── version.py            #   数据版本哈希与血缘
│   ├── scratch/                  # M5：不依赖框架的教学实现
│   │   ├── autograd.py           #   手写计算图与反向传播
│   │   └── optim.py              #   SGD / Adam / AdamW
│   ├── models/                   # M8、M9：模型层
│   │   ├── transformer.py        #   自研 GPT（RoPE / RMSNorm / SwiGLU / GQA）
│   │   ├── kv_cache.py           #   增量解码 + 显存核算
│   │   └── adapters.py           #   LoRA / QLoRA 适配
│   ├── ranker/                   # M6、M7：排序与训练
│   │   ├── baseline.py           #   LightGBM 基线
│   │   └── cross_encoder.py      #   重排模型
│   ├── train/                    # M7、M9：训练管线
│   │   ├── loop.py               #   通用训练循环（AMP / 断点续训 / 早停）
│   │   ├── sft.py / dpo.py / grpo.py
│   │   └── tracking.py           #   实验追踪（wandb / MLflow）
│   ├── index/                    # M3：检索内核（本项目最有特色的部分）
│   │   ├── hnsw.py               #   手写 HNSW 近似最近邻
│   │   ├── bm25.py               #   倒排索引 + BM25
│   │   ├── cache.py              #   LRU + LFU 混合缓存（含 TTL 与并发保护）
│   │   └── scheduler.py          #   优先队列调度器（含老化防饥饿）
│   ├── rag/                      # M13：检索增强管线
│   │   ├── pipeline.py           #   改写 → 混合召回 → RRF → 重排 → 压缩 → 生成
│   │   ├── compress.py           #   上下文压缩与 token 预算
│   │   └── cite.py               #   引用溯源（论断 → 原文 span）
│   ├── reason/                   # M10：推理与测试时计算
│   │   ├── cot.py / sc.py        #   思维链、自一致性
│   │   ├── prm.py                #   过程奖励模型打分
│   │   └── budget.py             #   推理预算路由
│   ├── mm/                       # M11：多模态
│   │   ├── vlm.py                #   VLM 推理封装
│   │   └── ingest.py             #   PDF/扫描件 → 版面结构化
│   ├── agent/                    # M14：Agent 与工具
│   │   ├── loop.py               #   ReAct / Plan-Execute 循环
│   │   ├── multi.py              #   多 Agent 分工 + A2A 消息契约
│   │   ├── memory.py             #   记忆分层与检查点
│   │   └── mcp/                  #   自建 MCP servers（检索 / SQL / 沙箱）
│   ├── serving/                  # M4、M16：服务层
│   │   ├── gateway.py            #   SSE 流式网关
│   │   ├── timeout.py            #   分层超时预算
│   │   ├── retry.py              #   分类重试 + 幂等键
│   │   ├── resilience.py         #   熔断 / 限流 / 背压
│   │   └── vllm_backend.py       #   vLLM 接入
│   ├── guard/                    # M15：护栏
│   │   ├── injection.py          #   提示注入检测
│   │   └── output.py             #   输出护栏（PII / 敏感 / 幻觉引用）
│   ├── evals/                    # M15：评测
│   │   ├── metrics.py            #   Recall@k / MRR / NDCG / 编辑距离
│   │   ├── judge.py              #   LLM-as-Judge（含与人工一致性检验）
│   │   ├── gate.py               #   CI 回归门禁
│   │   └── datasets/             #   黄金评测集（版本化）
│   └── observability/            # M1、M15：可观测
│       ├── tracing.py            #   OTel span 组织
│       └── metrics.py            #   TTFT / TPOT / 排队 / 成本
├── proto/hamauls_orion.proto             # M4：gRPC 契约
├── tests/{unit,integration,snapshots}/
├── scripts/                      # 入口脚本（bench_*.py, loadtest, migrate）
├── bench/                        # M2、M3、M16：基准与压测报告
│   ├── recall_vs_qps.md
│   ├── loadtest.md
│   └── cost_model.md
├── docs/
│   ├── architecture.md           # 第 17 阶段：让人 10 分钟看懂
│   ├── perf/{roofline.md, latency-budget.md}
│   ├── net/{timeout-budget.md, diagnosis.md}
│   ├── exp/{baseline.md, alignment.md, rag-ablation.md}
│   ├── safety/redteam.md
│   └── report/engineering-report.md
├── docker/{Dockerfile, docker-compose.yaml}
└── k8s/{deployment.yaml, hpa.yaml, canary.yaml}

二、17 个里程碑总览

下面这张表是「学习进度」与「项目进度」的合一双清单。阶段验收 = 里程碑验收。每个阶段的详情页里也都有对应的里程碑卡片。

三、关键接口契约（早定下来，后面少返工）

这些契约在第 1–4 阶段就定下，之后所有模块围绕它们实现。提前定接口的价值在于：它逼你思考边界，而边界清晰是系统可演进的前提。

python# src/hamauls_orion/core/types.py —— 全项目共享的数据契约（第 1 阶段就写好）
from dataclasses import dataclass, field
from typing import Protocol, AsyncIterator, Any

@dataclass(frozen=True, slots=True)
class Doc:
    doc_id: str
    text: str
    meta: dict = field(default_factory=dict)
    score: float = 0.0

@dataclass(frozen=True, slots=True)
class Chunk:
    chunk_id: str
    doc_id: str
    text: str
    start: int                 # 原文偏移 —— 引用溯源必需
    end: int
    vec: list[float] | None = None

@dataclass
class Answer:
    text: str
    citations: list[tuple[str, int, int]]     # (doc_id, start, end)
    trace_id: str
    usage: dict[str, int] = field(default_factory=dict)   # tokens / cost

# ---- 三个核心接口：所有实现都必须满足，这是可替换性的保证 ----

class Retriever(Protocol):
    """检索器。第 3 阶段手写实现，第 13 阶段可能换成 pgvector，接口不变。"""
    async def retrieve(self, q: str, k: int = 20, **filters) -> list[Doc]: ...
    async def ingest(self, docs: list[Doc]) -> int: ...

class Generator(Protocol):
    """生成器。让「NullPushChannel 精神」在这里延续：
       本地模型 / vLLM / 商业 API / mock 都可替换，上层代码零改动。"""
    async def generate(self, prompt: str, **kw) -> str: ...
    def stream(self, prompt: str, **kw) -> AsyncIterator[str]: ...

class Tool(Protocol):
    """工具。第 14 阶段的 MCP server 都要实现它。
       注意：tools 必须声明 side_effect，用于决定是否需要幂等保护与人工审批。"""
    name: str
    description: str
    side_effect: bool                # True = 有副作用 → 必须幂等 + 可能需审批
    schema: dict                     # JSON Schema，用于参数校验与 function calling
    async def call(self, **kw) -> Any: ...

四、明确不做的事（防止项目失控）

一个能持续 12 个月的项目，成败往往取决于「不做什么」。下面这些是刻意排除的范围——如果你发现自己在做这些，说明方向跑偏了。

五、怎么把它用起来