Handleidingen

RAG-evaluatie

De Engelse versie van deze pagina is gewijzigd sinds hij werd vertaald. De Engelse pagina is de actuele. Lees hem in het Engels

Een retrieval-augmented antwoord kan om vier verschillende redenen fout zijn: de juiste passage werd nooit opgehaald, ze werd opgehaald en te laag gerangschikt, ze werd hoog genoeg gerangschikt en daarna uit de context gelaten, of ze bereikte het model en het model deed het toch fout. Eén accuracycijfer kan ze niet uit elkaar houden. Oloproof draait een RAG-systeem als twee fasen die het kan zien, meet elke fase, en voert mislukte cases opnieuw uit onder gecontroleerde wijzigingen om uit te zoeken welke reden van toepassing is.

examples/support_rag/ is het project dat deze pagina draait. Het heeft geen providergegevens nodig.

Een gefaseerd systeem

Het systeem is een klasse met een retrievalfase en een generatiefase, gedecoreerd met @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) geeft tot depth kandidaten terug, als Passage(doc_id=..., score=..., text=...), in de volgorde waarin je retriever ze voortbracht. Oloproof legt de posities vast en herrangschikt nooit. Daarna houdt het de eerste top_k, laat het passages voorbij token_budget vallen, en geeft het wat overblijft door aan generate(input, context). count_tokens(passage) is alleen nodig met een token_budget; Oloproof schat nooit tokens.

oloproof.yaml wijst naar de klasse en mag elk van haar instellingen overschrijven:

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 maakt deel uit van de identiteit van de retrieval. Wijzig het wanneer de index verandert, anders worden gecachete retrievals hergebruikt tegen een index die ze niet meer teruggeeft.

Wat een case declareert

Een RAG-case draagt twee velden onder expected die geen enkele andere soort case nodig heeft:

{"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 somt de documenten op die de vraag beantwoorden. De retrievalmetrieken lezen

het, en een case zonder dit veld wordt ervan uitgesloten met no_relevance_labels.

expected.gold_context is de tekst van de passage zelf. Diagnose zet die in de plaats van de

opgehaalde context, en een mislukte case zonder dit veld kan niet worden gediagnosticeerd.

De evaluators

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 en ndcg nemen k en ontlenen daaraan hun eigen criteriumnaam: hit_rate_at_2. Een item in expected.relevant mag ook een chunk_id en een grade dragen, die standaard 1 is; relevance_unit: chunk telt dan elke chunk als een eigen eenheid in plaats van hele documenten. citation_validity controleert dat elke id die een antwoord citeert, een passage noemt in de context die het kreeg, en met require_citations: true faalt een antwoord dat niets citeert. groundedness_judge en citation_support_judge zijn LLM-judges die de samengestelde context lezen, en ze nemen een provider en model zoals elke andere judge.

oloproof run

Drie rijen van de metriektabel:

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

Daartussen lezen hit_rate_at_2 en recall_at_2 allebei 92.3%, 12 van 13 geobserveerd, met een ondergrens van 63.9%: de relevante passage van één vraag werd nooit opgehaald.

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

De regel Stages is de eigen cache van het gefaseerde systeem. Retrieval en generatie worden apart gecachet, dus een wijziging aan generatie draait retrieval nooit opnieuw.

Uitzoeken waarom

Vier vragen faalden. diagnose voert ze opnieuw uit met de gouden passage in plaats van de opgehaalde context, naast een controle die ze ongewijzigd opnieuw uitvoert:

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

Een case die slaagt met de gouden passage en faalt zonder, faalde vóór het model. Een case die faalt met de gouden passage in handen, is van het model. De controle is wat die lezing veilig maakt: een case die herstelt bij een gewone herhaling was wisselvallig, niet gediagnosticeerd.

De diagnose-id somt de case achter elk aantal op:

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

Ze noemt een factor, nooit een oorzaak. "Implicated" en "candidate experiment" zijn de sterkste woorden die ze gebruikt, omdat vier cases die herstellen onder één interventie niet vaststellen waarom ze faalden.

Een oplossing testen voordat je haar maakt

Twee andere interventies spelen de vastgelegde retrieval opnieuw af met een andere instelling, zodat er geen retriever wordt aangeroepen. top-k verruimt de afkapping:

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

Er herstelde niets, wat de labels voorspelden: geen enkele mislukking hier was een passage die net onder de afkapping was gerangschikt. De herhaling neemt de gold-context-labels mee, zodat de twee diagnoses samen te lezen zijn. reranker neemt --reranker met een module:function en speelt de retrieval in plaats daarvan opnieuw af via je reranker.

Het experiment draaien

De diagnose noemde een groter tokenbudget. Verhoog token_budget naar 120 en draai opnieuw:

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

Elke retrieval werd hergebruikt, omdat top_k en het tokenbudget buiten de identiteit van de retrieval vallen; alleen de zes cases waarvan de context veranderde, werden opnieuw gegenereerd. Vergelijk dan, met de vergelijkingspolicy van het voorbeeld:

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

Er volgt één verkennende regel per slice en metriek, en daarna de beslissingen:

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)

Het experiment hielp niet: geen van de dertien veranderde van oordeel. En dertien gepaarde cases hadden geen wijziging kunnen vaststellen van enige omvang waar een release om geeft, en dat is het andere dat het interval zegt.

Verder lezen

Slices behandelt relevant_position en context_truncated.
Vergelijkingsregels behandelt de regels waarmee over de laatste stap

werd beslist.

Judges behandelt waaraan een groundedness judge moet voldoen voordat die mag gaten.