Braintrust：AI 评估与可观测性平台

为什么需要 Braintrust：把「感觉还行」变成「可量化的分数」

传统 LLM 应用开发中，评估靠人工抽查：改一个提示词或换一个模型，团队成员手动跑几十条用例，凭感觉判断效果。这种方式有三个硬伤：一是不可复现，同一输入两次输出可能不同，人工判断无法对齐标准；二是不可回归，上个月的结论这个月无法回放验证；三是不可扩展，用例从几十条涨到上千条时，人工评估直接失效。线上问题只能靠用户投诉反馈，问题定位依赖翻阅原始日志。

Braintrust 的解法是把评估变成一等公民。你定义一组带预期答案的测试用例（Dataset），写一个任务函数（task）和一个评分函数（score），调用一次 Eval()，平台就自动完成批量评估、逐条打分、汇总统计。下一次改动模型或提示词后再跑一次，平台直接给出两次实验的分数对比和回归告警。生产环境则通过 SDK 或代理接入日志，把线上真实请求回流成回归测试集，形成「线上发现问题 → 回收样本 → 回归验证 → 修复上线」的闭环。

与同类工具相比，Braintrust 的气质差异在于「评估优先」：它不是先在应用里堆埋点、再被动看图表，而是要求你先定义「好」的标准（评分函数），再让可观测数据为这个标准服务。这种设计更适合对质量有硬性要求的 RAG 和 Agent 团队。

安装与环境配置：3 步就绪

步骤一：注册并获取 API Key。 打开 [app.braintrust.dev](https://app.braintrust.dev) 注册账号，进入 Settings → API Keys 创建密钥，形如 brt_xxx。API Key 是平台识别你身份的唯一凭据。

步骤二：安装 SDK。 Python 项目执行 pip install braintrust，Node/TypeScript 项目执行 npm install braintrust。SDK 负责本地数据收集、评估执行和异步上传。

步骤三：配置环境变量。 BRAINTRUST_API_KEY 必填；BRAINTRUST_PROJECT 可选，在代码中未显式指定项目名时作为默认值。建议通过 .env 文件或密钥管理服务注入，不要硬编码在源码里。

pip install braintrust# 或 npm install braintrust export BRAINTRUST_API_KEY="brt_xxx"export BRAINTRUST_PROJECT="my-llm-project" # 验证安装是否成功python -c "from braintrust import Eval, init; print('Braintrust SDK OK')"

快速上手：10 分钟跑通第一个评估实验

核心思路只有一句话：Eval = 用一组测试用例（data）跑一个任务函数（task），再用评分函数（scores）给每条输出打分，结果上传到云端项目里供对比。

1. 安装 SDK 并配置环境变量（见上一节）。

2. 新建文件 eval_demo.py，粘贴下方代码。task 函数内部替换成你真实的 LLM 调用；correctness 是一个最简单的评分函数，判断输出是否包含期望答案。

3. 运行 python eval_demo.py。

4. 打开脚本打印出的实验链接（登录后可见），在 UI 中查看：每条用例的输入输出、得分明细、错误样本列表和整体得分分布。

5. 修改 task 或提示词后再次运行，同一项目下自动生成新 Experiment，页面直接展示与上一次实验的分数 diff，分数下降即回归。

进阶技巧：data 官方推荐用 lambda 包裹而非直接传列表，因为测试集可能被多线程消费，传入可重复求值的函数能避免迭代器耗尽导致部分用例丢失。

import asynciofrom braintrust import Eval def task(input):    # 此处替换为你的真实 LLM 调用    return "巴黎" def correctness(input, output, expected):    return expected in output async def main():    result = await Eval(        name="qa-demo",        data=lambda: [            {"input": "法国首都是哪里？", "expected": "巴黎"},            {"input": "中国首都是哪里？", "expected": "北京"},        ],        task=task,        scores=[correctness],    )    print(result) asyncio.run(main())

核心能力详解：4 大支柱

支柱一：Experiments & Evals（实验与评估）。 一次 Eval() 运行就是一个 Experiment，自动记录任务输出、评分和运行元数据。平台会保留实验历史，任何一次运行都能与之前的结果逐条 diff，分数下降会高亮标记。评分函数支持自定义，既可以是纯字符串判断，也可以是 LLM-as-judge（用另一个模型打分）、RAG 命中率计算等任意 Python 代码。

支柱二：Datasets（数据集）。 数据集是可版本化的测试用例集合，支持从 CSV/JSON 导入，也支持把生产日志一键转存为回归集。每次修改数据集都会生成新版本，实验结果与数据集版本绑定，保证「这条分数是基于哪份数据跑的」可追溯。生产日志回流是数据集的杀手级用法：线上失败案例直接变成明天的回归用例。

支柱三：Prompt Management（提示词管理）。 在平台集中维护各模型的提示词版本，给指定版本打 alias（如 prod），代码运行时按 alias 拉取。修改提示词在平台完成，应用无需重新发版；提示词变更后立即触发一次 Eval，自动评估新提示词是否引入回归。

支柱四：Production Observability（生产可观测）。 用 init() 初始化后，通过 start_span 记录单次调用的输入输出、模型参数、token 用量、延迟和成本；@traced 装饰器可自动捕获函数调用链。平台按项目聚合出调用量、错误率、成本趋势、token 消耗等指标，并支持对生产日志打标签筛选。另外，将模型客户端 base_url 指向 Braintrust 代理（具体地址见官方文档），不改业务代码即可接入 OpenAl、Anthropic 等模型商的日志。

生产部署与监控：从上线到运维

部署方式一：SDK 直接埋点。 在 Python/TS 应用代码中调用 init(project="xxx") 初始化客户端，然后在业务函数上用 @traced 装饰，或在关键节点手动 start_span 并 log 输入输出。SDK 异步批量上传，正常情况下不阻塞业务请求，适用于对代码侵入可接受的团队。

部署方式二：代理接入。 团队有多个服务、不想逐个改代码时，把 LLM 客户端的环境变量（如 OPENAI_BASE_URL）指向 Braintrust 官方文档给出的代理区域地址即可。代理自动转发请求并记录完整日志，业务代码零改动。

部署方式三：OTLP 导入。 已有 OpenTelemetry 采集体系的团队，可将 OTLP 导出器指向 Braintrust 提供的数据接入端点，把现有 traces 导入平台统一分析，适合基础设施标准化程度高的组织。

可观测性要点： 上线后重点关注三个维度——成本趋势（按项目/模型聚合的 token 与花费）、延迟分布（P50/P95）、质量告警（基于评分阈值的回归检测）。每周把生产环境得分垫底的样本回流到数据集，重跑 Eval 驱动下一轮优化。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>生产链路不要同步内联调用 LLM 评分函数——评分本身消耗 token 且增加延迟，应放到异步任务或旁路分析中执行</li><li>SDK 默认异步上传，进程被强杀会丢失尾部日志，长任务结束前显式 flush，Serverless 场景需重点确认关闭时机</li><li>API Key 是明文凭据，泄露会产生真实计费；必须走环境变量或密钥管理服务，严禁提交进 Git 仓库</li><li>data 参数不要直接传一次性迭代器，多线程消费会耗尽数据，用 lambda 或可重复迭代对象包裹</li><li>平台是 SaaS 托管，日志默认上传云端；涉密业务先评估数据驻留策略，或用 OTLP 网关先做脱敏过滤再上报</li></ul>

AI 应用场景

常见误区

面试题