LangFuse Eğitimi: İzleme ve Değerlendirmeler için LLM Mühendislik Platformu

LLM uygulamaları geliştirmek kısa sürede karmaşıklaşır. Maliyetleri tahmin etmeye başlarsınız. Ne olduğunu göremediğinizde hataları ayıklamak zorlaşır. İstemler kod tabanınızın her yerine dağılır. LangFuse, her şeyi izleyen, istemleri yöneten ve kaliteyi ölçen bir platformla bunu çözer.

Bu eğitimde bir belge S&Ç aracı oluşturacak ve LangFuse’un geliştirme sürecinizi nasıl düzenlediğini göreceksiniz. Hata ayıklama için LLM çağrılarını izlemeyi, sürüm kontrolüyle istemleri yönetmeyi ve değerlendirme yaklaşımlarını keşfetmeyi öğreneceksiniz.

LangFuse Nedir?

LangFuse ekiplerin daha iyi LLM uygulamaları geliştirmesine yardımcı olan açık kaynaklı bir platformdur. Siz özellik geliştirmeye odaklanırken LangFuse izleme, test ve hata ayıklamayı üstlenir.

Platform üç ana alanı kapsar:

1. Gözlemlenebilirlik: LLM’iniz çalıştığında neler olduğunu görün. Maliyetleri izleyin, hataları tespit edin ve kullanıcıların uygulamanızla nasıl etkileşim kurduğunu anlayın. Bir şeyin neden bozulduğunu ya da geçen ay OpenAI’nin sizden ne kadar ücret aldığını artık tahmin etmeyeceksiniz.
2. İstem yönetimi: İstemlerinizi kod tabanına yaymak yerine tek bir yerde saklayın ve sürümlendirin. Ekibiniz üretim koduna dokunmadan farklı sürümleri test edebilir.
3. Değerlendirme: LLM’inizin ne kadar iyi performans gösterdiğini ölçün. Yanıtların mantıklı olup olmadığını, konu dışına çıkıp çıkmadığını veya kalite standartlarını karşılayıp karşılamadığını kontrol eden otomatik testler kurun.

LangFuse’u ne zaman kullanmalısınız?

LLM uygulamanız basit deneylerin ötesine geçtiğinde LangFuse’a ihtiyaç duyarsınız. İşte değerli hale geldiği durumlar:

• Birden fazla ekip üyesi istemler üzerinde çalışıyor ve sürüm kontrolüne ihtiyaç var
• Üretim uygulamaları için maliyetleri izleyip performansı takip etmeniz gerekiyor
• Karmaşık iş akışları (RAG sistemleri, çoklu ajan kurulumları veya konuşma zincirleri gibi)
• Kalite kaygıları ve manuel nokta kontrolleri yerine sistematik test ihtiyacı

Hızlı bir prototip veya kişisel bir proje geliştiriyorsanız muhtemelen henüz gerek yok. Ancak uygulamanız gerçek kullanıcıları ele almaya başladığında veya ekibiniz bir kişiyi aştığında LangFuse faydalı hale gelir.

Benimseme ve entegrasyon

LangFuse mevcut yapay zeka yığınınızla çalışır. LangChain, LlamaIndex, AutoGen ve CrewAI gibi büyük çerçevelerle entegre olur. Her model sağlayıcıyla kullanılabilir — OpenAI, Anthropic, Google Gemini, Mistral veya Hugging Face modelleri kutudan çıkar çıkmaz çalışır.

Platform Python ve JavaScript için yerel SDK’lar ile özel kurulumlar için OpenTelemetry desteği sunar. İsterseniz kodsuz ajan oluşturucular, isterseniz karmaşık çoklu ajan çerçeveleri kullanın, LangFuse çekirdek mimarinizi değiştirmeden bağlanır.

Samsara, Twilio ve Khan Academy gibi şirketler üretimde kullanıyor ve kurumsal güvenlik standartlarını karşılıyor. Projenin 16.500’den fazla GitHub yıldızı ve Y Combinator desteği var. Barındırılan sürümü kullanabilir veya kendi altyapınızda çalıştırabilirsiniz.

Artık LangFuse’un ne yaptığını ve ne zaman yardımcı olduğunu anladığınıza göre, onunla bir şeyler inşa edelim. Söz verdiğimiz gibi, üç özelliği de uygulamada gösterecek basit bir belge S&Ç aracı oluşturacağız.

Önkoşullar

LangFuse’a dalmadan önce biraz Python ve LLM deneyimine ihtiyacınız var.

Olmalı:

• Python 3.8+ ve temel API bilgisi
• OpenAI API deneyimi (GPT-4 kullanacağız)
• LangChain temelleri — istemler, zincirler ve çekirdek kavramlar

Olursa iyi olur:

• Gömme (embedding) ve geri getirme (retrieval) desenlerine hâkimiyet
• İstem mühendisliği deneyimi

Kurulum:

• OpenAI API anahtarı
• Python paket yöneticisi (uv veya pip)
• Birlikte ücretsiz bir LangFuse hesabı oluşturacağız

Yapay zeka geliştirmeye yeni misiniz? Önce tam yapay zeka öğrenme rehberimize göz atın.

LangFuse’un daha geniş ekosistemde nereye oturduğuna dair bağlam için LLMOps araçları genel bakışımıza göz atın.

Şimdi bir şeyler inşa edelim. Basit bir belge S&Ç işleviyle başlayacağız ve bunu çalıştırdığınızda LangFuse’un neleri izlediğini göreceğiz. Bu temel örnek, daha karmaşık projelere ölçeklenen üç ana özelliği — gözlemlenebilirlik, istem yönetimi ve değerlendirmeyi — gösterecek.

LangFuse ile Belge S&Ç Aracı Oluşturma

Bir PDF’den gelen soruları yanıtlayan basit bir belge S&Ç sistemi oluşturacaksınız. Bu, izlemek, yönetmek ve değerlendirmek için gerçek bir şey sağlar. Örneği basit tutsak da aynı kalıplar karmaşık RAG sistemleri ve çoklu ajan iş akışları için de çalışır.

Ortamı hazırlama

Önce proje için bir dizin oluşturun ve gereken paketleri kurun:

mkdir langfuse-qa-demo
cd langfuse-qa-demo
uv add langfuse langchain langchain-openai langchain-community pypdf python-dotenvAltyapı:

Ücretsiz bir LangFuse Cloud hesabına langfuse.com adresinden kaydolun. Oturum açtıktan sonra yeni bir organizasyon ve proje oluşturun. API anahtarlarınızı göreceğiniz bir ekran açılacak:

Genel Anahtarınızı (Public Key) ve Gizli Anahtarınızı (Secret Key) kopyalayın. Ayrıca platform.openai.com adresinden OpenAI API anahtarınıza da ihtiyacınız olacak.

Şimdi proje dizininizde bir .env dosyası oluşturun:

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

LangFuse’u kendi altyapınızda çalıştırmayı tercih ederseniz yerel test için Docker Compose kullanabilirsiniz. Self-hosting rehberi PostgreSQL, ClickHouse ve LangFuse servislerinin kurulumunu adım adım anlatır. Üretim dağıtımları için Kubernetes veya buluta özgü Terraform şablonlarını kullanın.

LangChain’de belge S&Ç zinciri oluşturma

Bir PDF’yi yükleyen, parçalara bölen, bir vektör veritabanında saklayan ve getirilen bağlama göre soruları yanıtlayan bir geri getirme zinciri oluşturacaksınız.

qa_chain.py adlı bir dosya oluşturun:

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()Altyapı:

Bu, ihtiyacınız olan her şeyi içe aktarır. load_dotenv() çağrısı, API anahtarlarınızı .env dosyasından yükler.

# 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)Altyapı:

Burada, Amazon Web Services tarafından yazılan teknik raporlardan biri olan ai-security-landscape.pdf belgesini yüklüyoruz. Bu örneği çalıştırmak için dosyayı kendiniz indirmeniz ve doğru adla çalışma dizininize eklemeniz gerekecek.

PyPDFLoader PDF’yi okur ve RecursiveCharacterTextSplitter belgeyi 200 karakter örtüşmeli 1000 karakterlik parçalara böler. Örtüşme, parça sınırları arasında bağlamın korunmasına yardımcı olur.

Şimdi vektör deposunu oluşturun:

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

InMemoryVectorStore belge gömmelerini bellekte saklar. Üretimde Pinecone, Weaviate veya başka bir vektör veritabanı kullanırsınız.

Şimdi S&Ç zincirini oluşturun:

# 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)Altyapı:

create_stuff_documents_chain getirilen belgeleri istem bağlamına “doldurur”. create_retrieval_chain ise getirme ve yanıtlama adımlarını tek bir zincirde birleştirir.

Zincir hazır olduğuna göre, izleme için LangFuse’a bağlayalım.

LangFuse ile İlk Çağrınızı İzleme

Betik dosyasına bir LangFuse geri çağırım (callback) işleyicisi ekleyin:

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"])Altyapı:

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.comAltyapı:

Bunu çalıştırdığınızda LangFuse, yürütmenin tam izini yakalar. LangFuse panonuza gidin; yeni ayrıntılarla güncellendiğini göreceksiniz:

Burada basit bir örnek kullansak da LangFuse, birden çok belge türünü işleyen, yeniden sıralama (re-ranking) kullanan veya paralelde birden fazla getirme stratejisi çalıştıran karmaşık RAG boru hatlarıyla da çalışır.

S&Ç sisteminiz çalışırken ve LangFuse izleme etkinleştirilmişken, LangFuse’un neleri yakaladığını ve bu bilgiyi uygulamanızı geliştirmek için nasıl kullanacağınızı anlamaya hazırsınız.

LangFuse’ta Gözlemlenebilirlik

Az önce LangFuse’a bir iz (trace) gönderdiniz. Şimdi bunun size ne sağladığını ve neden önemli olduğunu anlayalım.

LLM gözlemlenebilirliği neden önemlidir

Geleneksel günlükleme (logging) LLM uygulamaları için iyi işlemez. Bir işlevin çalıştığını kaydedebilirsiniz ama modelinizin kullanıcının girdisiyle gerçekte ne yaptığını göremezsiniz. Doğru belgeler getirildi mi? İstem doğru biçimlendirildi mi? Hangi adım beş saniye sürdü?

LLM gözlemlenebilirliği, yürütmenin tüm yolunu izler. Her girdi, çıktı ve ara adımı görürsünüz. Bir kullanıcı yanlış yanıtlar bildirdiğinde izini açar ve tam olarak ne olduğunu izlersiniz. Tahmin etmezsiniz. Bilirsiniz.

Uygulamanız karmaşıklaştıkça bu daha da önem kazanır. Basit bir S&Ç zinciri 4–5 adıma sahiptir. Üretim RAG sistemleri belge yükleyiciler, parçalama stratejileri, birden çok getirici, yeniden sıralayıcılar ve üretim adımlarını içerir. Gözlemlenebilirlik olmadan hata ayıklama imkânsızlaşır. Onunla birlikte sorunları nokta atışı belirlersiniz.

İzleri (trace) ve oturumları anlama

LangFuse panonuzu açın ve sol kenar çubuğundan “Tracing”e tıklayın. İlk izinizi listede göreceksiniz.

Tablo, izin ne zaman çalıştığını, adını (retrieval_chain) ve içeri-dışarı gidenleri gösterir. Her satır S&Ç zincirinizin tam bir yürütmesini temsil eder.

Ne olduğuna bakmak için ize tıklayın. Ayrıntılı bir döküm alacaksınız.

Sol panel yürütme ağacınızı gösterir. LangFuse zincirinizdeki her adımı izledi. Kök retrieval_chain toplamda 4,75 saniye sürdü. Altında çalışan her işlemi görürsünüz: belge getirme (retrieve_documents), vektör araması (VectorStoreRetriever) ve yanıt üretimi (stuff_documents_chain). Her adım yürütme süresini gösterir.

Bu hiyerarşi zincirinizin zamanı nerede harcadığını gösterir. Uygulamanız yavaş çalışıyorsa, sorun gömme bakışında mı, vektör aramasında mı yoksa LLM çağrısında mı anlayabilirsiniz.

Sağ panel iz verilerini gösterir. Üstte önemli metrikler yer alır: gecikme (4,75 sn), maliyet (~$0,016) ve kullanılan tokenlar (426 girdi, 55 çıktı). Altında ise gerçek girdi ve çıktıyı görürsünüz. context bölümü, getiricinizin vektör deposundan çektiği dört belge parçasını gösterir.

Altta ise zincirinizin işlemleri nasıl bağladığını gösteren bir akış diyagramı vardır. Birden çok dala sahip karmaşık zincirleri hata ayıklarken yardımcı olur.

Şimdi oturumlardan bahsedelim. Bir iz, bir soru-cevap döngüsünü yakalar. Ama gerçek uygulamalarda konuşmalar vardır. Bir kullanıcı güvenlik riskleri hakkında birbiriyle ilişkili üç soru sorabilir. Bu izleri birlikte gruplamak istersiniz.

Oturumlar tam da bunu yapar. Birden çok izi tek bir konuşma dizisinde birleştirir. Bir kullanıcı hata bildirdiğinde, tüm oturumunu açıp sorduğu her soruyu ve aldığı her yanıtı görürsünüz.

Bunu uygulamada görelim. Önce zincir oluşturma mantığınızı saran build_chain.py adlı bir yardımcı dosya oluşturun:

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_chainAltyapı:

Bu, her şeyi içe alan bir işlev içine sarar. Şimdi sessions_demo.py oluşturun:

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")Altyapı:

metadata alanındaki langfuse_session_id bu izi bir oturum kimliğiyle etiketler. Bunu çalıştırdığınızda şunu göreceksiniz:

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

Şimdi aynı oturum kimliğiyle takip sorusu ekleyin:

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")Altyapı:

Bu ikinci soru aynı konuşmaya ait olduğu için yine conversation-001 kullanır. Daha uzun bir yanıt göreceksiniz:

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.
....Altyapı:

Şimdi farklı sorulara sahip ikinci bir kullanıcıyı simüle edin. Bunu betiğinize ekleyin:

# 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")Altyapı:

Bu iki soru conversation-002 kullanır. Tüm betiği çalıştırın:

uv run python sessions_demo.pyAltyapı:

Son iki çıktı şöyle olacaktır:

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.Altyapı:

Şimdi LangFuse panonuza gidin ve sol kenar çubuğundan “Sessions”a tıklayın. Her iki konuşmayı da listede göreceksiniz:

İki oturum görünür: conversation-002 (~4 saniye süre) ve conversation-001 (~14 saniye süre). LangFuse izlerinizi oturum kimliğine göre grupladı.

conversation-001’e tıklayıp tüm konuşmayı görün:

Her iki izi de sırayla görürsünüz: Soru 1 güvenlik riskleri hakkında ve Soru 2 azaltma stratejileri hakkında. Oturum, toplam maliyeti (iki iz birlikte $0,05121) ve toplam süreyi (14 saniye) gösterir. Her iz, girdi, çıktı ve getirilen bağlamıyla birlikte görünür.

Bu oturum görünümü, bir kullanıcının etkileşimi sırasında tam olarak ne yaşadığını gösterir. Bir sorun bildirirlerse tek tek izlerde arama yapmanıza gerek yoktur. Oturumlarını açar ve tüm konuşma akışını görürsünüz.

Kullanıcıları izleme

Şimdiye kadar oturumları izlediniz, peki ya bireysel kullanıcılar? Gerçek LLM uygulamalarında, hangi isteği hangi kullanıcının yaptığını bilmek gerekir. Biri kaydolduğunda onun için benzersiz bir kimlik oluşturursunuz. Sonra yaptıkları her LLM çağrısına bu kimliği eklersiniz.

LangFuse, oturum gruplandırmasına ek olarak izleri kullanıcı kimliğine göre gruplamanıza olanak tanır. Bu da gözlemlenebilirlik verilerinizi düzenlemenin başka bir yolunu sunar.

İşte kullanıcı takibini nasıl eklersiniz. user_tracking.py oluşturun:

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']}")Altyapı:

langfuse_user_id alanı bu izi bir kullanıcı kimliğiyle etiketler. Betiği çalıştırın:

uv run python user_tracking.pyAltyapı:

Şunları göreceksiniz:

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.
......Altyapı:

Şimdi LangFuse panonuza gidin. Sol kenar çubuğundan “Users”a tıklayın; user-12345’in listelendiğini göreceksiniz. Kullanıcıya tıklayarak farklı oturumlar boyunca tüm izlerini görün.

Bu kullanıcı görünümü, “Kullanıcı X bu ay bize ne kadara mal oldu?” veya “Kullanıcı Y sürekli hangi soruları soruyor?” gibi soruları yanıtlamanıza yardımcı olur. Bireysel kullanıcı davranışını takip edebilir ve belirli kullanıcılara özgü sorunları ayıklayabilirsiniz.

LangFuse’ta İstem Yönetimi

S&Ç sisteminizin bir sorunu var. İstem kodunuzun içine gömülü. Sistemin nasıl yanıt verdiğini değiştirmek için qa_chain.py dosyasını düzenlemeniz, yerelde test etmeniz ve yeniden dağıtım yapmanız gerekir. Bir ekip arkadaşınız farklı bir yaklaşımı denemek istediğinde kod yapınızı anlaması ve yeni bir dal oluşturması gerekir. Farklı istem sürümlerini yan yana karşılaştıramazsınız ve geçen haftanın sürümüne git geçmişinde kazı yapmadan geri dönemazsiniz.

İstem yönetimi, istemleri kodunuzun dışında saklayarak bunu çözer. Onları bir arayüzde düzenler, otomatik olarak sürümlendirir ve çalışma zamanında çekersiniz. Kodunuz aynı kalırken istemleriniz iyileşir.

İş birliğine dayalı istem sorunu

S&Ç zincirinizdeki isteme bakı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}"),
])Altyapı:

Bu, tek kişilik projeler için işe yarar. Ancak bir ekiple çalışırken veya üretimde koşarken, sabit kodlanmış istemler sorun çıkarır:

• Dağıtım sürtünmesi: Her istem değişikliği bir kod dağıtımı gerektirir. Uygulama kodunu değiştirmeden farklı istemleri A/B testi yapamazsınız. “Yanıtı kısa ve olgusal tutun” ifadesini “Yanıtı öz tutun” yerine denemek isterseniz commit, push ve yeniden dağıtım yapmanız gerekir.
• Sürüm kontrolü yok: Git kod değişikliklerini izler ancak hangi istem sürümünün üretimde daha iyi performans gösterdiğini göstermez. “istem v1” ile “istem v2” için metrikleri göremez veya kod dağıtımı olmadan önceki sürüme hızla geri dönemezsiniz.
• Ekip darboğazları: Teknik olmayan ekip üyeleri istemler üzerinde iterasyon yapamaz. Ürün yöneticinizin daha iyi ifadeler için fikirleri vardır, ancak değişikliği yapmak için bir mühendisten rica etmesi gerekir. Bu da denemeyi yavaşlatır.
• Test zorlukları: İstem varyasyonlarını karşılaştırmak, kodunuzun birden çok sürümünü çalıştırmak anlamına gelir. Öz ve ayrıntılı yanıtları yan yana test etmek manuel iş olmadan mümkün değildir.

LangFuse’un istem yönetimi bu sorunları, istemleri kod değil veri olarak ele alarak çözer.

İstem oluşturma ve sürümlendirme

LangFuse istemlerinizi otomatik sürümlendirmeyle merkezi bir konumda saklar. İstemleri arayüzden veya SDK üzerinden oluşturabilirsiniz.

Arayüzde istem oluşturma

LangFuse panonuza gidin ve sol kenar çubuğundan “Prompts”a tıklayın. “New Prompt”a tıklayarak yeni bir tane oluşturun.

Bir form göreceksiniz; burada şunları yapabilirsiniz:

• İsteminizi adlandırın (document-qa-prompt kullanın)
• Türü seçin (text veya chat)
• {{variable}} söz dizimini kullanarak değişkenlerle istem şablonunuzu yazın
• Model ve temperature gibi yapılandırmaları ayarlayın
• Sürümleri işaretlemek için etiketler ekleyin (ör. production veya staging)

S&Ç sistemimiz için iki iletiden oluşan bir sohbet istemi oluşturun:

Sistem iletisi:

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}}Altyapı:

Kullanıcı iletisi:

{{input}}Altyapı:

LangFuse, {{context}} ve {{input}} değişkenlerini otomatik olarak algılar.

Ardından yapılandırmayı şu şekilde ayarlayın:

{
 "model": "gpt-4",
 "temperature": 0.0
}Altyapı:

production etiketini ekleyerek bunu üretim sürümü olarak işaretleyin.

Kaydettiğinizde LangFuse, isteminizin 1. sürümünü oluşturur. Her düzenleyip kaydettiğinizde yeni bir sürüm oluşturur. Eski sürümler erişilebilir durumda kalır.

SDK ile istem oluşturma

İstemleri Python SDK’sını kullanarak da oluşturabilirsiniz:

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"]
)Altyapı:

Bu, aynı istemi programlı olarak oluşturur. create_prompt()’i aynı adla tekrar çağırırsanız LangFuse üzerine yazmak yerine yeni bir sürüm ekler.

Etiketlerle sürüm kontrolü

LangFuse her istem değişikliğini sürüm numaralarıyla (v1, v2, v3) izler. Sürümlere etiketler de atayabilirsiniz. Etiketler dağıtımları yönetmenize yardımcı olur:

• production - Üretim uygulamanızın kullandığı sürüm
• staging - Hazırlık ortamınızdaki sürüm
• latest - Otomatik olarak en yeni sürümü işaret eder

İsteminizi geliştirdiğinizde yeni bir sürüm oluşturursunuz. Önce staging etiketi vererek hazırlıkta test edin. İyi çalıştığında production etiketini yeni sürüme taşıyın. Üretim uygulamanız bir sonraki istem çekişinde değişikliği otomatik olarak alır.

Oyun alanında (playground) varyasyonları test etme

LangFuse arayüzü, kodda kullanmadan önce istemleri test edebileceğiniz bir playground içerir. Şunları yapabilirsiniz:

• Farklı değişken değerlerini deneyin
• Birden çok sürümü yan yana karşılaştırın
• Değişikliklerin çıktıyı nasıl etkilediğini görün
• Test sonuçlarını ekibinizle paylaşın

Bu sayede teknik olmayan ekip üyeleri de koda dokunmadan ifadeler üzerinde deney yapabilir.

Yönetilen istemleri koda entegre etme

Uygulamanızda LangFuse tarafından yönetilen istemleri böyle kullanabilirsiniz. Bu iş akışı, istemleriniz evrilirken kodunuzu stabil tutar.

Adım 1: İstemi alın

Uygulama kodunuzda, istemi sabitlemek yerine LangFuse'tan alın:

from langfuse import Langfuse

langfuse = Langfuse()

# Get the production version
prompt = langfuse.get_prompt("document-qa-prompt", type="chat")Altyapı:

Bu, production etiketli sürümü getirir. LangFuse istemleri istemci tarafında önbelleğe alır, bu nedenle LLM çağrılarınızda ek gecikme olmaz.

Belirli sürümleri veya etiketleri de alabilirsiniz:

# 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")Altyapı:

Adım 2: İstemi değişkenlerle derleyin

Alınan istem, {{variables}} içeren bir şablondur. Değişkenleri gerçek değerlerle değiştirerek derleyin:

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

Bu, LLM'nize göndermeye hazır sohbet mesajlarının bir listesini döndürür:

[
   {
       "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?"
   }
]Altyapı:

Adım 3: Derlenmiş istemi LLM'inizle kullanın

Derlenmiş mesajları LLM çağrınıza iletin. Kullanacağınız kesin kod, LangChain, doğrudan OpenAI SDK'si veya başka bir çerçeve kullanıp kullanmadığınıza bağlıdır.

Adım 4: İstemi izlere bağlayın

LangFuse tarafından yönetilen bir istemle LLM çağrısı yaptığınızda, onu ize bağlayın. Bu, her LLM çağrısında hangi istem sürümünün kullanıldığını görmenizi ve metrikleri istem sürümüne göre takip etmenizi sağlar:

from langfuse.langchain import CallbackHandler

langfuse_handler = CallbackHandler()

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

LangFuse panonuzda izleri istem adı ve sürümüne göre gruplanmış olarak görürsünüz. Bu, hangi istem sürümlerinin daha pahalıya mal olduğunu, daha yavaş çalıştığını veya daha iyi sonuçlar ürettiğini gösterir.

Adım 5: Kod değişikliği olmadan yineleyin

İstem yönetiminin faydası burada ortaya çıkar. İsteminizi iyileştirmek için:

1. LangFuse arayüzüne gidin
2. İsteminizi düzenleyin (otomatik olarak yeni bir sürüm oluşturur)
3. Playground'da test edin
4. staging etiketini atayıp hazırlık ortamınızda test edin
5. production etiketini taşıyıp yayına alın

Kodunuz hiç değişmez. Bir sonraki get_prompt() çağrısında yeni sürüm çekilir.

Adım 6: Gerekirse geri alın

Yeni istem daha kötü performans gösteriyorsa, production etiketini önceki sürüme geri taşıyarak geri alın. Kod dağıtımı gerekmez.

Bu iş akışı, istem mühendisliğini yazılım mühendisliğinden ayırır. Ekibiniz istemler üzerinde hızla yineleme yapabilirken uygulama kodunuz stabil kalır.

İleri Okuma: LangFuse, istem sürümleri arasında trafiği otomatik olarak bölen A/B testlerini, istemler değiştiğinde sistemlerinizi bilgilendiren web kancalarını ve yorumlar ile onay iş akışları gibi ekip iş birliği özelliklerini de destekler. Bu gelişmiş özellikler, daha büyük ekiplerin istemleri ölçekli şekilde yönetmesine yardımcı olur. Ayrıntılar için prompt management docs bölümüne bakın.

LangFuse'ta değerlendirme

Bir S&C sistemi kurdunuz, gözlemlenebilirliği eklediniz ve istem yönetimini ayarladınız. Peki yanıtlarınızın iyi olduğunu nasıl anlarsınız? Şu anda muhtemelen manuel test yapıyorsunuz. Bir soru soruyor, yanıtı okuyup mantıklı olup olmadığına karar veriyorsunuz. Bu, birkaç örnek için işe yarar ama ölçeklenmez.

İsteminizi değiştirdiğinizde ne olur? Her şeyi yeniden test etmeniz gerekir. Kenar durumları peki? Daha önce test ettiğiniz her soruyu hatırlayamazsınız. Üretime geçtiğinizde ise isteminizin 2. sürümünün 1. sürümden daha iyi performans gösterip göstermediğini ölçmenin bir yolu yoktur.

Değerlendirme, LLM performansınızı sistematik olarak ölçerek bunu çözer. LangFuse, yanıtları otomatik puanlamanız, istem sürümlerini gerçek metriklerle karşılaştırmanız ve kullanıcılar görmeden kalite sorunlarını yakalamanız için araçlar sunar.

Sistematik LLM değerlendirme yaklaşımları

Manuel test, belirli bir yanıtın iyi görünüp görünmediğini söyler. Sistematik değerlendirme ise sisteminizin yüzlerce veya binlerce örnek genelinde iyi çalışıp çalışmadığını gösterir.

LangFuse'ta sistematik değerlendirme şöyle işler:

1. Bir test veri kümesi oluşturun: Belgelerde yanıtın bulunmadığı kenar durumlar dahil gerçek kullanımı temsil eden 20–50 soru toplayın.
2. Puanlama yöntemlerini seçin: S&C sisteminiz için hangi kalite boyutlarının önemli olduğuna karar verin (bunu bir sonraki bölümde ele alacağız).
3. Sisteminizi veri kümesine karşı çalıştırın: Her soruyu işleyin ve sonuçları LangFuse'a izler olarak kaydedin.
4. Yanıtları puanlayın: Puanlama yöntemlerinizi her yanıta otomatik olarak uygulayın.
5. Sonuçları analiz edin: LangFuse test setiniz genelinde puanları toplar ve hangi örneklerin başarısız olduğunu gösterir.
6. Yineleyin ve karşılaştırın: İsteminizi değiştirin, test setini yeniden çalıştırın ve iyileşme olup olmadığını görmek için metrikleri karşılaştırın.

Bu süreç, “Bence bu istem daha iyi”yi “Bu istem eski sürüme göre alaka düzeyinde 0,72 yerine 0,85 puan alıyor” ile değiştirir.

Değerlendirme yaklaşımlarına ve bunların LangFuse'ta nasıl uygulanacağına dair eksiksiz bir kılavuz için evaluation overview docs bölümüne göz atın.

Hakem olarak LLM değerlendirmesini anlama

Yüzlerce yanıtı puanlamanız gerekir. Bunu manuel yapmak saatler alır. Hakem olarak LLM, ana LLM'inizin çıktısını notlandırmak için başka bir LLM kullanarak bunu otomatikleştirir.

Nasıl çalışır

Bir hakem LLM'ye üç şey verirsiniz: orijinal soru, S&C sisteminizin yanıtı ve puanlama ölçütleri. Hakem yanıtı okur ve bir puan atar.

Bir S&C sistemi için, farklı kalite boyutları önemlidir. Oluşturabileceğiniz üç hakem örneği şunlardır:

Doğruluk hakemi: “Bu yanıtın, sağlanan bağlamdaki bilgileri doğru şekilde yansıtıp yansıtmadığını değerlendirin. Tamamen doğruysa 1, kısmen doğruysa 0,5, yanlışsa veya hayal ürünü ise 0 verin.”

Bu, belgelerinize aykırı olan veya uydurma yapan yanıtları yakalar.

Alaka düzeyi hakemi: “Bu yanıtın sorulan soruyu doğrudan ele alıp almadığını değerlendirin. Çok alakalıysa 1, kısmen alakalıysa 0,5, konu dışıysa 0 verin.”

Bu, sisteminizin, doğru ama alakasız bilgi vermek yerine konuya bağlı kalmasını sağlar.

Dayanaklılık hakemi: “Bu yanıtın yalnızca sağlanan bağlama dayanıp dayanmadığını değerlendirin. Tamamen bağlama dayanıyorsa 1, kısmen dayanıyorsa 0,5, bağlamda olmayan bilgiler içeriyorsa 0 verin.”

Bu, LLM'nin belgelerinizde olmayan olguları eklediği halüsinasyonları engeller.

Her hakem belirli bir kalite boyutuna bakar. Her yanıt için üç hakemi de çalıştırır ve eksiksiz bir kalite profili elde edersiniz. Üslup (özlü mü?), ton (profesyonel mi?) veya reddetme yönetimi (uygun olduğunda “Bilmiyorum” diyor mu?) için daha fazla hakem ekleyebilirsiniz.

LangFuse'ta hakemleri kurma

LangFuse, LLM hakemlerini arayüz veya API üzerinden yapılandırmanıza olanak tanır. Kurulum süreci:

1. Hakem isteminizi tanımlayın: Her puan düzeyi için belirli ölçütlerle açık puanlama talimatları yazın.
2. Hakem modelini seçin: GPT-4, Claude veya başka bir LLM kullanın. Daha güçlü modeller daha doğru puanlar verir ancak maliyeti daha yüksektir.
3. Hakemi LangFuse'ta yapılandırın: LangFuse'un izlere otomatik olarak uygulayacağı bir puanlama şablonu oluşturun.
4. Hakeminizi test edin: Doğru puanı bildiğiniz birkaç örnekte çalıştırın. Hakem çok sert veya fazla yumuşaksa istemi ayarlayın.
5. Veri kümenize uygulayın: Hakeminiz iyi çalıştığında LangFuse, tüm izlerinizi otomatik olarak puanlar.

Hakemler eşzamanlı olmayan şekilde çalışır, bu nedenle ana uygulamanızı yavaşlatmaz. Testleriniz bittikten sonra puanları LangFuse panosunda kontrol edersiniz.

Hakemlerin iyi çalıştığı durumlar

LLM hakemleri, kodla ölçülmesi zor öznel ölçütler için en iyi sonucu verir. Ton, alaka düzeyi ve üslup gibi. Nesnel olgular için ise daha az güvenilirdir. “2+2=4”ü doğrulamanız gerekiyorsa, bir hakem kullanmak yerine deterministik bir kontrol yazın.

S&C sistemimiz için hakemler alaka ve dayanaklılıkta iyi çalışır; ancak “yanıt uzunluğu 100 kelimenin altında” gibi konular için deterministik kontrollerle birleştirebilirsiniz.

Dikkate alınacak sınırlamalar

LLM hakemleri kusursuz değildir. Birbirleriyle aynı fikirde olmayabilirler, belirli yanıt üsluplarına karşı önyargıları olabilir ve kendinden emin görünen ama yanlış yanıtlara yüksek puan vererek hata yapabilirler.

Bunu, doğru puanı bildiğiniz örneklerde hakemlerinizi test ederek, birden fazla hakem kullanıp puanlarını ortalayarak ve hakem hatalarını yakalamak için sonuçları nokta kontrolleriyle inceleyerek yönetirsiniz.

Uygulama notu: Tam değerlendirme iş akışları veri kümeleri kurmayı, hakemleri yapılandırmayı, toplu değerlendirmeler çalıştırmayı ve sonuçları analiz etmeyi içerir. Bunu pratik kalırken bu eğitimde ele alabileceğimizden daha fazla hazırlık gerektirir. LLM-as-a-judge documentation, kod örnekleri ve en iyi uygulamalar dahil eksiksiz uygulama ayrıntıları sağlar. LLM hakemlerinin ötesindeki özel puanlama yaklaşımları için custom scores guide bölümüne bakın.

Burada özetlediğimiz iş akışı, değerlendirme bakış açısını gösterir. LangFuse'ta izleriniz ve istemleriniz yönetilir hale geldiğinde, sistematik değerlendirme eklemek doğal bir adım olur. Test setlerini kademeli olarak oluşturur, basit hakemlerle başlar ve uygulamanız için hangi metriklerin önemli olduğunu öğrendikçe yaklaşımınızı rafine edersiniz.

İleri Okuma: LangFuse, test vakalarını düzenlemek için veri kümesi yönetimini, deterministik kontroller için özel puanlama işlevlerini ve üretim trafiğinde otomatik olarak çalışan sürekli değerlendirmeyi de destekler. Bu özellikler, sisteminiz ölçeklenirken kaliteyi korumanıza yardımcı olur. Tüm resmi görmek için evaluation overview bölümüne bakın.

Sonuç

Bir belge S&C sistemi kurdunuz ve LangFuse'un üç ayağının birlikte nasıl çalıştığını öğrendiniz. Gözlemlenebilirlik, LLM'niz çalıştığında ne olduğunu gösterdi. Her izi, her maliyeti, her belirteci görüyorsunuz. İstem yönetimi, istemlerinizi kod dışına taşıyıp dağıtım gerektirmeden yineleme yapabildiğiniz, sürüm kontrollü bir sisteme aldı. Değerlendirme ise tahmin yürütmek yerine kaliteyi sistematik olarak ölçmenin yollarını sundu. Bu özellikler birbirine bağlıdır: izler, değerlendirme veri kümelerini besler; istem sürümleri performans metriklerine bağlanır; tüm sistem değişikliklerin işleri iyileştirip iyileştirmediğini anlamanıza yardımcı olur.

Kendi projelerinizle küçük başlayın. Bir özellik seçin. Belki uygulamanızın parayı nerede harcadığını görmek için izlemeyi ekleyin ya da kodda sabitlenmiş tek bir istemi LangFuse'un yönetim sistemine taşıyın. Basit S&C örneğimizle öğrendiğiniz kalıplar, karmaşık RAG boru hatlarına, çoklu ajan sistemlerine ve binlerce kullanıcıya hizmet veren üretim uygulamalarına ölçeklenir. Belirli özelliklere derinlemesine dalışlar için LangFuse documentation bölümüne göz atın veya gerçek dünya uygulamalarını gösteren example notebooks bölümünü deneyin. Bir sonraki LLM tabanlı geliştirme girişiminizde, neler olduğunu görmenizi, nelerin değiştiğini kontrol etmenizi ve önemli olanı ölçmenizi sağlayacak araçlara sahip olacaksınız.