🔬
LangSmith 치트시트

LangSmith 최신 기준 초보자 완벽 가이드: 필수 사전 설치, @traceable 데코레이터 및 wrap_openai 무설정 트레이싱, LangChain/LangGraph 자동 연동, 데이터셋 구축 및 evaluate() LLM-as-a-Judge 평가, Prompt Hub 프롬프트 버전 관리, 유저 피드백 수집 및 프로덕션 모니터링 실전 가이드
#langsmith#llm#observability#tracing#evaluation#langchain#langgraph#datasets#prompt-hub#monitoring#openai#python최종 업데이트: 2026-10-09
LangSmith 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 개발 환경 구성 (Prerequisites)

### 💻 시스템 설치 및 실행 요구사양 (System Requirements)

| 항목 | 최소 사양 (Minimum) | 권장 사양 (Recommended) | 참고 및 비고 |
| :--- | :--- | :--- | :--- |
| **운영체제 (OS)** | Linux, macOS, Windows 10/11 | Ubuntu 22.04 LTS, macOS 13+, Windows 11 | 모든 모던 64-bit OS |
| **CPU** | 1 코어 이상 | 2 코어 ~ 4 코어 이상 | 백그라운드 비동기 트레이스 전송 스레드 처리 |
| **메모리 (RAM)** | 1 GB 이상 | 2 GB ~ 4 GB 이상 | 인메모리 런(Run) 버퍼링 및 데이터셋 캐시 |
| **디스크 (Storage)** | 500 MB 이상의 여유 공간 | 2 GB 이상의 여유 공간 | LangSmith SDK 및 로컬 캐시 |
| **네트워크 / 런타임** | Python 3.9 ~ 3.12+, langsmith SDK | 아웃바운드 HTTPS 통신 (`api.smith.langchain.com:443`) | LangSmith 계정 및 API Key (`lsv2_pt_...`) |


**LangSmith**는 LangChain 생태계에서 제공하는 **LLM 엔지니어링 및 통합 관측성(Observability) 플랫폼**입니다. LLM 애플리케이션의 모든 입출력 호출 흐름(트레이스), 지연 시간, 토큰 소모량, 비용, 자동 평가(Evaluation), 골든 데이터셋 및 프롬프트 버전 관리를 하나의 웹 대시보드에서 완벽하게 추적할 수 있습니다.

초보자도 오류 없이 처음부터 끝까지 실습할 수 있도록 필수 사전 환경 구성부터 시작합니다.

---

### 🐍 1. Python 버전 & 가상환경 (Virtual Environment)

LangSmith SDK는 **Python 3.9 ~ 3.12+ (권장: Python 3.11 또는 3.12)** 환경을 지원합니다. 전역 패키지 오염 및 버전 충돌을 방지하기 위해 가상환경 생성이 **필수**입니다.

```bash
# 1. 표준 venv 가상환경 생성
python -m venv .venv

# 2. 가상환경 활성화 (Windows PowerShell)
# ※ 최초 1회 스크립트 실행 권한 부여: Set-ExecutionPolicy Unrestricted -Scope Process
.venv\Scripts\Activate.ps1

# 가상환경 활성화 (macOS / Linux / WSL)
source .venv/bin/activate

# 3. 또는 차세대 초고속 패키지 관리자 uv 사용 시 (강력 추천)
pip install uv
uv venv
# Windows: .venv\Scripts\activate / macOS: source .venv/bin/activate
uv pip install langsmith langchain-core langchain-openai openai python-dotenv
```

---

### 🛠️ 2. OS별 C/C++ 네이티브 빌드 도구 (Native Compiler)

`pydantic-core`, `tiktoken` 등 고성능 C++/Rust 바인딩 패키지 설치 시 발생할 수 있는 컴파일 오류를 방지하기 위해 권장됩니다.

| 운영체제 (OS) | 필요 설치 도구 | 설치 방법 |
| :--- | :--- | :--- |
| **Windows** | Microsoft C++ Build Tools | [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) 설치 시 **"C++를 사용한 데스크톱 개발"** 워크로드 체크 |
| **macOS** | Xcode Command Line Tools | 터미널에서 `xcode-select --install` 실행 |
| **Linux (Ubuntu/Debian)** | `build-essential` & `python3-dev` | `sudo apt update && sudo apt install -y build-essential python3-dev` |

---

### 📦 3. 필수 핵심 라이브러리 일괄 설치

```bash
# 1. LangSmith 코어 SDK
pip install langsmith

# 2. 실습에 사용할 LangChain 및 OpenAI SDK
pip install langchain-core langchain-openai openai

# 3. 환경변수 관리 및 프롬프트 허브 연동
pip install python-dotenv langchainhub
```

---

### 🔑 4. LangSmith 계정 생성 및 API 키 발급

1. [https://smith.langchain.com](https://smith.langchain.com) 에 접속하여 무료 회원가입을 완료합니다.
2. 좌측 하단 **Settings (설정)** ➔ **API Keys** 탭으로 이동합니다.
3. **Create API Key** 버튼을 클릭하여 새 키(`lsv2_pt_...` 형식)를 생성하고 복사합니다.

---

### ⚙️ 5. 환경 변수 구성 (`.env`)

프로젝트 루트 폴더에 `.env` 파일을 생성하고 아래 설정값을 입력합니다:

```bash
# 1. LangSmith 실시간 관측 활성화 (필수)
LANGCHAIN_TRACING_V2="true"

# 2. LangSmith API 키 (lsv2_pt_...)
LANGCHAIN_API_KEY="lsv2_pt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 3. 트레이스를 기록할 프로젝트 이름 (지정하지 않으면 'default' 프로젝트에 저장)
LANGCHAIN_PROJECT="lucky-langsmith-dev"

# 4. LangSmith 수집 엔드포인트 URL
LANGCHAIN_ENDPOINT="https://api.smith.langchain.com"

# 5. LLM 호출에 사용할 OpenAI API 키
OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Python 코드 시작 부분에서 `.env` 파일을 즉시 로드할 수 있도록 합니다:

```python
from dotenv import load_dotenv
load_dotenv()
```

---

## 2. 직관적인 멘탈 모델 (Mental Model & Architecture)

LangSmith는 단순한 로그 뷰어가 아닙니다. LLM 애플리케이션의 **개발 ➔ 디버깅 ➔ 평가 ➔ 모니터링** 전체 라이프사이클을 관장하는 플랫폼입니다.

```text
[LangSmith 전체 라이프사이클 아키텍처]

 ┌────────────────────────────────────────────────────────────────────────┐
 │                      1. Tracing & Observability                        │
 │                                                                        │
 │   User App (LangChain, LangGraph, 순수 OpenAI, 커스텀 Python)         │
 │     │                                                                  │
 │     ├── [Parent Run: Agent] (전체 실행 시간, 총 비용)                 │
 │     │     ├── [Child Run: Prompt Template] (프롬프트 구성)             │
 │     │     ├── [Child Run: LLM Call] (입출력 토큰, 지연 시간, 완성문)  │
 │     │     └── [Child Run: Tool Execution] (도구 파라미터 및 반환값)    │
 │     │                                                                  │
 │     ▼ (백그라운드 비동기 전송)                                          │
 │   LangSmith Web Dashboard (Runs, Latency, Token/Cost, Error Stack)    │
 └───────────────────┬───────────────────────────────┬────────────────────┘
                     │                               │
                     ▼ (클릭 한 번으로 추출)          ▼ (품질 모니터링)
 ┌───────────────────────────────────┐ ┌──────────────────────────────────┐
 │   2. Datasets & Evaluation        │ │   3. Feedback & Prompt Hub       │
 │                                   │ │                                  │
 │ • Golden Dataset 생성 & 관리      │ │ • User Feedback (👍/👎, 별점)    │
 │ • evaluate() 자동 배치 평가 실행   │ │ • Prompt Hub 버전 제어 (Push/Pull)│
 │ • LLM-as-a-Judge 자동 채점         │ │ • Annotation Queue (휴먼 리뷰)   │
 │ • 프롬프트/모델 변경 시 A/B 비교  │ │ • 실시간 알림 & 메타데이터 필터  │
 └───────────────────────────────────┘ └──────────────────────────────────┘
```

### 🔑 LangSmith의 4대 핵심 개념
1. **Run (실행 단위)**: 체인, LLM 호출, 도구 실행 각각의 단일 작업 스팬(Span).
2. **Trace (트레이스 트리)**: 하나의 최종 요청을 처리하기 위해 실행된 모든 Run들의 계층적 부모-자식 트리 구조.
3. **Dataset (데이터셋)**: 입력과 정답(Ground Truth)의 모음. 프롬프트 개선이나 모델 교체 시 회귀 테스트(Regression Test)의 기준점.
4. **Evaluator (평가기)**: LLM 출력의 정확성, 할루시네이션 유무, 응답 길이 등을 자동으로 채점하는 Python 함수 또는 LLM 심사위원(LLM-as-a-Judge).

---

## 3. [초보자 1단계] 헬로월드: 코드 변경 없는 무설정(Zero-Code) 자동 트레이싱

LangChain이나 LangGraph를 사용하는 경우, **단 한 줄의 로깅 코드 없이도** 환경 변수 설정만으로 모든 호출 흐름이 LangSmith에 자동 기록됩니다.

### 📝 완전한 실행 코드 (`01_zero_code_trace.py`)

```python
import os
from dotenv import load_dotenv

# 1. 환경 변수 로드 (.env에 설정된 LANGCHAIN_TRACING_V2="true" 활성화)
load_dotenv()

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

def run_zero_code_pipeline():
    print("=" * 60)
    print("1단계: LangSmith 무설정(Zero-Code) 자동 트레이싱 실행")
    print(f"현재 기록 프로젝트: {os.getenv('LANGCHAIN_PROJECT', 'default')}")
    print("=" * 60)

    # 2. 프롬프트 템플릿 생성
    prompt = ChatPromptTemplate.from_messages([
        ("system", "당신은 IT 기술을 알기 쉽게 3줄로 비유해 주는 개발 전문가입니다."),
        ("human", "{technology} 기술이 무엇인지 핵심을 설명해 주세요.")
    ])

    # 3. 모델 및 출력 파서 구성
    model = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)
    output_parser = StrOutputParser()

    # 4. LCEL 파이프라인 연결 (Prompt ➔ Model ➔ Parser)
    chain = prompt | model | output_parser

    # 5. 체인 실행 (LangSmith가 자동으로 전체 파이프라인 스팬을 캡처)
    tech_name = "Docker"
    print(f"\n[질문 전송] 기술명: {tech_name}\n")
    response = chain.invoke({"technology": tech_name})

    print("[LLM 답변 결과]")
    print(response)
    print("\n" + "=" * 60)
    print("✅ 실행 완료! smith.langchain.com 에서 실시간 트레이스를 확인하세요.")
    print("=" * 60)

if __name__ == "__main__":
    run_zero_code_pipeline()
```

### 💻 예상 콘솔 출력 결과

```text
============================================================
1단계: LangSmith 무설정(Zero-Code) 자동 트레이싱 실행
현재 기록 프로젝트: lucky-langsmith-dev
============================================================

[질문 전송] 기술명: Docker

[LLM 답변 결과]
1. 도커는 프로그램을 실행하는 데 필요한 모든 것을 하나로 포장한 '규격화된 이삿짐 컨테이너'입니다.
2. 어떤 컴퓨터 환경(내 노트북, 서버, 클라우드)에서든 "내 컴퓨터에서는 잘 됐는데..."라는 문제 없이 동일하게 실행됩니다.
3. 무거운 가상머신(VM)과 달리 운영체제를 통째로 복제하지 않고 커널을 공유하여 가볍고 초고속으로 작동합니다.

============================================================
✅ 실행 완료! smith.langchain.com 에서 실시간 트레이스를 확인하세요.
============================================================
```

> **대시보드 확인 포인트**: [smith.langchain.com](https://smith.langchain.com) 프로젝트 목록에서 `lucky-langsmith-dev`로 들어가면 방금 실행된 `RunnableSequence` 트리가 생성되어 있으며, 프롬프트 입력값, 사용된 토큰 수(Prompt + Completion), 소요 시간(Latency, 예: 850ms), 실시간 추정 비용($0.0001 등)이 완벽하게 시각화됩니다.

---

## 4. [2단계] 순수 Python & 비(非) LangChain 환경 트레이싱 (`@traceable` & `wrap_openai`)

LangChain 라이브러리를 쓰지 않고 **순수 Python 함수**나 **순수 OpenAI 공식 SDK**만 사용하는 프로젝트에서도 LangSmith의 강력한 관측 기능을 그대로 활용할 수 있습니다.

### 📝 완전한 실행 코드 (`02_traceable_decorator.py`)

```python
import os
import json
from dotenv import load_dotenv

load_dotenv()

from openai import OpenAI
from langsmith import traceable
from langsmith.wrappers import wrap_openai

# 1. wrap_openai: 순수 OpenAI 클라이언트를 감싸서 입출력 및 토큰 수를 자동 수집
client = wrap_openai(OpenAI())

# 2. 커스텀 비즈니스 함수에 @traceable 데코레이터 적용
@traceable(name="전처리_사용자_입력_검증", run_type="tool", tags=["preprocessing", "validation"])
def sanitize_user_input(user_query: str) -> str:
    """사용자 입력 문자열의 공백을 제거하고 금칙어를 필터링하는 도구 함수"""
    cleaned = user_query.strip()
    if len(cleaned) < 2:
        raise ValueError("입력 질의어가 너무 짧습니다.")
    return cleaned

@traceable(name="사내_지식_검색기", run_type="retriever", tags=["mock-rag", "search"])
def retrieve_internal_docs(query: str) -> list[str]:
    """간이 RAG 검색기 시뮬레이션"""
    mock_knowledge_base = {
        "배포": "사내 배포는 매주 목요일 오후 3시 CI/CD 파이프라인을 통해 진행됩니다.",
        "휴가": "연차 신청은 사내 그룹웨어 전자결재를 통해 최소 3일 전 제출해야 합니다.",
        "보안": "사내 Wi-Fi 접속 시에는 2단계 OTP 인증이 필수입니다."
    }
    for keyword, doc in mock_knowledge_base.items():
        if keyword in query:
            return [doc]
    return ["관련 문서를 찾지 못했습니다."]

# 3. 최상위 오케스트레이션 함수 (Parent Span)
@traceable(
    name="고객지원_AI_어시스턴트",
    run_type="chain",
    tags=["customer-support", "v1.2"],
    metadata={"environment": "development", "user_tier": "VIP"}
)
def customer_support_pipeline(raw_query: str) -> str:
    # 하위 스팬 1: 입력 검증
    clean_query = sanitize_user_input(raw_query)

    # 하위 스팬 2: 문서 검색
    retrieved_context = retrieve_internal_docs(clean_query)

    # 하위 스팬 3: OpenAI API 호출 (wrap_openai에 의해 자동으로 LLM Run으로 기록)
    system_instruction = (
        "당신은 친절한 사내 지원 AI입니다. "
        f"참고 문서: {retrieved_context[0]}\n참고 문서에 근거하여 질문에 답하세요."
    )

    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": system_instruction},
            {"role": "human", "content": clean_query}
        ],
        temperature=0.0
    )

    return response.choices[0].message.content

def main():
    print("=" * 60)
    print("2단계: 순수 Python & OpenAI 트레이싱 (@traceable & wrap_openai)")
    print("=" * 60)

    sample_query = "   이번 주 배포 일정이 어떻게 되나요?   "
    print(f"\n[사용자 원본 입력]: '{sample_query}'\n")

    result = customer_support_pipeline(sample_query)

    print("[AI 최종 안내 답변]")
    print(result)
    print("\n" + "=" * 60)
    print("✅ 계층적 스팬 트리(Parent ➔ Children)가 LangSmith에 기록되었습니다.")
    print("=" * 60)

if __name__ == "__main__":
    main()
```

### 💻 예상 콘솔 출력 결과

```text
============================================================
2단계: 순수 Python & OpenAI 트레이싱 (@traceable & wrap_openai)
============================================================

[사용자 원본 입력]: '   이번 주 배포 일정이 어떻게 되나요?   '

[AI 최종 안내 답변]
이번 주 사내 배포는 목요일 오후 3시에 CI/CD 파이프라인을 통해 진행될 예정입니다. 추가로 궁금한 점이 있으시면 언제든 문의해 주세요!

============================================================
✅ 계층적 스팬 트리(Parent ➔ Children)가 LangSmith에 기록되었습니다.
============================================================
```

> **대시보드 트리 구조 확인**:
> `고객지원_AI_어시스턴트 (chain)`
> ├── `전처리_사용자_입력_검증 (tool)`
> ├── `사내_지식_검색기 (retriever)`
> └── `ChatOpenAI / ChatCompletion (llm)`
> 각 스팬별 개별 소요 시간과 파라미터가 정확히 분리되어 병목 지점을 즉시 찾아낼 수 있습니다.

---

## 5. [3단계] 골든 데이터셋 구축 & 자동 평가 (`evaluate()` & LLM-as-a-Judge)

프롬프트나 모델을 변경했을 때 "이전보다 나아졌는지, 혹은 기존에 잘 되던 것이 망가졌는지(Regression)" 확인하려면 **테스트 데이터셋**과 **자동화된 평가(Evaluation)**가 필수입니다.

LangSmith의 `evaluate()` 함수는 골든 데이터셋의 모든 예제를 실행하고 커스텀 평가기 및 LLM 심사위원을 통해 점수를 집계합니다.

### 📝 완전한 실행 코드 (`03_dataset_and_evaluate.py`)

```python
import os
from dotenv import load_dotenv

load_dotenv()

from langsmith import Client, evaluate
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

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

DATASET_NAME = "lucky_qa_golden_dataset_v1"

def create_or_get_dataset():
    """테스트용 골든 데이터셋이 없으면 신규 생성하고 예제 데이터를 삽입"""
    if client.has_dataset(dataset_name=DATASET_NAME):
        print(f"기존 데이터셋 발견: '{DATASET_NAME}' 사용")
        return client.read_dataset(dataset_name=DATASET_NAME)

    print(f"신규 데이터셋 생성 중: '{DATASET_NAME}'")
    dataset = client.create_dataset(
        dataset_name=DATASET_NAME,
        description="LuckyTechWorld 개발 Q&A 평가용 골든 벤치마크 데이터셋"
    )

    # 평가용 예제 등록 (입력 질문 및 기대되는 정답/키워드)
    examples = [
        (
            {"question": "HTTP 상태 코드 404의 의미는 무엇인가요?"},
            {"expected": "요청한 리소스를 서버에서 찾을 수 없음 (Not Found)"}
        ),
        (
            {"question": "REST API에서 리소스를 수정할 때 주로 쓰는 HTTP 메서드 2가지는?"},
            {"expected": "PUT, PATCH"}
        ),
        (
            {"question": "SQL에서 중복된 행을 제거하고 조회할 때 사용하는 키워드는?"},
            {"expected": "DISTINCT"}
        )
    ]

    for inputs, outputs in examples:
        client.create_example(
            inputs=inputs,
            outputs=outputs,
            dataset_id=dataset.id
        )

    print(f"총 {len(examples)}개의 평가 예제가 데이터셋에 등록되었습니다.")
    return dataset

# 2. 평가 대상이 될 실제 어플리케이션 타겟 함수
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.0)
prompt = ChatPromptTemplate.from_messages([
    ("system", "당신은 소프트웨어 엔지니어링 면접관입니다. 간결하고 정확하게 답변하세요."),
    ("human", "{question}")
])
target_chain = prompt | llm | StrOutputParser()

def target_application(inputs: dict) -> dict:
    """evaluate()가 호출할 대상 함수"""
    response_text = target_chain.invoke({"question": inputs["question"]})
    return {"answer": response_text}

# 3. 커스텀 평가기 정의 (1: 키워드 포함 여부 검증)
def keyword_match_evaluator(run, example) -> dict:
    """예상 정답의 핵심 키워드가 실제 답변에 포함되어 있는지 채점 (0.0 ~ 1.0)"""
    expected = example.outputs["expected"].lower()
    actual = run.outputs["answer"].lower()

    # 단순 포함 여부 또는 분할 매칭
    keywords = [kw.strip() for kw in expected.replace("(", "").replace(")", "").split() if len(kw.strip()) > 1]
    matched = sum(1 for kw in keywords if kw in actual)
    score = matched / len(keywords) if keywords else 1.0

    return {
        "key": "keyword_coverage",
        "score": round(score, 2),
        "comment": f"총 {len(keywords)}개 키워드 중 {matched}개 일치"
    }

# 4. 커스텀 평가기 정의 (2: 답변 길이 적절성 검증)
def length_evaluator(run, example) -> dict:
    actual = run.outputs["answer"]
    is_concise = 10 <= len(actual) <= 300
    return {
        "key": "is_concise",
        "score": 1.0 if is_concise else 0.0,
        "comment": f"답변 글자 수: {len(actual)}자"
    }

def main():
    print("=" * 60)
    print("3단계: 데이터셋 구축 & evaluate() 자동 평가 실행")
    print("=" * 60)

    # 데이터셋 준비
    create_or_get_dataset()

    print("\n[평가 배치 시작] 데이터셋을 대상으로 target_application 실행 중...")

    # evaluate() 실행: LangSmith 대시보드에 실험(Experiment) 결과 생성
    results = evaluate(
        target_application,
        data=DATASET_NAME,
        evaluators=[keyword_match_evaluator, length_evaluator],
        experiment_prefix="prompt-v1-gpt4omini",
        max_concurrency=2
    )

    print("\n" + "=" * 60)
    print("✅ 평가 완료! 대시보드 Experiments 탭에서 매트릭스 결과를 확인하세요.")
    print("=" * 60)

if __name__ == "__main__":
    main()
```

### 💻 예상 콘솔 출력 결과

```text
============================================================
3단계: 데이터셋 구축 & evaluate() 자동 평가 실행
============================================================
신규 데이터셋 생성 중: 'lucky_qa_golden_dataset_v1'
총 3개의 평가 예제가 데이터셋에 등록되었습니다.

[평가 배치 시작] 데이터셋을 대상으로 target_application 실행 중...
View the evaluation results for experiment: 'prompt-v1-gpt4omini-xxxx' at:
https://smith.langchain.com/o/.../datasets/.../compare?selectedSessions=...

============================================================
✅ 평가 완료! 대시보드 Experiments 탭에서 매트릭스 결과를 확인하세요.
============================================================
```

> **평가 결과 분석**: 콘솔에 출력된 링크로 이동하면 3개의 테스트 케이스에 대해 모델이 도출한 `answer`, 그리고 각 평가기(`keyword_coverage`, `is_concise`)의 평균 점수(예: 1.0, 0.85)가 테이블로 시각화됩니다. 향후 `gpt-4o`로 모델을 변경하거나 프롬프트를 수정했을 때 두 실험을 나란히 놓고 비교(Diff)할 수 있습니다.

---

## 6. [4단계] Prompt Hub 연동: 프롬프트 버전 관리 및 팀 협업

코드 안에 긴 프롬프트를 하드코딩하면 수정할 때마다 서버를 재배포해야 합니다. **LangChain Prompt Hub**를 사용하면 웹상에서 프롬프트를 버전별로 관리하고 런타임에 동적으로 당겨올 수 있습니다.

### 📝 완전한 실행 코드 (`04_prompt_hub_usage.py`)

```python
from dotenv import load_dotenv
load_dotenv()

from langchain import hub
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

def demonstrate_prompt_hub():
    print("=" * 60)
    print("4단계: Prompt Hub 연동 (프롬프트 동적 로드 & 실행)")
    print("=" * 60)

    # 1. 커뮤니티 또는 본인 계정의 검증된 프롬프트 가져오기 (hub.pull)
    # 예: rlm/rag-prompt (LangChain 공식 RAG 표준 프롬프트)
    prompt_handle = "rlm/rag-prompt"
    print(f"\n[Prompt Hub] '{prompt_handle}' 템플릿 다운로드 중...")
    pulled_prompt = hub.pull(prompt_handle)

    print("\n[가져온 프롬프트 템플릿 구조]")
    for msg in pulled_prompt.messages:
        print(f"- {msg.prompt.template}")

    # 2. 다운로드받은 프롬프트로 체인 구성
    llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.0)
    rag_chain = pulled_prompt | llm | StrOutputParser()

    # 3. 변수 주입 및 실행
    sample_context = (
        "LuckyTechWorld는 개발자들을 위한 최고의 치트시트와 웹 개발 도구를 무료로 제공하는 기술 허브입니다."
    )
    sample_question = "LuckyTechWorld는 어떤 서비스인가요?"

    print(f"\n[질문 전송]: {sample_question}\n")
    output = rag_chain.invoke({
        "context": sample_context,
        "question": sample_question
    })

    print("[응답 결과]")
    print(output)
    print("\n" + "=" * 60)
    print("✅ Prompt Hub 연동 성공! 프롬프트 템플릿 변경 사항이 무배포로 반영됩니다.")
    print("=" * 60)

if __name__ == "__main__":
    demonstrate_prompt_hub()
```

### 💻 예상 콘솔 출력 결과

```text
============================================================
4단계: Prompt Hub 연동 (프롬프트 동적 로드 & 실행)
============================================================

[Prompt Hub] 'rlm/rag-prompt' 템플릿 다운로드 중...

[가져온 프롬프트 템플릿 구조]
- You are an assistant for question-answering tasks. Use the following pieces of retrieved context to answer the question. If you don't know the answer, just say that you don't know. Use three sentences maximum and keep the answer concise.
Question: {question} 
Context: {context} 
Answer:

[질문 전송]: LuckyTechWorld는 어떤 서비스인가요?

[응답 결과]
LuckyTechWorld는 개발자를 위한 유용한 치트시트와 웹 개발 도구를 무료로 제공하는 기술 허브입니다.

============================================================
✅ Prompt Hub 연동 성공! 프롬프트 템플릿 변경 사항이 무배포로 반영됩니다.
============================================================
```

> **프롬프트 푸시(Push) 팁**: 내가 만든 프롬프트를 Hub에 업로드하려면 `hub.push("내조직명/프롬프트이름", prompt_object)`를 호출하면 대시보드에 즉시 새 커밋 버전으로 저장됩니다.

---

## 7. [5단계] 실전 피드백 수집(User Feedback) & 런타임 메타데이터 태깅

실제 운영 환경에서는 사용자가 웹 화면에서 누르는 **좋아요/싫어요(Thumbs Up/Down)** 또는 별점 평가를 특정 LLM 호출(Run ID)에 연결하여 품질 저하를 추적할 수 있어야 합니다.

### 📝 완전한 실행 코드 (`05_user_feedback_and_metadata.py`)

```python
from dotenv import load_dotenv
load_dotenv()

from langsmith import Client
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.tracers.context import collect_runs

client = Client()

def run_feedback_pipeline():
    print("=" * 60)
    print("5단계: 실전 런타임 메타데이터 주입 & 사용자 피드백(Feedback) 등록")
    print("=" * 60)

    # 1. 프롬프트 및 모델 구성
    prompt = ChatPromptTemplate.from_messages([
        ("system", "사용자의 질문에 친절하고 정중하게 답변하세요."),
        ("human", "{question}")
    ])
    model = ChatOpenAI(model="gpt-4o-mini", temperature=0.7)
    chain = prompt | model

    # 2. 실행 메타데이터와 태그를 주입하며 호출하고, collect_runs()로 run_id를 캡처
    # (실무에서는 user_id, session_id, 환경, 클라이언트 OS 등을 주입)
    invocation_config = {
        "tags": ["production-chat", "mobile-app"],
        "metadata": {
            "user_id": "user_lucky_777",
            "session_id": "sess_abc_1234",
            "app_version": "2.4.0",
            "tier": "enterprise"
        }
    }

    user_query = "LangSmith에서 피드백은 어떻게 연결하나요?"

    with collect_runs() as cb:
        response = chain.invoke({"question": user_query}, config=invocation_config)
        # 실행된 Run의 고유 ID 추출
        captured_run = cb.traced_runs[0]
        run_id = captured_run.id

    print(f"\n[AI 응답 완료]: {response.content[:80]}...")
    print(f"[캡처된 LangSmith Run ID]: {run_id}")

    # 3. 사용자 피드백 시뮬레이션 (웹 프론트엔드에서 '좋아요' 클릭 시 백엔드 API 호출)
    print("\n[사용자 액션 발생] 사용자가 '👍 좋아요' 버튼을 클릭했습니다.")

    client.create_feedback(
        run_id=run_id,
        key="user_satisfaction",
        score=1.0,  # 좋아요: 1.0, 싫어요: 0.0
        comment="답변이 매우 정확하고 상세하여 큰 도움이 되었습니다.",
        source_info={"source": "user_ui_thumbs_button"}
    )

    print("✅ 피드백 데이터가 해당 Run에 성공적으로 결합되었습니다.")
    print("=" * 60)

if __name__ == "__main__":
    run_feedback_pipeline()
```

### 💻 예상 콘솔 출력 결과

```text
============================================================
5단계: 실전 런타임 메타데이터 주입 & 사용자 피드백(Feedback) 등록
============================================================

[AI 응답 완료]: LangSmith에서 피드백을 연결하는 방법은 다음과 같습니다. 먼저 각 LLM 실행의 Run ID를 캡처한 뒤...
[캡처된 LangSmith Run ID]: 7a9e102f-b258-4c17-8149-6f91f2be88dd

[사용자 액션 발생] 사용자가 '👍 좋아요' 버튼을 클릭했습니다.
✅ 피드백 데이터가 해당 Run에 성공적으로 결합되었습니다.
============================================================
```

> **대시보드 필터 활용**: LangSmith 화면에서 `feedback_key:user_satisfaction and feedback_score:0`으로 필터링하면, **사용자가 불만을 표시한 질문만 모아서** 즉시 문제점을 분석하고 테스트 데이터셋에 실패 케이스로 추가할 수 있습니다.

---

## 8. 실무 주의사항 & 프로덕션 체크리스트 (Best Practices)

### 🚨 1. 초보자가 흔히 겪는 실수 & 트러블슈팅

1. **트레이스가 대시보드에 전혀 나타나지 않는 경우**:
   - `LANGCHAIN_TRACING_V2="true"` 철자를 확인하세요 (`"True"`, `"1"`도 가능).
   - `LANGCHAIN_API_KEY`가 올바른 계정의 활성 키인지 확인하세요.
   - 단기 스크립트 실행 후 즉시 프로세스가 종료되면 백그라운드 큐가 전송되기 전에 끝날 수 있습니다. 스크립트 끝에 `from langsmith import Client; Client().flush()`를 호출하여 버퍼를 완전히 비우세요.
2. **비동기(`asyncio`) 환경에서 부모-자식 트리 끊김**:
   - 순수 Python에서 태스크를 비동기로 생성할 때 컨텍스트가 유실될 수 있습니다. 비동기 함수에는 반드시 `@traceable`을 달아주거나 `asyncio` 태스크 내에서 contextvars가 복사되도록 구성하세요.

---

### 🛡️ 2. 개인정보 및 민감정보 보호 (PII Masking)

프로덕션 환경에서 사용자의 비밀번호, 주민번호, 신용카드 번호 등이 LangSmith 대시보드에 평문으로 남지 않도록 마스킹 처리해야 합니다.

```python
# 1. 특정 함수의 입출력을 LangSmith에 기록하지 않고 숨김 처리
@traceable(name="개인정보_처리_함수", hide_inputs=True, hide_outputs=True)
def process_sensitive_data(user_ssn: str, secret_key: str):
    # 비즈니스 로직 수행
    return "처리 완료"
```

---

### 💰 3. 프로덕션 비용 및 성능 최적화 체크리스트

| 점검 항목 | 권장 설정 및 실무 가이드 |
| :--- | :--- |
| **환경별 프로젝트 분리** | `LANGCHAIN_PROJECT`를 `app-dev`, `app-staging`, `app-prod`로 명확히 분리하여 운영 데이터와 테스트 데이터가 섞이지 않도록 관리합니다. |
| **트레이싱 샘플링 (Sampling)** | 대규모 트래픽 발생 시 모든 요청을 기록하면 비용과 대역폭이 소모됩니다. 환경 변수 `LANGCHAIN_TRACING_SAMPLING_RATE="0.1"` (10% 샘플링) 설정을 통해 프로덕션 부담을 경감합니다. |
| **태그와 메타데이터 규격화** | `tags=["release-v2", "free-tier"]`, `metadata={"tenant_id": "...", "region": "ap-northeast-2"}`를 표준화하여 문제 발생 시 신속한 세부 필터링이 가능하도록 구성합니다. |
| **자동 회귀 방지 (CI/CD)** | GitHub Actions 파이프라인에서 새 프롬프트 배포 전 `evaluate()` 스크립트를 실행하여 골든 데이터셋의 합격 점수(예: 95점 이상)를 통과할 때만 머지되도록 보호합니다. |
💬
LangSmith 치트시트

의견 및 질문

댓글 수정

댓글 삭제
