Hướng dẫn

Đánh giá RAG

Phiên bản tiếng Anh của trang này đã thay đổi kể từ khi được dịch. Trang tiếng Anh là bản hiện hành. Đọc bằng tiếng Anh

Một câu trả lời có tăng cường truy xuất có thể sai vì bốn lý do khác nhau: đoạn văn đúng chưa bao giờ được truy xuất, nó được truy xuất nhưng bị xếp hạng quá thấp, nó được xếp hạng đủ cao nhưng sau đó bị loại khỏi ngữ cảnh, hoặc nó đã tới được mô hình nhưng mô hình vẫn trả lời sai. Một con số accuracy duy nhất không thể phân biệt các trường hợp này. Oloproof chạy một hệ thống RAG như hai giai đoạn mà nó có thể quan sát, đo từng giai đoạn, và thực thi lại các trường hợp thất bại dưới những thay đổi có kiểm soát để tìm ra lý do nào đúng.

examples/support_rag/ là dự án mà trang này chạy. Nó không cần thông tin xác thực của nhà cung cấp nào.

Một hệ thống theo giai đoạn

Hệ thống là một lớp có giai đoạn truy xuất và giai đoạn sinh, được trang trí bằng @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) trả về tối đa depth ứng viên truy xuất, dưới dạng Passage(doc_id=..., score=..., text=...), theo thứ tự mà bộ truy xuất của bạn tạo ra. Oloproof ghi lại các vị trí và không bao giờ xếp hạng lại. Sau đó nó giữ top_k đầu tiên, loại bỏ các đoạn văn vượt quá token_budget, và chuyển phần còn lại cho generate(input, context). count_tokens(passage) chỉ cần khi có token_budget; Oloproof không bao giờ ước lượng số token.

oloproof.yaml trỏ tới lớp đó và có thể ghi đè bất kỳ thiết lập nào của nó:

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 là một phần định danh của lần truy xuất. Hãy thay đổi nó khi chỉ mục thay đổi, nếu không các kết quả truy xuất đã lưu trong bộ nhớ đệm sẽ được dùng lại với một chỉ mục không còn trả về chúng nữa.

Một trường hợp khai báo những gì

Một trường hợp RAG mang hai trường dưới expected mà không loại trường hợp nào khác cần:

{"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 liệt kê các tài liệu trả lời câu hỏi. Các chỉ số truy xuất đọc

trường này, và một trường hợp không có nó sẽ bị loại trừ khỏi các chỉ số đó với no_relevance_labels.

expected.gold_context là chính văn bản của đoạn văn. Chẩn đoán thay nó vào chỗ ngữ cảnh đã truy xuất,

và một trường hợp thất bại không có nó thì không thể được chẩn đoán.

Các bộ đánh giá

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 và ndcg nhận k và tự đặt tên tiêu chí của chúng từ đó: hit_rate_at_2. Một mục trong expected.relevant cũng có thể mang chunk_id và grade, giá trị này mặc định là 1; khi đó relevance_unit: chunk tính mỗi chunk là một đơn vị riêng thay vì cả tài liệu. citation_validity kiểm tra rằng mọi id mà câu trả lời trích dẫn đều chỉ tới một đoạn văn trong ngữ cảnh mà nó được cung cấp, và với require_citations: true, một câu trả lời không trích dẫn gì sẽ thất bại. groundedness_judge và citation_support_judge là các giám khảo LLM đọc ngữ cảnh đã được ghép, và nhận provider và model như mọi giám khảo khác.

oloproof run

Ba hàng của bảng chỉ số:

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

Ở giữa chúng, hit_rate_at_2 và recall_at_2 đều cho 92.3%, 12 trên 13 được quan sát, với cận dưới 63.9%: đoạn văn liên quan của một câu hỏi chưa bao giờ được truy xuất.

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

Dòng Stages là bộ nhớ đệm riêng của hệ thống theo giai đoạn. Truy xuất và sinh được lưu đệm riêng biệt, nên một thay đổi ở phần sinh không bao giờ chạy lại phần truy xuất.

Tìm ra lý do

Bốn câu hỏi đã thất bại. diagnose thực thi lại chúng với đoạn văn chuẩn thay cho ngữ cảnh đã truy xuất, bên cạnh một nhóm đối chứng thực thi lại chúng mà không thay đổi gì:

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

Một trường hợp đạt khi có đoạn văn chuẩn và thất bại khi không có nó là đã thất bại ở phía trước mô hình. Một trường hợp thất bại ngay cả khi đã có đoạn văn chuẩn là lỗi của mô hình. Nhóm đối chứng là điều giúp cách đọc đó an toàn: một trường hợp phục hồi khi chỉ chạy lại đơn thuần là không ổn định, chứ không phải đã được chẩn đoán.

Id của chẩn đoán liệt kê trường hợp đứng sau mọi số đếm:

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

Nó nêu tên một yếu tố, không bao giờ là một nguyên nhân. "Implicated" và "candidate experiment" là những từ mạnh nhất mà nó dùng, vì bốn trường hợp phục hồi dưới một can thiệp không xác lập được lý do chúng thất bại.

Kiểm thử một bản sửa trước khi thực hiện nó

Hai can thiệp khác phát lại kết quả truy xuất đã ghi với một thiết lập khác, nên không có lời gọi bộ truy xuất nào được thực hiện. top-k mở rộng ngưỡng cắt:

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

Không có gì phục hồi, đúng như các nhãn đã dự đoán: không thất bại nào ở đây là một đoạn văn bị xếp hạng ngay dưới ngưỡng cắt. Lần phát lại mang theo các nhãn gold-context, nên hai chẩn đoán được đọc cùng nhau. reranker nhận --reranker với một module:function và thay vào đó phát lại kết quả truy xuất qua bộ xếp hạng lại của bạn.

Chạy thí nghiệm

Chẩn đoán đã nêu tên một ngân sách token lớn hơn. Tăng token_budget lên 120 và chạy lại:

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

Mọi kết quả truy xuất đều được dùng lại, vì top_k và ngân sách token nằm ngoài định danh của lần truy xuất; chỉ sáu trường hợp có ngữ cảnh thay đổi mới được sinh lại. Sau đó so sánh, với chính sách so sánh của ví dụ:

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

Tiếp theo là một dòng thăm dò cho mỗi lát cắt và chỉ số, rồi đến các quyết định:

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)

Thí nghiệm không giúp ích: không một trường hợp nào trong mười ba trường hợp thay đổi kết luận. Và mười ba trường hợp ghép cặp cũng không thể xác lập một thay đổi ở bất kỳ quy mô nào mà một lần phát hành quan tâm, đó là điều còn lại mà khoảng tin cậy cho biết.

Lát cắt trình bày relevant_position và context_truncated.
Quy tắc so sánh trình bày các quy tắc đã quyết định bước cuối cùng.
Giám khảo trình bày những gì một giám khảo groundedness phải vượt qua trước khi được phép làm cổng.