graph TD    A[模板化提示词+固定种子] --> B[批量生成]    B --> C[产物入库: 元数据台账]    C --> D{机审: 合规/相似度}    D -- 不通过 --> E[丢弃并记录原因]    D -- 通过 --> F{人审抽检}    F -- 不通过 --> E    F -- 通过 --> G[加水印发布]    G --> H[台账关联发布链接]  

前置准备

以文生图批量生产为例，生成侧用任意 OpenAI 兼容接口，台账用 SQLite 起步：

pip install openai pillow sqlite-utils

• 台账表：run_id、prompt 模板版本、种子、模型版本、参数、产物哈希、审核状态、发布链接
• 原则：先有台账再放量——没有元数据的产物一律视为不可发布

步骤一：模板化提示词与种子管理

风格可控的前提是输入可控：提示词走模板（风格词、禁词固定），种子显式记录：

TEMPLATE = "flat illustration, {subject}, soft palette, no text, no watermark"
BANNED = ["logo", "celebrity", "brand"]

def make_prompt(subject):
    p = TEMPLATE.format(subject=subject)
    assert not any(b in p.lower() for b in BANNED), "命中禁词"
    return p

• 模板版本化（v1/v2），与提示词工程流程共用一套管理方式
• 每次生成记录 seed：可复现 = 可审计的前提，投诉时能原样重放出问题的那张图

步骤二：批量生成并写入台账

生成与登记在一个事务里完成，杜绝”有图无账”：

import sqlite3, hashlib, uuid
db = sqlite3.connect("ledger.db")
db.execute("""CREATE TABLE IF NOT EXISTS assets(
  run_id TEXT, prompt_ver TEXT, prompt TEXT, seed INT, model TEXT,
  sha256 TEXT, status TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP)""")

for subject in subjects:
    seed = int(uuid.uuid4().int % 2**31)
    img = client.images.generate(prompt=make_prompt(subject), seed=seed, model="sdxl")
    sha = hashlib.sha256(img.bytes).hexdigest()
    save(img, f"out/{sha}.png")
    db.execute("INSERT INTO assets VALUES(?,?,?,?,?,?,?,CURRENT_TIMESTAMP)",
               (run_id, "v2", make_prompt(subject), seed, "sdxl", sha, "pending"))
db.commit()

步骤三：机审 + 人审双门禁

机审挡大头，人审抽检兜底，两道门都过才允许发布：

def machine_gate(sha):
    checks = {
        "nsfw": nsfw_score(sha) < 0.3,            # 安全分类器
        "dup":  perceptual_dup(sha) is None,     # pHash 去重, 防自抄袭
        "face": face_detect(sha) == 0,           # 无人脸, 规避肖像权
    }
    return all(checks.values()), checks

• 机审不通过的产物状态置 rejected 并记录原因——丢弃也要留痕
• 人审抽检率按风险分级：对外商用 100%，内部素材 10%；审核结论回写台账

步骤四：水印与发布关联

发布前叠加可见/不可见水印，并把发布链接回写台账形成闭环：

from PIL import Image
im = Image.open(f"out/{sha}.png")
im = add_visible_signature(im, "@heiau")     # 可见署名
im = add_invisible_watermark(im, run_id)     # 不可见水印携带 run_id
im.save(f"pub/{sha}.png")
db.execute("UPDATE assets SET status='published', publish_url=? WHERE sha256=?",
           (upload(f"pub/{sha}.png"), sha))

• 不可见水印带 run_id：外部发现侵权或违规内容时，可反查整条生产记录
• 台账定期导出冷备，保留期与内容合规要求对齐（建议 ≥ 2 年）

常见问题

• 风格漂移：模型升级后同模板出图风格变化——模板版本与模型版本绑定登记，换模型跑风格回归集
• 台账漏记：绕过管线手工出图——发布出口只认台账状态为 published 的产物，出口收口即杜绝
• 机审误杀率高：阈值一刀切——按品类分别标定阈值，误杀样本进人审队列回收再训练
• 成本失控：批量任务加预算熔断（日生成量/费用上限），超限自动暂停排队

小结

可控可审计的 AIGC 流水线 = 模板化输入（可控）+ 双门禁审核（合规）+ 全链路台账（可审计）+ 水印闭环（可追溯）。四件事做完，”AI 生产内容”才从个人手艺变成组织能力：任何一张已发布图都能反查出提示词、种子、模型版本与审核记录——这份可追溯性，就是 AIGC 规模化的许可证。

    graph TD    A[阶段1: 模拟器+奖励函数评审] --> B[阶段2: 离线数据训练约束策略]    B --> C[阶段3: 影子模式旁路观察]    C --> D{与人工决策一致率达标}    D -- 否 --> B    D -- 是 --> E[阶段4: 小流量灰度+安全约束]    E --> F{业务指标与护栏均正常}    F -- 是 --> G[逐步放量]    F -- 否 --> H[秒级回滚人工策略]  

前置准备

以”优惠券面额分配”为例：状态=用户特征与历史响应，动作=面额档位数，奖励=核销利润-成本：

• 历史日志：至少一个季度的人工/规则策略日志（state, action, reward）
• 模拟器：用历史数据拟合响应模型（核销率关于面额的曲线），供无限试错

步骤一：模拟器与奖励函数评审

奖励函数是 RL 的”需求文档”，必须评审签字而非工程师自定：

def reward(profit, cost, guard):
    r = profit - cost                      # 主目标:净利润
    if guard["freq"] > 3: r -= 10          # 护栏:同一用户月内触达<=3次
    if guard["margin"] < 0: r -= 100       # 护栏:禁止负毛利发券
    return r

• 每条护栏对应一个可解释的业务红线，写进评审记录
• 模拟器要带分布偏移测试：人为扰动响应曲线 ±20%，看策略是否仍稳健

步骤二：离线训练 + 约束探索

直接用历史日志做离线 RL（如 CQL），避免在线探索伤用户：

# 示意: CQL 保守 Q 学习, 对 OOD 动作压分
loss = td_loss(q, batch) + beta * (q(oos_action) - q(batch.action)).mean()

• 保守项让策略不偏离日志分布太远——“没见过的动作先不给高分”
• 训练完在模拟器里跑 1 万回合：累计奖励、护栏触发次数双达标才进入下一阶段

步骤三：影子模式旁路观察

策略上线但不生效：对每个真实请求给出决策并记录，与人工/规则决策对比：

shadow_action = policy(state)          # 只记录不执行
log(state, shadow_action, human_action)

• 一致率、分歧场景分布是核心读数：分歧集中在哪类用户？分歧处事后收益谁高？
• 影子期至少覆盖一个完整业务周期（含周末/大促），通常 2～4 周

步骤四：小流量灰度 + 硬约束兜底

灰度 5% 流量真正执行策略，同时上三层硬约束：

• 动作裁剪：面额输出 clamp 到 [min, max]，模型再疯也出不了业务边界
• 预算熔断：小时级成本超预算 110% 自动切回规则策略
• 秒级回滚：配置开关一键全量回人工，不依赖发版

灰度看板盯三组数：业务指标（核销利润）、护栏指标（触达频次/负毛利单数）、用户指标（投诉率）。

常见问题

• 奖励黑客：策略刷”看起来高奖励”的漏洞动作（如只给必核销用户发券）——护栏项进奖励 + 影子期人工抽检分歧 case
• 仿真-真实差距（sim2real）：模拟器响应曲线过时——每月用新日志重拟合，灰度期持续对比预测 vs 实际核销率
• 离线训练评估失真：OPE（FQE 等）估计方差大——只作排序参考，最终裁决靠影子期与灰度的真实读数
• 非平稳环境：竞品活动改变用户响应——监控奖励分布漂移，超阈值触发重训

小结

RL 安全落地 = 把试错限制在四个逐渐放开的笼子里：模拟器（无限错）、离线数据（不碰用户）、影子模式（只看不动）、小流量灰度（带护栏动）。每一阶段都有量化门禁（奖励+护栏+一致率），任何一门不过就回退上一阶段。算法决定上限，这条笼子链才决定它能不能真的上线。

    graph TD    A[PyTorch 训练模型] --> B[导出 ONNX 固定输入尺寸]    B --> C[边缘引擎构建 TensorRT/ORT]    C --> D[前后处理对齐 letterbox+NMS]    D --> E{精度对齐 mAP 差 < 0.5}    E -- 否 --> F[排查量化/归一化差异]    F --> C    E -- 是 --> G[实测 FPS/功耗/温度验收]  

前置准备

边缘目标设备以 Jetson Orin Nano 为例（x86 工控机流程相同，引擎换 OpenVINO/ORT）：

pip install onnx onnxruntime ultralytics   # 导出侧
# 设备侧: TensorRT 随 JetPack 自带, 或用 onnxruntime-gpu

• 导出侧与设备侧各留一套相同验证集图片（200 张即可）做对齐测试
• 明确输入契约：尺寸（如 640×640）、归一化方式（/255、BGR/RGB）

步骤一：导出 ONNX 并固定契约

动态轴在边缘引擎上支持差，导出时固定 batch 与尺寸：

yolo export model=best.pt format=onnx imgsz=640 batch=1 simplify=True

import onnx
m = onnx.load("best.onnx")
onnx.checker.check_model(m)
print([i.name for i in m.graph.input], [o.name for o in m.graph.output])

• simplify 会用 onnx-simplifier 折叠常量节点，减少边缘引擎不支持的算子
• 记录输入输出张量名与形状，写进部署文档——这是前后处理的唯一依据

步骤二：构建边缘推理引擎

Jetson 上用 TensorRT 做 FP16 引擎；x86 CPU 盒子用 ORT：

# Jetson: trtexec 构建引擎并序列化缓存
trtexec --onnx=best.onnx --saveEngine=best_fp16.engine --fp16 --workspace=4096

# x86 CPU 盒子: ORT + 线程绑定
import onnxruntime as ort
so = ort.SessionOptions()
so.intra_op_num_threads = 4
sess = ort.InferenceSession("best.onnx", so, providers=["CPUExecutionProvider"])

引擎文件与设备型号、JetPack 版本绑定——换硬件必须重构建，不能拷贝复用。

步骤三：前后处理对齐

边缘端掉点八成出在这里：letterbox 填充值、归一化顺序、NMS 阈值与训练侧不一致：

import cv2, numpy as np

def letterbox(img, size=640):
    r = min(size / img.shape[0], size / img.shape[1])
    nw, nh = int(img.shape[1] * r), int(img.shape[0] * r)
    pad = (size - nw) // 2, (size - nh) // 2
    canvas = np.full((size, size, 3), 114, np.uint8)      # 填充值必须与训练一致
    canvas[pad[1]:pad[1]+nh, pad[0]:pad[0]+nw] = cv2.resize(img, (nw, nh))
    return canvas / 255.0, r, pad                          # /255 与训练一致

• 坐标反算：(x - pad) / r 还原到原图——漏除 ratio 是框偏移的经典 bug
• NMS 用与验证脚本相同的 IoU/conf 阈值；设备端实现不同就统一用 numpy 版

步骤四：精度与性能验收

同一验证集跑”PyTorch 原模型”与”边缘引擎”，双指标验收：

• 精度对齐：mAP@0.5 差 < 0.5 个百分点；FP16 通常无感，INT8 需逐类检查
• 性能验收：连续跑 30 分钟记录 FPS、功耗、核心温度——边缘设备降频是隐性杀手

# 设备侧压测: 记录频率与温度曲线
sudo tegrastats --interval 1000 > stats.log &
python bench_edge.py --engine best_fp16.engine --images val/ --minutes 30

验收标准写进发布单：FPS ≥ 目标值、30 分钟无降频掉速、mAP 差在门禁内。

常见问题

• 框整体偏移：letterbox 的 pad/ratio 反算错误，或导出时内置了预处理又重复做了一遍
• FP16 某类召回崩了：小目标 score 下溢——该层关 FP16 或改 INT8 校准覆盖小目标样本
• 首帧极慢：引擎预热不足，上线前空跑 50 帧再接流
• 多路视频 FPS 不达标：单引擎串行是瓶颈——按路数开多 context 或多进程绑核

小结

边缘部署 = 契约工程：导出时固定输入契约，构建时绑定硬件契约，前后处理复刻训练契约，验收时用同一验证集对齐精度、用长时间压测对齐性能。四个契约任何一个”大概一致”，都会在设备上变成可见的掉点或掉帧——把”对齐”做成 checklist，边缘部署就从玄学变成流水线。

    graph LR    A[Teacher: BERT-base] -->|soft logits| B[Student: 4层小模型]    B --> C[导出 ONNX 计算图]    C --> D[INT8 动态量化]    D --> E{延迟与指标回归}    E -- 达标 --> F[替换线上推理]    E -- 不达标 --> G[回退 FP32 ONNX 或加大 Student]  

前置准备

以文本分类任务为例，准备已训好的 teacher 与无标签蒸馏数据：

pip install transformers torch onnxruntime datasets

• 蒸馏数据：线上真实请求日志脱敏 5～10 万条（比训练集分布更贴近服役分布）
• Student 结构：与 teacher 同族但层数减半（如 4 层 hidden 384）

步骤一：蒸馏训练

student 同时拟合硬标签与 teacher 的 soft logits（暗知识在 soft 分布里）：

import torch.nn.functional as F

T = 4.0  # 温度:越高 soft 分布信息越平滑
for batch in distill_loader:
    with torch.no_grad():
        t_logits = teacher(**batch).logits
    s_logits = student(**batch).logits
    loss_kd = F.kl_div(F.log_softmax(s_logits / T, dim=-1),
                       F.softmax(t_logits / T, dim=-1), reduction="batchmean") * T * T
    loss_ce = F.cross_entropy(s_logits, batch["labels"])
    (0.7 * loss_kd + 0.3 * loss_ce).backward()
    opt.step(); opt.zero_grad()

• 先在小验证集确认 student 硬标签基线，再开始蒸馏
• 温度 T 从 2～4 试起；teacher 越强、数据越贴近线上，蒸馏收益越大

步骤二：导出 ONNX

把 student 导出为静态计算图，交给 ONNX Runtime 做算子融合优化：

python -m transformers.onnx --model=./student_distilled \
  --feature=sequence-classification onnx/student.onnx

import onnxruntime as ort
sess = ort.InferenceSession("onnx/student.onnx", providers=["CPUExecutionProvider"])
out = sess.run(None, {"input_ids": ids, "attention_mask": mask})

导出后用同一批输入对比 PyTorch 与 ORT 的输出 logits，最大绝对差应 < 1e-4。

步骤三：INT8 动态量化

CPU 部署场景下动态量化收益最大，一行配置：

from onnxruntime.quantization import quantize_dynamic, QuantType
quantize_dynamic("onnx/student.onnx", "onnx/student_int8.onnx",
                 weight_type=QuantType.QUInt8)

• 动态量化：权重 INT8、激活运行时量化，无需校准集
• GPU 部署则考虑 ORT 的 TensorRT EP 或静态量化（需校准数据）

步骤四：延迟与指标双回归

建一张对比表，四个配置同机同批数据测量：

import time
def latency(sess_or_model, batches):
    t0 = time.time()
    for b in batches: predict(sess_or_model, b)
    return round((time.time()-t0) / len(batches) * 1000, 2)  # ms/条

门禁线：F1 掉点 ≤0.01 且 p99 延迟达标才允许替换线上模型。

常见问题

• 蒸馏后掉点超预期：蒸馏数据分布偏了（拿训练集蒸馏=二次过拟合），换线上日志数据
• ONNX 导出失败：自定义 head 含不支持算子——改写为等价基础算子或升级 opset
• 量化后个别类别崩坏：INT8 对离群权重敏感——该层回退 FP32（ORT 支持按节点排除）
• 线程数影响大：CPU 推理设置 sess.set_intra_op_num_threads(物理核数)，超线程反而降速

小结

文本模型压缩是一条有序流水线：蒸馏降模型规模（收益最大）、ONNX 降图开销、量化降位宽，每一步之后都做”延迟 + 指标”双回归，掉点超门禁就停在该步回退。最终拿到的不只是一个快模型，而是一张可复用的”配置-延迟-指标”对照表——下次换模型时，它就是容量规划的依据。

    graph TD    A[FP32 基线训练] --> B[开启 AMP 自动混合精度]    B --> C{loss 是否发散}    C -- 否 --> D[叠加梯度累积扩大等效 batch]    C -- 是 --> E[排查:损失缩放/白名单层改 FP32]    E --> B    D --> F[度量:显存/速度/指标三方对比]  

前置准备

PyTorch 1.10+ 原生 AMP，无需额外依赖；确认 GPU 支持 Tensor Core（Volta 及以后）：

python -c "import torch; print(torch.__version__, torch.cuda.get_device_name(0))"

• FP16：指数位少，单值范围小但矩阵运算快、占内存减半
• 混合精度：前向/反向的大矩阵运算用 FP16，权重主副本与归约保持 FP32

步骤一：开启 AMP

autocast 负责按算子选精度，GradScaler 负责防止 FP16 梯度下溢：

import torch
from torch.cuda.amp import autocast, GradScaler

scaler = GradScaler()
for x, y in loader:
    opt.zero_grad()
    with autocast():                 # 算子级自动选 FP16/FP32
        loss = criterion(model(x), y)
    scaler.scale(loss).backward()    # 放大 loss 防梯度下溢
    scaler.step(opt)                 # 反缩放后更新权重
    scaler.update()

不要手动把整个 model.half()——那会连 BatchNorm、LayerNorm 一起压到 FP16，是发散的头号原因。

步骤二：梯度累积扩大等效 batch

小显存跑不了大 batch，就攒 K 步梯度再更新一次：

ACCUM = 8   # 等效 batch = micro_batch * ACCUM
for i, (x, y) in enumerate(loader):
    with autocast():
        loss = criterion(model(x), y) / ACCUM   # 梯度按累积步数平均
    scaler.scale(loss).backward()
    if (i + 1) % ACCUM == 0:
        scaler.step(opt)
        scaler.update()
        opt.zero_grad()

• 学习率按等效 batch 线性缩放（batch ×8，lr ×8 起步再微调）
• 累积期间不要 zero_grad，更新后才清

步骤三：度量三方对比

加速不是信仰，用同一配置跑 200 step 对比三组数字：

import time
def bench(tag):
    torch.cuda.reset_peak_memory_stats()
    t0 = time.time()
    for step, (x, y) in enumerate(loader):
        if step >= 200: break
        train_step(x, y)
    print(tag, round(time.time()-t0, 1), "s |",
          torch.cuda.max_memory_allocated()/1024**3, "GB")

bench("fp32")        # 基线
bench("amp")         # 期望:速度 1.5-3x,显存 -30~50%
bench("amp+accum8")  # 期望:显存再降,等效 batch 变大

记录：step 耗时、峰值显存、验证集指标——三者一起看才算结论。

步骤四：对齐 loss 曲线

加速手段必须不伤收敛：画 FP32 基线与 AMP 的 loss 曲线对比：

• 前几百 step 允许 AMP 略高，但趋势应平行收敛
• 最终验证指标差距应在随机种子波动范围内（同种子跑 2 次估噪声）
• 差距超标 → 检查是否漏了 GradScaler、norm 层是否误入 FP16

常见问题

• loss 出现 NaN：GradScaler 会自动跳过该步；持续 NaN 则把 softmax/norm 相关层显式包到 autocast(enabled=False) 里
• 加速不明显：瓶颈在数据加载（CPU/IO）而非计算——先开 num_workers、pin_memory 再看 AMP
• 累积后效果变差：lr 没按等效 batch 缩放，或累积步数过大导致更新次数太少
• 分布式叠加：DDP + AMP + 累积三者可共存，注意 scaler 各卡独立、梯度同步在 step 前完成

小结

AMP 与梯度累积是显存-速度-精度三角里的两枚免费杠杆：autocast+GradScaler 拿速度与显存，累积拿等效 batch 与收敛稳定性。正确姿势是”基线 → 单开 AMP → 叠加累积 → 三方度量 + 曲线对齐”，每一步都有数字背书；任何一步指标跑偏，回到该步的防坑清单而不是盲目加 epoch。

    graph TD    A[训练脚本产出模型] --> B[序列化 + 元数据登记]    B --> C[FastAPI 包装推理接口]    C --> D[Docker 镜像固化环境]    D --> E[部署 + 健康检查]    E --> F{线上指标正常}    F -- 是 --> G[持续监控漂移]    F -- 否 --> H[回滚上一版本镜像]  

前置准备

以一个已训练好的分类模型为例，安装服务化依赖：

pip install scikit-learn fastapi uvicorn joblib pydantic

• joblib：sklearn 模型序列化事实标准
• pydantic：定义请求/响应契约，接口文档自动生成

步骤一：模型产物与元数据一起登记

只存 .pkl 是事故源头——半年后没人知道它用哪些特征、什么版本训练：

import joblib, json, sklearn

artifact = {
    "model": model,
    "feature_order": feature_cols,          # 特征顺序契约
    "sklearn_version": sklearn.__version__,
    "metrics": {"auc": 0.92, "val_size": 5000},
    "trained_at": "2026-10-13",
}
joblib.dump(artifact, "model_v3.joblib")

• 文件名带版本号（v3），新模型不覆盖旧文件——回滚即换文件
• feature_order 是关键契约：线上特征必须按训练顺序组装

步骤二：FastAPI 包装推理接口

用 pydantic 把入参校验前置，非法请求不进模型：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import joblib, numpy as np

ART = joblib.load("model_v3.joblib")  # 仅加载自有可信产物，见"常见问题"安全条
app = FastAPI(version="3")

class In(BaseModel):
    features: dict[str, float]

@app.get("/healthz")
def healthz():
    return {"model": "v3", "ok": True}

@app.post("/predict")
def predict(inp: In):
    try:
        x = np.array([[inp.features[c] for c in ART["feature_order"]]])
    except KeyError as e:
        raise HTTPException(422, f"缺少特征: {e}")
    return {"score": float(ART["model"].predict_proba(x)[0, 1])}

本地起服务验证：uvicorn serve:app --port 8000，打开 /docs 即得交互文档。

步骤三：容器化固化运行环境

“我本地能跑”的解药是镜像：Python 版本、依赖版本与模型文件一起冻结：

FROM python:3.11-slim
WORKDIR /srv
COPY requirements.txt model_v3.joblib serve.py ./
RUN pip install --no-cache-dir -r requirements.txt
EXPOSE 8000
CMD ["uvicorn", "serve:app", "--host", "0.0.0.0", "--port", "8000"]

docker build -t churn-model:v3 . && docker run -p 8000:8000 churn-model:v3

镜像 tag 与模型版本对齐（v3），部署平台按 tag 发布与回滚。

步骤四：上线监控与漂移检测

服务活着 ≠ 模型好用，监控要覆盖三层：

• 服务层：QPS、p99 延迟、错误率（/healthz 供探针）
• 输入层：特征分布 PSI > 0.2 告警——上游埋点改了的典型信号
• 输出层：预测分数分布漂移、正例率突变；无标签期用代理指标（如人工抽检一致率）

def psi(expected, actual, bins=10):
    edges = np.quantile(expected, np.linspace(0, 1, bins + 1))
    e, a = np.histogram(expected, edges)[0] / len(expected), np.histogram(actual, edges)[0] / len(actual)
    return float(np.sum((a - e) * np.log((a + 1e-6) / (e + 1e-6))))

常见问题

• 线上离线特征不一致（training-serving skew）：特征组装逻辑抽成共享模块，训练与 serving 同代码路径
• sklearn 版本升级后加载报错：镜像冻结版本；升级 = 新模型重训 + 新镜像，不做原地升级
• 冷启动慢：模型加载放启动阶段（lifespan），就绪探针通过后才接流量
• 批量预测需求：另开 /predict_batch 接口，复用同一模型实例，注意限流防 OOM
• 反序列化安全红线：joblib/pickle 加载时会执行对象构造代码，等价于运行任意程序——只加载自己训练管线产出、存放于可信仓库的产物；对外交换的模型数据优先用 ONNX 等不带代码执行的格式，并校验文件哈希/签名

小结

模型服务化四步：产物带元数据登记（可追溯）、接口带契约校验（可调用）、镜像固化环境（可回滚）、三层监控（可运营）。链路搭好后，”上线一个新模型”就退化为一次配置变更：换镜像 tag、跑回归、灰度、全量——模型迭代速度取决于这条链路的自动化程度，而不是训练脚本。

    graph LR    A[修改模板 PR] --> B[schema 校验]    B --> C[离线回归评估]    C --> D{指标是否达标}    D -- 否 --> A    D -- 是 --> E[合并并打版本 tag]    E --> F[灰度 10% 流量]    F --> G{线上指标平稳}    G -- 是 --> H[全量发布]    G -- 否 --> I[一键回滚旧版本]  

前置准备

模板独立成文件入库，渲染用 Jinja2，校验用 pydantic：

mkdir prompts && pip install jinja2 pydantic

目录约定：

prompts/
  answer_with_rag.v2.j2      # 模板文件名带语义版本号
  answer_with_rag.schema.json  # 该模板需要的变量 schema

步骤一：模板入库与版本化

模板从代码里抽出来，用 Jinja2 语法声明变量：

你是客服助手。依据以下资料回答，资料不足时说明无法确认。
资料：
{% for doc in docs %}- {{ doc.title }}: {{ doc.snippet }}
{% endfor %}
用户问题：{{ question }}

• 文件名语义版本（v2/v3），不覆盖旧文件——回滚就是换文件名
• git 管历史，PR 管评审：prompt 改动与代码改动走同一套 review 流程
• 代码里只引用 name + version，禁止再出现裸字符串 prompt

步骤二：变量 schema 校验

渲染前校验入参，把”模板要 docs 却传了 doc”这类错误挡在运行前：

from pydantic import BaseModel, ValidationError
import json, jinja2

class RagVars(BaseModel):
    question: str
    docs: list[dict]

env = jinja2.Environment(autoescape=False)

def render(name_ver: str, variables: dict) -> str:
    schema = json.load(open(f"prompts/{name_ver.split('.')[0]}.schema.json"))
    RagVars.model_validate(variables)          # 缺字段/类型错直接抛错
    tpl = env.from_string(open(f"prompts/{name_ver}.j2").read())
    return tpl.render(**variables)

schema 与模板同 PR 修改，保证”模板-变量”契约始终一致。

步骤三：离线回归评估

维护 30+ 条输入样例与期望要点，每次模板变更跑全量对比：

import pytest

CASES = [("订单到哪了", ["物流", "单号"]), ("能退款吗", ["退款政策"])]

@pytest.mark.parametrize("q,expects", CASES)
def test_template_regression(q, expects):
    prompt = render("answer_with_rag.v2", {"question": q, "docs": load_docs(q)})
    answer = llm.chat(prompt)
    assert all(e in answer for e in expects)

• 关键场景再加”禁语断言”（如不得承诺赔偿金额）
• 对比基线：新版本与旧版本在同批 case 上的得分差，写进 PR 描述

步骤四：灰度发布与回滚

prompt 版本做成运行时配置，而非发版常量：

ver = config.get("prompt.answer_with_rag", default="v2")  # 配置中心可热更
if hash(request_id) % 100 < 10:
    ver = config.get("prompt.answer_with_rag.canary", default=ver)

• 灰度期对比两组指标：拒答率、人工转接率、用户负反馈率
• 回滚 = 配置改回旧版本号，秒级生效，无需重新部署服务

常见问题

• 模板里要不要写示例（few-shot）：要，但示例也是回归对象——改示例等同改逻辑，必须跑评估
• 多模型共用一套模板：避免；不同模型对格式敏感度不同，按模型族分模板分支
• 版本爆炸：废弃模板季度归档删除，保留最近 3 个版本即可
• 评估成本高：全量 case nightly 跑，PR 门禁只跑核心 10 条 + 变更涉及的场景

小结

把提示词当代码管，核心是四件事：文件化与语义版本（可回滚）、schema 契约（可校验）、回归评估（可度量）、灰度与热回滚（可发布）。做到这四件，prompt 迭代就从”改字符串碰运气”变成有门禁、有灰度、有回滚的标准变更流程——LLM 应用的可维护性，一大半藏在这个目录里。

    sequenceDiagram    participant U as 用户    participant A as Agent    participant L as LLM    participant T as 工具    participant S as Trace 存储    U->>A: 任务请求    A->>S: span 开始(run)    A->>L: 规划调用    L-->>A: 决策:调用工具    A->>T: tool span    T-->>A: 工具结果    A->>L: 汇总调用    L-->>A: 最终答案    A->>S: span 结束(耗时/token/结果)    A-->>U: 返回答案  

前置准备

不引重型平台，先用结构化日志实现 trace，评估用 pytest 承载：

pip install pytest openai
mkdir -p agent_eval/cases

• trace：一次 run 一条 JSONL，内含嵌套 span（llm / tool / memory）
• 黄金集：cases/*.json，每条含 task、期望要点、禁止行为

步骤一：给 run 加 trace 埋点

用装饰器把每次 LLM 调用与工具调用记成 span：

import json, time, uuid, contextlib

TRACE = open("trace.jsonl", "a", encoding="utf-8")

@contextlib.contextmanager
def span(run_id, kind, name, **extra):
    sid, t0 = uuid.uuid4().hex[:8], time.time()
    rec = {"run": run_id, "span": sid, "kind": kind, "name": name, **extra}
    yield rec
    rec.update(ms=round((time.time()-t0)*1000), ts=time.time())
    TRACE.write(json.dumps(rec, ensure_ascii=False) + "\n")

Agent 主循环里包一层即可：

with span(run_id, "llm", "plan", prompt=prompt) as s:
    decision = llm.chat(prompt)
    s["tokens"] = decision.usage.total_tokens

with span(run_id, "tool", decision.tool) as s:
    result = run_tool(decision)
    s["ok"] = result.ok

步骤二：构建黄金评估集

从线上真实任务里挑 30～50 条，标注”必须做到”和”绝不允许”：

{
  "task": "查询订单 2024-118 的物流状态并告知用户",
  "must": ["调用订单工具", "回复包含物流单号"],
  "must_not": ["编造物流时间", "泄露其他订单信息"]
}

黄金集要持续生长：线上每出一次 bad case，修完后就补进集里防回归。

步骤三：规则 + LLM-as-judge 双判分

规则判硬指标（工具调用序列、must_not），LLM 判软指标（完整性、语气）：

def judge(case, trace, answer):
    hits = [m for m in case["must"] if m in flatten(trace, answer)]
    violations = [m for m in case["must_not"] if m in answer]
    soft = llm.chat(f"按 rubric 给 1-5 分：{case['task']}\n回答：{answer}")
    return {"hard": not violations and len(hits) == len(case["must"]),
            "violations": violations, "soft": soft}

pytest 里每条 case 一个用例，CI 跑全量：改 prompt、换模型、动工具定义，都必须过这道门禁。

步骤四：线上监控与告警

从 trace 聚合四个核心指标进监控面板：

• 任务成功率：硬判分口径的线上抽样版（每天抽 5% run 跑 judge）
• 平均步数与重试率：步数突增 = 规划退化或工具不稳
• token 成本 / run：按 span.kind 拆分，定位是规划烧钱还是汇总烧钱
• 工具失败率：按 tool name 分组，区分”Agent 笨”和”工具挂”

告警阈值示例：成功率环比降 5 个百分点、p95 步数翻倍即告警。

常见问题

• trace 数据量太大：span 只记摘要（prompt 哈希 + 首尾 200 字），原文按 run_id 落冷存储
• LLM judge 不稳定：rubric 写成 checklist、温度设 0、同条跑 3 次取多数
• 评估集过拟合：只盯着黄金集调 prompt 会换来”应试 Agent”，每月换血 20% case
• 隐私合规：trace 含用户数据，入库前脱敏，保留期与隐私政策对齐

小结

Agent 的质量工程 = 看得清 + 判得准 + 防得住：trace 把黑盒拆成可查询的 span，黄金集把”好”定义成可执行的断言，监控把退化拦在用户投诉之前。先埋点再谈优化——没有 trace 的 Agent 调优是占卜，有了 trace 和评估门禁，迭代才是一门工程。

    graph TD    Q[用户问题] --> V[向量检索 top-20]    Q --> B[BM25 关键词检索 top-20]    V --> R[RRF 融合去重]    B --> R    R --> K{融合后是否够 10 条}    K -- 够 --> RR[rerank 模型精排]    K -- 不够 --> E[告警并检查索引覆盖]    RR --> T[取 top-3 拼入提示词]  

前置准备

在已有向量库 RAG 的基础上加装关键词检索与重排模型：

pip install rank-bm25 flag-reranker
# flag-reranker 提供 bge-reranker 系列交叉编码器

• rank-bm25：纯 Python 的 BM25 实现，小规模语料足够
• reranker：交叉编码器，把”问题-段落”拼在一起打分，比双塔向量更准但更慢，所以只排候选集

步骤一：双路召回

向量检索抓语义，BM25 抓字面（型号、错误码、人名这类词向量经常糊掉）：

from rank_bm25 import BM25Okapi
import jieba

corpus_tokens = [list(jieba.cut(c)) for c in chunks]
bm25 = BM25Okapi(corpus_tokens)

def recall(question, k=20):
    vec_hits = vector_store.query(embed(question), top_k=k)      # 语义路
    kw_ids = bm25.get_top_n(list(jieba.cut(question)), range(len(chunks)), n=k)
    kw_hits = [chunks[i] for i in kw_ids]                        # 字面路
    return vec_hits, kw_hits

两路各取 top-20 而不是 top-5：召回阶段宁可冗余，把裁减交给后面的精排。

步骤二：RRF 融合

不用加权分数相加（两路分数量纲不同），用 Reciprocal Rank Fusion 只认排名：

def rrf_fuse(vec_hits, kw_hits, k=60):
    score = {}
    for rank, doc in enumerate(vec_hits):
        score[doc] = score.get(doc, 0) + 1 / (k + rank + 1)
    for rank, doc in enumerate(kw_hits):
        score[doc] = score.get(doc, 0) + 1 / (k + rank + 1)
    return sorted(score, key=score.get, reverse=True)[:10]

同时出现在两路的段落分数叠加，自然浮到前面——这就是”混合”的价值。

步骤三：rerank 精排

交叉编码器对融合后的 10 条逐一打分，取 top-3 进 prompt：

from FlagEmbedding import FlagReranker
reranker = FlagReranker("BAAI/bge-reranker-base", use_fp16=True)

pairs = [[question, doc] for doc in fused]
scores = reranker.compute_score(pairs)
top3 = [doc for _, doc in sorted(zip(scores, fused), reverse=True)[:3]]

注意设置分数阈值（如 >0）：全部低分的宁可不注入，避免”没有依据硬答”变成”拿着错依据答”。

步骤四：上线召回率回归

准备 50～100 条”问题-应命中段落”标注集，对比改造前后：

def recall_at_k(pred_docs, gold_doc, k=3):
    return gold_doc in pred_docs[:k]

before = sum(recall_at_k(old_pipeline(q), g, 3) for q, g in labeled) / len(labeled)
after  = sum(recall_at_k(new_pipeline(q), g, 3) for q, g in labeled) / len(labeled)
print(f"recall@3: {before:.2%} -> {after:.2%}")

recall@3 提升 10 个百分点以上再上线；同时记录端到端延迟增量（rerank 约 +50～150ms）。

常见问题

• BM25 路毫无贡献：中文没分词或停用词没处理，检查 jieba 分词与索引一致性
• rerank 成为延迟瓶颈：候选从 10 砍到 8、换 reranker-small、或 fp16/INT8 推理
• 融合后反而变差：某一路噪声太大（如 BM25 命中大量模板句），给该路加 IDF 过滤或降 k
• 阈值怎么定：在标注集上看 rerank 分数分布，取”金标准段落最低分”再留 10% 余量

小结

生产级召回是一条漏斗：双路宽召回保覆盖，RRF 融合做无量纲合并，rerank 精排保精度，最后用 recall@k 标注集做上线门禁。每一段都可独立替换（换向量模型、换 ES、换 reranker），但”宽召回 → 融合 → 精排 → 度量”的骨架不变——召回质量的提升来自漏斗设计，而不是某个单点模型。

    graph TD    A[FP16 原始模型] --> B{显存是否充足}    B -- 充足 --> C[FP16 直接部署]    B -- 不足 --> D[INT4 量化 AWQ/GPTQ]    D --> E{质量回归是否达标}    E -- 达标 --> F[单卡部署上线]    E -- 不达标 --> G[升 INT8 或换更大显存]    G --> F  

前置准备

硬件与工具：一张 12GB 以上显存的 NVIDIA 卡；安装 llama.cpp 或 vLLM：

# 路线一：llama.cpp（GGUF 量化，CPU/GPU 混合，最省资源）
git clone https://github.com/ggerganov/llama.cpp && cd llama.cpp
pip install -r requirements.txt

# 路线二：vLLM（AWQ/GPTQ，GPU 服务化吞吐更高）
pip install vllm

• GGUF：llama.cpp 生态格式，量化档位 q4_k_m / q5_k_m / q8_0
• AWQ/GPTQ：校准数据感知的量化，同比特下通常比朴素 RTN 更保精度

步骤一：估算显存需求

先算账再动手，避免盲目下载：

def vram_gb(params_b, bits, ctx_tokens=4096, kv_bytes_per_token=0.5*1024*1024/1024/1024*1024):
    weight = params_b * 1e9 * bits / 8 / 1024**3      # 权重显存
    kv = ctx_tokens * kv_bytes_per_token / 1024**3 * 13  # KV cache 粗估(13%系数示例)
    return round(weight + kv + 1.0, 2)                # +1GB 运行时开销

print(vram_gb(7, 16), "GB (FP16)")   # 约 14+ GB
print(vram_gb(7, 4),  "GB (INT4)")   # 约 4.5 GB

结论：12GB 卡跑 7B，INT4 是唯一可行档位；INT8（约 8GB）也能跑但上下文要收紧。

步骤二：量化模型（GGUF 路线）

下载 FP16 权重后转换为 GGUF 并量化到 q4_k_m：

# 转换为 GGUF
python convert_hf_to_gguf.py ./model-7b-fp16 --outfile model-7b-f16.gguf

# 量化到 q4_k_m（精度/体积平衡档）
./llama-quantize model-7b-f16.gguf model-7b-q4_k_m.gguf q4_k_m

vLLM 路线则直接用社区已量化好的 AWQ 权重，无需自己校准：

pip download --no-deps solidcodes-7b-awq  # 示意：替换为实际 AWQ 模型 ID

步骤三：启动推理服务

llama.cpp 起一个 OpenAI 兼容接口：

./llama-server -m model-7b-q4_k_m.gguf -ngl 99 --port 8080 -c 4096

vLLM 起 AWQ 模型：

python -m vllm.entrypoints.openai.api_server \
  --model your-org/model-7b-awq --quantization awq --max-model-len 4096

两条路线都暴露 /v1/chat/completions，业务代码无需改动。

步骤四：质量与速度回归

量化必须过回归关，用同一批样例对比 FP16 与量化版：

import openai, time
client = openai.Client(base_url="http://localhost:8080/v1", api_key="x")

cases = ["解释什么是梯度下降", "写一首五言绝句", "9.11 和 9.9 哪个大？"]
for q in cases:
    t = time.time()
    r = client.chat.completions.create(model="q4", messages=[{"role":"user","content":q}])
    print(round(time.time()-t, 2), "s |", r.choices[0].message.content[:60])

• 主观题看答案是否仍连贯、无乱码与复读
• 客观题（数学/指令遵循）记录准确率，掉点超过 5 个百分点就升档到 q5/q8
• 记录 tokens/s 与首 token 延迟，作为容量规划基线

常见问题

• 量化后输出复读/乱码：档位过低或校准不匹配，升 q5_k_m 或换 AWQ 重 quant
• 仍然 OOM：上下文太长，KV cache 吃满——降 -c 或开 vLLM 的 block 限制
• CPU 推理太慢：llama.cpp 加 -ngl 99 把全部层放 GPU；无 GPU 时选 moe 小模型而非硬跑 7B
• 困惑度怎么测：llama.cpp 的 perplexity 工具对比 FP16/量化版，涨幅 <10% 一般可接受

小结

单卡部署的本质是显存预算分配：权重（靠量化压缩）+ KV cache（靠上下文长度控制）+ 运行时开销。先估算、再选档、后回归，量化就从”碰运气”变成一条可复现的工程流水线：FP16 算账 → INT4 量化 → 服务化 → 质量/速度双回归，任何一环不达标就回到选型调整档位。

记忆分类学（对照人类记忆）

• 工作记忆（感官/短期）：当前上下文窗口内的对话——昂贵且易失
• 情景记忆（episodic）：发生过的事：”用户 3 月 5 日让我订了靠窗座位”——带时间的经历日志
• 语义记忆（semantic）：提炼的事实与偏好：”用户偏好靠窗、花生过敏”——去时间化的知识
• 程序记忆（procedural）：学会的技能/流程（成功的工作流模板）——进阶形态

工程上优先做语义+情景两层：语义记忆服务个性化，情景记忆服务追溯与审计。

三段式设计：写入 → 存储 → 读取

写入（什么值得记）：

• 对话结束后（或每 N 轮）用 LLM 做记忆抽取：从对话中提炼候选事实（”用户提到 X”），而非整段对话入库
• 抽取 prompt 要求结构化输出：{事实, 类别, 重要性, 时间}；重要性过滤掉寒暄噪声
• 冲突处理：新事实与旧记忆矛盾时（”我搬家了，现在住上海”），更新而非并存——记忆需要”改写”能力

存储（存在哪、怎么组织）：

• 语义记忆：向量库（事实文本 embedding）+ 结构化表（用户画像字段：偏好/禁忌/身份）双写——向量供模糊召回，表供精确读取
• 情景记忆：带时间戳的事件日志（append-only），按会话/主题分片
• 元数据必备：来源会话 ID、创建时间、最后访问时间、访问次数——供遗忘与审计

读取（何时召回、召回什么）：

• 每轮用户消息 → 嵌入 → 向量检索 top-k 相关记忆 + 画像表全量注入（画像小，常驻系统提示）
• 召回内容以”记忆块”形式插入 prompt 并标注来源与时间（”据 3 月 5 日对话：用户花生过敏”），让模型知道这是历史而非当前输入
• 控制注入量：记忆 token 占上下文预算的固定比例（如 10-15%），防记忆挤占工作记忆

遗忘机制：不遗忘的记忆库必然腐烂

• 时间衰减：权重随创建时间衰减（艾宾浩斯式），长期未召回的情景记忆降权/归档
• 访问强化：被召回且”用上了”（用户未纠正）的记忆加权——用反馈做记忆巩固
• 合并去重：周期任务把相似记忆聚类合并为一条概括（”多次提到喜欢清淡口味”）
• 遗忘不是删除是降级：归档区保留可审计，主库保持精瘦

实践参照与自建最小版

• 参照系：MemGPT（把记忆当 OS 分层管理，自编辑记忆）、LangGraph 的 store/checkpointer、Zep（时序知识图谱记忆）
• 自建最小三件套：抽取 prompt + 向量库/画像表 + 召回注入中间件——百行级起步，先跑通”偏好记住”一个场景再扩展

陷阱清单

• 记忆污染：把模型的错误推断当事实写入（”用户应该喜欢 X”）→ 只记用户明确陈述与行为证据
• 隐私红线：敏感信息（证件、健康、财务）入记忆库需脱敏或加密，并提供”查看/删除我的记忆”用户接口（合规要求）
• 召回噪声：不相关记忆注入会误导回答 → 相似度阈值+重要性双过滤，宁缺毋滥
• 记忆与 RAG 混淆：RAG 检索的是外部知识，记忆检索的是用户历史——两者索引、更新频率、权限模型都不同，别共用一套库

长期记忆让 Agent 从”工具”变成”熟人”：写入靠抽取与冲突更新，存储靠向量+画像双轨，读取靠预算内召回，维护靠衰减与合并。四段做齐，再加隐私与污染两条护栏，记忆系统才既好用又可信。

生成即逐步采样

自回归生成每步做同一件事：模型给出词表概率分布 → 解码策略选一个 token → 拼入上下文 → 下一步。贪心（永远选概率最大）只是策略之一；采样类策略在”确定性”与”多样性”之间提供连续可调的光谱。

温度（temperature）：分布的锐化旋钮

采样前对 logits 除以 T 再 softmax：

• T → 0：分布无限锐化，退化为贪心——最确定、最保守，也最容易重复与呆板
• T = 1：模型原始分布
• T > 1：分布拉平，低概率词机会变大——更发散、更有”创意”，也更容易胡话

直觉：温度不改变概率排序，只改变差距。T=0.3 时 Top1 几乎必中；T=1.5 时第 20 名的词也有机会上台。

top-k：候选池硬截断

只从概率最高的 k 个词中采样，其余置零：

• k=1 即贪心；k=40 表示每步在 40 个候选里抽签
• 缺陷：k 是静态的——分布平坦时（该发散时）40 个太少，分布尖锐时（该确定时）40 个太多（尾部垃圾词混入）

top-p（nucleus sampling）：候选池动态截断

按概率从高到低累加，达到累积阈值 p 即截断（如 p=0.9：候选集=凑够 90% 概率质量的最小词集）：

• 分布尖锐时候选集自动变小（甚至 1-2 个词）→ 确定
• 分布平坦时候选集自动变大 → 多样
• 动态自适应是 top-p 优于 top-k 的核心，今天的主流默认

重复惩罚类：压制车轱辘话

• repetition_penalty / frequency_penalty：对已出现过的 token 降权，惩罚系数 >1 抑制复读
• presence_penalty：出现过即固定降权
• 场景：长文本生成、代码补全中防循环；过强会导致”不敢用常用词”的怪异文风

组合配方（按任务类型）

原则：温度与 top-p 通常只调一个（两者作用重叠，同调易失校准）；API 默认值多为对话场景优化，代码类任务记得手动压到 0 附近。

其他解码策略速览

• beam search：保留 k 条最优序列并行扩展，翻译/摘要时代的主流；成本高、多样性差，聊天场景已被采样取代
• min_p：按 Top1 概率的比例设下限（Top1 的 10% 以下全剔除），比 top-p 更抗”分布异常平坦”的崩坏步
• best-of-n / 重排序：采样 n 条用裁判模型选最佳——用算力换质量的上限玩法

调参实验方法

固定 seed 对比会掩盖采样差异（同 seed 同结果）；正确做法：固定 prompt、变参数、每配置采样 10-20 条，人工或 LLM 裁判评多样性与质量均值——解码策略是分布级属性，单条对比无统计意义。

解码策略是模型与用户之间的最后一层创作权：温度管锐度、top-p 管候选池、惩罚管复读。理解每个旋钮在概率分布上做了什么，”调参”就从玄学变成对分布形状的主动 sculpting。

先建成本模型：钱花在哪

推理成本由三部分构成：

• 显存占用 ≈ 参数量 × 每参数字节（FP16=2B、INT8=1B、INT4=0.5B）+ KV cache（随上下文长度线性增长）。7B FP16 ≈ 14GB 显存起步；70B FP16 单卡放不下
• 计算量 ≈ 2 × 参数量 × token 数（每 token 一次全参数矩阵乘）——参数翻倍，每 token 成本翻倍
• 延迟 = 首 token 延迟（prefill，随输入长度）+ 逐 token 生成（decode，受显存带宽限制）

由此推出硬约束：候选模型必须先过”显存放得下”与”延迟可接受”两关，效果比较只在过关者之间进行。

量化：最便宜的降成本杠杆

• FP16 → INT8：显存减半，多数任务效果损失 <1%
• INT8 → INT4：再减半，复杂推理开始可见损失（用 AWQ/GPTQ 等校准量化可缓解）
• 实践顺序：先试 INT4/INT8 量化版大模型，对比 FP16 小模型——**”量化的大”常常赢过”全精的小”**（知识容量在参数里，量化只是压缩表示）

效果-规模的经验规律

• 通用能力随规模平滑上升（scaling law），但特定垂直任务上，微调小模型可追平甚至超过通用大模型（ LoRA 微调 7B 在分类/抽取类任务上常见追平 70B 零样本）
• 推理类任务（数学/多步规划）规模收益最陡，小模型天花板明显
• 因此选型第一问：**任务是需要”广博知识+复杂推理”，还是”窄域模式匹配”**？前者买大，后者训小

分层路由：让每个 token 花该花的钱

生产系统的标准架构是模型路由（LLM router）：

• 简单请求（FAQ、格式转换、简单分类）→ 1-3B 本地小模型或量化 7B
• 中等请求（摘要、普通问答）→ 7-14B
• 困难请求（复杂推理、代码生成、多文档综合）→ 70B+ 或旗舰 API
• 路由器本身：一个小分类模型或规则+置信度回退（小模型低置信时升级大模型）

成本收益：80% 流量落在小模型时，总成本可降一个数量级而体验无损。

决策速查表

别忘了隐性成本

• 上下文长度：长上下文使 KV cache 显存暴涨，RAG 场景控制召回量比选小模型更省钱
• 批处理与并发：decode 阶段显存带宽是瓶颈，batch 提升吞吐但不降单请求延迟——成本核算要按吞吐口径
• 失败重试：小模型错误率高的任务，重试与人工兜底成本可能反超大模型一次做对

模型选型的完整答案 = 显存/延迟硬约束过滤 → 量化杠杆压成本 → 任务类型定规模（窄域训小、推理买大）→ 路由分层省总账。记住”量化的大常赢全精的小”与”80% 流量该走小模型”两条经验，多数选型争论就有了裁决依据。