如何将Braintrust用于任意框架或提供商

2026年6月16日 Jess Wang 10分钟

每个AI团队的栈看起来都不一样。有些团队用LangGraph构建agent，有些用CrewAI，还有些自己写循环逻辑，从此不再回头。有些团队通过Vercel AI SDK运行一切，而另一些团队则有一个从未接触过Python SDK的Go服务。大多数团队会混合使用模型提供商：用OpenAI实现一个功能，用Claude实现另一个，再用一个自托管模型处理不能离开VPC的工作负载。

Braintrust正是为这种现实而设计的。你只需通过SDK或OpenTelemetry对应用进行一次instrument（插桩），然后继续使用你偏好的任何agent框架和模型提供商，同时获得跨所有组件的、一致的trace（追踪）、eval（评估）和调试。即使你的栈不断演变，你衡量质量的方式也保持不变。

一次instrument，三种方式

将trace导入Braintrust有三种途径，你可以根据需要混合使用。

自动instrumentation（Auto-instrumentation） 是推荐的起点。在启动时调用一次，即可对每个受支持的AI库进行补丁，从而捕获所有LLM调用（输入、输出、延迟、token用量和成本），无需包装单个客户端：

python

import braintrustbraintrust.auto_instrument()braintrust.init_logger(project="My Project")

在TypeScript中，等价操作是initLogger()加上使用node --import braintrust/hook.mjs运行你的应用，或者如果你使用Vite、Next.js（Webpack或Turbopack）、Nuxt、esbuild或Rollup，则使用相应的bundler插件。这远不止两种语言。Braintrust提供了Python、TypeScript、Go（通过Orchestrion实现编译时instrumentation）、Ruby、Java（一个在JVM启动时进行instrument的ByteBuddy agent）和.NET的SDK。自动instrumentation覆盖了OpenAI、Anthropic、Gemini、Mistral和Cohere的SDK，以及LangChain、LlamaIndex、LiteLLM、DSPy、Instructor等框架，以及下面的agent框架。版本支持请参阅完整支持矩阵。流式处理由Braintrust为你处理，因为数据块会被收集并记录为单个span。

手动instrumentation（Manual instrumentation） 适用于你需要显式控制，或者你构建了自己的框架时。使用wrapOpenAI等辅助函数包装单个客户端，或直接使用span来追踪检索步骤、工具调用和业务逻辑，与你的LLM调用一起，这样eval trace就能显示你的整个pipeline，而不仅仅是模型调用。

OpenTelemetry 覆盖了所有其他情况。如果你不想添加Braintrust SDK，或者你使用的语言没有对应的SDK，可以将你现有的OTel设置指向Braintrust作为后端。使用纯OTLP，只需设置两个环境变量：

bash

OTEL_EXPORTER_OTLP_ENDPOINT=https://api.braintrust.dev/otelOTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <api key>, x-bt-parent=project_id:<project id>"

Braintrust实现了OpenTelemetry GenAI语义约定，因此携带gen_ai.*属性的span会自动映射到结构化的输入、输出、元数据和token指标，包括缓存读取和写入的token。LLM调用会变成span，你可以将其保存为prompt并在playground中进行评估。你还可以通过braintrust.*属性命名空间，直接从OTel span设置Braintrust原生字段，如分数、期望值和标签。对于Python和TypeScript，BraintrustSpanProcessor可以插入到你现有的tracer provider中，并带有filterAISpans选项，以便只发送与AI相关的span，以及用于细粒度采样的customFilter钩子。此外，还有OTel兼容性模式和分布式追踪支持，用于处理混乱的现实世界场景，例如一个由Braintrust instrument的服务调用一个由OTel instrument的服务，或者反过来，trace上下文在HTTP边界双向流动。

使用任何agent框架，或同时使用多个

Braintrust将provider调用、工具调用和agent步骤捕获为trace span，与哪个框架运行循环无关。不同的团队会选择不同的框架，框架也需要迁移，但当trace结构一致时，无论是由什么产生的，你都可以用相同的方式进行比较、评估和调试行为。

对于LangGraph，auto_instrument()会注册一个全局的LangChain回调处理器，LangGraph也会使用它，从而捕获图执行、节点转换和模型调用。如果你想要显式控制，可以直接配置该处理器：

python

from braintrust import init_loggerfrom braintrust.integrations.langchain import BraintrustCallbackHandler, set_global_handlerinit_logger(project="My Project")set_global_handler(BraintrustCallbackHandler())# ...像往常一样构建并调用你的StateGraph

对于CrewAI，同样的auto_instrument()调用会将一次运行追踪为一个嵌套的trace，该trace镜像了执行流程：crew启动、任务执行、agent推理（角色、目标、背景故事、可用工具）、带有完整provider配置的LLM调用，以及带有参数、输出、重试和缓存命中的工具调用，外加token指标和流式调用的首字节时间。如果你只想追踪CrewAI而不修补其他库，可以使用setup_crewai()，并且该集成适用于CrewAI支持的任何模型提供商。

同样的模式也扩展到OpenAI Agents SDK、Claude Agent SDK、Pydantic AI、AutoGen、AgentScope、Mastra、Google ADK、Strands和LiveKit Agents，甚至包括Temporal等工作流引擎。如果你的框架已经使用OpenTelemetry进行了instrument，请保留该设置并将span路由到Braintrust，无需重新instrument。

框架中立的好处既是组织性的，也是技术性的。使用一个框架的团队和使用自定义循环的团队，最终都能得到可以并排比较、使用相同eval评分、并使用相同流程进行调试的trace。

一致地进行评估

Tracing是将数据导入Braintrust。下一步是使用这些数据进行评估。Braintrust的eval原语可以跨框架和提供商应用。一个Eval()包含三样东西（一个数据集、一个任务和评分器），而任务只是一个函数。无论其内部发生什么，无论是LangGraph调用、CrewAI启动，还是你自定义的agent循环，都会被同样地追踪和评分：

python

from braintrust import Eval, init_datasetfrom autoevals import FactualityEval( "My project", data=init_dataset(project="My project", name="My dataset"), task=lambda input: run_my_agent(input), # 这里可以是任何框架 scores=[Factuality], trial_count=3, # 对每个输入运行多次以衡量方差)

使用bt eval my_eval.py在本地运行（添加--watch可在文件更改时重新运行），或通过GitHub Action将其接入CI，该Action会将结果作为PR评论发布。运行bt eval tests/ --first 20可以在pull request上进行廉价的冒烟测试，而完整的测试套件则保留给合并操作。实验是不可变的快照，因此任何两次运行之间的回归总是可比较的，而model和prompt_version等元数据使比较可以过滤。

有些任务确实无法在eval文件内部运行，例如具有重度依赖的agent、VPN后的内部API或特定于操作系统的工具。在这些情况下，远程eval和沙箱可以弥补差距。运行bt eval path/to/eval.py --dev，你的eval就会变成一个本地服务器，Braintrust playground可以触发它。你在代码中定义的参数（模型选择器、可编辑的prompt、自定义选项）会显示为UI控件，并且你的代码永远不会离开你的基础设施，因为只有结果会发送到Braintrust。你还可以将eval作为沙箱工件推送，Braintrust会在隔离的云环境中按需调用它，这样团队成员就可以从playground运行你的agent eval，而无需克隆仓库。

随身携带你的数据

采用Braintrust并不意味着从零开始。团队有几种常见的方式可以导入现有数据。

通过OpenTelemetry从现有的可观测性工具导入。 如果你的应用已经发出OTel trace，Braintrust可以作为一个额外的接收端。保留你当前的instrumentation和导出器，将Braintrust添加为目标，并在那里整合特定于AI的分析。filterAISpans选项可以过滤掉基础设施噪音。

从LangSmith导入，无需重写代码。 实验性的LangSmith包装器会将@traceable装饰器重定向到Braintrust的@traced，将evaluate()调用重定向到Braintrust的Eval()，并且你的LangSmith风格评估器会自动转换为Braintrust评分器。它有两种运行模式：并行模式，同时向两个平台发送trace和eval（对于比较服务或逐步迁移很有用）；独立模式，仅发送到Braintrust。切换只需在你的LangSmith导入之前调用一次setup_langsmith()。使用OpenLLMetry和Traceloop进行instrument的应用也可以类似地直接转发trace。

从文件、脚本和pipeline导入。 测试集和真实数据可以通过任何合适的途径导入：在UI中通过拖放列映射上传CSV或JSON；使用SDK的init_dataset()和insert()进行程序化填充；或者使用bt CLI用于终端和CI工作流：

bash

bt datasets create my-dataset --file records.jsonl

CLI还可以双向移动数据。bt sync pull将日志、实验和数据集下载到本地的NDJSON文件，用于离线分析或备份；bt sync push将本地数据上传回去。对于存储在数据仓库或流式系统中的数据，数据集插入API和BTQL端点为你提供了程序化钩子，可以在其上构建富化pipeline，而bt sql可以直接从脚本中对你的日志运行SQL。

混合搭配模型提供商

对于使用AI构建的团队来说，多提供商已成为默认情况，而非边缘案例。Braintrust通过两种互补的方式使其变得安全。

首先，可观测性和eval在设计上就与提供商无关。无论一个span来自OpenAI SDK、Anthropic SDK还是Bedrock，它都会以相同的trace格式和相同的指标落地，因此比较模型意味着通过多次实验运行相同的数据集，并排读取准确性、延迟、成本和token使用情况。

其次，Braintrust网关为你提供了一个位于所有提供商之前的、兼容OpenAI的API。在Braintrust中添加你的提供商密钥，可以在组织级别作为默认设置，也可以在项目级别（如果你需要单独的计费或凭证隔离），然后将你的SDK的基础URL指向https://gateway.braintrust.dev，就完成了。这包括一个非常实用的技巧：标准化使用一个SDK，同时调用任何提供商的模型：

python

from openai import OpenAIclient = OpenAI( base_url="https://gateway.braintrust.dev", api_key=os.environ["BRAINTRUST_API_KEY"],)# 通过OpenAI SDK调用Clauderesponse = client.responses.create( model="claude-sonnet-4-5", input=[{"role": "user", "content": "Hello!"}],)

切换提供商变成了一行模型名称的更改，同时自动进行响应缓存和日志记录。设置x-bt-parent头，网关调用就会嵌套到你的分布式trace中。

对于网关未列出的模型，无论是Ollama或vLLM上的自托管模型、微调模型还是专有模型，自定义提供商都可以接入同一个端点。你配置端点URL、API格式和任何认证头（使用Mustache模板处理{{email}}和{{model}}等值），可选地声明每百万token的成本，以便实验成本估算保持准确，然后该模型就会出现在与GPT和Claude相同的下拉菜单中。自定义模型在标准模型能用的任何地方都能工作，包括作为LLM-as-a-judge评分器，因此你可以使用自己微调的评判模型来对输出进行评分。如果你根本不想通过网关路由流量，SDK和OTel instrumentation可以直接针对任何提供商工作，包括你自己的基础设施。

这也与你开发栈的其他部分配合得很好。Vercel AI SDK的原生OTel支持开箱即用地与Braintrust配合；你已经运行的网关（Cloudflare AI Gateway、LiteLLM、TrueFoundry）可以转发trace；bt CLI可以在你的编码agent所在之处与它们协作。bt setup会为Claude、Cursor、Copilot、Codex等安装Braintrust技能文件和MCP配置，然后对你的项目进行instrument，并通过捕获的trace进行验证。

开始使用

Braintrust与你正在使用的任何agent框架和模型提供商都能配合：进行一次instrument（SDK或OpenTelemetry），然后一致地运行eval、调试trace、比较prompt和模型，即使你的栈不断演变。

如果你想看看它在你的特定栈上是什么样子，集成目录中几乎为所有内容都提供了设置指南。如果你的框架还没有被收录，OTel端点意味着你只需设置几个环境变量即可。 免费注册 或 预约演示 开始使用。