LLM Eval ve Gözlemlenebilirlik: Gerçek Vakalardan Eval Seti, LLM Hakem ve OpenTelemetry ile İzleme
Gerçek vakalardan eval seti kurmak; kod tabanlı kontroller, LLM-as-a-judge ve insan değerlendirmesi; hakem yanlılıkları (pozisyon, uzunluk, kendini kayırma) ve hakemi insan etiketlerine göre kalibre etmek; CI'da offline ve canlıda örneklemli eval; nondeterminizm ve regresyon testi; ajan ve trajektori eval'i; OpenTelemetry GenAI semantik konvansiyonlarıyla tracing; her çağrıda neyin loglanacağı; araçlara genel bakış ve başlangıç kontrol listesi.
Güncellendi:
Kısa özet
Bir LLM uygulamasında "çalışıyor gibi görünüyor" ile "çalışıyor" arasındaki farkı iki şey kapatır: eval ve gözlemlenebilirlik (observability). Eval, bir değişikliği (yeni prompt, yeni model, yeni araç) canlıya almadan önce ve aldıktan sonra kendi görevlerinde ölçmenin tekrarlanabilir yolu. Gözlemlenebilirlik ise canlıda her çağrının ne yaptığını (hangi model, kaç token, ne kadar sürdü, neye mal oldu, nerede koptu) sonradan okuyabilmek.
İkisi aynı döngünün iki yarısı: canlıdaki izlerden (trace) gerçek hatalar çıkar, bu hatalar eval setine girer, eval seti bir sonraki değişikliği CI'da yakalar.
Not: Bilgiler 8 Kasım 2026'da makalelerden (arXiv), OpenTelemetry'nin GitHub depolarından ve araçların kendi dokümanlarından kontrol edildi. OpenTelemetry GenAI konvansiyonları hâlâ geliştirme aşamasında; öznitelik adları değişebilir. Araçlar hakkındaki her cümle o aracın kendi dokümanının söylediğidir; karşılaştırma ya da sıralama yapmıyoruz.
Eval seti: gerçek vakalardan başla
Eval seti üç parçadan oluşur: girdi, beklenen davranış (bazen tam bir cevap, çoğu zaman bir kriter) ve puanlama yöntemi. En değerli girdiler uydurulmuş örnekler değil, gerçek kullanımdan gelenlerdir.
Nereden toplanır?
- Canlıdaki trace'ler: kullanıcının cevabı beğenmediği, tekrar sorduğu, destek bileti açtığı konuşmalar.
- Ekibin elle denediği şeyler: "bunu bir de şununla deneyelim" diye Slack'e yapıştırılan her prompt potansiyel bir test.
- Bilinen hata türleri: halüsinasyon, yanlış araç çağrısı, format bozulması, prompt injection denemeleri, reddetmemesi gerekirken reddetme.
- Kenar durumlar: boş girdi, çok uzun girdi, başka dil, yazım hatası.
Ne kadar büyük? Anthropic'in "Demystifying evals for AI agents" yazısı (Ocak 2026), ekiplerin yüzlerce görev gerektiğini düşünüp eval yazmayı ertelediğini, oysa gerçek hatalardan seçilmiş 20-50 basit görevin iyi bir başlangıç olduğunu söylüyor: erken aşamada her değişikliğin etkisi büyük olduğu için küçük set de farkı gösterir. Anthropic'in test geliştirme dokümanı aynı yönde "hacmi kaliteye tercih et" diyor: elle puanlanmış az sayıda soru yerine otomatik puanlanan daha çok soru.
İyi bir eval örneği nasıl olur?
- Tek anlamlı. Talimatı doğru izleyen bir sistem geçebilmeli. Anthropic, Terminal-Bench denetiminde görevin dosya yolunu belirtmediği ama testlerin belirli bir yol beklediği vakalar bulduğunu anlatıyor; bu tür testler sistemi değil testi ölçer.
- Etiketli. Hangi kategoriden geldiği (fatura sorusu, iade, teknik), zorluk ve kaynak (canlı, elle, sentetik) yazılı olsun; sonuçları kırılımlara göre okuyabilirsin.
- Sürümlü. Set de kod gibi versiyonlanır. Bir örneği "artık geçmiyor" diye silmek, regresyonu gizlemenin en kolay yoludur.
- Gizli veriden arındırılmış. Canlıdan alınan örneklerde kişisel veriyi maskele.
Sentetik veri (bir LLM'e varyasyon ürettirmek) kapsama alanını genişletmek için işe yarar, ama gerçek örneklerin yerini tutmaz: model, kendi hayal ettiği kullanıcıyı test eder.
Üç puanlama yöntemi: kod, LLM hakem, insan
Anthropic'in test dokümanı puanlamayı üçe ayırıyor ve sıralaması açık: kod tabanlı en hızlı ve en güvenilir ama nüanstan yoksun; insan en esnek ve en kaliteli ama yavaş ve pahalı ("mümkünse kaçın"); LLM tabanlı hızlı ve esnek, karmaşık yargıya uygun, ama "önce güvenilirliğini test et, sonra ölçekle".
| Kod tabanlı kontrol | LLM-as-a-judge | İnsan değerlendirmesi | |
|---|---|---|---|
| Örnekler | Tam eşleşme, regex, JSON şeması, birim testi, SQL sonucu, araç çağrısı argümanı | Rubriğe göre geçti/kaldı, iki cevaptan hangisi iyi, ton, sadakat (faithfulness) | Uzman etiketlemesi, kullanıcı geri bildirimi, A/B |
| Hız ve maliyet | Anında, neredeyse bedava | Saniyeler, token maliyeti | Saatler-günler, pahalı |
| Tekrarlanabilirlik | Tam | Kısmi (hakemin kendisi de nondeterministik) | Düşük-orta (insanlar arası uyuşmazlık) |
| Zayıf yanı | Açık uçlu kaliteyi ölçemez | Yanlılıklar; kalibrasyon şart | Ölçeklenmez |
| Ne zaman | Cevabın doğruluğu mekanik olarak kontrol edilebiliyorsa: önce bu | Kriter yazılabilir ama kodlanamıyorsa | Hakemi kalibre etmek, yüksek riskli kararlar |
Pratik kural: kodla kontrol edebildiğin her şeyi kodla kontrol et, geri kalan için LLM hakem kullan, insanı da hakemi ölçmek ve en riskli örnekler için sakla. Bir görev birden çok kontrol içerebilir: "JSON geçerli mi" (kod) + "iade politikasına uygun mu" (hakem).
Kod tabanlı kontrol örneği
import json, re
def check_refund_reply(output: str) -> dict:
"""Kod ile kontrol edilebilen her şey: format, zorunlu alanlar, yasaklı içerik."""
results = {}
try:
data = json.loads(output)
results["valid_json"] = True
except json.JSONDecodeError:
return {"valid_json": False}
results["has_order_id"] = bool(re.fullmatch(r"ORD-\d{6}", data.get("order_id", "")))
results["amount_is_number"] = isinstance(data.get("refund_amount"), (int, float))
results["no_internal_link"] = "intranet." not in data.get("message", "")
return resultsLLM-as-a-judge ve yanlılıkları
LLM-as-a-judge, bir LLM'e bir rubrik verip başka bir modelin (ya da kendisinin) çıktısını puanlatmaktır. Terimi yaygınlaştıran çalışma Zheng ve ark. (2023), "Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena" (NeurIPS 2023 Datasets and Benchmarks). Makale üç biçim tanımlıyor:
- İkili karşılaştırma (pairwise): soru + iki cevap; hakem hangisinin iyi olduğunu ya da beraberliği söyler.
- Tek cevap puanlama: hakem tek bir cevaba doğrudan puan verir.
- Referanslı puanlama: hakeme bir referans çözüm de verilir (ör. matematik).
Makalenin ana bulgusu: GPT-4 gibi güçlü bir hakem, hem kontrollü hem kitle kaynaklı insan tercihleriyle %80'in üzerinde uyuştu; bu, insanların kendi aralarındaki uyuşma seviyesiyle aynı. Aynı makale hakemin sınırlarını da belgeledi:
- Pozisyon yanlılığı: hakem, cevapların sırasına göre farklı karar verebiliyor. Wang ve ark. (2023), "Large Language Models are not Fair Evaluators", yalnızca sırayı değiştirerek sonucu çevirebildiklerini gösterdi: ChatGPT hakemken Vicuna-13B, test edilen 80 sorunun 66'sında ChatGPT'yi "yendi".
- Uzunluk (verbosity) yanlılığı: daha uzun cevabı, daha iyi olmasa da tercih etme. Zheng ve ark. bunu, bir cevaptaki listeyi yeni bilgi eklemeden tekrar eden bir "repetitive list" saldırısıyla test etti.
- Kendini kayırma (self-enhancement / self-preference): hakemin kendi ürettiği cevapları kayırması. Zheng ve ark. bazı hakemlerin bazı modelleri kayırdığını gördü ama verinin sınırlı olduğunu ve kesin bir sonuca varamadıklarını açıkça yazıyor. Panickssery, Bowman ve Feng (2024), "LLM Evaluators Recognize and Favor Their Own Generations", modellerin kendi metinlerini ayırt edebildiğini ve bu kendini tanıma yeteneği ile kendini kayırma yanlılığının gücü arasında doğrusal bir ilişki bulduğunu raporladı.
- Sınırlı akıl yürütme: hakem, kendi başına çözebildiği basit bir matematik sorusunda bile verilen yanlış cevaba kanıp hatalı puan verebiliyor.
Önerilen önlemler (makalelerin kendisinden):
- Sırayı değiştir: Zheng ve ark.'nın "muhafazakâr" yöntemi: hakemi iki kez, cevapların yerini değiştirerek çağır; yalnızca iki sırada da aynı cevap kazanırsa kazandı say, değilse beraberlik. Wang ve ark.'nın "Balanced Position Calibration" yöntemi de farklı sıralardaki sonuçları birleştiriyor.
- Önce gerekçe, sonra puan: Wang ve ark.'nın "Multiple Evidence Calibration"ı puandan önce kanıt üretmeyi istiyor; Anthropic'in dokümanı da hakemde düşünmeyi (thinking) açmayı öneriyor.
- Referans ver: Zheng ve ark.'nın referanslı yönteminde hakem önce soruyu kendi başına çözüyor, sonra bu çözüm hakem prompt'una referans olarak konuyor; matematik sorularında hata oranı makaledeki tabloya göre %70'ten %15'e indi.
- Farklı model ailesinden hakem: kendini kayırmayı azaltmanın bariz yolu, değerlendirilen modelle aynı modeli hakem yapmamak.
- Net ve dar rubrik: Anthropic'in önerisi "ayrıntılı, net rubrikler" ve "yalnızca 'doğru' ya da 'yanlış' yaz" gibi belirgin çıktılar. Bir hakeme beş kriteri tek seferde puanlatmak yerine her kriter için ayrı, ikili (geçti/kaldı) bir hakem genellikle daha kolay kalibre edilir (bu bir pratik gözlem, ölçülmüş bir iddia değil).
Hakemi insan etiketlerine göre kalibre etmek
Hakem bir ölçüm aletidir; aleti kullanmadan önce ayarlarsın. Yöntem, makine öğrenmesindeki sınıflandırıcı değerlendirmesiyle aynı:
- İnsan etiketli bir örneklem oluştur. Canlıdan ya da eval setinden çıktıları al; alan uzmanı her birine geçti/kaldı (ve kısa gerekçe) yazsın. Mümkünse iki kişi etiketlesin; ikisinin uyuşması, hakemden bekleyebileceğin tavanı gösterir.
- Örneklemi ikiye böl. Bir kısmında hakem prompt'unu geliştir, diğer kısmı hiç görmeden ölç. Aynı örneklerde hem ayarlayıp hem ölçersen hakemi o örneklere ezberletmiş olursun (overfitting).
- Uyuşmayı yalnızca yüzde ile değil, karışıklık matrisiyle oku. "%90 uyuştu" etiketlerin %90'ı "geçti" ise anlamsızdır. Karışıklık matrisi, precision/recall, gerçek pozitif ve gerçek negatif oranları ve şansa göre düzeltilmiş bir uyuşma ölçüsü (Cohen's kappa) birlikte bakılır.
- Uyuşmadığı vakaları oku. Hata hakemde mi, rubrikte mi, yoksa insan etiketinde mi? Çoğu zaman rubrik belirsizdir.
- Hakemi ve prompt'unu sürümle. Hakem modeli ya da prompt'u değişince kalibrasyonu tekrarla; eski skorlarla yenileri doğrudan karşılaştırılamaz.
from sklearn.metrics import cohen_kappa_score, confusion_matrix
# human: uzman etiketleri, judge: hakemin kararları (aynı sırada, held-out örneklem)
human = ["pass", "fail", "pass", "pass", "fail", "fail", "pass", "fail"]
judge = ["pass", "fail", "pass", "fail", "fail", "pass", "pass", "fail"]
tn, fp, fn, tp = confusion_matrix(human, judge, labels=["fail", "pass"]).ravel()
print("TPR (insan 'geçti' dediğinde hakem de geçti dedi):", tp / (tp + fn))
print("TNR (insan 'kaldı' dediğinde hakem de kaldı dedi):", tn / (tn + fp))
print("Cohen's kappa:", round(cohen_kappa_score(human, judge), 3))Hakem ile insanlar arasındaki uyuşma, iki insanın kendi aralarındaki uyuşmaya yakınsa hakem işini yapıyordur. Ondan belirgin biçimde düşükse, hakemin skorlarını karar vermek için değil yalnızca eğilim izlemek için kullan.
Offline eval (CI) ve örneklemli canlı eval
| Offline (canlıya almadan önce) | Online (canlıda) | |
|---|---|---|
| Veri | Sabit, sürümlü eval seti | Gerçek trafikten örneklem |
| Beklenen cevap | Çoğu zaman var | Genelde yok; referanssız kontroller |
| Ne zaman | Her PR'da, model/prompt değişikliğinde | Sürekli, asenkron |
| Amaç | Regresyonu yakalamak, iki sürümü karşılaştırmak | Kayma (drift), yeni hata türleri, gerçek kalite |
| Puanlama | Kod + hakem | Ucuz kod kontrolleri her çağrıda, hakem örneklemde |
LangSmith ve Braintrust dokümanları da aynı ayrımı yapıyor: geliştirme sırasında küratörlü veri setinde offline, canlı trafikte gerçek zamanlı online değerlendirme.
Offline, CI'da:
- Eval setini her PR'da çalıştır; skoru ana daldaki son skorla karşılaştır.
- Toplam skorun yanında kırılımlara bak: genel skor sabitken "iade" kategorisi çökmüş olabilir.
- Pahalı hakem eval'lerini her commit'te değil, prompt/model dosyaları değiştiğinde ya da gece çalıştırabilirsin.
- Eşik koy ve CI'ı gerçekten kır: "skor düştü ama merge ettik" bir kez olursa eval seti süs olur.
Online, canlıda:
- Her çağrıda ucuz kontroller: JSON geçerli mi, yasaklı içerik var mı, cevap boş mu, araç hatası döndü mü. Bunlar aynı zamanda guardrail adayıdır.
- Örneklemde hakem: trafiğin belirli bir yüzdesini asenkron olarak hakeme gönder; yüzdeyi bütçen belirler. Kullanıcıyı bekletme.
- Kullanıcı sinyallerini (beğenme, yeniden üretme, konuşmayı terk etme) trace'e bağla.
- Hakemin "kaldı" dediği ya da kullanıcının şikâyet ettiği trace'leri bir inceleme kuyruğuna al; doğrulananları eval setine ekle. Döngü burada kapanır.
Regresyon testi ve nondeterminizm
Aynı girdi iki kez farklı çıktı verebilir; bu, klasik "beklenen == gerçekleşen" testlerini bozar. Nedenleri iki katmanda:
- Örnekleme: temperature, top-p gibi parametreler sıfırdan büyükse model bilinçli olarak rastgele seçer.
- Sayısal nondeterminizm: temperature 0 bile yetmeyebilir. OpenAI'ın API dokümanı
seedparametresinin "en iyi çaba" olduğunu, determinizmin garanti edilmediğini ve arka uç değişikliklerinisystem_fingerprintile izlemek gerektiğini yazıyor. Thinking Machines'ten Horace He ve ekibinin "Defeating Nondeterminism in LLM Inference" yazısı (Eylül 2025), yaygın "eşzamanlılık + kayan nokta" açıklamasının LLM çıkarımındaki asıl neden olmadığını, asıl nedenin çekirdeklerin batch-invariant olmaması olduğunu savunuyor: sunucudaki yük değiştikçe batch boyutu değişiyor ve aynı isteğin sayısal sonucu değişebiliyor. Yazıdaki deneyde Qwen3-235B ile temperature 0'da alınan 1000 tamamlamadan 80'i birbirinden farklıydı; batch-invariant çekirdekler açılınca 1000'i de aynı çıktı.
Pratikte ne yapılır?
- Mümkünse çıktının kendisini değil özelliğini test et: "cevap
ORD-ile başlayan bir kimlik içeriyor mu" gibi. - Her örneği birden çok kez çalıştır ve oran raporla. Ajan eval'lerinde iki ölçü kullanılır: pass@k (k denemeden en az biri başarılı) ve pass^k (k denemenin hepsi başarılı). pass^k, Yao ve ark. (2024), "τ-bench" makalesinde ajan güvenilirliğini ölçmek için önerildi. Anthropic'in örneği: deneme başına başarı %75 ise üç denemenin üçünün de geçme olasılığı (0,75)³ ≈ %42.
- Sürümleri karşılaştırırken küçük farklara güvenme; aynı sürümü birkaç kez çalıştırıp skorun kendi kendine ne kadar oynadığını gör. Fark bu oynamadan küçükse "iyileşme" yoktur.
- Model adını sabitle: takma ad (alias) yerine sağlayıcının tarihli/sabit model kimliğini kullan; trace'te dönen model adını da kaydet.
Ajan ve trajektori eval'i
Ajanlarda tek bir cevap değil, bir dizi adım değerlendirilir: model çağrıları, araç çağrıları, ara sonuçlar (ajan döngüsü). Anthropic'in ajan eval'leri yazısı iki şeyi ayırıyor:
- Transcript (trajektori): ajanın tüm adımlarının kaydı.
- Outcome (sonuç): denemenin sonunda ortamın son durumu. Yazının örneği: uçuş rezervasyonu yapan ajan "uçuşunuz ayrıldı" diyebilir; asıl sonuç, ortamın veritabanında gerçekten bir rezervasyon olup olmadığıdır. τ-bench de konuşma sonundaki veritabanı durumunu hedef durumla karşılaştırarak puanlıyor.
Neye bakılır?
- Sonuç: görev bitti mi? Kodlama ajanında testler geçiyor mu, destek ajanında kayıt doğru mu güncellendi?
- Süreç verimliliği: kaç tur, kaç token, kaç araç çağrısı, ne kadar sürdü.
- Kurallar: yetkisiz bir araç çağrıldı mı, onay gerektiren bir adımda insan onayı beklendi mi, gizli veri dışarı sızdı mı.
- Araç çağrısı doğruluğu: doğru araç, geçerli argümanlar (function calling).
Dikkat: Anthropic, araç çağrılarının belirli bir sırayla yapılıp yapılmadığını kontrol etmenin çok katı olduğunu ve kırılgan testler ürettiğini yazıyor; ajanlar tasarımcının öngörmediği geçerli yollar bulabiliyor. Yazının tavsiyesi, izlenen yolu değil ajanın ürettiği sonucu puanlamak. Yol kontrollerini yalnızca gerçekten kural olan şeyler için kullan ("ödeme aracını onaysız çağırma" gibi).
Ve en ucuz yöntem: transcript'leri oku. Anthropic, grader'ların doğru çalışıp çalışmadığını ancak çok sayıda denemenin transcript'ini ve puanını okuyarak bilebileceğini söylüyor; başarısız bir görevde transcript, hatanın ajanda mı yoksa grader'da mı olduğunu gösterir. Ajanın etrafındaki makine için AI Harness Anatomisi rehberine bak.
OpenTelemetry GenAI semantik konvansiyonlarıyla tracing
Bir trace, bir isteğin uçtan uca kaydıdır; içinde iç içe span'ler olur: "ajanı çağır" span'inin altında "model çağrısı" ve "araç çalıştır" span'leri. OpenTelemetry (OTel), bu kayıtların biçimini ve dağıtımını standartlaştıran açık kaynak proje; semantik konvansiyonlar da hangi özniteliğin hangi adla yazılacağını tanımlıyor. Herkes aynı adı kullanınca bir kez enstrümante edip veriyi istediğin arka uca (Langfuse, Phoenix, LangSmith, Datadog, Grafana…) gönderebilirsin.
Durum (Kasım 2026 itibarıyla):
- GenAI konvansiyonlarının statüsü Development; yani kararlı değil.
- Konvansiyonlar ana
semantic-conventionsdeposundan çıkıp ayrı bir depoya,open-telemetry/semantic-conventions-genai'ye taşındı. Ana depo v1.41.0'da (Nisan 2026) GenAI sayfalarını hâlâ içeriyordu; v1.42.0'dan (Haziran 2026) itibaren opentelemetry.io'daki eski sayfalar "Moved" uyarısıyla yeni depoya yönlendiriyor. Yeni deponun henüz yayımlanmış bir sürümü yok. - Adlar değişmeye devam ediyor. Örneğin eski sürümlerdeki
gen_ai.client.token.usagemetriği, deponun güncel halindegen_ai.client.inference.usage.input_tokensgibi ayrı metriklere bölünmüş durumda. Kullandığın enstrümantasyon kütüphanesinin hangi sürümü izlediğini kontrol et.
Model çağrısı span'i için temel öznitelikler (güncel depoya göre):
| Öznitelik | Ne |
|---|---|
gen_ai.operation.name |
İşlem: chat, generate_content, embeddings, execute_tool, invoke_agent… (zorunlu) |
gen_ai.provider.name |
Sağlayıcı: openai, anthropic, aws.bedrock… |
gen_ai.request.model / gen_ai.response.model |
İstenen ve gerçekte cevap veren model |
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens |
Girdi ve çıktı token'ları |
gen_ai.usage.cache_read.input_tokens |
Sağlayıcı önbelleğinden okunan girdi token'ları |
gen_ai.usage.reasoning.output_tokens |
Akıl yürütmeye (thinking) harcanan çıktı token'ları |
gen_ai.response.finish_reasons |
Neden durdu: ör. ["stop"], ["stop", "length"] (sağlayıcının değerleri) |
gen_ai.conversation.id |
Aynı konuşmaya ait çağrıları bağlar |
gen_ai.input.messages / gen_ai.output.messages |
Mesajların kendisi: Opt-In |
Span adı {gen_ai.operation.name} {gen_ai.request.model} biçiminde olmalı (ör. chat model-adı). Ajanlar için create_agent, invoke_agent ve execute_tool span'leri; metrikler tarafında gen_ai.client.operation.duration ile ajan için gen_ai.invoke_agent.duration, gen_ai.invoke_agent.tool_calls gibi metrikler tanımlı. A2A ve MCP için ayrı konvansiyon sayfaları da var (bkz. Ajan Protokolleri).
İçerik kaydı opt-in: Konvansiyonlara göre talimatların, prompt'ların, cevapların, araç argüman/sonuçlarının ve hafıza kayıtlarının kaydı açık bir kullanıcı onayına (opt-in) bağlı ve enstrümantasyonların bunun için bir ayar sunması zorunlu. Mesajları span'e gömmek yerine harici depolamaya koyup yalnızca adresini yazmak için gen_ai.input.messages_ref gibi öznitelikler de var.
Sık düşülen tuzak, önbellekli token'lar: Konvansiyona göre gen_ai.usage.input_tokens önbellekli token'ları içermeli. Anthropic API'si ise input_tokens alanında önbellekli token'ları saymıyor ve önbellek okuma/yazmayı ayrı alanlarda döndürüyor; konvansiyonun Anthropic sayfası toplamın bu alanların eklenmesiyle hesaplanmasını istiyor. Bunu atlarsan prompt caching açıldığı gün girdi token'ların "düşmüş" görünür.
import os
from anthropic import Anthropic
from opentelemetry import trace
tracer = trace.get_tracer("support-bot")
client = Anthropic()
MODEL = os.environ["LLM_MODEL"] # sabit, tarihli model kimliği
def answer(question: str, conversation_id: str) -> str:
with tracer.start_as_current_span(f"chat {MODEL}") as span:
span.set_attribute("gen_ai.operation.name", "chat")
span.set_attribute("gen_ai.provider.name", "anthropic")
span.set_attribute("gen_ai.request.model", MODEL)
span.set_attribute("gen_ai.conversation.id", conversation_id)
resp = client.messages.create(
model=MODEL, max_tokens=1024,
messages=[{"role": "user", "content": question}],
)
u = resp.usage
cache_read = u.cache_read_input_tokens or 0
cache_write = u.cache_creation_input_tokens or 0
span.set_attribute("gen_ai.response.model", resp.model)
# Konvansiyon: input_tokens önbellekli token'ları da içermeli
span.set_attribute("gen_ai.usage.input_tokens", u.input_tokens + cache_read + cache_write)
span.set_attribute("gen_ai.usage.output_tokens", u.output_tokens)
span.set_attribute("gen_ai.usage.cache_read.input_tokens", cache_read)
span.set_attribute("gen_ai.response.finish_reasons", [resp.stop_reason])
return resp.content[0].textBu örnek öznitelikleri elle yazıyor; gerçek projede sağlayıcı SDK'si ya da framework için hazır bir OTel enstrümantasyonu kullanmak genelde daha az iş. Hangisini seçersen seç, ürettiği adları bir kez gerçek bir trace'te kontrol et.
Her çağrıda ne loglanmalı?
| Alan | Neden |
|---|---|
| Trace / span / konuşma kimliği | Bir şikâyeti tek tıkla ilgili çağrılara bağlamak |
| Sağlayıcı, istenen model, dönen model | Takma ad arkasında model değiştiğinde fark etmek |
| Prompt sürümü / şablon adı | Hangi prompt'un hangi skoru verdiğini bilmek (gen_ai.prompt.name, gen_ai.prompt.version) |
| Girdi, çıktı, önbellekten okunan (ve yazılan) token'lar, reasoning token'ları | Maliyet ve token optimizasyonu |
| Toplam gecikme, ilk token'a kadar süre | Kullanıcının hissettiği hız; streaming'de ikisi çok farklı |
| Bitiş nedeni | length ile kesilen cevaplar sessiz bir hata kaynağı |
| Hata, yeniden deneme sayısı, rate limit | Güvenilirlik |
| Hesaplanmış maliyet | Token sayılarını kendi fiyat tablonla çarp; fiyat tablosunu da sürümle |
| Araç çağrıları (ad, süre, hata) | Ajanlarda darboğaz ve hata yeri |
| Kullanıcı geri bildirimi ve eval skorları | Kaliteyi trace'e bağlamak |
| Prompt ve cevap metni | Yalnızca bilinçli opt-in ile, maskeleme ve saklama süresiyle |
Maliyeti sağlayıcının faturasıyla ara ara karşılaştır: önbellek yazma ve okuma, batch indirimi, reasoning token'ları farklı fiyatlanabilir. Token tasarrufu için Token Tasarrufu Yöntemleri rehberine bak.
Araçlara genel bakış
Aşağıdaki her açıklama aracın kendi dokümanından ya da deposundan (8 Kasım 2026'da kontrol edildi); sıralama ya da tavsiye değil. Lisanslar ve sahiplik değişebilir.
- Langfuse: Kendini "agent evals and observability" için açık kaynak bir AI mühendisliği platformu olarak tanımlıyor: tracing, prompt yönetimi, eval (LLM-as-a-judge, kod evaluator'ları, kullanıcı geri bildirimi, elle etiketleme), veri setleri ve deneyler, dashboard'lar. OpenTelemetry üzerine kurulu olduğunu ve OTLP trace'lerini kabul ettiğini yazıyor. Bulutta ya da Docker Compose ile kendi sunucunda çalışıyor. Lisans:
ee/klasörleri dışında MIT. README'ye göre Ocak 2026'dan beri ClickHouse'un parçası. - Braintrust: Dokümanı kendini ajanlar için bir observability platformu olarak tanıtıyor. Bir eval'i üç parçaya ayırıyor: veri, görev ve evaluator'lar (scorer ve sınıflandırıcılar); playground → deney → CI/CD → canlıda online scoring → canlı trace'leri veri setine geri besleme döngüsünü anlatıyor. Hazır scorer'lar için açık kaynak (MIT)
autoevalskütüphanesi var. - LangSmith: LangChain'in platformu. Dokümanı observability (trace'ler, canlı izleme) ve evaluation'ı (offline: veri setinde CI öncesi; online: canlı trafikte) ayrı ürün alanları olarak anlatıyor; gerçek trace'leri veri setine ekleyip "bir kez görülen hatayı her seferinde çalışan teste" çevirmeyi öneriyor. LangChain dışındaki framework'lerle de çalıştığını ve OpenTelemetry ile trace aldığını yazıyor.
- Helicone: README'sine göre bir AI gateway ve LLM observability platformu: OpenAI uyumlu tek bir uç noktadan çok sayıda modele erişim, yönlendirme ve otomatik yedekleme (fallback), trace ve oturum incelemesi, maliyet/gecikme takibi, prompt yönetimi. Entegrasyon, istemcinin
baseURL'ini değiştirmekle yapılıyor. Lisans: Apache-2.0. - Arize Phoenix: README'ye göre Arize'ın deneme, değerlendirme ve hata ayıklama için açık kaynak AI observability platformu: OpenTelemetry tabanlı tracing (OpenInference enstrümantasyonu), LLM ile eval, sürümlü veri setleri, deneyler, playground, prompt yönetimi. Yerelde, container'da ya da bulutta kendin barındırıyorsun; yönetilen sürüm Arize AX. Lisans: Elastic License 2.0 (ELv2).
- promptfoo: LLM uygulamalarını değerlendirmek ve red-teaming için bir CLI ve kütüphane: otomatik eval'ler, güvenlik açığı taraması, modelleri yan yana karşılaştırma, CI/CD'de otomatik kontroller. README'ye göre promptfoo artık OpenAI'ın parçası ve açık kaynak (MIT) kalmaya devam ediyor.
- OpenAI Evals:
openai/evalsdeposu, LLM'leri ve LLM tabanlı sistemleri değerlendirmek için bir framework ve hazır eval'lerden oluşan bir kayıt (registry). README, eval'lerin artık doğrudan OpenAI Dashboard'da da yapılandırılıp çalıştırılabildiğini söylüyor (platformun Evals rehberi). - Inspect: Birleşik Krallık AI Security Institute'un LLM değerlendirme framework'ü (Python, MIT). Bir eval'i task (veri seti + solver + scorer) olarak tanımlıyor; prompt mühendisliği, araç kullanımı, çok turlu diyalog, ajanlar, model ile puanlama ve sandbox içinde çalıştırma için hazır bileşenler sunuyor. README'ye göre 200'den fazla hazır eval içeren bir koleksiyonu var.
Seçerken sorulacaklar: Veri nerede duracak (bulut, kendi sunucun, AB)? Açık kaynak/self-host şart mı? OTel ile mi, kendi SDK'siyle mi enstrümante edeceksin (OTel, araç değiştirmeyi kolaylaştırır)? Eval'ler CI'da kod olarak mı yaşayacak, yoksa arayüzde mi? Ajan trace'lerini (iç içe span'ler) nasıl gösteriyor?
Başlangıç kontrol listesi
Eval seti
- Gerçek kullanımdan (trace, destek bileti, ekip denemeleri) en az birkaç düzine örnek topladın mı?
- Her örnekte kategori, kaynak ve beklenen davranış yazılı mı?
- Set sürüm kontrolünde mi ve kişisel veri maskelenmiş mi?
- Her örnek, talimatı doğru izleyen bir sistemin geçebileceği kadar tek anlamlı mı?
Puanlama
- Kodla kontrol edilebilen her şey kodla mı kontrol ediliyor?
- LLM hakemin rubriği dar ve ikili mi; hakem farklı bir model ailesinden mi?
- İkili karşılaştırmada cevapların sırası değiştirilerek iki kez soruluyor mu?
- Hakem, ayrı tutulmuş insan etiketli bir örneklemde karışıklık matrisi ve kappa ile ölçüldü mü?
- Hakem modeli ve prompt'u sürümlü mü?
Süreç
- Eval seti her PR'da çalışıyor ve eşik altında CI kırılıyor mu?
- Skorlar kategori kırılımıyla raporlanıyor mu?
- Her örnek birden çok kez çalıştırılıyor ve skorun kendi oynaması biliniyor mu?
- Model kimliği sabit mi?
- Ajanlarda sonuç (ortamın son durumu) puanlanıyor ve transcript'ler düzenli okunuyor mu?
Canlı
- Her çağrı bir trace'e bağlı mı; model, token (önbellek dahil), gecikme, bitiş nedeni, maliyet ve prompt sürümü kaydediliyor mu?
- Prompt/cevap metni kaydı bilinçli bir opt-in mi; maskeleme ve saklama süresi tanımlı mı?
- Ucuz kontroller her çağrıda, hakem örneklemde asenkron çalışıyor mu?
- Başarısız trace'ler inceleme kuyruğundan eval setine geri dönüyor mu?
Devamı için
- Evals ve LLM-as-a-Judge: kısa tanımlar.
- Benchmark: ortak sınavlar ve neden kendi eval setinin yerini tutmadıkları.
- Guardrails ve Human-in-the-Loop: canlıdaki kontrollerin ve insan onayının yeri.
- AI Harness Anatomisi: ajanın etrafındaki döngü, araçlar ve izler.
- Token Tasarrufu Yöntemleri ve Prompt Caching: loglanan maliyeti düşürmek.
- Sistem Prompt'u Rehberi: eval ile ölçeceğin şeyin kendisi.
Kaynaklar
- Zheng, L., Chiang, W.-L., Sheng, Y., Zhuang, S. ve ark. — "Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena", NeurIPS 2023 Datasets and Benchmarks. https://arxiv.org/abs/2306.05685
- Wang, P., Li, L., Chen, L., Cai, Z. ve ark. — "Large Language Models are not Fair Evaluators", 2023. https://arxiv.org/abs/2305.17926
- Panickssery, A., Bowman, S. R., Feng, S. — "LLM Evaluators Recognize and Favor Their Own Generations", 2024. https://arxiv.org/abs/2404.13076
- Yao, S., Shinn, N., Razavi, P., Narasimhan, K. — "τ-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains", 2024. https://arxiv.org/abs/2406.12045
- He, H. ve Thinking Machines — "Defeating Nondeterminism in LLM Inference" (Eylül 2025): https://thinkingmachines.ai/blog/defeating-nondeterminism-in-llm-inference/
- Anthropic — "Demystifying evals for AI agents" (Ocak 2026): https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents
- Anthropic — Define success criteria and build evaluations: https://platform.claude.com/docs/en/test-and-evaluate/develop-tests
- OpenAI — Chat Completions API,
seedparametresi (openai-python): https://github.com/openai/openai-python/blob/main/src/openai/types/chat/completion_create_params.py - OpenTelemetry — GenAI semantic conventions deposu: https://github.com/open-telemetry/semantic-conventions-genai
- OpenTelemetry — Eski GenAI sayfası ("Moved" uyarısı): https://opentelemetry.io/docs/specs/semconv/gen-ai/
- OpenTelemetry — Document status tanımları: https://opentelemetry.io/docs/specs/otel/document-status
- Langfuse: https://github.com/langfuse/langfuse · https://langfuse.com/docs
- Braintrust — Evaluate systematically: https://docs.braintrust.dev/evaluate/index.md · autoevals: https://github.com/braintrustdata/autoevals
- LangSmith — Evaluation: https://docs.langchain.com/langsmith/evaluation · Trace with OpenTelemetry: https://docs.langchain.com/langsmith/trace-with-opentelemetry
- Helicone: https://github.com/Helicone/helicone · https://docs.helicone.ai
- Arize Phoenix: https://github.com/Arize-ai/phoenix · https://arize.com/docs/phoenix
- promptfoo: https://github.com/promptfoo/promptfoo · https://www.promptfoo.dev/blog/promptfoo-joining-openai/
- OpenAI Evals: https://github.com/openai/evals · https://platform.openai.com/docs/guides/evals
- Inspect (UK AI Security Institute): https://github.com/UKGovernmentBEIS/inspect_ai · https://inspect.aisi.org.uk/
Sık sorulan sorular
LLM eval nedir, benchmark'tan farkı ne?
Eval, kendi uygulamanın kendi görevlerinde ne kadar iyi çalıştığını ölçen tekrarlanabilir testlerdir: girdiler, beklenen davranış ve bir puanlama yöntemi. Benchmark ise modelleri herkesin aynı sorularla karşılaştırdığı ortak bir sınavdır. Benchmark model seçimini daraltır; canlıya çıkıp çıkmama kararını senin eval setin verir.
LLM-as-a-judge güvenilir mi?
Koşullu olarak. Zheng ve ark. (2023), GPT-4 gibi güçlü bir hakemin insan tercihleriyle %80'in üzerinde uyuştuğunu ve bunun insanlar arası uyuşmayla aynı seviyede olduğunu raporladı; aynı çalışma pozisyon, uzunluk ve kendini kayırma yanlılıklarını da belgeledi. Bu yüzden hakemi kendi görevinde, insan etiketli bir örnek üzerinde ölçmeden sonuçlarına güvenme.
Bir eval seti kaç örnekle başlamalı?
Kesin bir sayı yok. Anthropic'in ajan eval'leri yazısı, gerçek hatalardan seçilmiş 20-50 basit görevin iyi bir başlangıç olduğunu söylüyor; erken aşamada değişikliklerin etkisi büyük olduğu için küçük set yeterli. Set, canlıda gördüğün yeni hatalarla zamanla büyür.
temperature 0 verince çıktılar deterministik olur mu?
Hayır, garanti değil. OpenAI seed parametresinin 'en iyi çaba' olduğunu ve determinizmin garanti edilmediğini yazıyor. Thinking Machines'in 2025 yazısı, sunucudaki yükle değişen batch boyutunun aynı isteğin sayısal sonucunu değiştirebildiğini gösterdi. Regresyon testlerini tek koşuya değil, tekrar ve eşiklere dayandır.
OpenTelemetry'nin GenAI konvansiyonları kararlı mı?
Kasım 2026 itibarıyla hayır. GenAI semantik konvansiyonları 'Development' statüsünde ve ana semantic-conventions deposundan ayrı bir depoya (semantic-conventions-genai) taşındı. Metrik ve öznitelik adları hâlâ değişiyor; enstrümantasyon kütüphanenin hangi sürümü izlediğini kontrol et.
Her LLM çağrısında ne loglamalıyım?
Asgari: istenen ve dönen model adı, sağlayıcı, girdi, çıktı ve önbellekten okunan token sayıları, gecikme (toplam ve ilk token), bitiş nedeni, hata, hesaplanmış maliyet, prompt sürümü ve bir trace/konuşma kimliği. Prompt ve cevap metinlerini kaydetmek kişisel veri içerebileceği için OpenTelemetry'de de açıkça opt-in.
Hangi eval/observability aracını seçmeliyim?
Bu rehber sıralama yapmıyor. Önce açık kaynak ya da kendi sunucunda barındırma ihtiyacına, OpenTelemetry desteğine, CI entegrasyonuna ve verinin nerede tutulacağına karar ver; sonra iki aracı kendi küçük eval setinle dene.