LESSON · 11

给模型
套上
缰绳

Harness Engineering · 让 AI 真正能上生产。

能用
≠
够用

Demo 跑通是 5%，剩下 95% 是工程。

模型能力 · 四件套

  • 理解 · 看懂输入：文本 / 图像 / 代码 / 数据
  • 生成 · 产出输出：文本 / 代码 / 图 / 决策
  • 推理 · 多步思考：规划、因果、反思
  • 调用工具 · 走出沙盒：函数 / API / Shell / RAG
  • 这四件套是模型的"原始马力"

原始马力大
≠
能拉车

没有缰绳，马力越大越危险

Harness
=
缰绳

套在模型外面的工程系统：约束 + 验证 + 追溯 + 回退 + 沉淀 + 审批。

Harness 最佳实践流程 (点击节点高亮)

📥 输入 🔒 约束 输入护栏/预算/边界 🧠 模型 理解 · 生成 · 推理 · 工具 ✅ 验证 输出护栏/规则/事实 通过 🛑 审批 HITL/风险分级 📤 输出 失败 ↩️ 回退 重试/降级/熔断/人工 重试 📋 追溯 · trace_id 贯穿全链路（输入 → 约束 → 模型 → 验证 → 审批 → 输出） 📚 沉淀 规则化/回归集/改Prompt 失败案例归类 分析日志 改进

① 约束 · Constraint

  • 边界：能做什么 / 不能做什么（白/黑名单）
  • 预算：步数 / token / 时间 / 金额上限
  • 资源：哪些工具能调、哪些目录能写
  • 输入护栏：长度截断、敏感词过滤、注入防御
  • 输出护栏：JSON Schema、内容审核、PII 脱敏
  • → 越自由的模型，越需要明确的边界

② 验证 · Verification

  • 语法验证：JSON / SQL / 代码可解析
  • 规则验证：必填字段、值域、引用完整性
  • 事实验证：引用是否在 RAG 检索结果里
  • 测试验证：跑单测 / 仿真 / dry-run
  • 双 LLM 互检：Critic 角色复核
  • "信任但验证" — 验证失败 = 重试或回退

③ 追溯 · Traceability

  • 请求级：trace_id 串起每一次调用
  • 步骤级：每个 thought / action / observation 都存
  • 引用级：答案的每一句来自哪段证据
  • 版本级：模型版本 + Prompt 版本 + 工具版本
  • 工具：LangSmith / Langfuse / Phoenix / 自建
  • → 能"复盘"的系统，才能"改进"

④ 回退 · Fallback

  • 重试策略：指数退避、max retries、温度抖动
  • 降级方案：旗舰模型→中模型→规则脚本
  • 断路器：连续失败 N 次熔断，避免雪崩
  • 事务回滚：写库 / 发邮件等副作用必须可撤销
  • 人工兜底：模型放弃时切到客服
  • 回退 = 别让一次失败，毁掉整条流程

⑤ 沉淀 · Distillation

  • 从日志学：失败模式归类、典型错误打标
  • 更新 Prompt：把教训写进 SYSTEM
  • 沉淀到规则：高频场景固化为代码
  • 构建评测集：把 bug 变成回归用例
  • 反哺微调：积累足够数据后做 SFT/DPO
  • → 系统越用越聪明，而不是越用越混乱

⑥ 审批 · Approval

  • 风险分级：只读 / 可逆写 / 不可逆写 / 高风险
  • HITL · Human in the Loop：高风险操作必须人确认
  • 审批链：金额阶梯 → 不同审批人
  • 预览 + diff：让人看清"将要改什么"
  • 审计留痕：谁在何时批准了什么
  • 越自动化的系统，越需要"刹车手"

没 Harness vs 有 Harness

裸调模型

  • Demo 5 分钟搞定
  • 线上 5 天就翻车
  • 错了不知道为什么
  • 改不动也回不去
→

带 Harness

  • 初期慢一点
  • 越跑越稳
  • 错了能定位
  • 能改也能回

checklist


[ ] 输入 schema 校验
[ ] 输出 JSON 严格模式
[ ] 步数 / 成本 / 超时上限
[ ] trace_id 全链路追踪
[ ] 错误分类 + 重试 + 熔断
[ ] 高风险操作必须人审批
[ ] 失败用例进回归集
[ ] 模型 / Prompt / 工具的版本号
[ ] 仪表盘：延迟 / 成功率 / 成本
[ ] 红队评测 + 上线 A/B

实战：Pydantic 输出验证


# pip install pydantic openai
from pydantic import BaseModel, Field
from openai import OpenAI

class ReviewResult(BaseModel):
    """代码审查结果的结构化输出"""
    issues: list[str] = Field(description="问题列表")
    severity: str = Field(pattern="^(critical|major|minor)$")
    suggestion: str

client = OpenAI()
resp = client.beta.chat.completions.parse(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "审查这段代码: def f(x): return x+1"}],
    response_format=ReviewResult
)
result = resp.choices[0].message.parsed  # 类型安全！
print(f"严重度: {result.severity}, 问题: {result.issues}")

实战：Langfuse 追溯（3行接入）


# pip install langfuse openai
from langfuse.openai import openai  # 一行替换 import！

# 之后所有 openai 调用自动上报 trace
# 效果：每次调用的 prompt/completion/latency/cost 全部可视化
# 控制台：https://cloud.langfuse.com

client = openai.OpenAI()
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "hello"}],
    metadata={"session_id": "user-123", "task": "greeting"}
)
# → Langfuse 自动记录 trace_id, 延迟, token 消耗, 成本

主流落地工具

  • 编排 · LangGraph / Temporal / Restate
  • 验证 · Guardrails / Pydantic / JSON Schema
  • 观测 · Langfuse / LangSmith / Phoenix
  • 评测 · Promptfoo / Ragas / OpenAI Evals
  • 审批 · Slack/IM 审批机器人 + 自建工作流

模型管智能，
Harness 管可靠。
缺一不可。

AI 工程的两条腿

本课收获

模型四件套 约束 / 验证 追溯 / 回退 沉淀 / 审批 实战清单

回到门户 · 从今天起，给你的 AI 套上缰绳。