Panduan

Evaluasi RAG

Versi bahasa Inggris halaman ini telah berubah sejak diterjemahkan. Halaman berbahasa Inggris adalah versi terkini. Baca dalam bahasa Inggris

Jawaban retrieval-augmented bisa salah karena empat alasan berbeda: passage yang tepat tidak pernah diambil, passage itu diambil tetapi peringkatnya terlalu rendah, peringkatnya cukup tinggi tetapi kemudian dibuang dari konteks, atau passage itu sampai ke model dan model tetap salah. Satu angka accuracy tidak dapat membedakannya. Oloproof menjalankan sistem RAG sebagai dua tahap yang dapat dilihatnya, mengukur masing-masing, dan mengeksekusi ulang kasus yang gagal di bawah perubahan terkendali untuk mengetahui alasan mana yang berlaku.

examples/support_rag/ adalah proyek yang dijalankan halaman ini. Proyek ini tidak memerlukan kredensial penyedia.

Sistem bertahap

Sistemnya adalah sebuah kelas dengan tahap retrieval dan tahap generation, didekorasi dengan @rag_system:

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) mengembalikan hingga depth kandidat, sebagai Passage(doc_id=..., score=..., text=...), dalam urutan yang dihasilkan retriever Anda. Oloproof mencatat posisinya dan tidak pernah mengurutkan ulang. Oloproof kemudian mempertahankan top_k pertama, membuang passage yang melewati token_budget, dan meneruskan sisanya ke generate(input, context). count_tokens(passage) hanya diperlukan bersama token_budget; Oloproof tidak pernah memperkirakan token.

oloproof.yaml menunjuk ke kelas itu dan dapat menimpa pengaturan mana pun darinya:

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 adalah bagian dari identitas retrieval. Ubah nilainya ketika indeks berubah, atau retrieval yang di-cache akan dipakai ulang terhadap indeks yang tidak lagi mengembalikannya.

Apa yang dinyatakan sebuah kasus

Kasus RAG membawa dua field di bawah expected yang tidak diperlukan jenis kasus lain:

{"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 mencantumkan dokumen yang menjawab pertanyaan. Metrik retrieval membacanya,

dan kasus tanpa field ini dikecualikan dari metrik tersebut dengan no_relevance_labels.

expected.gold_context adalah teks passage itu sendiri. Diagnosis menggantikan konteks hasil

retrieval dengannya, dan kasus gagal tanpa field ini tidak dapat didiagnosis.

Evaluatornya

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, dan ndcg menerima k dan menamai kriterianya sendiri berdasarkan nilai itu: hit_rate_at_2. Entri dalam expected.relevant juga dapat membawa chunk_id dan grade, yang bawaannya 1; relevance_unit: chunk lalu menghitung setiap chunk sebagai unit tersendiri alih-alih dokumen utuh. citation_validity memeriksa bahwa setiap id yang dikutip sebuah jawaban menyebut passage dalam konteks yang diberikan kepadanya, dan dengan require_citations: true jawaban yang tidak mengutip apa pun dinyatakan gagal. groundedness_judge dan citation_support_judge adalah juri LLM yang membaca konteks yang telah dirakit, dan menerima provider serta model seperti juri lainnya.

oloproof run

Tiga baris dari tabel metrik:

│ 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    │

Di antara keduanya, hit_rate_at_2 dan recall_at_2 sama-sama bernilai 92.3%, 12 dari 13 teramati, dengan batas bawah 63.9%: passage relevan untuk satu pertanyaan tidak pernah diambil.

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

Baris Stages adalah cache milik sistem bertahap itu sendiri. Retrieval dan generation di-cache secara terpisah, sehingga perubahan pada generation tidak pernah menjalankan ulang retrieval.

Mencari tahu penyebabnya

Empat pertanyaan gagal. diagnose mengeksekusi ulang keempatnya dengan gold passage sebagai pengganti konteks hasil retrieval, berdampingan dengan kontrol yang mengeksekusi ulang tanpa perubahan:

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

Kasus yang lolos dengan gold passage dan gagal tanpanya gagal di hulu model. Kasus yang gagal meskipun gold passage sudah tersedia adalah kesalahan model. Kontrol itulah yang membuat pembacaan tersebut aman: kasus yang pulih pada eksekusi ulang biasa itu tidak stabil, bukan terdiagnosis.

Id diagnosis mencantumkan kasus di balik setiap hitungan:

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

Diagnosis menyebut sebuah faktor, tidak pernah sebuah penyebab. "Implicated" dan "candidate experiment" adalah kata-kata terkuat yang digunakannya, karena empat kasus yang pulih di bawah satu intervensi tidak membuktikan mengapa kasus-kasus itu gagal.

Menguji perbaikan sebelum menerapkannya

Dua intervensi lain memutar ulang retrieval yang tercatat dengan pengaturan berbeda, sehingga tidak ada panggilan ke retriever. top-k melebarkan batas potongnya:

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

Tidak ada yang pulih, sesuai dengan prediksi label: tidak ada kegagalan di sini yang berupa passage dengan peringkat tepat di bawah batas potong. Pemutaran ulang membawa label gold-context ke depan, sehingga kedua diagnosis dibaca bersama. reranker menerima --reranker dengan sebuah module:function dan memutar ulang retrieval melalui reranker Anda.

Menjalankan eksperimen

Diagnosis menyebut anggaran token yang lebih besar. Naikkan token_budget ke 120 lalu jalankan lagi:

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

Setiap retrieval dipakai ulang, karena top_k dan anggaran token berada di luar identitas retrieval; hanya enam kasus yang konteksnya berubah yang di-generate ulang. Lalu bandingkan, dengan kebijakan perbandingan milik contoh ini:

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

Satu baris eksploratif menyusul untuk setiap irisan dan metrik, lalu keputusannya:

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)

Eksperimen itu tidak membantu: tidak satu pun dari ketiga belas kasus berubah vonisnya. Dan tiga belas kasus berpasangan tidak mungkin membuktikan perubahan sebesar apa pun yang berarti bagi sebuah rilis, yang merupakan hal lain yang dinyatakan interval itu.

Langkah selanjutnya

Irisan (slice) membahas relevant_position dan context_truncated.
Aturan perbandingan membahas aturan yang memutuskan langkah terakhir.
Juri membahas apa yang harus dipenuhi juri groundedness sebelum boleh menjadi

gerbang.