OpenTelemetry로 평가하는 방법

이 가이드는 LangSmith와 함께 OpenTelemetry 추적을 사용해 평가를 실행하는 방법을 보여드려요.

평가 | 데이터셋 | OpenTelemetry로 추적

이미 LLM 애플리케이션 추적에 OpenTelemetry를 사용하고 있다면, 트레이스를 실험 세션으로 라우팅하여 평가를 실행할 수 있어요. 이 접근 방식은 OpenTelemetry로 계측되어 있지만 LangSmith SDK의 evaluate() 함수를 사용하지 않는 애플리케이션을 평가하려 할 때 유용합니다.

출처: 문서

본문

개요 (Overview)

OpenTelemetry로 평가할 때 다음을 수행해야 합니다:

LangSmith에 실험 세션을 생성합니다.
OpenTelemetry가 LangSmith로 트레이스를 보내도록 구성합니다.
특정 스팬 속성을 추가해 트레이스를 실험과 데이터셋 예시에 연결합니다.
데이터셋의 각 예시에 대해 애플리케이션을 실행합니다.

사전 요구사항 (Prerequisites)

이 가이드는 다음이 있다고 가정합니다:

OpenTelemetry로 계측되어 LangSmith로 트레이스를 보내는 애플리케이션.
평가할 예시가 있는 LangSmith 데이터셋. 데이터셋은 LangSmith UI 또는 SDK로 만들 수 있습니다.

이 튜토리얼은 예제 구현으로 Strands 에이전트를 사용하지만, 이 접근 방식은 모든 OpenTelemetry 계측과 함께 작동합니다.

의존성 설치:

pip install langsmith strands-agents strands-agents-tools opentelemetry-sdk opentelemetry-exporter-otlp

npm install langsmith @strands-agents/sdk @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources

다음 환경 변수를 설정합니다:

# Tracing configuration
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 Credentials
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단계. 실험 세션 생성하기 (Create an experiment session)

이 가이드는 평가할 예시가 있는 LangSmith 데이터셋이 생성되어 있다고 가정합니다. 데이터셋은 LangSmith UI 또는 SDK로 만들 수 있습니다.

실험 세션은 모든 평가 트레이스를 함께 그룹화합니다. LangSmith 클라이언트를 사용해 하나를 만드세요:

from langsmith import Client

# LangSmith 클라이언트 초기화
client = Client()

experiment_name = "strands-agent-experiment"
# 데이터셋이 생성되었다고 가정. 데이터셋 ID는 LangSmith UI 또는 SDK에서 찾을 수 있음.
dataset_id = "<your-dataset-id>"

# 데이터셋에 연결된 실험 세션 생성
project = client.create_project(
    project_name=experiment_name,
    reference_dataset_id=dataset_id
)

experiment_id = str(project.id)

import { Client } from "langsmith";

// LangSmith 클라이언트 초기화
const client = new Client({
  apiKey: proces...KEY,
});

const experimentName = "strands-agent-experiment";
const datasetId = "your-dataset-id";

// 데이터셋에 연결된 실험 세션 생성
const project = await client.createProject({
  projectName: experimentName,
  referenceDatasetId: datasetId,
});

const experimentId = project.id;

추가로, LangSmith UI에서 평가기를 만들고 데이터셋에 바인딩할 수 있습니다. UI에서 정의되어 데이터셋에 바인딩된 평가기는 실험 트레이스에서 자동으로 실행됩니다.

평가기에 대한 자세한 내용은 평가기를 참고하세요.

2단계. 애플리케이션 정의 및 OpenTelemetry 구성하기 (Define an application and configure OpenTelemetry)

먼저, 추적에 OpenTelemetry를 사용하는 애플리케이션이 필요합니다. 이 예시는 Strands 에이전트를 사용하지만, 모든 OpenTelemetry 계측 애플리케이션을 사용할 수 있어요. OTEL 헤더에 실험 ID를 포함하여 트레이스를 실험 세션으로 라우팅하도록 OpenTelemetry를 설정합니다. 이 단계의 핵심 아이디어는 OpenTelemetry로 계측된 에이전트 또는 애플리케이션을 갖는 것입니다.

Strands TypeScript SDK가 현재(2026년 2월 기준) OpenTelemetry 관찰 가능성을 지원하지 않으므로 이 단계에는 TypeScript 예시가 제공되지 않습니다.

import os
from strands import Agent
from strands_tools import file_read, file_write, python_repl, shell, journal
from strands.telemetry import StrandsTelemetry

# 실험 ID를 프로젝트로 하는 OTEL 헤더 설정
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 스팬을 만듦)
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",
)

LangSmith에서 OpenTelemetry 추적 설정에 대한 자세한 내용은 OpenTelemetry로 추적을 참고하세요.

3단계. 핵심 스팬 속성 설정하기 (Set up key span attributes)

각 애플리케이션 실행에 필수 스팬 속성을 추가합니다. 이 속성들은 각 트레이스를 실험과 특정 데이터셋 예시에 연결합니다.

실험 평가와 관련된 속성은 다음과 같습니다:

속성 (Attribute)	목적 (Purpose)
`langsmith.trace.session_id`	트레이스를 실험 세션으로 라우팅
`langsmith.reference_example_id`	트레이스를 특정 데이터셋 예시에 연결
`langsmith.span.kind`	스팬 유형 설정 (예: "llm", "chain", "tool")
`inputs`	애플리케이션에 대한 입력 기록
`outputs`	애플리케이션의 출력 기록

지원되는 OpenTelemetry 속성의 전체 목록은 OpenTelemetry로 추적을 참고하세요.

from opentelemetry import trace

def evaluate_with_opentelemetry(agent, example_id: str, example_input: str, experiment_id: str):
    tracer = trace.get_tracer(__name__)

    # 실험 메타데이터를 추가하는 래퍼 스팬
    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

import { trace, Span } from "@opentelemetry/api";

async function evaluateWithAgent(
  agent: Agent,
  exampleId: string,
  exampleInput: string,
  experimentId: string
): Promise<string> {
  const tracer = trace.getTracer("experiment-runner");

  return await tracer.startActiveSpan(
    "experiment_evaluation",
    async (span: Span) => {
      try {
        // 트레이스를 실험으로 라우팅
        span.setAttribute("langsmith.trace.session_id", experimentId);

        // 트레이스를 특정 데이터셋 예시에 연결
        span.setAttribute("langsmith.reference_example_id", exampleId);

        // 입력 기록
        span.setAttribute("inputs", exampleInput);

        // 애플리케이션 실행
        const result = await agent.invoke(exampleInput);
        // 출력 기록
        const response = String(result);
        span.setAttribute("outputs", response);

        return response;
      } finally {
        span.end();
      }
    }
  );
}

4단계. 데이터셋 예시를 순회하며 평가 실행하기 (Run evaluation by iterating through dataset examples)

각 실험 실행은 데이터셋 예시에 연결된 트레이스를 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
    )

// 데이터셋 예시 순회
for await (const example of client.listExamples({ datasetName })) {
  // 예시 입력 딕셔너리에서 입력 추출
  // 데이터셋 구조에 따라 키 조정
  // (예: "input", "question" 등)
  const exampleInput = example.inputs.input;

  await evaluateWithAgent(
    agent,
    example.id,
    String(exampleInput),
    experimentId
  );
}

평가를 실행한 후 LangSmith UI에서 실험 분석을 통해 다음을 볼 수 있습니다:

각 예시의 개별 트레이스 세부정보
평가기 점수와 피드백
서로 다른 실험 실행 간의 비교

결과를 분석하려면 LangSmith UI의 실험으로 이동하세요.

더 알아보기 (Learn more)

OpenTelemetry로 추적