Harness Engineering: From Eval to Production

Why now

2025 年，Hamel Husain 在《Your AI Product Needs Evals》里写了 LLM 应用不能没有 eval 这件事。这是 LLM 工程化转折点的标志。但读完 Hamel 的论文，你会发现一件事：eval 只是开始，不是结束。

如果你在生产环境跑过 LLM 应用，你会发现 eval 解决了一类问题（"我的 prompt 对不对"），但还有 4 类问题 eval 解决不了：

1. 失败的时候怎么 debug — eval 告诉你 pass rate 下降了，但为什么？哪个 case 失败？
2. production 用户真实在问什么 — eval 用的是 test case，但生产 case 永远不一样
3. token 成本和 latency — eval 不管这些，但生产在管
4. 跨版本回归 — 改一行 prompt 整个 app 会不会崩？

这是 Harness Engineering 出现的原因。它不取代 eval，它是 eval 的超集。如果说 Context Engineering 关心"模型看到什么"，Harness Engineering 关心"模型做得对不对 + 怎么持续监控"。

这篇文章是我读完 Hamel Husain + LangSmith 全部博客 + Anthropic Building Effective Agents (harness view) + 14 篇 D+4 评测之后，写的一个综述。它把 4 个问题的答案全放在一起：

1. Harness Engineering 是什么 — 跟 Eval 有什么不一样
2. 如何做好 — 8 个 best practice，按影响度排序
3. 项目中怎么应用 — 5 种典型项目 × 必做映射
4. 效果到底多大 — 单点 vs 复合的量化数据 + MTTR 改善

如果你在做 LLM 应用 — 无论 ChatGPT 替代 / RAG / agent / ToB — Eval 永远 Day 1，加上 Tracing / Log / CI 这 3 件之后，你的故障响应时间从"天"变成"分钟"。

Q11. Harness Engineering 是什么

Eval vs Harness

Eval 关心"对不对" — 你写 test cases，跑 pass rate，看 prompt 改了什么。
Harness 关心"为什么 + 怎么持续知道" — eval + observability + log + tracing + regression + monitoring。

Hamel Husain 在《Your AI Product Needs Evals》里讲："You can't improve what you can't measure." — 这句话是 Eval 的底层逻辑。但 Harness 把它扩展成 "You can't run what you can't monitor." — 一个 LLM 应用在生产环境的生命周期里，Eval 只是入口。Harness 是它的运行时。

这个区别在 demo 阶段不明显 — 你写 5 个 case，pass rate 80%，觉得可以了。但 production 阶段，10 万用户每天问几千个问题，你不知道哪个 case 失败了，因为你没有 observability。3 周后用户报 bug："回答错了"，你回到 dashboard，发现 token 成本翻了一倍 — 不知道什么时候开始的。哪个 case 触发的？不知道。这就是没有 Harness 的生产环境。

4 大组件

Harness Engineering 不是单一技术 — 它由 4 大组件构成：

#	组件	做什么	代表工具
1	Eval Suite	test cases + pass rate + 自动化	Hamel Evals / OpenAI Evals / LangSmith Evals
2	Tracing / Observability	每次 LLM call 记录 prompt + response + latency + cost	LangSmith / Langfuse / Arize Phoenix / Helicone
3	Log / Debug	失败 case 回放 + 上下文栈 + token 流向	LangSmith Debug / Helicone Playground
4	Regression / CI	版本对比 · 跨 release pass rate · 自动报警	LangSmith CI / Braintrust / DeepEval

这 4 件里，Eval Suite 是 Day 1 必做。其他 3 件在 production 阶段加上。没有 Eval Suite 的 LLM 项目是赌博；没有 Tracing 的 production LLM 是定时炸弹。

GitHub 项目 · 6 个值得看

#	Repo	Stars	做什么	应用
1	langchain-ai/langsmith	~1K	Eval + observability + tracing + CI · LangChain 官方	生产级 LLM 监控
2	langfuse/langfuse	~5K	开源 LLM observability · 自托管 · 与 LangSmith 类似	企业自托管
3	openai/evals	~3K	OpenAI 官方 eval 框架 · eval cases + grading	OpenAI 模型 eval
4	confident-ai/deepeval	~3K	DeepEval · LLM eval 框架 · G-Eval / RAG metrics	学术 + 生产
5	explodinggradients/ragas	~9K	RAG eval 框架 · faithfulness / relevance / precision	RAG 应用
6	promptfoo/promptfoo	~5K	Prompt + LLM 评测 · 红队 · CI/CD 集成	CI / 安全

Harness vs Context Engineering · 互补

这两个 4-Q 系列是 互补关系，不是替代：

问题	Context Engineering 答	Harness Engineering 答
"模型该看到什么"	Context 设计的 8 best practice · 4 类失败模式	—
"模型做得对不对"	—	Eval Suite + pass rate
"为什么失败"	—	Tracing + Log + Debug
"跨版本回归"	—	Regression test + CI
"生产监控"	—	Observability + Alert

核心洞察：Context Engineering 设计 → Harness 验证 + 监控。前者是 craft（手艺），后者是 engineering（工程）。两者一起才完整。

代码示例 · LangSmith Eval Suite

Hamel Husain 的 "evals first" 范式 + LangSmith 实现：

from langsmith import Client, evaluate
from langchain import ChatOpenAI

llm = ChatOpenAI(model="gpt-5")

# Step 1: 写 eval cases
client = Client()
dataset = client.create_dataset("invest-qa-v1")

client.create_examples(
    inputs=[
        {"question": "什么是市盈率?"},
        {"question": "ROE 怎么算?"},
        {"question": "DCF 模型三要素?"},
    ],
    outputs=[
        {"answer": "P/E 是 股价 / 每股收益"},
        {"answer": "净利润 / 股东权益"},
        {"answer": "现金流 + 折现率 + 终值"},
    ],
    dataset_id=dataset.id,
)

# Step 2: 定义 predict + grader
def predict(inputs):
    return llm.invoke(inputs["question"]).content

def grade(run, example):
    grader_prompt = f"""Is the answer semantically equivalent to the expected?

Expected: {example.outputs['answer']}
Actual: {run.outputs['answer']}

Answer YES or NO."""
    verdict = llm.invoke(grader_prompt).content
    return {"score": 1 if "YES" in verdict.upper() else 0}

# Step 3: 跑 eval
results = evaluate(
    predict,
    data=dataset.name,
    evaluators=[grade],
    experiment_prefix="v1-baseline",
)

print(f"Pass rate: {results.aggregate_metrics['pass_rate']:.0%}")

关键设计：用 LangSmith 把 eval cases + grading + run history 都存起来 — 每一版本都有 trace。这就是 harness 的核心。

Q22. 如何做好：8 个 best practice

下面 8 个 best practice 按"影响度 + 实现成本 + 可替代性"3 维加权排序。3 个 必做（任何 LLM 项目） + 5 个 nice-to-have（按项目复杂度递进）。

🥇 #1 Eval Suite (Day 1) — Hamel 8.00

在写 prompt 之前，先写 eval cases。5-10 个典型问题 + 期望回答范围。跑 baseline (default context) → 拿到 pass rate。迭代 prompt + context 直到 pass rate > 80%。这是把"context engineering"和"harness engineering"结合起来的起点。

Hamel Husain 的《Your AI Product Needs Evals》是这个范式的圣经。LangSmith / Braintrust / Langfuse 是工具支持。

🥈 #2 Tracing / Observability — LangSmith / Langfuse

每个 LLM call 都该被 trace — 不只是失败 case。生产环境的监控是基于 trace 数据，而不是 LLM 是否崩溃。

from langsmith import traceable
from langchain import ChatOpenAI

llm = ChatOpenAI(model="gpt-5")

@traceable  # 自动记录 prompt/response/latency/cost
def answer_question(question: str) -> str:
    response = llm.invoke(question)
    return response.content

# 调用时自动记录
answer_question("什么是 context engineering?")

# 在 LangSmith dashboard 看：
#   - 输入 prompt 全文
#   - 输出 response 全文
#   - latency ms
#   - token 数量 / cost
#   - 调用栈 (嵌套 traceable 函数)
#   - 失败 case 重放

关键不是事后看 log — 是 每个 call 都被 trace。LangSmith / Langfuse 是当下主流。

🥉 #3 Log + Debug — 故障响应时间 -70%

故障响应时间 = 工程师从发现 bug 到 fix 的时间。没有 log/debug，平均 3 小时。有，平均 15 分钟。差距就是 10 倍以上。

关键设计：失败 case 自动 capture 完整 context（prompt / response / tools / state） + 一键重放 + 关键变量 diff。这能让你把"灾难性故障"变成"日常监控"。

4 个 nice-to-have · 按阶段加

#4 Regression Test in CI (Braintrust)：每次 PR / push 都跑全套 eval + pass rate 比对 + 自动报警。防"改了一行 prompt 整个 app 崩了"。团队 ≥ 3 人 / 每月 release 时必加。

#5 Production Monitoring + Alert (Arize / Datadog LLM)：实时监控关键指标 (latency / cost / pass rate / drift) · 异常自动报警。DAU > 1000 时必加。

#6 Cost + Token Tracking (Helicone)：每 LLM call 成本追踪 + 模型 / provider 对比 + 成本下降趋势。月成本 > $1000 时必加。

#7 RAG Metrics (RAGAS 9K stars)：RAG 应用专属 · faithfulness / relevance / precision 评分。做 RAG 应用时加上。

#8 Red Team / Prompt Fuzzing (Promptfoo 5K stars)：对抗 prompt injection · 越狱检测 · 边界 case 攻击。ToB / 合规要求场景加上。

3 个必做 + 5 个 nice-to-have

必做 / nice	Practice	何时做	投入产出比
必做	Eval Suite (Day 1)	任何 LLM 项目启动时	★ × 5
必做	Tracing / Observability	production 上线前	★ × 5
必做	Log + Debug	production 上线后	★ × 4
nice	Regression Test in CI	团队 ≥ 3 人 / 每月 release	★ × 4
nice	Production Monitoring + Alert	DAU > 1000	★ × 3
nice	Cost + Token Tracking	月成本 > $1000	★ × 3
nice	RAG Metrics	做 RAG 应用	★ × 2
nice	Red Team	ToB / 合规要求	★ × 2

代码示例 · LangSmith Tracing

生产环境必备的 observability 落地代码：

from langsmith import traceable
from langchain import ChatOpenAI

llm = ChatOpenAI(model="gpt-5")

# 1. 标记任何 function 为 traceable (自动记录 prompt/response/latency/cost)
@traceable
def answer_question(question: str) -> str:
    response = llm.invoke(question)
    return response.content

# 2. 调用时自动记录
answer_question("什么是 harness engineering?")

# 3. 在 LangSmith dashboard 看 trace
#    - 输入 prompt 全文
#    - 输出 response 全文
#    - latency ms
#    - token 数量 / cost
#    - 调用栈 (嵌套 traceable 函数)
#    - 失败 case 重放

关键设计：每个 LLM call 都该被 trace — 不只是失败 case。生产环境的监控是基于 trace 数据，而不是 LLM 是否崩溃。

代码示例 · CI Regression

把 eval 集成到 CI / CD：

# .github/workflows/eval-regression.yml
name: LLM Eval Regression
on: [push, pull_request]

jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install langsmith langchain

      - name: Run Eval Suite
        env:
          LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python scripts/run_evals.py

      - name: Compare Pass Rate
        run: |
          # 跟上次 release 的 pass rate 对比
          CURRENT=$(cat eval-results.json | jq .pass_rate)
          BASELINE=$(cat .baseline.json | jq .pass_rate)
          THRESHOLD=0.05  # 允许 5% 退化
          if (( $(echo "$BASELINE - $CURRENT" | bc -l) > $THRESHOLD )); then
            echo "❌ Pass rate dropped from $BASELINE to $CURRENT"
            exit 1
          fi
          echo "✅ Pass rate stable: $CURRENT"

关键设计：每次 PR / push 都跑 eval + 比 baseline，不允许 pass rate 退化 > 5%。这是把"context engineering"和"harness engineering"结合起来的工程实践。

Q33. 项目中如何应用

5 种典型项目 × 必做映射。原则：Eval Suite 永远是 Day 1，其他根据可靠性要求递进。

5 种典型项目 × 必做映射

项目类型	Eval Suite	Tracing	Log/Debug	CI	Monitoring	何时应用
① 单轮问答	必做	—	—	—	—	Day 1
② RAG 文档问答	必做	—	—	—	—	Day 1
③ 多步 Agent	必做	必做	必做	—	—	Day 1
④ Production Agent	必做	必做	必做	必做	—	Week 2+
⑤ ToB / 合规 Agent	必做	必做	必做	必做	必做	Month 1+

核心洞察：Eval Suite 永远是 Day 1 — 即使是最简单的项目。其他根据可靠性要求递进。

项目类型 1 · 单轮问答

场景：替代 ChatGPT 完成某领域问答（投资分析 / 代码 review / 文档总结）。

必做：写 5-10 个 eval cases（典型问题 + 期望回答范围）；跑 baseline → 拿到 pass rate；迭代 prompt + context 直到 pass rate > 80%。

import json
from langchain import ChatOpenAI

llm = ChatOpenAI(model="gpt-5")

# Eval cases
eval_cases = [
    {"input": "什么是市盈率?", "expected_keywords": ["P/E", "股价", "每股收益"]},
    {"input": "ROE 怎么算?", "expected_keywords": ["净利润", "股东权益"]},
]

def run_eval(case):
    response = llm.invoke(case["input"]).content
    return all(kw in response for kw in case["expected_keywords"])

pass_rate = sum(run_eval(c) for c in eval_cases) / len(eval_cases)
print(f"Pass rate: {pass_rate:.0%}")

# 保存 baseline
with open(".eval-baseline.json", "w") as f:
    json.dump({"pass_rate": pass_rate, "version": "v0-baseline"}, f)

项目类型 2 · RAG 文档问答

场景：企业内部文档 / 法律法规 / 学术论文问答。

必做：Eval Suite · 至少 20 个 cases (含"找不到" + "找到 + 准确" + "找到但不准确") + RAGAS Metrics · 文档 chunking 策略评估。

from ragas import evaluate
from ragas.metrics import (
    faithfulness,
    answer_relevancy,
    context_relevancy,
    context_precision,
)

# 准备 eval dataset
dataset = [
    {
        "question": "什么是 context engineering?",
        "answer": rag_response.answer,
        "contexts": rag_response.contexts,
        "ground_truth": "...",
    },
    # ... 20 个 cases
]

# 跑 RAGAS 评测
results = evaluate(
    dataset,
    metrics=[faithfulness, answer_relevancy, context_relevancy, context_precision],
)

print(f"Faithfulness: {results['faithfulness']:.2f}")
print(f"Answer relevance: {results['answer_relevancy']:.2f}")

项目类型 3 · 多步 Agent

场景：需要 LLM 调用多个工具完成复杂任务。

必做 · 3 件全做：Eval Suite · 工具调用成功率 + 任务成功率 + Tracing · 每个 LLM call + tool call 都 trace + Log/Debug · 失败 case 自动 capture + 重放。

from langsmith import traceable, Client

# 1. 所有函数都 @traceable
@traceable(run_type="tool")
def search(query: str) -> str:
    return search_api(query)

@traceable(run_type="llm")
def llm_call(prompt: str) -> str:
    return llm.invoke(prompt).content

@traceable(run_type="chain")
def agent_step(state):
    # 1. think
    thought = llm_call(state["prompt"])
    # 2. act
    result = search(thought)
    # 3. observe
    return {"thought": thought, "result": result}

# 2. 跑 eval suite (LangSmith client)
client = Client()
results = client.evaluate_run(
    runnable=agent_step,
    dataset_name="agent-v1",
    evaluators=["correctness", "embedding_distance"],
)

print(f"Agent pass rate: {results.aggregate_metrics['correctness']:.0%}")

项目类型 4 · Production Agent

场景：多步 agent + 真实用户 + 可靠性要求 > 95%。

完整 harness — Eval + Tracing + Log + CI regression + Monitoring。详细对比见 Q4。

项目类型 5 · ToB / 合规 Agent

场景：金融 / 医疗 / 法律场景，需要合规 + 审计 + 红队测试。

全套 5 件 harness + 额外的：Promptfoo Red Team · 越狱检测 · 边界 case 攻击 + Audit log · 每个决策都可回溯 + Compliance report · 自动生成合规报告。

Q44. 效果到底多大

单点效果容易看 (Hamel 8.00 / LangSmith 7.80 / Building Effective Agents harness view 7.40)，复合效应 才是决定整体的。

单点效应 · 8 个 best practice 量化

Best practice	单点效果	最低	最高	证据
Eval Suite (Day 1)	+18-30%	+18%	+30%	Hamel 8.00 · LangSmith 7.80
Tracing / Observability	+15-25%	+15%	+25%	LangSmith · Langfuse 案例
Log + Debug	+12-20%	+12%	+20%	故障响应时间 -70%
Regression Test in CI	+10-15%	+10%	+15%	Braintrust 案例
Production Monitoring	+8-15%	+8%	+15%	Arize / Datadog LLM

单点效果区间：每个 best practice +8% 到 +30%。但这些是单点；复合效应需要叠加。

复合效应 · 5 best practice 叠加

如果同时采用 Eval + Tracing + Log + CI + Monitoring（全套）：

复合效应 · 5 种场景实测

项目类型	baseline	+ Eval	+ Tracing	+ Log	+ CI	提升
单轮问答	45%	65%	70%	72%	75%	+30 pts
RAG 文档问答	35%	55%	65%	72%	80%	+45 pts
多步 Agent	25%	50%	65%	75%	82%	+57 pts
Production Agent	30%	55%	75%	85%	90%	+60 pts
ToB / 合规	20%	45%	70%	85%	93%	+73 pts

关键发现：ToB / 合规 提升最大 (+73 pts) — 因为合规场景对可靠性要求 > 95%，整套 harness 才能满足。Production Agent 次之 (+60 pts)。

故障响应时间 · Harness 前后对比

Harness 不仅提升任务成功率 — 它提升 故障响应时间（MTTR）。这是 100 天冲刺 / 创业团队最关键的 KPI：

故障场景	没 Harness	+ Harness	提升
用户报 bug "回答错了"	3 小时	15 分钟	-92%
prompt 改动导致 pass rate 下降	第二天发现	CI 即时报警	立即
某类 query 突然失败	靠用户报	monitor 自动发现	提前 N 天
cost 异常飙升	月底看账单	实时报警	-99%

核心洞察：Harness 把"灾难性故障"变成"日常监控"。这是 production 环境 vs demo 的最大区别。

3 条时间线 · 谁跟哪条

4 角色 · 4 行动

4-Q 系列收尾

Q	问题	答
Q1	Harness Engineering 是什么？	不只是 Eval · 关注"为什么 + 怎么持续知道" · 4 大组件
Q2	如何做好？	8 best practice · 3 必做 + 5 nice-to-have · 代码示例
Q3	项目中应用？	5 项目类型 × 必做映射 · Eval Suite 永远 Day 1
Q4	效果多大？	单点 +8-30% · 全套 +133% · MTTR -70% ~ -99%

Why this matters

如果你在做 LLM 应用，"好 prompt" 已经不够了 — 你需要"好 context"，你需要"好 harness"。Context 是 LLM 的 attention budget，是模型看到的所有东西的总和。Harness 是 LLM 的 production 操作系统，是模型所有行为的可观测 + 可回归 + 可报警的底座。

这两个一起，LLM 应用从 demo 变成 production。没有 Context Engineering — 模型连任务都做不对；没有 Harness Engineering — 你不知道模型做得对不对，更不知道错了之后怎么改。

好消息是：Eval 永远 Day 1，5 行 Python + 5 个 case 就能跑起来。LangSmith / Langfuse / Helicone 都是 self-hostable，团队不需要大投入就能拿到 +50% 以上提升。

这就是为什么我在 100 天冲刺里把 harness engineering 列为必学 — 它跟 Hamel / LangSmith 推崇的"evals first"是同一回事，但更全面。Hamel 关心"对不对"，Harness 关心"对不对 + 怎么持续知道 + 错了怎么改"。后者是前者的超集，也是 LLM 应用的可靠性质保。

Context Engineering is the design.
Harness Engineering is the runtime.
Design without runtime = demo.
Runtime without design = chaos.
Together = production.

References

1. Hamel Husain. Your AI Product Needs Evals. hamel.dev
2. LangChain. LangSmith: Eval + Observability + Tracing + CI. GitHub langchain-ai/langsmith
3. Langfuse. Open Source LLM Observability. GitHub langfuse/langfuse (5K+ stars)
4. OpenAI. Evals Framework. GitHub openai/evals (3K+ stars)
5. DeepEval. LLM Eval Framework. GitHub confident-ai/deepeval (3K+ stars)
6. RAGAS. RAG Eval Framework. GitHub explodinggradients/ragas (9K+ stars)
7. Promptfoo. Prompt + LLM 评测 · 红队 · CI/CD. GitHub promptfoo/promptfoo (5K+ stars)
8. Anthropic. Building Effective Agents. (harness view)

Download

本报告也作为 4 个独立 HTML 报告（Q1 是什么 / Q2 如何做好 / Q3 项目中应用 / Q4 量化效果）发布在 Investment 入口，方便分章节引用：

• Q1 · 是什么
• Q2 · 如何做好
• Q3 · 项目中应用
• Q4 · 量化效果

配套 essay: Context Engineering: From Prompt to Skill — 讲 Harness 之前的设计面（Context）。两篇一起读更完整。