LangSmith로 LangChain 체인/에이전트 관측과 평가하기

LangChain 애플리케이션을 운영 환경에 올리면, 단순히 동작 여부만 확인하는 것으로는 부족합니다. 응답 품질, 비용, 실패율, 지연 시간을 체계적으로 추적하고 개선해야 합니다. 이를 위한 공식 툴이 LangSmith입니다. 이번 글에서는 체인과 에이전트의 관측(Observability), 리트라이 정책, 메트릭 관리를 LangSmith로 설정하는 방법을 살펴보겠습니다.

---

1. LangSmith란 무엇인가?

LangSmith는 LangChain 팀에서 제공하는 LLM 앱 관측·평가 플랫폼입니다.

• ✅ 트레이싱(Tracing): 체인/에이전트 실행 과정을 단계별로 기록
• ✅ 로깅(Logging): 입력·출력, 토큰 사용량, 비용 추적
• ✅ 리트라이(Retry): 실패하거나 품질이 낮은 실행을 재시도
• ✅ 평가(Evaluation): LLM 응답을 정량적·정성적으로 평가

즉, LangChain 앱의 "블랙박스"를 "화이트박스"로 바꿔주는 도구라 할 수 있습니다.

---

2. LangSmith 환경 설정

1) 계정 생성 및 키 발급

LangSmith(https://www.langchain.com/langsmith)에 가입 후, API Key를 발급받습니다.

LangSmith

API KEY발급 버튼

API 키 발급

 

발급이 완료되면 KEY를 Copy할 수 있게 해줍니다.

2) Langsmith 프로젝트 생성

본격적으로 LangSmith 프로젝트를 수행하기 위해서 아래의 작업이 수행되어야 한다. 

아래의 내용 대로 코드를 수행하면 Langsmith 모니터링이 가능해 진다. 

 

2) 환경 변수 등록

LANGSMITH_TRACING="true"
LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
LANGSMITH_API_KEY="<your-api-key>"
LANGSMITH_PROJECT="langsmith_test"
OPENAI_API_KEY="<your-openai-api-key>"

 

---

3. 체인 관측 예제 - 전체 예제 

기본 예제

아래 스니펫은 (1) 체인 팩토리 정의 → (2) LangSmith 클라이언트 생성 → (3) 데이터셋 없으면 생성 → (4) 데이터셋 실행(run_on_dataset) 을 한 번에 보여줍니다.
※ dataset_name과 프롬프트 변수명({question})을 반드시 일치시키세요.

# ==== 0) 상수 ====
OPENAI_API_KEY = "sk-your-openai-key"
LANGSMITH_API_KEY = "ls__your-langsmith-key"
LANGSMITH_API_URL = "https://api.smith.langchain.com"
PROJECT_NAME = "qa_evaluation"
DATASET_NAME = "qa_dataset"


# ==== 1) 체인 팩토리 ====
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

def build_chain():
    llm = ChatOpenAI(model="gpt-4o-mini", temperature=0, api_key=OPENAI_API_KEY)
    prompt = ChatPromptTemplate.from_messages([
        ("system", "너는 한 문장 요약기다."),
        ("human", "다음을 한 문장으로 요약: {question}"),  # ← inputs 키와 동일
    ])
    return prompt | llm | StrOutputParser()


# ==== 2) LangSmith 클라이언트 ====
from langsmith import Client
client = Client(api_key=LANGSMITH_API_KEY, api_url=LANGSMITH_API_URL)


# ==== 3) 데이터셋 보장(없으면 생성) ====
def ensure_dataset(client: Client, dataset_name: str):
    try:
        return client.read_dataset(dataset_name=dataset_name)
    except Exception:
        ds = client.create_dataset(                 # ← 여기!
            dataset_name=dataset_name,              # name(X) → dataset_name(O)
            description="QA demo dataset"
        )
        client.create_example(
            inputs={"question": "LangChain은 무엇인가?"},
            outputs={"answer": "LLM 앱 개발을 돕는 프레임워크"},
            dataset_id=ds.id,
        )
        client.create_example(
            inputs={"question": "Redis는 무엇인가?"},
            outputs={"answer": "인메모리 키-값 저장소"},
            dataset_id=ds.id,
        )
        return ds

ds = ensure_dataset(client, DATASET_NAME)

# ==== 4) 데이터셋 실행 ====
run = client.run_on_dataset(
    dataset_name=DATASET_NAME,
    dataset_id=ds.id,                      # 오타 방지를 위해 id 사용
    llm_or_chain_factory=build_chain,      # 팩토리 함수 권장
    project_name=PROJECT_NAME,
    concurrency=4,
    tags=["eval", "qa"],
    metadata={"owner": "4ourfuture", "env": "local"},
)

print("dataset:", ds.name, ds.id)
print("run started:", run)

 

실행 후 LangSmith 대시보드에서 Tracing Projects → qa_evaluation,
또는 Datasets & Experiments → qa_dataset → Runs에서 추적/결과가 확인 가능합니다. 

 

실제 수행했던 이력이 로그로 쌓인 것을 그래프로 확인 가능합니다.

 

상세 질문과 답변의 이력을 확인해 볼 수 있습니다.

---

4. 리트라이 설정 (Retry)

LLM 호출은 종종 불안정하거나 품질이 낮습니다. LangChain은 with_retry로 간단히 재시도 로직을 추가할 수 있습니다.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

prompt = ChatPromptTemplate.from_messages([
    ("system", "숫자만 반환해."),
    ("human", "1부터 10까지 중 랜덤 숫자 하나 줘"),
])

chain = prompt | llm | StrOutputParser()

# 재시도 설정 (최대 3회)
robust_chain = chain.with_retry(stop_after_attempt=3)

print(robust_chain.invoke({}))

👉 실패(예: 빈 응답) 시 최대 3회까지 재시도하여 안정성을 높입니다.

---

5. 실행 메타데이터와 태그 (Metrics)

LangSmith는 체인/에이전트 실행을 메타데이터와 태그로 구분 관리할 수 있습니다.

config = {
    "tags": ["prod", "summary_chain"],
    "metadata": {"owner": "jungbok", "team": "ai-platform"}
}

res = chain.invoke({"text": "Redis는 인메모리 데이터 저장소다."}, config=config)

👉 대시보드에서 prod 태그와 ai-platform 팀 기준으로 실행 데이터를 필터링할 수 있습니다.

---

6. LangSmith 평가 (Evaluation)

LangSmith는 LLM 응답을 자동/수동 평가할 수 있습니다.

• 자동 평가: 기준 답변과 비교 (정확성, F1 Score 등)
• 휴먼 피드백: 운영자가 직접 Good/Bad 라벨링
• LLM 기반 평가: 메타 평가 모델이 응답 품질을 판정

예시: 평가 데이터셋 실행

from langsmith import Client
client = Client()

# 데이터셋 실행 및 평가
client.run_on_dataset(
    dataset_name="qa_dataset",
    llm_or_chain_factory=chain,
    project_name="qa_evaluation"
)

👉 결과는 LangSmith에서 자동 리포트로 확인할 수 있습니다.

---

7. 에이전트 관측 (Agents)

에이전트는 도구 호출 루프가 포함되어 더 복잡합니다. LangSmith는 각 단계(프롬프트 → 도구 호출 → 도구 응답 → 최종 답변)를 모두 기록합니다.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.tools import tool

@tool
def fx_krw(amount: float) -> str:
    return f"{amount} USD ≈ {amount*1350:,.0f} KRW"

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

prompt = ChatPromptTemplate.from_messages([
    ("system", "너는 합리적인 비서야."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_tool_calling_agent(llm, [fx_krw], prompt)
executor = AgentExecutor(agent=agent, tools=[fx_krw], verbose=True)

executor.invoke({"input": "20달러를 원화로 바꿔줘"})

👉 LangSmith에서는 프롬프트 → 툴 선택 → 툴 실행 → 최종 답변 과정이 모두 시각화됩니다.

---

8. 정리

• LangSmith는 LangChain 실행을 투명하게 보여주는 관측 플랫폼이다.
• Tracing으로 실행 경로를 시각화하고, Retry로 안정성을 높인다.
• Tags/Metadata로 실행을 체계적으로 관리하고, Evaluation으로 품질을 검증한다.
• 체인뿐 아니라 에이전트의 도구 호출 과정도 세밀하게 기록된다.