本指南向您展示如何使用 OpenTelemetry 追踪与 LangSmith 一起运行评估。
如果您已经在使用 OpenTelemetry 追踪您的 LLM 应用程序，您可以通过将追踪路由到实验会话来运行评估。当您想要评估已使用 OpenTelemetry 进行检测但未使用 LangSmith SDK 的 evaluate() 函数的应用程序时，此方法非常有用。
使用 OpenTelemetry 进行评估时，您需要：
- 在 LangSmith 中创建一个实验会话。
- 配置 OpenTelemetry 将追踪发送到 LangSmith。
- 添加特定的 span 属性以将追踪链接到实验和数据集示例。
- 为数据集中的每个示例运行您的应用程序。
前提条件
本指南假设您已具备：
- 一个已使用 OpenTelemetry 进行检测并向 LangSmith 发送追踪的应用程序。
- 一个在 LangSmith 中创建的、包含待评估示例的数据集。您可以通过 LangSmith UI 或通过 SDK 创建数据集。
本教程使用 Strands 代理作为示例实现，但该方法适用于任何 OpenTelemetry 检测。
安装依赖项：
pip install langsmith strands-agents strands-agents-tools opentelemetry-sdk opentelemetry-exporter-otlp
# 追踪配置
LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
LANGSMITH_API_KEY="<your-langsmith-api-key>"
OTEL_EXPORTER_OTLP_ENDPOINT = "https://api.smith.langchain.com/otel/"
# AWS 凭证
AWS_ACCESS_KEY_ID="<your-aws-access-key-id>"
AWS_SECRET_ACCESS_KEY="<your-aws-secret-access-key>"
AWS_REGION_NAME="<your-aws-region>"
如果您正在自托管 LangSmith，请将 OTEL_EXPORTER_OTLP_ENDPOINT 替换为您的自托管 URL 并附加 /api/v1/otel。例如：OTEL_EXPORTER_OTLP_ENDPOINT = "https://ai-company.com/api/v1/otel"。将 LANGSMITH_ENDPOINT 替换为您的 LangSmith API 端点。例如：LANGSMITH_ENDPOINT = "https://ai-company.com/api/v1"。 步骤 1. 创建实验会话
本指南假设已在 LangSmith 中创建了一个包含待评估示例的数据集。您可以通过 LangSmith UI 或通过 SDK 创建数据集。
实验会话将所有评估追踪分组在一起。使用 LangSmith 客户端创建一个：
from langsmith import Client
# 初始化 LangSmith 客户端
client = Client()
experiment_name = "strands-agent-experiment"
# 假设已创建数据集。您可以在 LangSmith UI 或通过 SDK 中找到数据集 ID。
dataset_id = "<your-dataset-id>"
# 创建链接到数据集的实验会话
project = client.create_project(
project_name=experiment_name,
reference_dataset_id=dataset_id
)
experiment_id = str(project.id)
步骤 2. 定义应用程序并配置 OpenTelemetry
首先，您需要一个使用 OpenTelemetry 进行追踪的应用程序。此示例使用 Strands 代理，但您可以使用任何已检测 OpenTelemetry 的应用程序。通过在 OTEL 头中包含实验 ID，设置 OpenTelemetry 将追踪路由到您的实验会话。此步骤的一般思路是拥有一个已使用 OpenTelemetry 进行检测的代理或应用程序。
此步骤未提供 TypeScript 示例，因为 Strands TypeScript SDK 目前（截至 2026 年 2 月）不支持 OpenTelemetry 可观测性。
import os
from strands import Agent
from strands_tools import file_read, file_write, python_repl, shell, journal
from strands.telemetry import StrandsTelemetry
# 设置 OTEL 头，将实验 ID 作为项目
api_key = os.getenv('LANGSMITH_API_KEY')
os.environ['OTEL_EXPORTER_OTLP_HEADERS'] = f"x-api-key={api_key},Langsmith-Project={experiment_id}"
# 初始化遥测
strands_telemetry = StrandsTelemetry()
strands_telemetry.setup_otlp_exporter()
# 创建代理（Strands 自动创建 OTel span）
agent = Agent(
tools=[file_read, file_write, python_repl, shell, journal],
system_prompt="You are an Expert Software Developer.",
model="us.anthropic.claude-sonnet-4-20250514-v1:0",
)
步骤 3. 设置关键 span 属性
为每次应用程序运行添加所需的 span 属性。这些属性将每个追踪链接到实验和特定的数据集示例。
以下属性与实验评估相关：
| 属性 | 用途 |
|---|
langsmith.trace.session_id | 将追踪路由到您的实验会话 |
langsmith.reference_example_id | 将追踪链接到特定的数据集示例 |
langsmith.span.kind | 设置 span 类型（例如 “llm”、“chain”、“tool”） |
inputs | 记录应用程序的输入 |
outputs | 记录应用程序的输出 |
from opentelemetry import trace
def evaluate_with_opentelemetry(agent, example_id: str, example_input: str, experiment_id: str):
tracer = trace.get_tracer(__name__)
# 包装 span 以添加实验元数据
with tracer.start_as_current_span("experiment_evaluation") as span:
# 将追踪路由到实验
span.set_attribute("langsmith.trace.session_id", experiment_id)
# 将追踪链接到特定的数据集示例
span.set_attribute("langsmith.reference_example_id", example_id)
# 记录输入
span.set_attribute("inputs", example_input)
# 运行应用程序
response = agent(example_input)
# 记录输出
output_text = getattr(response, "output", str(response))
span.set_attribute("outputs", output_text)
return output_text
步骤 4. 通过遍历数据集示例运行评估
每次实验运行都会在 LangSmith 中创建链接到您数据集示例的追踪。
# 遍历数据集示例
for example in client.list_examples(dataset_name=dataset_name):
# 从示例输入字典中提取输入
# 根据您的数据集结构调整键
# （例如 "input"、"question" 等）
example_input = example.inputs.get("input")
evaluate_with_opentelemetry(
agent=agent,
example_id=str(example.id),
example_input=str(example_input),
experiment_id=experiment_id
)
- 每个示例的单独追踪详情
- 评估器分数和反馈
- 不同实验运行之间的比较
导航到 LangSmith UI 中的实验以分析结果。
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。 
