LeanX

랭스미스로 디버깅: 실행 추적과 품질 평가

환경변수 세 줄로 LangSmith 추적을 활성화하면 체인과 에이전트의 모든 LLM 호출, 입출력, 지연 시간, 토큰 수가 대시보드에 자동 기록되며, 데이터셋과 평가(evaluation) 기능으로 RAG나 챗봇의 답변 품질을 수치로 측정할 수 있습니다.

콘텐츠: LeanX · 최초 공개 2026.07.08 · 콘텐츠 기준일 2026.08.14

'AI 답변이 가끔 이상해'라는 버그를 잡아본 적 있으신가요? 체인이 길어질수록 어느 단계에서 문제가 생겼는지 알 수 없습니다. 프롬프트가 잘못됐는지, 검색 결과가 엉뚱한지, 모델이 무시한 건지. LangSmith(랭스미스)는 이 문제를 해결하는 LangChain 팀의 관측성(observability) 플랫폼입니다.

LangSmith란: LLM 앱의 블랙박스 비행 기록기

비행기 블랙박스가 모든 비행 데이터를 기록하듯, LangSmith는 체인·에이전트의 모든 실행을 기록합니다. '어느 노드에서 몇 ms 걸렸는지', '프롬프트에 실제로 무엇이 담겼는지', '얼마나 많은 토큰을 썼는지'를 대시보드에서 시각적으로 봅니다. 코드를 바꾸지 않아도 환경변수 세 줄만 추가하면 추적이 시작됩니다.

LangSmith 설정 3단계

  1. smith.langchain.com에서 계정을 만들고 API 키를 발급받습니다
  2. pip install langsmith 로 패키지를 설치합니다
  3. 환경변수 LANGCHAIN_TRACING_V2, LANGCHAIN_API_KEY, LANGCHAIN_PROJECT를 설정합니다

환경변수 설정만으로 자동 추적 시작하기

import os

# LangSmith 추적 활성화: 이 세 줄이 전부입니다
os.environ['LANGCHAIN_TRACING_V2'] = 'true'
os.environ['LANGCHAIN_API_KEY'] = 'ls-여기에-랭스미스-키'  # smith.langchain.com 에서 발급
os.environ['LANGCHAIN_PROJECT'] = 'rag-study'  # 대시보드에 표시될 프로젝트명

# 기존 체인 코드는 한 줄도 바꾸지 않아도 됩니다
from langchain.chat_models import init_chat_model
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

chain = (
    ChatPromptTemplate.from_template('{question}에 대해 한 문장으로 설명해줘')
    | init_chat_model('openai:gpt-4o-mini')
    | StrOutputParser()
)

# 이 invoke 한 번이 LangSmith 대시보드에 자동으로 기록됩니다
result = chain.invoke({'question': 'RAG'})
print(result)

대시보드에서 볼 수 있는 것들

  • 실행 트리: 체인의 각 노드가 트리 형태로 펼쳐져 어디서 느린지 한눈에 보입니다
  • 입출력 전문: 프롬프트에 실제로 무엇이 담겼는지, AI가 정확히 뭐라 답했는지 확인합니다
  • 지연 시간(latency): 각 LLM 호출마다 몇 ms 걸렸는지 측정해 병목을 찾습니다
  • 토큰 사용량과 비용: 호출별·프로젝트별 토큰 수와 예상 비용을 집계합니다
  • 에러 위치: 예외가 어느 노드에서 발생했는지 스택 트레이스와 함께 표시합니다

@traceable: 일반 함수도 추적 대상에 포함하기

랭체인 외부 함수를 LangSmith 트리에 등록하기

from langsmith import traceable
from langchain.chat_models import init_chat_model

# @traceable 을 붙이면 이 함수도 LangSmith 트리에 나타납니다
@traceable(name='감정_분석')
def analyze_sentiment(text: str) -> str:
    '''텍스트의 감정을 positive 또는 negative 로 분류합니다.'''
    model = init_chat_model('openai:gpt-4o-mini', temperature=0)
    prompt = '다음 문장 감정을 positive 또는 negative 하나로만 답해: ' + text
    return model.invoke(prompt).content.strip()

@traceable(name='리뷰_번역')
def translate_review(text: str) -> str:
    '''한국어 리뷰를 영어로 번역합니다.'''
    model = init_chat_model('openai:gpt-4o-mini')
    return model.invoke('한국어를 영어로 번역해: ' + text).content

# 두 함수가 LangSmith 에서 부모-자식 관계 트리로 시각화됩니다
review = '배송이 너무 늦었어요. 실망스럽습니다.'
sentiment = analyze_sentiment(review)
english = translate_review(review)
print(f'감정: {sentiment}')
print(f'영어: {english}')

평가(Evaluation): 품질을 숫자로 측정하기

추적만으로는 '이번 결과가 좋은가 나쁜가'를 판단하기 어렵습니다. LangSmith 평가는 질문-정답 데이터셋을 만들어 두고, 우리 시스템의 답변과 정답을 LLM이 자동으로 채점하는 기능입니다. RAG 파이프라인을 바꿀 때마다 점수가 오르는지 내리는지 수치로 확인할 수 있어, 직감이 아닌 데이터로 개선 방향을 정할 수 있습니다.

LangSmith 대시보드에서 '느린 실행'을 클릭하면 어느 노드가 병목인지 바로 보입니다. 리트리버가 느리면 벡터스토어 인덱스를 점검하고, LLM 호출이 느리면 더 작은 모델로 교체하거나 스트리밍을 적용하세요. 문제를 찾기 전에 코드를 바꾸지 마세요.

추적 데이터에는 사용자의 질문과 AI의 답변이 모두 LangSmith 서버에 전송됩니다. 개인정보나 영업비밀이 포함될 수 있으므로, 운영 환경에서는 민감 데이터 마스킹 후 전송하거나 LangSmith 온프레미스(self-hosted) 버전 사용을 검토하세요.