Bài 4 — Langfuse

Langfuse là nền tảng observability mã nguồn mở, self-host được (chạy trên hạ tầng của bạn) — điểm cộng lớn khi dữ liệu nhạy cảm không được rời khỏi công ty. Nó độc lập framework: dùng với LangChain, LlamaIndex, hay SDK thuần đều được.

Bước 1 — Cài đặt và cấu hình

Dùng bản cloud (cloud.langfuse.com) hoặc self-host bằng Docker Compose. Sau đó:

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_HOST="https://cloud.langfuse.com"   # hoặc URL self-host

pip install langfuse

Bước 2 — Tracing bằng decorator

from langfuse import observe, get_client

@observe()
def search_docs(query):
    return vector_db.search(query, k=5)

@observe()
def run_agent(question, user_id):
    langfuse = get_client()
    langfuse.update_current_trace(
        user_id=user_id,
        session_id="conv-123",
        tags=["prod", "lang:vi"],
        metadata={"prompt_version": "v7"},
    )
    docs = search_docs(question)
    return call_llm(question, docs)

@observe() tự tạo span; hàm lồng nhau tự thành cây. update_current_trace gắn ngữ cảnh cho cả trace.

Bước 3 — Tracing thủ công (kiểm soát chi tiết)

Khi cần kiểm soát từng span:

langfuse = get_client()
with langfuse.start_as_current_span(name="support_agent") as span:
    with langfuse.start_as_current_generation(
        name="llm.answer", model="gpt-4o", input=prompt
    ) as gen:
        out = call_llm(prompt)
        gen.update(output=out, usage_details={"input": 900, "output": 120})
    span.update(output=out)

start_as_current_generation là span chuyên cho LLM call — nơi Langfuse tính token và chi phí.

Bước 4 — Prompt Management (điểm mạnh riêng của Langfuse)

Langfuse quản lý prompt như một tài nguyên có phiên bản, tách khỏi code:

prompt = langfuse.get_prompt("support-system", label="production")
text = prompt.compile(customer_name="An", policy="refund_v3")

Lợi ích: bạn sửa prompt trên UI, gắn nhãn production, và mọi trace tự liên kết với đúng phiên bản prompt. Khi so sánh chất lượng giữa v6 và v7, Langfuse biết trace nào dùng prompt nào — không cần bạn gắn tay.

Bước 5 — Scores (chấm điểm) và eval

langfuse.create_score(
    trace_id=trace_id,
    name="relevance",
    value=0.9,
    comment="Đúng trọng tâm",
)

Score có thể đến từ: người dùng (👍/👎), LLM-as-judge, hoặc quy tắc tự động. Đây là nền cho dashboard chất lượng.

Khung: chọn Langfuse khi nào?

• Cần self-host vì lý do bảo mật/tuân thủ → Langfuse mạnh.
• Muốn prompt management gắn liền tracing → điểm cộng lớn.
• Không muốn khóa vào một framework cụ thể → Langfuse trung lập.
• Ngân sách hạn chế, thích open-source → phù hợp.

Checklist triển khai

• [ ] Keys và HOST (cloud hay self-host) đã cấu hình đúng.
• [ ] @observe() bọc các bước chính; LLM call dùng generation span.
• [ ] user_id, session_id, metadata.prompt_version được set.
• [ ] Prompt được quản lý qua Langfuse với nhãn production.
• [ ] Có tối thiểu một loại score chảy về (feedback người dùng).

Sai lầm thường gặp

• Không flush trước khi tiến trình ngắn thoát (script/serverless): trace mất. Gọi langfuse.flush() ở cuối.
• Self-host nhưng bỏ quên backup ClickHouse/Postgres: mất lịch sử trace.
• Dùng generation span cho tool call (và ngược lại): token/chi phí bị tính sai.
• Hardcode prompt trong code dù đã bật prompt management: mất khả năng liên kết phiên bản.
• Quên đặt usage_details khi tự gọi model không qua wrapper → Langfuse không tính được chi phí.

Bạn đã có hai nền tảng. Bài 5 giới thiệu Braintrust — nền tảng lấy eval làm trung tâm.