Hướng dẫn LangFuse: Nền tảng Kỹ thuật LLM cho Giám sát và Đánh giá

Việc xây dựng ứng dụng LLM rất nhanh trở nên phức tạp. Bạn bắt đầu phải đoán chi phí. Gỡ lỗi trở nên khó hơn khi bạn không nhìn thấy điều gì đã xảy ra. Prompt bị rải rác khắp codebase. LangFuse khắc phục điều này với một nền tảng theo dõi mọi thứ, quản lý prompt và đo lường chất lượng.

Trong hướng dẫn này, bạn sẽ xây dựng một công cụ Hỏi-Đáp tài liệu và xem cách LangFuse tổ chức quá trình phát triển. Bạn sẽ học cách theo vết các lời gọi LLM để gỡ lỗi, quản lý prompt với kiểm soát phiên bản và khám phá các phương pháp đánh giá.

LangFuse là gì?

LangFuse là một nền tảng mã nguồn mở giúp các đội ngũ xây dựng ứng dụng LLM tốt hơn. Trong khi bạn tập trung xây dựng tính năng, LangFuse xử lý việc giám sát, kiểm thử và gỡ lỗi.

Nền tảng bao phủ ba mảng chính:

1. Observability: Xem điều gì xảy ra khi LLM của bạn chạy. Theo dõi chi phí, phát hiện lỗi và hiểu cách người dùng tương tác với ứng dụng. Không còn phải đoán vì sao có lỗi hay tháng trước OpenAI tính phí bao nhiêu.
2. Quản lý prompt: Lưu trữ và quản lý phiên bản prompt ở một nơi thay vì rải rác trong codebase. Đội ngũ có thể thử các phiên bản khác nhau mà không cần chạm vào mã sản xuất.
3. Đánh giá: Đo lường mức độ hiệu quả của LLM. Thiết lập kiểm thử tự động để kiểm tra xem phản hồi có hợp lý, đúng chủ đề hoặc đạt tiêu chuẩn chất lượng hay không.

Khi nào bạn nên dùng LangFuse?

Bạn sẽ muốn dùng LangFuse khi ứng dụng LLM vượt khỏi các thử nghiệm đơn giản. Dưới đây là những tình huống mà nó trở nên hữu ích:

• Nhiều thành viên trong nhóm làm việc trên prompt và bạn cần kiểm soát phiên bản
• Ứng dụng sản xuất nơi bạn cần theo dõi chi phí và giám sát hiệu năng
• Luồng công việc phức tạp như hệ thống RAG, thiết lập đa tác tử hoặc chuỗi hội thoại
• Quan ngại về chất lượng cần kiểm thử có hệ thống thay vì kiểm tra thủ công ngẫu nhiên

Nếu bạn đang xây dựng một nguyên mẫu nhanh hoặc dự án cá nhân, có lẽ bạn chưa cần. Nhưng khi ứng dụng phục vụ người dùng thật hoặc nhóm của bạn vượt quá một người, LangFuse sẽ hữu ích.

Tiếp nhận và tích hợp

LangFuse hoạt động với ngăn xếp AI hiện có của bạn. Nó tích hợp với các framework lớn như LangChain, LlamaIndex, AutoGen và CrewAI. Bạn có thể dùng với bất kỳ nhà cung cấp mô hình nào — OpenAI, Anthropic, Google Gemini, Mistral hay các mô hình Hugging Face đều chạy được ngay.

Nền tảng cung cấp SDK gốc cho Python và JavaScript, cùng hỗ trợ OpenTelemetry cho thiết lập tùy chỉnh. Dù bạn dùng công cụ agent no-code hay framework đa tác tử phức tạp, LangFuse cắm vào mà không cần thay đổi kiến trúc lõi.

Các công ty như Samsara, Twilio và Khan Academy sử dụng trong sản xuất, và nó đáp ứng tiêu chuẩn bảo mật doanh nghiệp. Dự án có hơn 16.500 sao GitHub với hậu thuẫn từ Y Combinator. Bạn có thể dùng bản host sẵn hoặc tự chạy trên hạ tầng của mình.

Giờ khi bạn đã hiểu LangFuse làm gì và khi nào hữu ích, hãy xây dựng thử. Như đã hứa, chúng ta sẽ tạo một công cụ Hỏi-Đáp tài liệu đơn giản để trình diễn cả ba tính năng.

Yêu cầu tiên quyết

Bạn cần có chút kinh nghiệm Python và LLM trước khi bắt đầu với LangFuse.

Bắt buộc:

• Python 3.8+ và kiến thức API cơ bản
• Kinh nghiệm với OpenAI API (chúng ta sẽ dùng GPT-4)
• LangChain cơ bản — prompt, chain và các khái niệm cốt lõi

Nên có:

• Hiểu về embedding và mô hình truy xuất
• Kinh nghiệm với kỹ thuật prompt

Thiết lập:

• Khóa API OpenAI
• Trình quản lý gói Python (uv hoặc pip)
• Chúng ta sẽ cùng tạo tài khoản LangFuse miễn phí

Mới bắt đầu phát triển AI? Hãy bắt đầu với hướng dẫn học AI hoàn chỉnh của chúng tôi trước.

Để hiểu LangFuse nằm ở đâu trong hệ sinh thái rộng hơn, hãy xem tổng quan công cụ LLMOps.

Giờ hãy bắt tay xây dựng. Chúng ta sẽ bắt đầu với hàm Hỏi-Đáp tài liệu đơn giản và xem LangFuse theo dõi những gì xảy ra khi bạn chạy nó. Ví dụ cơ bản này sẽ trình bày cả ba tính năng chính — observability, quản lý prompt và đánh giá — theo cách có thể mở rộng cho các dự án phức tạp hơn.

Xây dựng Công cụ Hỏi-Đáp Tài liệu với LangFuse

Bạn sẽ xây dựng hệ thống Hỏi-Đáp tài liệu đơn giản trả lời câu hỏi từ PDF. Điều này cung cấp một đối tượng thực tế để theo vết, quản lý và đánh giá. Dù ví dụ đơn giản, các mẫu này áp dụng được cho hệ thống RAG phức tạp và luồng công việc đa tác tử.

Thiết lập môi trường

Đầu tiên, tạo thư mục cho dự án và cài các gói cần thiết:

mkdir langfuse-qa-demo
cd langfuse-qa-demo
uv add langfuse langchain langchain-openai langchain-community pypdf python-dotenvĐược hỗ trợ bởi

Đăng ký tài khoản LangFuse Cloud miễn phí tại langfuse.com. Sau khi đăng nhập, tạo tổ chức và dự án mới. Bạn sẽ thấy màn hình với khóa API:

Sao chép Public Key và Secret Key của bạn. Bạn cũng sẽ cần khóa API OpenAI từ platform.openai.com.

Giờ hãy tạo tệp .env trong thư mục dự án:

OPENAI_API_KEY=your_openai_key_here
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.comĐược hỗ trợ bởi

Nếu bạn muốn tự chạy LangFuse trên hạ tầng riêng, bạn có thể dùng Docker Compose để thử nghiệm cục bộ. Hướng dẫn tự host sẽ hướng dẫn thiết lập PostgreSQL, ClickHouse và các dịch vụ LangFuse. Với triển khai sản xuất, hãy dùng Kubernetes hoặc các mẫu Terraform theo nền tảng đám mây.

Xây dựng chuỗi Hỏi-Đáp tài liệu trong LangChain

Bạn sẽ xây dựng retrieval chain tải PDF, chia nhỏ thành các đoạn, lưu vào vector database và trả lời câu hỏi dựa trên ngữ cảnh được truy xuất.

Tạo tệp tên qa_chain.py:

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_core.vectorstores import InMemoryVectorStore
from langchain.chains import create_retrieval_chain
from langchain.chains.combine_documents import create_stuff_documents_chain
from langchain_core.prompts import ChatPromptTemplate
from dotenv import load_dotenv

load_dotenv()Được hỗ trợ bởi

Đoạn này nhập mọi thứ bạn cần. Lệnh load_dotenv() tải khóa API từ tệp .env.

# Load and split PDF
loader = PyPDFLoader("ai-security-landscape.pdf")
docs = loader.load()

text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
splits = text_splitter.split_documents(docs)Được hỗ trợ bởi

Ở đây, chúng ta đang tải tài liệu ai-security-landscape.pdf, một trong các whitepaper do Amazon Web Services viết. Để chạy ví dụ này, bạn cần tự tải tệp về và thêm vào thư mục làm việc với đúng tên.

PyPDFLoader đọc PDF và RecursiveCharacterTextSplitter chia thành các đoạn 1.000 ký tự với phần chồng 200 ký tự. Phần chồng giúp duy trì ngữ cảnh qua ranh giới đoạn.

Tiếp theo, tạo vector store:

# Create vector store
embeddings = OpenAIEmbeddings()
vectorstore = InMemoryVectorStore.from_documents(documents=splits, embedding=embeddings)Được hỗ trợ bởi

InMemoryVectorStore lưu embedding tài liệu trong bộ nhớ. Trong sản xuất, bạn sẽ dùng Pinecone, Weaviate hoặc một vector database khác.

Giờ hãy xây dựng QA chain:

# Build QA chain
llm = ChatOpenAI(model="gpt-4")
prompt = ChatPromptTemplate.from_messages([
   ("system", "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\n{context}"),
   ("human", "{input}"),
])

question_answer_chain = create_stuff_documents_chain(llm, prompt)
qa_chain = create_retrieval_chain(vectorstore.as_retriever(), question_answer_chain)Được hỗ trợ bởi

create_stuff_documents_chain nhận các tài liệu đã truy xuất và nhúng chúng vào ngữ cảnh prompt. create_retrieval_chain kết hợp truy xuất và trả lời thành một chain.

Khi chain đã sẵn sàng, hãy kết nối nó với LangFuse để theo vết.

Theo vết lời gọi đầu tiên với LangFuse

Thêm trình xử lý callback của LangFuse vào script:

from langfuse.langchain import CallbackHandler

langfuse_handler = CallbackHandler()

response = qa_chain.invoke(
   {"input": "What are the main security risks discussed?"},
   config={"callbacks": [langfuse_handler]}
)

print(response["answer"])Được hỗ trợ bởi

The main security risks discussed in relation to generative artificial intelligence (AI) are context window overflow, agent mismanagement, indirect prompt injections and data leaks from overprivileged agents, logging, and caching.

Trace sent to LangFuse! Check your dashboard at https://cloud.langfuse.comĐược hỗ trợ bởi

Khi bạn chạy, LangFuse sẽ thu thập toàn bộ vết thực thi. Truy cập bảng điều khiển LangFuse, bạn sẽ thấy cập nhật với chi tiết mới:

Lưu ý rằng dù dùng ví dụ đơn giản, LangFuse hoạt động với các pipeline RAG phức tạp xử lý nhiều loại tài liệu, dùng re-ranking hoặc chạy song song nhiều chiến lược truy xuất.

Với hệ thống H&Đ của bạn đang chạy và theo vết bởi LangFuse, bạn đã sẵn sàng hiểu LangFuse thu thập gì và cách dùng thông tin đó để cải thiện ứng dụng.

Observability trong LangFuse

Bạn vừa gửi một trace tới LangFuse. Giờ hãy hiểu bạn nhận được gì và vì sao điều đó quan trọng.

Vì sao observability cho LLM quan trọng

Ghi log truyền thống không hiệu quả với ứng dụng LLM. Bạn có thể log rằng một hàm đã chạy, nhưng bạn không thấy mô hình thực sự làm gì với đầu vào của người dùng. Nó có truy xuất đúng tài liệu không? Prompt có được định dạng đúng không? Bước nào mất năm giây?

Observability cho LLM theo dõi toàn bộ đường thực thi. Bạn thấy mọi đầu vào, đầu ra và bước trung gian. Khi người dùng báo trả lời sai, bạn mở trace của họ và xem chính xác chuyện gì đã xảy ra. Bạn không đoán. Bạn biết.

Điều này càng quan trọng khi ứng dụng phức tạp hơn. Một chuỗi H&Đ đơn giản có 4–5 bước. Hệ thống RAG sản xuất có bộ tải tài liệu, chiến lược chia khối, nhiều bộ truy xuất, bộ re-ranker và bước sinh. Không có observability, gỡ lỗi là bất khả thi. Có nó, bạn xác định đúng điểm vấn đề.

Hiểu về trace và session

Mở bảng điều khiển LangFuse và nhấp “Tracing” ở thanh bên trái. Bạn sẽ thấy trace đầu tiên xuất hiện trong bảng.

Bảng hiển thị thời điểm trace chạy, tên gọi (retrieval_chain) và dữ liệu vào/ra. Mỗi hàng là một lần thực thi đầy đủ của chuỗi H&Đ.

Nhấp vào trace để xem những gì xảy ra bên trong. Bạn sẽ nhận phân tích chi tiết.

Bảng trái hiển thị cây thực thi. LangFuse theo dõi mọi bước trong chuỗi. Nút gốc retrieval_chain mất tổng cộng 4,75 giây. Bên dưới là các thao tác đã chạy: truy xuất tài liệu (retrieve_documents), tìm kiếm vector (VectorStoreRetriever) và sinh câu trả lời (stuff_documents_chain). Mỗi bước hiển thị thời gian thực thi.

Cấu trúc phân cấp này cho biết chuỗi của bạn tiêu tốn thời gian ở đâu. Nếu ứng dụng chạy chậm, bạn sẽ biết là do tra cứu embedding, tìm kiếm vector hay lời gọi LLM.

Bảng phải hiển thị dữ liệu trace. Trên cùng là các số liệu quan trọng: độ trễ (4,75s), chi phí (~$0,016) và token dùng (426 đầu vào, 55 đầu ra). Bên dưới là đầu vào và đầu ra thực tế. Phần context hiển thị bốn đoạn tài liệu mà bộ truy xuất của bạn đã lấy từ vector store.

Phía dưới cùng, sơ đồ luồng ánh xạ cách chuỗi kết nối các thao tác. Điều này hữu ích khi gỡ lỗi chuỗi phức tạp có nhiều nhánh.

Giờ nói về session. Một trace ghi lại một vòng hỏi-đáp. Nhưng ứng dụng thực có hội thoại. Người dùng có thể hỏi ba câu liên quan về rủi ro bảo mật. Bạn muốn nhóm các trace đó lại với nhau.

Đó là vai trò của session. Chúng gom nhiều trace vào một luồng hội thoại. Khi người dùng báo lỗi, bạn có thể mở toàn bộ session và xem mọi câu hỏi cùng câu trả lời họ nhận được.

Hãy xem thực tế. Trước hết, tạo tệp tiện ích build_chain.py để bọc logic xây dựng chain:

from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_core.vectorstores import InMemoryVectorStore
from langchain.chains import create_retrieval_chain
from langchain.chains.combine_documents import create_stuff_documents_chain
from langchain_core.prompts import ChatPromptTemplate
from dotenv import load_dotenv

load_dotenv()

def build_qa_chain():
   # Load and split PDF
   loader = PyPDFLoader("ai-security-landscape.pdf")
   docs = loader.load()

   text_splitter = RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
   splits = text_splitter.split_documents(docs)

   # Create vector store
   embeddings = OpenAIEmbeddings()
   vectorstore = InMemoryVectorStore.from_documents(documents=splits, embedding=embeddings)

   # Build QA chain
   llm = ChatOpenAI(model="gpt-4")
   prompt = ChatPromptTemplate.from_messages([
       ("system", "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\n{context}"),
       ("human", "{input}"),
   ])

   question_answer_chain = create_stuff_documents_chain(llm, prompt)
   qa_chain = create_retrieval_chain(vectorstore.as_retriever(), question_answer_chain)

   return qa_chainĐược hỗ trợ bởi

Đoạn này gom mọi thứ vào một hàm để bạn import. Giờ tạo sessions_demo.py:

from build_chain import build_qa_chain
from langfuse.langchain import CallbackHandler

# Build the Q&A chain
qa_chain = build_qa_chain()

# Set up LangFuse handler
langfuse_handler = CallbackHandler()
This imports your chain and sets up the LangFuse handler. Now add session tracking for the first conversation:
# Session 1: User asking about security risks
response1 = qa_chain.invoke(
   {"input": "What are the main security risks discussed?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {"langfuse_session_id": "conversation-001"}
   }
)
print(f"Q1: {response1['answer']}\n")Được hỗ trợ bởi

Trường metadata với langfuse_session_id gắn nhãn trace này với ID session. Chạy lên và bạn sẽ thấy:

Q1: The main security risks discussed are context window overflow, agent mismanagement, and indirect prompt injections.Được hỗ trợ bởi

Giờ thêm câu hỏi tiếp theo với cùng session ID:

response2 = qa_chain.invoke(
   {"input": "How can these risks be mitigated?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {"langfuse_session_id": "conversation-001"}
   }
)
print(f"Q2: {response2['answer']}\n")Được hỗ trợ bởi

Câu hỏi thứ hai thuộc cùng hội thoại, nên tiếp tục dùng conversation-001. Bạn sẽ thấy câu trả lời dài hơn:

Q2: Risks can be mitigated through several strategies including:
1. Input Management: Limit and sanitize inputs going into the model.
2. Real-time Monitoring: Use systems that alert when the context window is nearing capacity.
3. Principle of Least Privilege: Implement this for all agents and external integrations.
....Được hỗ trợ bởi

Bây giờ mô phỏng người dùng thứ hai với các câu hỏi khác. Thêm đoạn này vào script:

# Session 2: Different user asking about AI applications
response3 = qa_chain.invoke(
   {"input": "What AI applications are mentioned in the document?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {"langfuse_session_id": "conversation-002"}
   }
)
print(f"Q3: {response3['answer']}\n")

response4 = qa_chain.invoke(
   {"input": "What are the benefits of these applications?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {"langfuse_session_id": "conversation-002"}
   }
)
print(f"Q4: {response4['answer']}\n")Được hỗ trợ bởi

Hai câu hỏi này dùng conversation-002. Chạy toàn bộ script:

uv run python sessions_demo.pyĐược hỗ trợ bởi

Hai đầu ra cuối sẽ là:

Q3: The document does not specifically mention any AI applications. However, it discusses the concept of generative AI and its security considerations.

Q4: The context does not provide specific benefits of these applications.Được hỗ trợ bởi

Giờ vào bảng điều khiển LangFuse và nhấp “Sessions” ở thanh bên trái. Bạn sẽ thấy cả hai hội thoại được liệt kê:

Xuất hiện hai session: conversation-002 (~4 giây) và conversation-001 (~14 giây). LangFuse đã nhóm trace theo session ID.

Nhấp vào conversation-001 để xem trọn hội thoại:

Bạn thấy cả hai trace theo thứ tự: Câu hỏi 1 về rủi ro bảo mật, và Câu hỏi 2 về giảm thiểu. Session hiển thị tổng chi phí ($0,05121 cho cả hai) và thời lượng (14 giây tổng). Mỗi trace đi kèm đầu vào, đầu ra và ngữ cảnh truy xuất.

Chế độ xem session cho bạn thấy chính xác trải nghiệm của người dùng trong quá trình tương tác. Nếu họ báo vấn đề, bạn không cần dò tìm từng trace. Chỉ cần mở session của họ để xem luồng hội thoại đầy đủ.

Theo dõi người dùng

Đến giờ bạn đã theo dõi session, nhưng còn từng người dùng thì sao? Ứng dụng LLM thực tế cần biết người dùng nào đã thực hiện yêu cầu nào. Khi ai đó đăng ký, bạn tạo một ID duy nhất cho họ. Sau đó gắn ID đó vào mọi lời gọi LLM của họ.

LangFuse cho phép nhóm trace theo user ID bên cạnh grouping theo session. Điều này cung cấp một cách khác để tổ chức dữ liệu observability.

Cách thêm theo dõi người dùng như sau. Tạo user_tracking.py:

from build_chain import build_qa_chain
from langfuse.langchain import CallbackHandler

# Build the Q&A chain
qa_chain = build_qa_chain()

# Set up LangFuse handler
langfuse_handler = CallbackHandler()

# Simulate a new user asking a question
user_response = qa_chain.invoke(
   {"input": "What security controls are recommended for AI systems?"},
   config={
       "callbacks": [langfuse_handler],
       "metadata": {
           "langfuse_session_id": "conversation-003",
           "langfuse_user_id": "user-12345"
       }
   }
)
print(f"Response: {user_response['answer']}")Được hỗ trợ bởi

Trường langfuse_user_id gắn trace này với user ID. Chạy script:

uv run python user_tracking.pyĐược hỗ trợ bởi

Bạn sẽ thấy:

Response: The recommended security controls for AI systems include:

1. Adaptive defenses: Incorporate machine learning-powered filters that continuously learn and adapt to new adversarial techniques.
2. Defense-in-depth: Introduce layered security mechanisms, such as refusal classifiers and real-time input monitoring, to fortify AI system integrity.
3. Data classification: Properly classify your data according to sensitivity.
......Được hỗ trợ bởi

Giờ vào bảng điều khiển LangFuse. Nhấp “Users” ở thanh bên trái, bạn sẽ thấy user-12345. Nhấp vào người dùng để xem tất cả trace của họ trên các session.

Chế độ xem người dùng giúp bạn trả lời các câu như “Người dùng X tốn của chúng ta bao nhiêu tháng này?” hoặc “Người dùng Y cứ hỏi những câu gì?”. Bạn có thể theo dõi hành vi từng người dùng và gỡ lỗi các vấn đề cụ thể.

Quản lý Prompt trong LangFuse

Hệ thống H&Đ của bạn có một vấn đề. Prompt bị chôn trong mã. Để thay đổi cách hệ thống phản hồi, bạn cần sửa qa_chain.py, kiểm thử cục bộ và redeploy. Nếu đồng đội muốn thử cách khác, họ cần hiểu cấu trúc mã và tạo nhánh mới. Bạn không thể so sánh các phiên bản prompt cạnh nhau hoặc quay lại phiên bản tuần trước mà không phải lục tìm lịch sử git.

Quản lý prompt giải quyết việc này bằng cách lưu prompt ngoài mã. Bạn chỉnh trong UI, tự động tạo phiên bản và fetch tại runtime. Mã của bạn giữ nguyên trong khi prompt được cải thiện.

Bài toán cộng tác với prompt

Xem prompt trong chuỗi H&Đ của bạn:

prompt = ChatPromptTemplate.from_messages([
   ("system", "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\n{context}"),
   ("human", "{input}"),
])Được hỗ trợ bởi

Điều này ổn với dự án cá nhân. Nhưng khi làm việc nhóm hoặc chạy sản xuất, prompt hardcode gây vấn đề:

• Ma sát triển khai: Mỗi thay đổi prompt yêu cầu triển khai mã. Bạn không thể A/B test các prompt khác nhau mà không sửa mã ứng dụng. Nếu muốn thử “Hãy ngắn gọn và chính xác” thay vì “Giữ câu trả lời súc tích”, bạn phải commit, push và redeploy.
• Thiếu kiểm soát phiên bản: Git theo dõi thay đổi mã, nhưng không hiển thị phiên bản prompt nào hoạt động tốt hơn trong sản xuất. Bạn không thể xem số liệu cho “prompt v1” so với “prompt v2” hoặc nhanh chóng quay lại phiên bản trước mà không triển khai mã.
• Nút thắt cho đội ngũ: Thành viên không kỹ thuật không thể lặp nhanh trên prompt. Quản lý sản phẩm có ý tưởng cải tiến câu chữ nhưng phải nhờ kỹ sư sửa. Điều này làm chậm thử nghiệm.
• Khó kiểm thử: So sánh biến thể prompt đồng nghĩa chạy nhiều phiên bản mã. Bạn không thể kiểm thử câu trả lời ngắn gọn so với chi tiết cạnh nhau mà không tốn công thủ công.

Quản lý prompt của LangFuse giải quyết các vấn đề này bằng cách coi prompt là dữ liệu, không phải mã.

Tạo và quản lý phiên bản prompt

LangFuse lưu trữ prompt ở một nơi trung tâm với tự động đánh phiên bản. Bạn có thể tạo prompt qua UI hoặc SDK.

Tạo prompt trong UI

Vào bảng điều khiển LangFuse và nhấp “Prompts” ở thanh bên trái. Nhấp “New Prompt” để tạo.

Bạn sẽ thấy biểu mẫu nơi có thể:

• Đặt tên prompt (dùng document-qa-prompt)
• Chọn loại (text hoặc chat)
• Viết mẫu prompt với biến dùng cú pháp {{variable}}
• Đặt cấu hình như model và temperature
• Thêm nhãn để đánh dấu phiên bản (như production hoặc staging)

Với hệ thống H&Đ của chúng ta, hãy tạo một chat prompt với hai tin nhắn:

Thông điệp hệ thống:

Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.

{{context}}Được hỗ trợ bởi

Thông điệp người dùng:

{{input}}Được hỗ trợ bởi

LangFuse sẽ tự động phát hiện các biến {{context}} và {{input}}.

Tiếp theo, đặt cấu hình như sau:

{
 "model": "gpt-4",
 "temperature": 0.0
}Được hỗ trợ bởi

Thêm nhãn production để đánh dấu đây là phiên bản sản xuất.

Khi lưu, LangFuse tạo phiên bản 1 cho prompt của bạn. Mỗi lần chỉnh sửa và lưu sẽ tạo một phiên bản mới. Các phiên bản cũ vẫn sẵn có.

Tạo prompt qua SDK

Bạn cũng có thể tạo prompt bằng Python SDK:

from langfuse import Langfuse

langfuse = Langfuse()

langfuse.create_prompt(
   name="document-qa-prompt",
   type="chat",
   prompt=[
       {"role": "system", "content": "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\n{{context}}"},
       {"role": "user", "content": "{{input}}"}
   ],
   labels=["production"]
)Được hỗ trợ bởi

Đoạn này tạo cùng một prompt bằng lập trình. Nếu bạn gọi create_prompt() lần nữa với cùng tên, LangFuse sẽ thêm phiên bản mới thay vì ghi đè.

Kiểm soát phiên bản với nhãn

LangFuse theo dõi mọi thay đổi prompt bằng số phiên bản (v1, v2, v3). Bạn cũng có thể gán nhãn cho phiên bản. Nhãn giúp bạn quản lý triển khai:

• production - Phiên bản ứng dụng sản xuất sử dụng
• staging - Phiên bản trong môi trường staging
• latest - Tự động trỏ đến phiên bản mới nhất

Khi cải thiện prompt, bạn tạo phiên bản mới. Kiểm thử ở staging trước bằng cách gán nhãn staging. Khi đã ổn, chuyển nhãn production sang phiên bản mới. Ứng dụng sản xuất sẽ tự động nhận thay đổi ở lần fetch prompt tiếp theo.

Kiểm thử biến thể trong playground

Giao diện LangFuse có playground để bạn kiểm thử prompt trước khi đưa vào mã. Bạn có thể:

• Thử các giá trị biến khác nhau
• So sánh nhiều phiên bản cạnh nhau
• Xem thay đổi ảnh hưởng đến đầu ra ra sao
• Chia sẻ kết quả kiểm thử với đội ngũ

Điều này cho phép thành viên không kỹ thuật thử nghiệm câu chữ mà không cần động vào mã.

Tích hợp prompt được quản lý vào mã

Cách dùng prompt do LangFuse quản lý trong ứng dụng của bạn. Luồng này giữ cho mã ổn định trong khi prompt tiến hóa.

Bước 1: Fetch prompt

Trong mã ứng dụng, fetch prompt từ LangFuse thay vì hardcode:

from langfuse import Langfuse

langfuse = Langfuse()

# Get the production version
prompt = langfuse.get_prompt("document-qa-prompt", type="chat")Được hỗ trợ bởi

Lệnh này fetch phiên bản gắn nhãn production. LangFuse cache prompt phía client, nên không ảnh hưởng độ trễ lời gọi LLM.

Bạn cũng có thể fetch phiên bản hoặc nhãn cụ thể:

# Get version 2 specifically
prompt = langfuse.get_prompt("document-qa-prompt", version=2, type="chat")

# Get staging version
prompt = langfuse.get_prompt("document-qa-prompt", label="staging", type="chat")

# Get latest version (automatically maintained by LangFuse)
prompt = langfuse.get_prompt("document-qa-prompt", label="latest", type="chat")Được hỗ trợ bởi

Bước 2: Biên dịch prompt với biến

Prompt fetch về là một template với {{variables}}. Biên dịch bằng cách thay biến bằng giá trị thực:

compiled_messages = prompt.compile(
   context="Retrieved document context goes here",
   input="What are the main security risks?"
)Được hỗ trợ bởi

Kết quả là danh sách tin nhắn chat sẵn sàng gửi tới LLM:

[
   {
       "role": "system",
       "content": "Use the given context to answer the question. If you don't know the answer, say you don't know. Keep the answer concise.\n\nRetrieved document context goes here"
   },
   {
       "role": "user",
       "content": "What are the main security risks?"
   }
]Được hỗ trợ bởi

Bước 3: Dùng prompt đã biên dịch với LLM

Truyền danh sách tin nhắn đã biên dịch vào lời gọi LLM. Mã cụ thể tùy vào việc bạn dùng LangChain, OpenAI SDK trực tiếp hay framework khác.

Bước 4: Liên kết prompt với trace

Khi bạn gọi LLM với prompt do LangFuse quản lý, hãy liên kết nó với trace. Điều này cho phép xem phiên bản prompt nào được dùng cho mỗi lời gọi LLM và theo dõi số liệu theo phiên bản prompt:

from langfuse.langchain import CallbackHandler

langfuse_handler = CallbackHandler()

response = qa_chain.invoke(
   {"input": "What are the main security risks?"},
   config={"callbacks": [langfuse_handler]}
)Được hỗ trợ bởi

Trên bảng điều khiển LangFuse, bạn sẽ thấy trace được nhóm theo tên và phiên bản prompt. Điều này cho thấy phiên bản nào tốn chi phí hơn, chạy chậm hơn hoặc cho kết quả tốt hơn.

Bước 5: Lặp lại mà không cần đổi mã

Đây là nơi quản lý prompt phát huy hiệu quả. Để cải thiện prompt:

1. Vào UI của LangFuse
2. Chỉnh prompt (tự động tạo phiên bản mới)
3. Kiểm thử trong playground
4. Gán nhãn staging để thử trong môi trường staging
5. Di chuyển nhãn production để triển khai

Mã của bạn không cần thay đổi. Lần gọi get_prompt() tiếp theo sẽ fetch phiên bản mới.

Bước 6: Rollback khi cần

Nếu prompt mới hoạt động kém hơn, rollback bằng cách di chuyển nhãn production về phiên bản trước. Không cần triển khai mã.

Luồng này tách biệt kỹ thuật prompt khỏi kỹ thuật phần mềm. Đội ngũ có thể lặp nhanh trên prompt trong khi mã ứng dụng vẫn ổn định.

Đọc thêm: LangFuse còn hỗ trợ A/B testing để tự động chia lưu lượng giữa các phiên bản prompt, webhook thông báo hệ thống của bạn khi prompt thay đổi và các tính năng cộng tác như bình luận, quy trình phê duyệt. Những tính năng nâng cao này giúp đội ngũ lớn quản lý prompt ở quy mô. Xem tài liệu quản lý prompt để biết chi tiết.

Đánh giá trong LangFuse

Bạn đã xây dựng hệ thống H&Đ, thêm observability và thiết lập quản lý prompt. Nhưng làm sao biết câu trả lời có tốt không? Hiện tại, có lẽ bạn đang kiểm thử thủ công: hỏi một câu, đọc phản hồi và tự đánh giá. Cách này ổn cho vài ví dụ, nhưng không mở rộng được.

Khi bạn thay đổi prompt thì sao? Bạn cần kiểm thử lại mọi thứ. Còn các trường hợp biên? Bạn không thể nhớ mọi câu đã từng thử. Và khi đưa vào sản xuất, bạn không có cách đo lường liệu phiên bản 2 của prompt có hoạt động tốt hơn phiên bản 1 hay không.

Đánh giá khắc phục điều này bằng cách đo lường có hệ thống hiệu năng của LLM. LangFuse cung cấp công cụ chấm điểm tự động phản hồi, so sánh phiên bản prompt với số liệu thực và phát hiện vấn đề chất lượng trước khi người dùng nhìn thấy.

Các cách tiếp cận đánh giá LLM có hệ thống

Kiểm thử thủ công cho bạn biết một câu trả lời cụ thể có ổn không. Đánh giá có hệ thống cho bạn biết toàn bộ hệ thống có hoạt động tốt trên hàng trăm hay hàng nghìn ví dụ hay không.

Cách đánh giá có hệ thống hoạt động trong LangFuse:

1. Xây dựng tập dữ liệu kiểm thử: Thu thập 20–50 câu hỏi đại diện cho cách dùng thực tế, bao gồm các trường hợp biên khi câu trả lời không có trong tài liệu.
2. Chọn phương pháp chấm điểm: Quyết định các khía cạnh chất lượng quan trọng cho hệ thống H&Đ (chúng ta sẽ bàn ở phần sau).
3. Chạy hệ thống với tập dữ liệu: Xử lý từng câu hỏi và log kết quả lên LangFuse dưới dạng trace.
4. Chấm điểm phản hồi: Áp dụng phương pháp chấm điểm cho mỗi phản hồi một cách tự động.
5. Phân tích kết quả: LangFuse tổng hợp điểm trên tập kiểm thử và hiển thị các ví dụ thất bại.
6. Lặp lại và so sánh: Thay đổi prompt, chạy lại tập kiểm thử và so sánh số liệu để xem bạn đã cải thiện chưa.

Quy trình này thay cho “Tôi nghĩ prompt này tốt hơn” bằng “prompt này đạt 0,85 về độ liên quan so với 0,72 của phiên bản cũ”.

Để có hướng dẫn đầy đủ về các cách đánh giá và cách triển khai trong LangFuse, xem tài liệu tổng quan đánh giá.

Hiểu về đánh giá LLM-đóng-vai-trò-trọng-tài (LLM-as-a-Judge)

Bạn cần chấm hàng trăm phản hồi. Làm thủ công sẽ tốn hàng giờ. LLM-as-a-judge tự động hóa bằng cách dùng một LLM khác để chấm đầu ra của LLM chính.

Cách hoạt động

Bạn cung cấp cho LLM trọng tài ba thứ: câu hỏi gốc, câu trả lời từ hệ thống H&Đ và tiêu chí chấm. Trọng tài đọc câu trả lời và gán điểm.

Với hệ thống H&Đ, bạn quan tâm các khía cạnh chất lượng khác nhau. Dưới đây là ba trọng tài bạn có thể tạo:

Trọng tài tính đúng: “Đánh giá xem câu trả lời có phản ánh đúng thông tin trong ngữ cảnh cung cấp không. Chấm 1 nếu hoàn toàn đúng, 0,5 nếu đúng một phần, 0 nếu sai hoặc bịa.”

Điều này bắt được các câu trả lời mâu thuẫn với tài liệu hoặc bịa đặt.

Trọng tài mức độ liên quan: “Đánh giá xem câu trả lời có trực tiếp trả lời câu hỏi không. Chấm 1 nếu rất liên quan, 0,5 nếu hơi liên quan, 0 nếu lạc đề.”

Điều này đảm bảo hệ thống bám sát chủ đề thay vì đưa thông tin chính xác nhưng không liên quan.

Trọng tài mức độ bám ngữ cảnh (groundedness): “Đánh giá xem câu trả lời chỉ dựa trên ngữ cảnh cung cấp. Chấm 1 nếu hoàn toàn bám ngữ cảnh, 0,5 nếu bám một phần, 0 nếu có thông tin không có trong ngữ cảnh.”

Điều này ngăn hiện tượng bịa đặt khi LLM thêm thông tin không có trong tài liệu.

Mỗi trọng tài xem xét một khía cạnh chất lượng cụ thể. Bạn chạy cả ba trên mỗi phản hồi để có hồ sơ chất lượng đầy đủ. Bạn có thể thêm trọng tài về phong cách (có súc tích không?), giọng điệu (có chuyên nghiệp không?) hoặc xử lý từ chối (có nói “Tôi không biết” khi phù hợp?).

Thiết lập trọng tài trong LangFuse

LangFuse cho phép bạn cấu hình LLM trọng tài qua UI hoặc API. Quy trình thiết lập:

1. Định nghĩa prompt cho trọng tài: Viết hướng dẫn chấm điểm rõ ràng với tiêu chí cụ thể cho từng mức điểm.
2. Chọn mô hình trọng tài: Dùng GPT-4, Claude hoặc LLM khác. Mô hình mạnh hơn cho điểm chính xác hơn nhưng tốn chi phí hơn.
3. Cấu hình trọng tài trong LangFuse: Tạo mẫu chấm điểm để LangFuse tự động áp dụng cho các trace.
4. Kiểm thử trọng tài: Chạy trên vài ví dụ mà bạn biết điểm đúng. Điều chỉnh prompt nếu trọng tài quá khắt khe hoặc quá dễ dãi.
5. Áp dụng cho tập dữ liệu: Khi trọng tài hoạt động tốt, LangFuse sẽ tự động chấm tất cả trace của bạn.

Các trọng tài chạy bất đồng bộ, nên không làm chậm ứng dụng chính. Bạn kiểm tra điểm trên bảng điều khiển LangFuse sau khi kiểm thử hoàn tất.

Khi nào trọng tài hoạt động tốt

LLM trọng tài hoạt động tốt cho các tiêu chí chủ quan khó đo bằng mã, như giọng điệu, mức độ liên quan và phong cách. Chúng ít đáng tin hơn với sự thật khách quan. Nếu cần xác minh “2+2=4”, hãy viết kiểm tra tất định thay vì dùng trọng tài.

Với hệ thống H&Đ của chúng ta, trọng tài phù hợp cho độ liên quan và mức độ bám ngữ cảnh, nhưng bạn có thể kết hợp kiểm tra tất định cho yêu cầu như “độ dài câu trả lời dưới 100 từ”.

Các hạn chế cần lưu ý

LLM trọng tài không hoàn hảo. Chúng có thể bất đồng, thiên vị một số kiểu trả lời và mắc lỗi khi cho điểm cao những câu trả lời nghe tự tin nhưng sai.

Bạn xử lý bằng cách kiểm thử trọng tài trên các ví dụ đã biết điểm đúng, dùng nhiều trọng tài và lấy trung bình điểm, và kiểm tra ngẫu nhiên để bắt lỗi của trọng tài.

Lưu ý triển khai: Quy trình đánh giá đầy đủ liên quan đến thiết lập tập dữ liệu, cấu hình trọng tài, chạy đánh giá theo lô và phân tích kết quả. Điều này cần nhiều thiết lập hơn phạm vi hướng dẫn này có thể bao quát mà vẫn thực tiễn. Tài liệu LLM-as-a-judge cung cấp chi tiết triển khai đầy đủ, gồm ví dụ mã và thực tiễn tốt. Với các phương pháp chấm điểm tùy chỉnh ngoài trọng tài LLM, xem hướng dẫn custom scores.

Quy trình phác thảo ở đây cho bạn tư duy đánh giá. Khi bạn đã có trace và prompt được quản lý trong LangFuse, việc bổ sung đánh giá có hệ thống trở nên tự nhiên. Bạn xây dựng tập kiểm thử dần dần, bắt đầu với trọng tài đơn giản và tinh chỉnh khi hiểu các chỉ số quan trọng với ứng dụng của mình.

Đọc thêm: LangFuse cũng hỗ trợ quản lý tập dữ liệu để tổ chức ca kiểm thử, hàm chấm điểm tùy chỉnh cho kiểm tra tất định và đánh giá liên tục chạy tự động trên lưu lượng sản xuất. Những tính năng này giúp bạn duy trì chất lượng khi hệ thống mở rộng. Xem tổng quan đánh giá để có cái nhìn đầy đủ.

Kết luận

Bạn đã xây dựng hệ thống Hỏi-Đáp tài liệu và học cách ba trụ cột của LangFuse phối hợp. Observability cho bạn thấy điều gì xảy ra khi LLM chạy. Bạn thấy mọi trace, mọi chi phí, mọi token. Quản lý prompt đưa prompt ra khỏi mã và vào hệ thống có kiểm soát phiên bản nơi bạn có thể lặp mà không cần triển khai. Đánh giá cung cấp cách đo chất lượng có hệ thống thay vì đoán mò. Những tính năng này liên kết với nhau: trace nuôi tập dữ liệu đánh giá, phiên bản prompt liên kết với chỉ số hiệu năng, và toàn bộ hệ thống giúp bạn hiểu thay đổi làm mọi thứ tốt hơn hay tệ đi.

Hãy bắt đầu nhỏ với dự án của chính bạn. Chọn một tính năng. Có thể thêm tracing để xem ứng dụng tốn tiền ở đâu, hoặc chuyển một prompt hardcode vào hệ thống quản lý của LangFuse. Các mẫu bạn học được từ ví dụ H&Đ đơn giản của chúng tôi có thể mở rộng cho pipeline RAG phức tạp, hệ thống đa tác tử và ứng dụng sản xuất phục vụ hàng nghìn người dùng. Xem tài liệu LangFuse để tìm hiểu sâu hơn về từng tính năng, hoặc thử notebook ví dụ trình bày triển khai thực tế. Lần tới khi bạn xây dựng với LLM, bạn sẽ có công cụ để nhìn thấy điều gì đang xảy ra, kiểm soát những gì thay đổi và đo lường điều quan trọng.