콘텐츠로 이동
LLaMON Agent SDK v0.6.0

Langfuse 필터와 비교

Langfuse에서는 tags와 루트 metadata로 실행 집합을 좁힌 뒤 observation의 name, type, 로컬 metadata를 더합니다. 마지막으로 같은 score 이름의 값과 분포를 비교합니다.

기록이 보이는 구조

섹션 제목: “기록이 보이는 구조”

문서 검증 워크플로우 한 번은 개념적으로 다음과 같이 보입니다. Langfuse UI가 type을 대문자로 표시하더라도 Python API에는 소문자 값을 전달합니다. 아래 예시는 반복 평가이므로 선택 요청 metadata인 evaluationSuite와 evaluationCase도 기록했습니다.

Trace
  tags: [document-review, workflow:contract-approval]
  metadata: {evaluationSuite: contract-v1, evaluationCase: refund-policy, serviceRole: orchestrator, workflowVariant: v3}
  score: decision_accuracy = 0.94


  Agent  orchestrator.call:verification
    metadata: {stage: verification, policyVariant: contract-v3}
    score: verification_quality = 0.91


    Span  document-verifier service invoke
      metadata: {serviceRole: document-verifier}


      # 직접 기록 경로
      Evaluator  contract-check
        metadata: {stage: validation, policyVariant: contract-v3}
        score: policy_compliance = 0.96


      # Runtime Evaluator 경로
      Evaluator  business-validate-document
        metadata: {stage: validation}
        score: policy_compliance = 0.96


        Evaluator  evaluation:policy_compliance
          metadata: {policyVariant: contract-v3, threshold: 0.8}
          output: {passStatus: true, reason: ...}


      Guardrail  pii-check
        metadata: {stage: safety}
        score: pii_safe = true

직접 기록 경로와 Runtime Evaluator 경로는 서로 대안 관계입니다. 같은 평가를 두 경로로 중복 기록하라는 뜻이 아닙니다. observe("contract-check", observation_type="evaluator") 안에서 record_score()를 호출하면 Evaluator contract-check에 단계·정책·점수가 함께 남습니다. Runtime Evaluator를 쓰면 evaluation:policy_compliance에 평가 과정과 판정 사유가 남고, policy_compliance score는 evaluation:policy_compliance가 아니라 원래의 business-validate-document observation에 연결됩니다. 이 예시는 대상이 열려 있는 Flow 노드라 evaluation observation도 그 하위에 있습니다. 종료된 대상을 명시적으로 평가할 때는 부모가 다를 수 있으므로 evaluatedObservationId로 관계를 확인합니다.

비교 집합 만들기

섹션 제목: “비교 집합 만들기”

워크플로우 전체 품질, Orchestrator의 하위 호출, 그 안의 특정 단계를 서로 다른 필터로 고릅니다.

# 평가 케이스(행) × 워크플로우 구성(열)의 한 셀
tag = workflow:contract-approval
# 다음 두 조건은 반복 평가를 케이스별로 나눌 때만 추가
metadata.evaluationSuite = contract-v1
metadata.evaluationCase = refund-policy
metadata.serviceRole = orchestrator
metadata.workflowVariant = v3
score.name = decision_accuracy


# Orchestrator가 호출한 verification Agent
tag = workflow:contract-approval
observation.name = orchestrator.call:verification
observation.type = AGENT
observation.metadata.stage = verification
score.name = verification_quality


# Runtime Evaluator로 자동 평가한 검증 단계
tag = workflow:contract-approval
observation.name = business-validate-document
observation.type = EVALUATOR
observation.metadata.stage = validation
score.name = policy_compliance


# 자동 평가의 정책과 판정 사유
tag = workflow:contract-approval
observation.name = evaluation:policy_compliance
observation.type = EVALUATOR
observation.metadata.policyVariant = contract-v3


# observe() + record_score()로 직접 기록한 경우
tag = workflow:contract-approval
observation.name = contract-check
observation.type = EVALUATOR
observation.metadata.stage = validation
observation.metadata.policyVariant = contract-v3
score.name = policy_compliance


# 안전 검사만 비교
tag = workflow:contract-approval
observation.name = pii-check
observation.type = GUARDRAIL
score.name = pii_safe

서비스 역할과 observation type은 다릅니다. document-verifier 서비스 안에도 span, agent, evaluator, guardrail, generation이 함께 존재합니다. 이름과 metadata의 의미를 고정하면 같은 단계끼리 비교할 수 있습니다.

serviceRole은 두 곳에서 확인합니다. 루트 trace metadata에는 루트 서비스의 값이, 각 서비스 invoke span의 metadata에는 해당 서비스의 값이 기록됩니다. 따라서 trace 목록의 metadata.serviceRole은 그 서비스가 루트인 실행을 고를 때 씁니다. trace 안의 하위 단계는 위 예시처럼 observation의 name, type, 로컬 metadata로 좁힙니다.

Langfuse UI에서 실제로 거는 순서

섹션 제목: “Langfuse UI에서 실제로 거는 순서”

Langfuse Cloud v4의 빠른 필터 검색창을 기준으로 한 동선입니다.

  1. Tracing → Traces에서 tag와 루트 metadata로 비교할 집합을 고릅니다.

    tags:"workflow:contract-approval" metadata.serviceRole:orchestrator metadata.workflowVariant:v3

    반복 평가를 묶음·케이스별로 나눌 때만 다음 조건을 더합니다.

    metadata.evaluationSuite:contract-v1 metadata.evaluationCase:refund-policy

  2. trace를 열어 Scores에서 전체 실행 점수를 확인합니다. Observations에서는 name, type, 로컬 metadata, score를 조합해 단계까지 좁힐 수 있습니다.

    name:business-validate-document type:EVALUATOR metadata.stage:validation scores.policy_compliance:>0.9

  3. Runtime Evaluator를 썼다면 business-validate-document의 score와 그 아래 evaluation:policy_compliance의 output을 함께 봅니다. 낮은 점수의 reason과 details는 evaluator observation의 output에 있습니다. 직접 기록했다면 Evaluator contract-check에 score가 직접 붙습니다.

  4. 자체 호스팅이나 이전 UI에서 빠른 검색을 지원하지 않으면 Tags·Metadata·Scores 사이드바 필터로 같은 조건을 순서대로 적용합니다. 검색창 지원 범위는 설치 버전에 따라 다를 수 있으므로 기록 계약 자체를 검색 문자열에 의존시키지 마세요.

Langfuse v4에서 새 집계 기능을 만들 때는 Metrics API v2를 우선 사용하세요. 개별 score 행은 Scores API v3, observation 행은 Observations API v2로 조회합니다. 이전 /api/public/v2/scores는 폐기 예정이므로 새 코드에서 사용하지 마세요. v2 데이터 경로를 실시간으로 쓰려면 Langfuse Python SDK 4.7.0 이상이 필요하며, 이전 SDK로 수집한 데이터는 최대 10분 늦게 보일 수 있습니다.

CLI 선택 예제의 scripts/compare_scores.py는 소규모 확인과 구버전 호환을 위한 trace 상세 조회 기준선입니다. 최신 API를 지원하는 배포에서 대규모 대시보드를 만들 때는 위 전용 API를 사용하세요.

빠른 필터 검색 예시

섹션 제목: “빠른 필터 검색 예시”

직접 만든 evaluator observation과 점수를 한 번에 찾으려면 다음처럼 검색합니다.

tags:"workflow:contract-approval" type:EVALUATOR name:contract-check metadata.policyVariant:contract-v3 scores.policy_compliance:>0.9

evaluationSuite와 evaluationCase를 기록했다면 두 값이 같은 실행을 먼저 고른 뒤 workflowVariant를 비교 열로 나눕니다. 두 요청 값을 생략한 일반 호출은 tag와 serviceRole, workflowVariant로 집합을 고릅니다. 평가 기준이 바뀌었다면 policyVariant도 나눠야 서로 다른 정책의 점수가 섞이지 않습니다.

공식 문서: tags, metadata, 빠른 필터 검색, observation types, scores via SDK, Scores API v3, Observations API, Metrics API.