Tutorial LangFuse: Platform Rekayasa LLM untuk Monitoring dan Evaluasi

Membangun aplikasi LLM bisa cepat menjadi berantakan. Anda mulai menebak-nebak biaya. Debug kegagalan makin sulit saat Anda tidak bisa melihat apa yang terjadi. Prompt tersebar di seluruh basis kode Anda. LangFuse mengatasinya dengan platform yang melacak semuanya, mengelola prompt, dan mengukur kualitas.

Dalam tutorial ini, Anda akan membangun alat tanya jawab dokumen dan melihat bagaimana LangFuse mengatur pengembangan Anda. Anda akan belajar menelusuri panggilan LLM untuk debugging, mengelola prompt dengan kontrol versi, dan mengeksplorasi pendekatan evaluasi.

Apa itu LangFuse?

LangFuse adalah platform open-source yang membantu tim membangun aplikasi LLM yang lebih baik. Saat Anda fokus membangun fitur, LangFuse menangani monitoring, pengujian, dan debugging.

Platform ini mencakup tiga area utama:

1. Observability: Lihat apa yang terjadi saat LLM Anda berjalan. Lacak biaya, temukan error, dan pahami bagaimana pengguna berinteraksi dengan aplikasi Anda. Tidak perlu lagi menebak mengapa sesuatu rusak atau berapa banyak OpenAI menagih Anda bulan lalu.
2. Manajemen prompt: Simpan dan versikan prompt Anda di satu tempat alih-alih tersebar di basis kode. Tim Anda dapat menguji versi berbeda tanpa menyentuh kode produksi.
3. Evaluasi: Ukur seberapa baik performa LLM Anda. Siapkan pengujian otomatis yang memeriksa apakah respons masuk akal, tetap pada topik, atau memenuhi standar kualitas.

Kapan Anda sebaiknya menggunakan LangFuse?

Anda akan memerlukan LangFuse ketika aplikasi LLM Anda melampaui eksperimen sederhana. Berikut situasi saat ini menjadi berharga:

• Banyak anggota tim mengerjakan prompt, dan Anda memerlukan kontrol versi
• Aplikasi produksi di mana Anda perlu melacak biaya dan memantau performa
• Alur kerja kompleks seperti sistem RAG, pengaturan multi-agen, atau rantai percakapan
• Kekhawatiran kualitas di mana Anda memerlukan pengujian sistematis alih-alih pemeriksaan manual sesekali

Jika Anda membangun prototipe cepat atau proyek pribadi, Anda mungkin belum membutuhkannya. Namun begitu aplikasi Anda menangani pengguna nyata atau tim Anda tumbuh lebih dari satu orang, LangFuse menjadi berguna.

Adopsi dan integrasi

LangFuse bekerja dengan tumpukan AI yang sudah Anda gunakan. Ia terintegrasi dengan kerangka kerja utama seperti LangChain, LlamaIndex, AutoGen, dan CrewAI. Anda dapat menggunakannya dengan penyedia model apa pun — OpenAI, Anthropic, Google Gemini, Mistral, atau model Hugging Face semuanya berfungsi langsung.

Platform ini menawarkan SDK native untuk Python dan JavaScript, plus dukungan OpenTelemetry untuk penyiapan kustom. Baik Anda menggunakan pembuat agen no-code atau kerangka multi-agen yang kompleks, LangFuse terpasang tanpa mengubah arsitektur inti Anda.

Perusahaan seperti Samsara, Twilio, dan Khan Academy menggunakannya di produksi, dan platform ini memenuhi standar keamanan enterprise. Proyek ini memiliki lebih dari 16.500 bintang GitHub dengan dukungan Y Combinator. Anda dapat menggunakan versi hosted atau menjalankannya di infrastruktur Anda sendiri.

Sekarang setelah Anda memahami apa yang dilakukan LangFuse dan kapan ia membantu, mari kita bangun sesuatu dengannya. Seperti yang dijanjikan, kita akan membuat alat tanya jawab dokumen sederhana yang menunjukkan ketiga fitur tersebut dalam aksi.

Prasyarat

Anda memerlukan sedikit pengalaman Python dan LLM sebelum menyelami LangFuse.

Wajib:

• Python 3.8+ dan pengetahuan dasar API
• Pengalaman API OpenAI (kita akan menggunakan GPT-4)
• Dasar-dasar LangChain — prompt, chain, dan konsep inti

Akan lebih baik jika ada:

• Pemahaman tentang embedding dan pola retrieval
• Pengalaman dengan rekayasa prompt

Penyiapan:

• Kunci API OpenAI
• Pengelola paket Python (uv atau pip)
• Kita akan membuat akun LangFuse gratis bersama

Baru dalam pengembangan AI? Mulailah dengan panduan lengkap belajar AI kami terlebih dahulu.

Untuk konteks tentang posisi LangFuse dalam ekosistem yang lebih luas, lihat ikhtisar alat LLMOps kami.

Sekarang mari kita membangun sesuatu. Kita akan mulai dengan fungsi tanya jawab dokumen sederhana dan melihat bagaimana LangFuse melacak apa yang terjadi saat Anda menjalankannya. Contoh dasar ini akan menunjukkan ketiga fitur utama — observability, manajemen prompt, dan evaluasi — dengan cara yang dapat diskalakan ke proyek yang lebih kompleks.

Membangun Alat Tanya Jawab Dokumen dengan LangFuse

Anda akan membangun sistem tanya jawab dokumen sederhana yang menjawab pertanyaan dari PDF. Ini memberi Anda sesuatu yang nyata untuk ditelusuri, dikelola, dan dievaluasi. Walaupun kita menjaga contoh ini sederhana, pola yang sama bekerja untuk sistem RAG yang kompleks dan alur kerja multi-agen.

Menyiapkan lingkungan

Pertama, buat direktori untuk proyek dan instal paket yang Anda butuhkan:

mkdir langfuse-qa-demo
cd langfuse-qa-demo
uv add langfuse langchain langchain-openai langchain-community pypdf python-dotenvDidukung oleh

Daftar untuk akun LangFuse Cloud gratis di langfuse.com. Setelah masuk, buat organisasi dan proyek baru. Anda akan melihat layar dengan kunci API Anda:

Salin Public Key dan Secret Key Anda. Anda juga memerlukan kunci API OpenAI dari platform.openai.com.

Sekarang buat file .env di direktori proyek Anda:

OPENAI_API_KEY=your_openai_key_here
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.comDidukung oleh

Jika Anda lebih suka menjalankan LangFuse di infrastruktur Anda sendiri, Anda dapat menggunakan Docker Compose untuk pengujian lokal. Panduan self-hosting membahas penyiapan PostgreSQL, ClickHouse, dan layanan LangFuse. Untuk deployment produksi, gunakan Kubernetes atau template Terraform khusus cloud.

Membangun rantai tanya jawab dokumen di LangChain

Anda akan membangun rantai retrieval yang memuat PDF, membaginya menjadi potongan, menyimpannya di basis data vektor, dan menjawab pertanyaan berdasarkan konteks yang diambil.

Buat file bernama 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()Didukung oleh

Ini mengimpor semua yang Anda perlukan. Panggilan load_dotenv() memuat kunci API Anda dari file .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)Didukung oleh

Di sini, kita memuat dokumen ai-security-landscape.pdf, salah satu whitepaper yang ditulis oleh Amazon Web Services. Untuk menjalankan contoh ini, Anda perlu mengunduh file sendiri dan menambahkannya ke direktori kerja Anda dengan nama yang benar.

PyPDFLoader membaca PDF dan RecursiveCharacterTextSplitter memecahnya menjadi potongan 1.000 karakter dengan tumpang tindih 200 karakter. Tumpang tindih membantu menjaga konteks di batas potongan.

Selanjutnya, buat vector store:

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

InMemoryVectorStore menyimpan embedding dokumen di memori. Di produksi, Anda akan menggunakan Pinecone, Weaviate, atau basis data vektor lainnya.

Sekarang bangun rantai QA:

# 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)Didukung oleh

create_stuff_documents_chain mengambil dokumen yang diambil dan memasukkannya ke konteks prompt. create_retrieval_chain menggabungkan retrieval dan penjawaban dalam satu chain.

Dengan chain siap, mari hubungkan ke LangFuse untuk tracing.

Menelusuri Panggilan Pertama Anda dengan LangFuse

Tambahkan handler callback LangFuse ke skrip:

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"])Didukung oleh

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.comDidukung oleh

Saat Anda menjalankannya, LangFuse menangkap jejak eksekusi lengkap. Buka dasbor LangFuse Anda, dan Anda akan melihatnya diperbarui dengan detail baru:

Perhatikan bahwa meskipun kita menggunakan contoh sederhana di sini, LangFuse bekerja dengan pipeline RAG yang kompleks yang menangani banyak tipe dokumen, menggunakan re-ranking, atau menjalankan banyak strategi retrieval secara paralel.

Dengan sistem tanya jawab Anda berjalan dan tracing LangFuse diterapkan, Anda siap memahami apa yang ditangkap LangFuse dan bagaimana menggunakan informasi itu untuk meningkatkan aplikasi Anda.

Observability di LangFuse

Anda baru saja mengirim trace ke LangFuse. Sekarang, mari pahami apa yang Anda dapatkan dan mengapa itu penting.

Mengapa observability LLM penting

Logging tradisional tidak bekerja baik untuk aplikasi LLM. Anda bisa mencatat bahwa sebuah fungsi berjalan, tetapi Anda tidak bisa melihat apa yang sebenarnya dilakukan model terhadap input pengguna. Apakah ia mengambil dokumen yang tepat? Apakah prompt diformat dengan benar? Langkah mana yang memakan waktu lima detik?

Observability LLM melacak seluruh jalur eksekusi. Anda melihat setiap input, output, dan langkah perantara. Saat pengguna melaporkan jawaban yang salah, Anda membuka trace mereka dan melihat persis apa yang terjadi. Anda tidak menebak. Anda tahu.

Ini semakin penting seiring aplikasi Anda menjadi kompleks. Rantai tanya jawab sederhana memiliki 4–5 langkah. Sistem RAG produksi memiliki pemuat dokumen, strategi pemotongan, beberapa retriever, re-ranker, dan langkah generasi. Tanpa observability, debugging menjadi mustahil. Dengannya, Anda dapat menemukan masalah dengan tepat.

Memahami trace dan sesi

Buka dasbor LangFuse Anda dan klik "Tracing" di bilah sisi kiri. Anda akan melihat trace pertama Anda tercantum dalam tabel.

Tabel menunjukkan kapan trace berjalan, apa namanya (retrieval_chain), dan apa yang masuk serta keluar. Setiap baris mewakili eksekusi lengkap dari rantai tanya jawab Anda.

Klik trace untuk melihat apa yang terjadi di dalamnya. Anda akan mendapatkan rincian terperinci.

Panel kiri menampilkan pohon eksekusi Anda. LangFuse melacak setiap langkah di chain Anda. Akar retrieval_chain memakan waktu total 4,75 detik. Di bawahnya, Anda melihat setiap operasi yang berjalan: pengambilan dokumen (retrieve_documents), pencarian vektor (VectorStoreRetriever), dan generasi jawaban (stuff_documents_chain). Setiap langkah menampilkan waktu eksekusinya.

Hierarki ini memberi tahu Anda di mana chain Anda menghabiskan waktu. Jika aplikasi Anda berjalan lambat, Anda akan tahu apakah itu pada pencarian embedding, pencarian vektor, atau panggilan LLM.

Panel kanan menampilkan data trace. Di bagian atas, Anda mendapatkan metrik yang penting: latensi (4,75 dtk), biaya (~$0,016), dan token yang digunakan (426 input, 55 output). Di bawahnya, Anda melihat input dan output sebenarnya. Bagian context menampilkan empat potongan dokumen yang diambil retriever Anda dari vector store.

Di bagian bawah, diagram alur memetakan bagaimana chain Anda menghubungkan operasinya. Ini membantu saat Anda men-debug chain kompleks dengan beberapa cabang.

Sekarang mari bicara tentang sesi. Trace menangkap satu siklus tanya-jawab. Namun aplikasi nyata memiliki percakapan. Seorang pengguna bisa menanyakan tiga pertanyaan terkait tentang risiko keamanan. Anda ingin mengelompokkan trace tersebut.

Itulah fungsi sesi. Mereka mengelompokkan banyak trace ke dalam satu utas percakapan. Saat pengguna melaporkan bug, Anda dapat membuka seluruh sesi mereka dan melihat setiap pertanyaan yang mereka ajukan dan setiap jawaban yang mereka dapatkan.

Mari lihat ini dalam aksi. Pertama, buat file pembantu bernama build_chain.py yang membungkus logika pembuatan chain Anda:

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_chainDidukung oleh

Ini membungkus semuanya dalam fungsi yang dapat Anda impor. Sekarang buat 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")Didukung oleh

Kolom metadata dengan langfuse_session_id menandai trace ini dengan ID sesi. Jalankan ini dan Anda akan melihat:

Q1: The main security risks discussed are context window overflow, agent mismanagement, and indirect prompt injections.Didukung oleh

Sekarang tambahkan pertanyaan lanjutan dengan ID sesi yang sama:

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")Didukung oleh

Pertanyaan kedua ini termasuk dalam percakapan yang sama, jadi kembali menggunakan conversation-001. Anda akan melihat respons yang lebih panjang:

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.
....Didukung oleh

Sekarang simulasikan pengguna kedua dengan pertanyaan berbeda. Tambahkan ini ke skrip Anda:

# 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")Didukung oleh

Kedua pertanyaan ini menggunakan conversation-002. Jalankan skrip lengkapnya:

uv run python sessions_demo.pyDidukung oleh

Dua keluaran terakhir akan seperti ini:

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.Didukung oleh

Sekarang buka dasbor LangFuse Anda dan klik "Sessions" di bilah sisi kiri. Anda akan melihat kedua percakapan tersebut tercantum:

Muncul dua sesi: conversation-002 (~4 detik durasi) dan conversation-001 (~14 detik durasi). LangFuse mengelompokkan trace Anda berdasarkan ID sesi.

Klik conversation-001 untuk melihat percakapan lengkap:

Anda melihat kedua trace secara berurutan: Pertanyaan 1 tentang risiko keamanan, dan Pertanyaan 2 tentang mitigasi. Sesi menampilkan total biaya ($0,05121 untuk kedua trace digabung) dan durasi (total 14 detik). Setiap trace muncul dengan input, output, dan konteks yang diambil.

Tampilan sesi ini menunjukkan persis apa yang dialami pengguna selama interaksi mereka. Jika mereka melaporkan masalah, Anda tidak perlu mencari-cari di antara trace individual. Anda membuka sesi mereka dan melihat alur percakapan lengkap.

Melacak pengguna

Sejauh ini, Anda telah melacak sesi, tetapi bagaimana dengan pengguna individual? Aplikasi LLM nyata perlu mengetahui pengguna mana yang membuat permintaan mana. Saat seseorang mendaftar, Anda menghasilkan ID unik untuk mereka. Lalu Anda menyematkan ID itu ke setiap panggilan LLM yang mereka lakukan.

LangFuse memungkinkan Anda mengelompokkan trace berdasarkan ID pengguna di atas pengelompokan sesi. Ini memberikan cara lain untuk mengatur data observability Anda.

Begini cara Anda menambahkan pelacakan pengguna. Buat 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']}")Didukung oleh

Kolom langfuse_user_id menandai trace ini dengan ID pengguna. Jalankan skrip:

uv run python user_tracking.pyDidukung oleh

Anda akan melihat:

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.
......Didukung oleh

Sekarang buka dasbor LangFuse Anda. Klik "Users" di bilah sisi kiri, dan Anda akan melihat user-12345 tercantum. Klik pengguna tersebut untuk melihat semua trace mereka di berbagai sesi.

Tampilan pengguna ini membantu Anda menjawab pertanyaan seperti “Berapa biaya pengguna X untuk kita bulan ini?” atau “Pertanyaan apa yang terus diajukan pengguna Y?” Anda dapat melacak perilaku pengguna individual dan men-debug masalah spesifik pengguna tertentu.

Manajemen Prompt di LangFuse

Sistem tanya jawab Anda memiliki masalah. Prompt tersembunyi di dalam kode Anda. Untuk mengubah cara sistem merespons, Anda perlu mengedit qa_chain.py, menguji secara lokal, dan redeploy. Jika rekan ingin mencoba pendekatan berbeda, mereka perlu memahami struktur kode Anda dan membuat branch baru. Anda tidak bisa membandingkan versi prompt berdampingan atau rollback ke versi minggu lalu tanpa menggali riwayat git.

Manajemen prompt menyelesaikan ini dengan menyimpan prompt di luar kode Anda. Anda mengeditnya di UI, versi dibuat otomatis, dan mengambilnya saat runtime. Kode Anda tetap sama sementara prompt Anda membaik.

Masalah kolaborasi prompt

Lihat prompt di rantai tanya jawab Anda:

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}"),
])Didukung oleh

Ini berfungsi untuk proyek solo. Namun saat Anda bekerja dengan tim atau berjalan di produksi, prompt yang di-hardcode menimbulkan masalah:

• Friction deployment: Setiap perubahan prompt memerlukan deployment kode. Anda tidak bisa melakukan A/B test berbagai prompt tanpa mengubah kode aplikasi. Jika Anda ingin mencoba “Bersikap ringkas dan faktual” alih-alih “Tetap ringkas,” Anda perlu commit, push, dan redeploy.
• Tidak ada kontrol versi: Git melacak perubahan kode, tetapi tidak menunjukkan versi prompt mana yang berkinerja lebih baik di produksi. Anda tidak bisa melihat metrik untuk “prompt v1” vs “prompt v2” atau cepat rollback ke versi sebelumnya tanpa deploy kode.
• Bottleneck tim: Anggota tim non-teknis tidak bisa beriterasi pada prompt. Manajer produk Anda punya ide untuk frasa yang lebih baik, tetapi mereka perlu meminta engineer untuk melakukan perubahan. Ini memperlambat eksperimen.
• Kesulitan pengujian: Membandingkan variasi prompt berarti menjalankan beberapa versi kode Anda. Anda tidak bisa menguji respons ringkas versus detail secara berdampingan tanpa pekerjaan manual.

Manajemen prompt LangFuse mengatasi masalah ini dengan memperlakukan prompt sebagai data, bukan kode.

Membuat dan memversi prompt

LangFuse menyimpan prompt Anda di lokasi terpusat dengan versi otomatis. Anda dapat membuat prompt melalui UI atau via SDK.

Membuat prompt di UI

Buka dasbor LangFuse Anda dan klik "Prompts" di bilah sisi kiri. Klik "New Prompt" untuk membuatnya.

Anda akan melihat formulir tempat Anda dapat:

• Memberi nama prompt Anda (gunakan document-qa-prompt)
• Memilih tipe (text atau chat)
• Menulis template prompt Anda dengan variabel menggunakan sintaks {{variable}}
• Mengatur konfigurasi seperti model dan temperature
• Menambahkan label untuk menandai versi (seperti production atau staging)

Untuk sistem tanya jawab kita, buat prompt chat dengan dua pesan:

Pesan sistem:

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}}Didukung oleh

Pesan pengguna:

{{input}}Didukung oleh

LangFuse akan mendeteksi variabel {{context}} dan {{input}} secara otomatis.

Selanjutnya, atur konfigurasi ke:

{
 "model": "gpt-4",
 "temperature": 0.0
}Didukung oleh

Tambahkan label production untuk menandai ini sebagai versi produksi Anda.

Setelah Anda menyimpan, LangFuse membuat versi 1 dari prompt Anda. Setiap kali Anda mengedit dan menyimpan, ia membuat versi baru. Versi lama tetap tersedia.

Membuat prompt via SDK

Anda juga bisa membuat prompt menggunakan 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"]
)Didukung oleh

Ini membuat prompt yang sama secara programatik. Jika Anda memanggil create_prompt() lagi dengan nama yang sama, LangFuse menambahkan versi baru alih-alih menimpa.

Kontrol versi dengan label

LangFuse melacak setiap perubahan prompt dengan nomor versi (v1, v2, v3). Anda juga dapat menetapkan label ke versi. Label membantu Anda mengelola deployment:

• production - Versi yang digunakan aplikasi produksi Anda
• staging - Versi di lingkungan staging Anda
• latest - Secara otomatis menunjuk ke versi terbaru

Saat Anda memperbaiki prompt, Anda membuat versi baru. Uji terlebih dahulu di staging dengan memberi label staging. Setelah berfungsi baik, pindahkan label production ke versi baru. Aplikasi produksi Anda otomatis mengambil perubahan pada pengambilan prompt berikutnya.

Menguji variasi di playground

UI LangFuse menyertakan playground tempat Anda dapat menguji prompt sebelum menggunakannya dalam kode. Anda bisa:

• Mencoba berbagai nilai variabel
• Membandingkan beberapa versi berdampingan
• Melihat bagaimana perubahan mempengaruhi output
• Berbagi hasil uji dengan tim Anda

Ini memungkinkan anggota tim non-teknis bereksperimen dengan perumusan tanpa menyentuh kode.

Mengintegrasikan prompt terkelola dalam kode

Berikut cara menggunakan prompt yang dikelola LangFuse dalam aplikasi Anda. Alur kerja ini menjaga kode Anda stabil sementara prompt Anda berevolusi.

Langkah 1: Ambil prompt

Dalam kode aplikasi Anda, ambil prompt dari LangFuse alih-alih meng-hardcode-nya:

from langfuse import Langfuse

langfuse = Langfuse()

# Get the production version
prompt = langfuse.get_prompt("document-qa-prompt", type="chat")Didukung oleh

Ini mengambil versi berlabel production. LangFuse melakukan cache prompt di sisi klien, jadi tidak ada dampak latensi pada panggilan LLM Anda.

Anda juga bisa mengambil versi atau label tertentu:

# 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")Didukung oleh

Langkah 2: Kompilasi prompt dengan variabel

Prompt yang diambil adalah template dengan {{variables}}. Kompilasi dengan mengganti variabel dengan nilai sebenarnya:

compiled_messages = prompt.compile(
   context="Retrieved document context goes here",
   input="What are the main security risks?"
)Didukung oleh

Ini mengembalikan daftar pesan chat yang siap dikirim ke LLM Anda:

[
   {
       "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?"
   }
]Didukung oleh

Langkah 3: Gunakan prompt terkompilasi dengan LLM Anda

Teruskan pesan terkompilasi ke panggilan LLM Anda. Kode pastinya bergantung pada apakah Anda menggunakan LangChain, langsung OpenAI SDK, atau kerangka lain.

Langkah 4: Tautkan prompt ke trace

Saat Anda melakukan panggilan LLM dengan prompt yang dikelola LangFuse, tautkan ke trace. Ini memungkinkan Anda melihat versi prompt mana yang digunakan untuk setiap panggilan LLM dan melacak metrik berdasarkan versi prompt:

from langfuse.langchain import CallbackHandler

langfuse_handler = CallbackHandler()

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

Di dasbor LangFuse Anda, Anda akan melihat trace dikelompokkan berdasarkan nama dan versi prompt. Ini menunjukkan versi prompt mana yang lebih mahal, berjalan lebih lambat, atau menghasilkan hasil yang lebih baik.

Langkah 5: Beriterasi tanpa perubahan kode

Di sinilah manajemen prompt memberikan manfaat. Untuk memperbaiki prompt Anda:

1. Buka UI LangFuse
2. Edit prompt Anda (secara otomatis membuat versi baru)
3. Uji di playground
4. Beri label staging untuk pengujian di lingkungan staging
5. Pindahkan label production untuk deploy

Kode Anda tidak pernah berubah. Pada pemanggilan get_prompt() berikutnya, ia mengambil versi baru.

Langkah 6: Rollback jika diperlukan

Jika prompt baru berkinerja lebih buruk, rollback dengan memindahkan label production kembali ke versi sebelumnya. Tidak perlu deploy kode.

Alur kerja ini memisahkan rekayasa prompt dari rekayasa perangkat lunak. Tim Anda dapat cepat beriterasi pada prompt sementara kode aplikasi Anda tetap stabil.

Bacaan Lanjutan: LangFuse juga mendukung A/B testing untuk membagi trafik secara otomatis antar versi prompt, webhook yang memberi tahu sistem Anda ketika prompt berubah, dan fitur kolaborasi tim seperti komentar dan alur persetujuan. Fitur lanjutan ini membantu tim besar mengelola prompt dalam skala. Lihat dokumen manajemen prompt untuk detail.

Evaluasi di LangFuse

Anda telah membangun sistem tanya jawab, menambahkan observability, dan menyiapkan manajemen prompt. Namun bagaimana Anda tahu apakah jawaban Anda bagus? Saat ini, Anda mungkin menguji secara manual. Anda mengajukan pertanyaan, membaca respons, dan memutuskan apakah masuk akal. Ini berfungsi untuk beberapa contoh, tetapi tidak dapat diskalakan.

Apa yang terjadi saat Anda mengubah prompt? Anda perlu menguji ulang semuanya. Bagaimana dengan kasus tepi? Anda tidak bisa mengingat setiap pertanyaan yang pernah diuji sebelumnya. Dan saat Anda menerapkan ke produksi, Anda tidak punya cara untuk mengukur apakah versi 2 dari prompt Anda berkinerja lebih baik daripada versi 1.

Evaluasi memperbaiki ini dengan secara sistematis mengukur performa LLM Anda. LangFuse memberi Anda alat untuk memberi skor respons secara otomatis, membandingkan versi prompt dengan metrik nyata, dan menangkap masalah kualitas sebelum dilihat pengguna.

Pendekatan evaluasi LLM yang sistematis

Pengujian manual memberi tahu Anda apakah satu jawaban spesifik terlihat bagus. Evaluasi sistematis memberi tahu Anda apakah seluruh sistem Anda bekerja baik di ratusan atau ribuan contoh.

Berikut cara evaluasi sistematis bekerja di LangFuse:

1. Bangun dataset uji: Kumpulkan 20–50 pertanyaan yang mewakili penggunaan nyata, termasuk kasus tepi di mana jawabannya tidak ada di dokumen.
2. Pilih metode penilaian: Putuskan dimensi kualitas mana yang penting untuk sistem tanya jawab Anda (kita bahas di bagian berikutnya).
3. Jalankan sistem Anda terhadap dataset: Proses setiap pertanyaan dan catat hasilnya ke LangFuse sebagai trace.
4. Beri skor respons: Terapkan metode penilaian Anda ke setiap respons secara otomatis.
5. Analisis hasil: LangFuse mengagregasi skor di seluruh set uji Anda dan menunjukkan contoh mana yang gagal.
6. Iterasi dan bandingkan: Ubah prompt Anda, jalankan ulang set uji, dan bandingkan metrik untuk melihat apakah Anda membaik.

Proses ini menggantikan “Menurut saya prompt ini lebih baik” dengan “prompt ini mendapat skor 0,85 pada relevansi vs. 0,72 untuk versi lama.”

Untuk panduan lengkap tentang pendekatan evaluasi dan cara menerapkannya di LangFuse, lihat dokumen ikhtisar evaluasi.

Memahami Evaluasi LLM-sebagai-Juri

Anda perlu memberi skor ratusan respons. Melakukannya secara manual memakan waktu berjam-jam. LLM-sebagai-juri mengotomatiskannya dengan menggunakan LLM lain untuk menilai output LLM utama Anda.

Cara kerjanya

Anda memberi LLM juri tiga hal: pertanyaan asli, jawaban dari sistem tanya jawab Anda, dan kriteria penilaian. Juri membaca jawaban dan menetapkan skor.

Untuk sistem tanya jawab, Anda peduli pada berbagai dimensi kualitas. Berikut tiga juri yang mungkin Anda buat:

Juri ketepatan: “Nilai apakah jawaban ini dengan benar mencerminkan informasi dalam konteks yang disediakan. Skor 1 jika sepenuhnya benar, 0,5 jika sebagian benar, 0 jika salah atau berhalusinasi.”

Ini menangkap jawaban yang bertentangan dengan dokumen Anda atau mengada-ada.

Juri relevansi: “Nilai apakah jawaban ini secara langsung menjawab pertanyaan yang diajukan. Skor 1 jika sangat relevan, 0,5 jika agak relevan, 0 jika di luar topik.”

Ini memastikan sistem Anda tetap pada topik alih-alih memberikan informasi akurat namun tidak relevan.

Juri keterlandasan: “Nilai apakah jawaban ini hanya didasarkan pada konteks yang disediakan. Skor 1 jika sepenuhnya berlandaskan konteks, 0,5 jika sebagian, 0 jika menyertakan informasi yang tidak ada dalam konteks.”

Ini mencegah halusinasi di mana LLM menambahkan fakta yang tidak ada di dokumen Anda.

Setiap juri melihat dimensi kualitas tertentu. Anda menjalankan ketiganya pada setiap respons dan mendapatkan profil kualitas lengkap. Anda bisa menambahkan lebih banyak juri untuk gaya (apakah ringkas?), nada (apakah profesional?), atau penanganan penolakan (apakah mengatakan “Saya tidak tahu” saat tepat?).

Menyiapkan juri di LangFuse

LangFuse memungkinkan Anda mengonfigurasi juri LLM melalui UI atau API. Proses penyiapannya:

1. Definisikan prompt juri Anda: Tulis instruksi penilaian yang jelas dengan kriteria spesifik untuk setiap tingkat skor.
2. Pilih model juri: Gunakan GPT-4, Claude, atau LLM lain. Model yang lebih kuat memberi skor lebih akurat tetapi lebih mahal.
3. Konfigurasikan juri di LangFuse: Buat template penilaian yang akan diterapkan LangFuse ke trace secara otomatis.
4. Uji juri Anda: Jalankan pada beberapa contoh di mana Anda tahu skor yang benar. Sesuaikan prompt jika juri terlalu keras atau terlalu lunak.
5. Terapkan ke dataset Anda: LangFuse memberi skor seluruh trace Anda secara otomatis setelah juri bekerja dengan baik.

Para juri berjalan secara asinkron, jadi mereka tidak memperlambat aplikasi utama Anda. Anda memeriksa skor di dasbor LangFuse setelah pengujian selesai.

Kapan juri bekerja dengan baik

Juri LLM bekerja paling baik untuk kriteria subjektif yang sulit diukur dengan kode. Hal-hal seperti nada, relevansi, dan gaya. Mereka kurang andal untuk fakta objektif. Jika Anda perlu memverifikasi bahwa “2+2=4,” tulislah pemeriksaan deterministik alih-alih menggunakan juri.

Untuk sistem tanya jawab kita, juri bekerja baik untuk relevansi dan keterlandasan, tetapi Anda dapat menggabungkannya dengan pemeriksaan deterministik untuk hal-hal seperti “panjang jawaban di bawah 100 kata.”

Batasan yang perlu dipertimbangkan

Juri LLM tidak sempurna. Mereka bisa saling tidak setuju, memiliki bias terhadap gaya jawaban tertentu, dan membuat kesalahan dengan memberi skor tinggi pada jawaban yang terdengar meyakinkan tetapi salah.

Anda menanganinya dengan menguji juri pada contoh di mana Anda tahu skor yang benar, menggunakan beberapa juri dan merata-ratakan skor mereka, serta melakukan spot-check untuk menangkap kesalahan juri.

Catatan implementasi: Alur kerja evaluasi lengkap melibatkan penyiapan dataset, konfigurasi juri, menjalankan evaluasi batch, dan menganalisis hasil. Ini memerlukan penyiapan lebih dari yang bisa kita bahas dalam tutorial ini sambil tetap praktis. Dokumentasi LLM-sebagai-juri menyediakan detail implementasi lengkap, termasuk contoh kode dan praktik terbaik. Untuk pendekatan penilaian kustom di luar juri LLM, lihat panduan skor kustom.

Alur kerja yang kita uraikan di sini menunjukkan pola pikir evaluasi. Setelah Anda memiliki trace dan prompt yang dikelola di LangFuse, menambahkan evaluasi sistematis menjadi alami. Anda membangun set uji secara bertahap, mulai dengan juri sederhana, dan menyempurnakan pendekatan saat Anda belajar metrik mana yang penting untuk aplikasi Anda.

Bacaan Lanjutan: LangFuse juga mendukung manajemen dataset untuk mengatur kasus uji, fungsi penilaian kustom untuk pemeriksaan deterministik, dan evaluasi berkelanjutan yang berjalan otomatis pada trafik produksi. Fitur-fitur ini membantu Anda menjaga kualitas saat sistem Anda menskalakan. Lihat ikhtisar evaluasi untuk gambaran lengkap.

Kesimpulan

Anda telah membangun sistem tanya jawab dokumen dan mempelajari bagaimana tiga pilar LangFuse bekerja bersama. Observability menunjukkan apa yang terjadi saat LLM Anda berjalan. Anda melihat setiap trace, setiap biaya, setiap token. Manajemen prompt memindahkan prompt Anda keluar dari kode dan ke sistem berkontrol versi di mana Anda dapat beriterasi tanpa deployment. Evaluasi memberi Anda cara untuk mengukur kualitas secara sistematis alih-alih menebak. Fitur-fitur ini saling terhubung: trace mengalir ke dataset evaluasi, versi prompt tertaut ke metrik performa, dan keseluruhan sistem membantu Anda memahami apakah perubahan membuat segalanya lebih baik atau lebih buruk.

Mulailah dari yang kecil dengan proyek Anda sendiri. Pilih satu fitur. Mungkin tambahkan tracing untuk melihat di mana aplikasi Anda menghabiskan uang, atau pindahkan satu prompt yang di-hardcode ke sistem manajemen LangFuse. Pola yang Anda pelajari dengan contoh tanya jawab sederhana kami dapat diskalakan ke pipeline RAG yang kompleks, sistem multi-agen, dan aplikasi produksi yang menangani ribuan pengguna. Lihat dokumentasi LangFuse untuk ulasan lebih mendalam tentang fitur spesifik, atau coba notebook contoh yang menunjukkan implementasi dunia nyata. Saat berikutnya Anda membangun dengan LLM, Anda akan memiliki alat untuk melihat apa yang terjadi, mengendalikan apa yang berubah, dan mengukur hal yang penting.