Kılavuzlar

RAG değerlendirmesi

Bu sayfanın İngilizce sürümü çevrildiğinden bu yana değişti. Güncel olan İngilizce sayfadır. İngilizce okuyun

Getirmeyle zenginleştirilmiş (retrieval-augmented) bir yanıt dört farklı nedenle yanlış olabilir: doğru pasaj hiç getirilmemiştir; getirilmiş ama çok aşağıda sıralanmıştır; yeterince yukarıda sıralanmış ama sonra bağlamdan düşürülmüştür; ya da modele ulaşmış ve model yine de yanlış yapmıştır. Tek bir doğruluk sayısı bunları birbirinden ayıramaz. Oloproof bir RAG sistemini görebildiği iki aşama olarak çalıştırır, her birini ölçer ve hangi nedenin geçerli olduğunu bulmak için başarısız vakaları kontrollü değişiklikler altında yeniden yürütür.

examples/support_rag/ bu sayfanın çalıştırdığı projedir. Hiçbir sağlayıcı kimlik bilgisi gerektirmez.

Aşamalı bir sistem

Sistem, bir getirme aşaması ve bir üretim aşaması olan, @rag_system ile dekore edilmiş bir sınıftır:

from oloproof import Passage, Retrieval, rag_system


@rag_system(
    name="support-rag",
    version="slice-b-example",
    depth=6,
    top_k=2,
    token_budget=40,
    index_version="kb-2026-09-16",
)
class SupportRag:
    def retrieve(self, input, depth):
        ...
        return Retrieval(query=input["question"], depth=depth, candidates=tuple(passages))

    def generate(self, input, context):
        ...
        return {"answer": answer, "citations": [best.doc_id]}

    def count_tokens(self, passage):
        return len((passage.text or "").split())

retrieve(input, depth) en fazla depth aday döndürür; bunlar Passage(doc_id=..., score=..., text=...) biçimindedir ve getiricinizin ürettiği sıradadır. Oloproof konumları kaydeder ve asla yeniden sıralamaz. Ardından ilk top_k adayı tutar, token_budget sınırını aşan pasajları düşürür ve kalanı generate(input, context) fonksiyonuna verir. count_tokens(passage) yalnızca bir token_budget ile gereklidir; Oloproof token sayısını asla tahmin etmez.

oloproof.yaml sınıfı gösterir ve ayarlarından herhangi birini geçersiz kılabilir:

system:
  name: support-rag
  version: slice-b-example
  rag:
    object: app:SupportRag
    depth: 6
    top_k: 2
    token_budget: 40
    index_version: kb-2026-09-16

index_version, getirmenin kimliğinin bir parçasıdır. Dizin değiştiğinde onu da değiştirin; aksi hâlde önbellekteki getirmeler, artık onları döndürmeyen bir dizine karşı yeniden kullanılır.

Bir vakanın bildirdikleri

Bir RAG vakası expected altında, başka hiçbir vaka türünün ihtiyaç duymadığı iki alan taşır:

{"id":"refund_annual","input":{"question":"How long do refunds take for annual plans?"},"expected":{"answer":"14 days","relevant":[{"doc_id":"kb-01"}],"gold_context":[{"doc_id":"kb-01","text":"Refunds for annual plans are issued within 14 days of an approved request. Support reviews each request on the same business day."}]},"metadata":{"topic":"billing"}}

expected.relevant, soruyu yanıtlayan belgeleri listeler. Getirme metrikleri onu okur ve bu

alanı olmayan bir vaka onlardan no_relevance_labels ile hariç tutulur.

expected.gold_context, pasaj metninin kendisidir. Teşhis onu getirilen bağlamın yerine koyar ve

bu alanı olmayan başarısız bir vakanın teşhisi yapılamaz.

Değerlendiriciler

evaluators:
  - {type: contains, criterion: answer_correct, field: answer, expected_field: answer}
  - {type: hit_rate, k: 2}
  - {type: recall, k: 2}
  - {type: ndcg, k: 6}
  - {type: citation_validity}
slices: [metadata.topic, relevant_position, context_truncated]
min_slice_support: 4

hit_rate, recall, mrr ve ndcg bir k alır ve kendi ölçütlerini ondan adlandırır: hit_rate_at_2. expected.relevant içindeki bir girdi ayrıca bir chunk_id ve varsayılanı 1 olan bir grade taşıyabilir; bu durumda relevance_unit: chunk, belgelerin tamamı yerine her parçayı (chunk) kendi birimi olarak sayar. citation_validity, bir yanıtın alıntıladığı her kimliğin, yanıta verilen bağlamdaki bir pasajı adlandırdığını denetler; require_citations: true ile hiçbir şey alıntılamayan bir yanıt başarısız olur. groundedness_judge ve citation_support_judge, birleştirilmiş bağlamı okuyan LLM hakemleridir ve diğer her hakem gibi bir provider ve model alırlar.

oloproof run

Metrik tablosunun üç satırı:

│ answer_correct  │ 69.2%    │ [38.5%, 91.0%]  │ 9 / 13 observed · 0 missing · 0 excluded     │
│ ndcg_at_6       │ 0.866    │ [0.506, 0.990]  │ mean of 13 observed · 0 missing · 0 excluded │
│ citations_valid │ 100.0%   │ [75.2%, 100.0%] │ 13 / 13 observed · 0 missing · 0 excluded    │

Bunların arasında hit_rate_at_2 ve recall_at_2 ikisi de %92,3 gösterir, gözlenen 13 vakanın 12'si, alt sınır %63,9: bir sorunun ilgili pasajı hiç getirilmedi.

Cache: execution 0 hit/13 miss; judgment 0 hit/65 miss
Stages: retrieve 0 hit/13 miss; generate 0 hit/13 miss

Stages satırı aşamalı sistemin kendi önbelleğidir. Getirme ve üretim ayrı ayrı önbelleğe alınır; böylece üretimdeki bir değişiklik getirmeyi asla yeniden çalıştırmaz.

Nedenini bulmak

Dört soru başarısız oldu. diagnose bunları, getirilen bağlamın yerine altın pasajla (gold passage) yeniden yürütür; yanında da onları değiştirmeden yeniden yürüten bir kontrol çalıştırır:

oloproof diagnose RUN_ID --intervention gold-context --criterion answer_correct

Selected: 4 failed cases with gold context (observed; no population claim)
Control: 0 of 4 passed when re-executed without the intervention
Recovered under gold context: 3 of 4
RETRIEVAL_MISS: 1 of 4, recovered; no relevant evidence was retrieved
CONTEXT_ASSEMBLY_LOSS: 2 of 4, recovered; relevant evidence within top-k was left out of the context
GENERATION_FAILURE: 1 of 4, still failed with the gold context
Implicated: context budget, in 2 of the 3 recovered failures.
Candidate experiment: a larger token budget. This is a hypothesis to test, not an established cause.
Candidate experiment: smaller chunks. This is a hypothesis to test, not an established cause.
Diagnosis sha256:b2846cbe04099225bda4bf21beb1738f54d6cc0e9a7ce210bb3eb467619cbd69
Child runs: gold context run_01M3C3REAAZDF9FD8N2C8BG17P, control run_01M3C3REAFVXK2VM4MYAQYH6KE
Cases: oloproof inspect sha256:b2846cbe04099225bda4bf21beb1738f54d6cc0e9a7ce210bb3eb467619cbd69

Altın pasajla geçen ve onsuz başarısız olan bir vaka, modelin öncesinde başarısız olmuştur. Altın pasaj elindeyken başarısız olan bir vaka ise modelindir. Bu okumayı güvenli kılan kontroldür: sade bir yeniden çalıştırmada düzelen bir vaka kararsızdı (flaky), teşhis edilmiş değildi.

Teşhis kimliği her sayının arkasındaki vakayı listeler:

oloproof inspect DIAGNOSIS_ID

money_back: RETRIEVAL_MISS, relevant_not_retrieved, strength intervention_recovery, best relevant position none
refund_review: CONTEXT_ASSEMBLY_LOSS, relevant_dropped_from_context, strength intervention_recovery, best relevant position 2
seat_count: GENERATION_FAILURE, fails_with_gold_context, strength intervention_non_recovery, best relevant position 1
security_review: CONTEXT_ASSEMBLY_LOSS, relevant_dropped_from_context, strength intervention_recovery, best relevant position 2

Bir etken adlandırır, asla bir neden değil. Kullandığı en güçlü sözcükler "implicated" (ilişkili bulunan) ve "candidate experiment" (aday deney) sözcükleridir, çünkü tek bir müdahale altında düzelen dört vaka neden başarısız olduklarını kanıtlamaz.

Bir düzeltmeyi yapmadan önce test etmek

Diğer iki müdahale, kaydedilmiş getirmeyi farklı bir ayarla yeniden oynatır; böylece hiçbir getirici çağrısı yapılmaz. top-k kesme noktasını genişletir:

oloproof diagnose RUN_ID --intervention top-k --top-k 4 --criterion answer_correct

Selected: 4 failed cases with gold context (observed; no population claim)
Control: 0 of 4 passed when re-executed without the intervention
Recovered under top-k 4: 0 of 4
Confirmed under top-k 4: 0 of 0 RANKED_OUT cases also recovered
Labels from gold context (diagnosis sha256:b2846cbe04099225bda4bf21beb1738f54d6cc0e9a7ce210bb3eb467619cbd69): 3 of 4 recovered
RETRIEVAL_MISS: 1 of 4, recovered; no relevant evidence was retrieved
CONTEXT_ASSEMBLY_LOSS: 2 of 4, recovered; relevant evidence within top-k was left out of the context
GENERATION_FAILURE: 1 of 4, still failed with the gold context
Diagnosis sha256:668084c3e99df84f7b63f138792aa96f48e5cb8251fee3acae8e1cc0500ba085
Child runs: gold context run_01M3C3REAAZDF9FD8N2C8BG17P, control run_01M3C3REAFVXK2VM4MYAQYH6KE, top-k 4 run_01M3C3RKHTGGV37079V11JJ78M, replay control run_01M3C3RKJ076K7MSVQ94J4ZE2P
Cases: oloproof inspect sha256:668084c3e99df84f7b63f138792aa96f48e5cb8251fee3acae8e1cc0500ba085

Hiçbiri düzelmedi; etiketlerin öngördüğü de buydu: buradaki hiçbir başarısızlık, kesme noktasının hemen altında sıralanmış bir pasaj değildi. Yeniden oynatma altın bağlam etiketlerini ileri taşır; böylece iki teşhis birlikte okunur. reranker, bir module:function ile --reranker alır ve getirmeyi bunun yerine sizin yeniden sıralayıcınız üzerinden yeniden oynatır.

Deneyi çalıştırmak

Teşhis daha büyük bir token bütçesini adlandırdı. token_budget değerini 120'ye yükseltin ve yeniden çalıştırın:

Cache: execution 0 hit/13 miss; judgment 0 hit/65 miss
Stages: retrieve 13 hit/0 miss; generate 7 hit/6 miss

Her getirme yeniden kullanıldı, çünkü top_k ve token bütçesi getirmenin kimliğinin dışındadır; yalnızca bağlamı değişen altı vaka yeniden üretildi. Ardından örnek projenin karşılaştırma politikasıyla karşılaştırın:

oloproof compare CANDIDATE_RUN_ID BASELINE_RUN_ID --policy compare.yaml

Comparison sha256:d801ed897f1fa1b196ca1e3f73a1ef4ffe6845d6ee8bddaea8a44da94d27a75b of run_01M3C3RYJZ4PAJ8P4P9NT71360 against run_01M3C3R5Y9D18WGSZQFA7N4XRT · 13 paired cases
answer_correct: +0.0 points [-33.6, +33.6] · 13 paired · 0 missing · 0 excluded
hit_rate_at_2: +0.0 points [-33.6, +33.6] · 13 paired · 0 missing · 0 excluded
recall_at_2: +0.0 points [-33.6, +33.6] · 13 paired · 0 missing · 0 excluded
ndcg_at_6: +0.0 points [-33.6, +33.6] · 13 paired · 0 missing · 0 excluded
citations_valid: +0.0 points [-33.6, +33.6] · 13 paired · 0 missing · 0 excluded

Her dilim ve metrik için birer keşif amaçlı satır izler, ardından kararlar gelir:

Decisions
  answers-not-worse  answer_correct  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
  citations-not-worse  citations_valid  non-inferiority, margin 2.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
Gate: BLOCK (exit 3)

Deney işe yaramadı: on üç vakanın hiçbirinin hükmü değişmedi. Üstelik on üç eşleştirilmiş vaka, bir sürümün önemseyeceği büyüklükte hiçbir değişikliği kanıtlayamazdı; güven aralığının söylediği diğer şey de budur.

Sonraki adımlar

Dilimler relevant_position ve context_truncated dilimlerini anlatır.
Karşılaştırma kuralları son adımın karara bağlandığı kuralları anlatır.
Hakemler bir dayanaklılık (groundedness) hakeminin kapı olabilmesi için neyi

aşması gerektiğini anlatır.