Bài 3 — Thiết lập LangSmith

LangSmith (của LangChain) mạnh nhất khi bạn dùng hệ sinh thái LangChain/LangGraph — tracing bật gần như tự động. Nhưng nó cũng hoạt động độc lập qua decorator @traceable. Bài này bạn sẽ gắn tracing end-to-end.

Bước 1 — Lấy API key và cấu hình

• Đăng ký tại smith.langchain.com, tạo một project (ví dụ support-agent-prod).
• Tạo API key trong Settings.
• Đặt biến môi trường:

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="lsv2_..."
export LANGSMITH_PROJECT="support-agent-prod"

Chỉ cần đặt các biến này, mọi lệnh gọi qua LangChain sẽ tự động được trace — không cần sửa code.

Bước 2 — Tracing code không dùng LangChain

Nếu agent bạn viết tay (gọi SDK trực tiếp), dùng decorator:

from langsmith import traceable

@traceable(run_type="tool", name="search_docs")
def search_docs(query: str) -> list:
    return vector_db.search(query, k=5)

@traceable(run_type="chain", name="support_agent")
def run_agent(question: str) -> str:
    docs = search_docs(question)          # tự thành span con
    answer = call_llm(question, docs)     # bọc call_llm bằng @traceable nữa
    return answer

Hàm lồng hàm sẽ tự dựng thành run tree. run_type giúp LangSmith phân loại span (llm/tool/retriever/chain).

Bước 3 — Gắn metadata và tags

from langsmith import traceable

@traceable(run_type="chain", name="support_agent")
def run_agent(question, user_id, prompt_version):
    ...

run_agent(
    "Chính sách hoàn tiền?",
    langsmith_extra={
        "metadata": {"user_id": user_id, "prompt_version": "v7"},
        "tags": ["prod", "lang:vi"],
    },
)

Bước 4 — Xem và lọc trace

Vào project trên UI, bạn thấy danh sách trace. Thực hành ngay:

• Sắp xếp theo latency giảm dần — tìm 5 request chậm nhất.
• Lọc error = true — xem tool nào hay hỏng.
• Lọc theo metadata.prompt_version = v7 — cô lập phiên bản.
• Mở một trace, click từng span xem input/output đầy đủ.

Bước 5 — Gắn feedback (điểm chất lượng) vào trace

LangSmith cho phép đính "feedback" (điểm số/nhãn) lên run — nền tảng cho eval online:

from langsmith import Client
client = Client()

client.create_feedback(
    run_id=run_id,
    key="user_thumbs",
    score=1,          # 1 = 👍, 0 = 👎
    comment="Trả lời đúng chính sách",
)

Gắn run_id này vào nút 👍/👎 trong app của bạn, thế là bạn có tín hiệu chất lượng thật từ người dùng.

Checklist "tracing LangSmith đã chuẩn chưa?"

• [ ] Biến môi trường LANGSMITH_TRACING, API_KEY, PROJECT đã set.
• [ ] Mỗi tool/LLM call là một span riêng có tên rõ ràng.
• [ ] Metadata user_id, prompt_version, environment được gắn.
• [ ] Tách project prod và dev để không lẫn dữ liệu.
• [ ] Nút 👍/👎 trong app ghi feedback về đúng run_id.

Sai lầm thường gặp

• Để chung project dev và prod: dữ liệu test làm nhiễu chỉ số production.
• Quên bắt run_id trả về, nên không gắn được feedback người dùng vào đúng trace.
• Trace cả traffic test tải (load test) vào project prod → chi phí và nhiễu số liệu; hãy tắt tracing hoặc tách project.
• Dùng @traceable nhưng để hàm không thuần (side effect ngoài) khiến input/output ghi lại không phản ánh đúng.
• Không set environment, khiến về sau không lọc tách được.

Giờ bạn đã có trace chảy về LangSmith. Bài 4 làm điều tương tự với Langfuse (mã nguồn mở, self-host được).