Kılavuzlar
Eğitim: bir RAG uygulamasını değerlendirme
Getirmeyle güçlendirilmiş bir uygulama için çalıştırılabilir bir anlatım, iki yolda: getirmesini, bağlamını ve alıntılarını dışarıdan kaydettiğiniz, kara kutu olarak mevcut bir uygulama; ve oloproof diagnose başarısız vakaları denetimli değişiklikler altında yeniden yürütebilsin diye Oloproof'un aşama aşama çalıştırdığı aşamalı bir uygulama. İkisi de sağlayıcı kimlik bilgisi olmadan yerelde çalışır.
Her adımın arkasındaki kavramlar (aşamalar, ilgililik etiketleri, altın bağlam, dört başarısızlık etiketi) RAG değerlendirmesi sayfasındadır; vaka, değerlendirici, metrik, aralık ve kapı terimleri Temel kavramlar sayfasındadır. Bu sayfa onların içinden geçen uygulamalı yoldur.
Sizinki hangi yol
| Uygulamanız | Yol | Ne elde edersiniz | Ne elde etmezsiniz |
|---|---|---|---|
| Bir çağrı girer, bir yanıt çıkar (bir hizmet, bir HTTP uç noktası, bölmek istemediğiniz bir çatı zinciri) | A, kara kutu | Getirme metrikleri, alıntı denetimleri, dayanaklılık hakemleri, kapı denetimi, karşılaştırma | Denetimli müdahaleler: diagnose hiçbir şeyi yeniden yürütmez |
| Ayrı ayrı çağırabildiğiniz getirme ve üretim | B, aşamalı | A'daki her şey, aşama başına önbellek ve bir kontrolün yanında altın bağlam, top-k ve bir yeniden sıralayıcıyla diagnose | Bu üçü dışındaki müdahaleler |
Emin değilseniz A ile başlayın. Uygulamada hiçbir değişiklik gerektirmez ve daha sonra B'ye geçmek veri kümesini, değerlendiricileri ve politikayı korur.
Ön koşullar
- Python 3.11 veya üstü ve kurulu Oloproof (pip install oloproof).
- Paketle birlikte gelen örnek projeler: A yolu için blackbox_rag, B yolu için support_rag. Birini yeni bir dizine kopyalayın ve orada çalışın:
oloproof init --example blackbox_rag my-rag
cd my-ragAşağıdaki her komut kopyalanan dizinin içinden çalışır. Çalıştırmalar, yargılar ve teşhisler orada .oloproof/ içinde saklanır.
A yolu: kara kutu olarak mevcut bir uygulama
Dosyalar
| Dosya | Nedir |
|---|---|
| app.py | Uygulamanızın yerine geçen support_api(question) ve bağdaştırıcı olan run(case) |
| server.py | Aşağıdaki HTTP çeşidi için HTTP üzerinden aynı uygulama |
| data/corpus.jsonl | Uygulamanın aradığı 14 pasajlık bilgi tabanı |
| data/support.jsonl | 15 vaka: 13'ü ilgililik etiketleri ve altın pasajlarla, 2'si ikisi de olmadan |
| oloproof.yaml | Paket: veri kümesi, sistem, değerlendiriciler, dilimler |
| oloproof.http.yaml | HTTP sunucusuna karşı aynı paket |
| release.yaml | Tek bir çalıştırma için sürüm politikası |
| compare.yaml | Bir aday çalıştırmayı bir temelle karşılaştırma politikası |
Uygulama ne döndürür
support_api, zaten sahip olduğunuz bir uygulama gibi davranır: arar, bir sözcük bütçesine sığan en iyi kaynaklardan bir istem kurar, yanıtlar ve alıntı yapar. Yanıtı ne yaptığını zaten taşır:
{
"answer": "Team plans include five seats.",
"cited": ["kb-03"],
"sources": [{"id": "kb-03", "score": 3.0, "text": "Team plans include five seats. ..."}],
"prompt_sources": [{"id": "kb-03", "score": 3.0, "text": "...", "rank": 1, "tokens": 17}],
"skipped": [{"id": "kb-05", "rank": 3, "why": "top_k"}]
}Uygulamanızın alan adları farklı olacaktır. Önemli olan, her soru için getirdiği sıralı kaynakları, modele ulaşanları ve alıntıladıklarını size söyleyebilmesidir. Söyleyemiyorsa önce bunları yanıtına ya da günlüklerine ekleyin: Oloproof kaydedileni ölçer ve getirmeyi asla bir yanıttan çıkarsamaz.
Bağdaştırıcı
run, uygulamayı değiştirmeden çağırır ve yanıtı, getirme ve alıntı değerlendiricilerinin okuduğu kayıtlar olan üç tipli yapıta eşler:
@system(
name="support-rag-blackbox",
version="tutorial",
records=("retrieval/v1", "context/v1", "citations/v1"),
)
def run(case):
response = support_api(str(case["question"]))
recorder = current_case()
recorder.retrieval(
Retrieval(
query=case["question"],
depth=SEARCH_DEPTH,
candidates=tuple(
Passage(doc_id=s["id"], score=s["score"], text=s["text"])
for s in response["sources"]
),
)
)
recorder.context(
Context(
items=tuple(
ContextItem(doc_id=i["id"], position=i["rank"], tokens=i["tokens"], text=i["text"])
for i in response["prompt_sources"]
),
dropped=tuple(
DroppedItem(doc_id=i["id"], position=i["rank"], reason=i["why"])
for i in response["skipped"]
),
token_budget=PROMPT_WORD_BUDGET,
)
)
recorder.citations(response["cited"])
return {"answer": response["answer"], "citations": response["cited"]}| Yapıt | Biçim | Okuyan |
|---|---|---|
| retrieval/v1 | query, depth ve getiricinizin döndürdüğü sırayla candidates, her biri bir Passage(doc_id, chunk_id, score, text) | hit_rate, recall, mrr, ndcg |
| context/v1 | Modele ulaşan items (doc_id, position, tokens, text), top_k ya da token_budget değerinde bir reason taşıyan dropped öğeleri ve token_budget | citation_validity, groundedness_judge, citation_support_judge |
| citations/v1 | ids, her biri bir doc_id ya da doc_id#chunk_id | citation_validity, citation_support_judge |
Oloproof konumları verildiği gibi kaydeder ve asla yeniden sıralamaz. Hatalı biçimli bir yapıt saklanmak yerine çalıştırmayı 2 çıkış koduyla durdurur. case, vakanın input nesnesidir, yani case["question"] veri kümesindeki sorudur.
Kendi uygulamanızı kullanmak için support_api gövdesini ona yapılan bir çağrıyla (bir SDK çağrısı, bir HTTP isteği) değiştirin ve run fonksiyonunu tutun. oloproof.yaml içindeki system.callable değerini module:function olarak ona yöneltin.
HTTP çeşidi
Bir HTTP sistemi kaydediciyi çağıramaz, bu yüzden kanıtı onun yerine yanıtı taşır, zaten yukarıdaki üç biçimde, ve yapılandırma nerede olduğunu adlandırır:
system:
name: support-rag-http
version: tutorial
http:
url: http://127.0.0.1:8766/answer
output_path: result
artifacts:
retrieval/v1: evidence.retrieval
context/v1: evidence.context
citations/v1: evidence.citationsserver.py tam olarak bunu sunar. Onu başlatın, sonra ona karşı çalıştırın:
python server.py 8766
oloproof run --config oloproof.http.yamlVaka girdisi JSON gövdesi olarak gönderilir. output_path çıktıyı yanıttan seçer ve her artifacts girdisi noktalı bir yolu o tür olarak kaydeder; eksik ya da hatalı biçimli bir alan çalıştırmayı 2 çıkış koduyla durdurur. Sonuçlar aşağıdaki callable yoluyla aynıdır. Kendi hizmetinizde kanıt nesnesi genellikle değerlendirme trafiği için etkinleştirdiğiniz bir hata ayıklama alanıdır.
Bir vaka neyi bildirir
{"id":"seat_count","input":{"question":"How many seats does a team plan include?"},"expected":{"answer":"5 seats","relevant":[{"doc_id":"kb-03"}],"gold_context":[{"doc_id":"kb-03","text":"Team plans include five seats. ..."}]},"metadata":{"topic":"billing"}}
{"id":"office_hours","input":{"question":"What are the support office hours?"},"expected":{"answer":"09:00"},"metadata":{"topic":"account"}}- expected.relevant, soruyu yanıtlayan pasajları listeler. Getirme metrikleri onu okur. office_hours gibi onsuz bir vaka bu metriklerden no_relevance_labels ile dışlanır: bir geçiş ya da başarısızlık sayılmak yerine paydadan çıkar.
- expected.gold_context pasaj metninin kendisidir. A yolu onu asla kullanmaz; B yolu teşhis sırasında onu getirilen bağlamın yerine koyar.
Etiketsiz vakalar pratikte olağandır, çünkü ilgililiği etiketlemek emek ister. Yanıt ve alıntı denetimlerinde yine de sayılırlar.
Değerlendiricileri seçme
evaluators:
- {type: contains, criterion: answer_correct, field: answer, expected_field: answer}
- {type: hit_rate, k: 2}
- {type: recall, k: 2}
- {type: citation_validity, require_citations: true}
slices: [metadata.topic]
min_slice_support: 4- contains, yanıtın beklenen metni içerip içermediğini denetler. Görev denetimidir: kullanıcı doğru yanıtı aldı mı. İfadeler değiştiğinde onun yerine tam eşleşme ya da bir rubrik hakemi kullanın.
- k: 2 değerindeki hit_rate ve recall, getirmeyi uygulamanın istemine gerçekten koyduğu derinlikte ölçer. Modelin hiç görmediği bir derinlikteki bir getirme metriği uygulamayı değil dizini tarif eder.
- citation_validity, alıntılanan her kimliğin modele ulaşmış bir pasajı adlandırdığını denetler; require_citations: true hiçbir şey alıntılamayan bir yanıtı da başarısız sayar.
- groundedness_judge ve citation_support_judge (isteğe bağlı), bir modele yanıtın bağlam tarafından desteklenip desteklenmediğini sorar. Bir sağlayıcı, bir model ve bir ortam değişkeninde kimlik bilgileri gerektirirler ve vaka başına para tutarlar; bir hakemin kapı denetimi yapabilmesi için neyi geçmesi gerektiği için Hakemler sayfasına bakın.
relevant_position ve context_truncated dilimleri burada kullanılamaz: konumları uygulamanın top-k değeriyle karşılaştırırlar, bunu da yalnızca aşamalı bir sistem bildirir. Onları istemek çalıştırmayı slice 'relevant_position' compares relevant positions with top_k, so it needs a staged system ile durdurur.
Sürüm politikası
version: 1
confidence_level: 0.95
block_on: [FAIL, INSUFFICIENT_EVIDENCE, MANUAL_REVIEW]
rules:
- id: answer-floor
metric: answer_correct
min: 0.70
- id: retrieval-floor
metric: hit_rate_at_2
min: 0.80
- id: citations-valid
metric: citations_valid
kind: observed_count
max_failures: 0Bir min kuralı yalnızca aralığın tamamı tabanı aştığında geçer, aralığın tamamı tabanın altında kaldığında başarısız olur, aksi halde INSUFFICIENT_EVIDENCE olur. Bir observed_count kuralı gerçekten çalıştırılan vakalar üzerinde, aralık olmadan karar verir: "bu pakette geçersiz alıntı yok". Bkz. Kapı denetimi.
Çalıştırın
oloproof runRun run_01M4FCBPE0G550CKCVGXCNEM2P [DECIDED/COMPLETE]
Gate: BLOCK (exit 1)
│ answer-floor │ answer_correct │ INSUFFICIENT_EVIDENCE │ interval_overlaps_threshold │
│ retrieval-floor │ hit_rate_at_2 │ INSUFFICIENT_EVIDENCE │ interval_overlaps_threshold │
│ citations-valid │ citations_valid │ FAIL │ observed_failures_exceed_limit │
│ answer_correct │ 73.3% │ [44.8%, 92.3%] │ 11 / 15 observed · 0 missing · 0 excluded │
│ hit_rate_at_2 │ 92.3% │ [63.9%, 99.9%] │ 12 / 13 observed · 0 missing · 2 excluded │
│ recall_at_2 │ 92.3% │ [63.9%, 99.9%] │ 12 / 13 observed · 0 missing · 2 excluded │
│ citations_valid │ 93.3% │ [68.0%, 99.9%] │ 14 / 15 observed · 0 missing · 0 excluded │
Cache: execution 0 hit/15 miss; judgment 0 hit/56 missNasıl okunur:
- Gate: BLOCK (exit 1): bir kural FAIL oldu. 1 çıkışı bir FAIL demektir; 3 çıkışı kapının FAIL olmadan engellediği demektir (burada INSUFFICIENT_EVIDENCE olurdu); 0 çıkışı politikanın engellediği hiçbir şey olmadığı demektir. [DECIDED/COMPLETE] yürütme durumudur: her vaka çalıştı.
- citations-valid FAIL olur: bir yanıt hiçbir şey alıntılamadı ve require_citations bunu geçersiz sayar.
- answer-floor, %73,3 %70'in üzerinde olsa da PASS değil INSUFFICIENT_EVIDENCE olur: 15 vakayla aralık %44,8'e kadar iner, bu yüzden kanıt tabanın karşılandığını gösteremez.
- hit_rate_at_2, 2 excluded gösterir: iki etiketsiz vaka. Paydası 15 değil 13'tür.
- Ardından gelen Slices tablosu keşif amaçlıdır ve asla kapı denetimine girmez; min_slice_support altındaki bir dilim aralık göstermez.
Başarısızlıkları inceleyin
Çalıştırma kimliği, çalıştırma çıktısının ilk satırındadır.
oloproof inspect RUN_ID --failures4 of 15 cases failed, errored or did not finish
refund_review
output: {"answer": "Every refund request on an annual plan is logged in the audit trail, and the same request is listed again on the day it was reviewed and approved."…
answer_correct: failed
money_back
output: {"answer": "I could not find that in the knowledge base.", "citations": []}
answer_correct: failed
hit_rate_at_2: failed
recall_at_2: failed
citations_valid: failed
security_review
output: {"answer": "Security reviews during Enterprise onboarding include an access review and a written summary for the customer, and every review is scheduled with t…
answer_correct: failed
seat_count
output: {"answer": "Team plans include five seats.", "citations": ["kb-03"]}
answer_correct: failedoloproof inspect RUN_ID --case refund_review, bir vakanın girdisini, beklenen değerlerini, çıktısını ve her yargıyı yazdırır. Kaydedilen yapıtlar dışa aktarılan pakettedir:
oloproof export RUN_ID.oloproof/bundles/RUN_ID/cases.jsonl dosyasının her satırı bir vakanın kaydıdır; artifacts alanı kaydedilenleri tutar. money_back için bu alan şöyledir:
{"retrieval/v1": [{"candidates": [], "depth": 6, "query": "Where do I claim money back on a yearly subscription?"}], "context/v1": [{"dropped": [], "items": [], "source": "retrieval", "token_budget": 40}], "citations/v1": [{"ids": []}]}Dört başarısızlığı yalnızca kaydedilen kanıttan okumak:
| Vaka | Kaydın gösterdiği | Anlamlı bir sonraki eylem |
|---|---|---|
| money_back | Getirme hiçbir şey döndürmedi: soru iade pasajıyla hiçbir sözcüğü paylaşmıyor | Sorgu yeniden yazımı ya da eş anlamlılar, hit_rate_at_2 ile ölçülür |
| refund_review, security_review | hit_rate_at_2 geçti, yine de yanıt başka bir pasajdan geldi | context/v1 inceleyin: ilgili pasaj bütçe yüzünden mi düşürüldü? |
| seat_count | Doğru pasaj getirildi, tutuldu ve alıntılandı; yanıt "five" diyor, vaka "5" bekliyor | Getirmeyi değil, beklentiyi ya da yanıt biçimini düzeltin |
Bu tablo sizin kayıt okumanızdır. Bir başarısızlıkla bir aşama arasında bir ilişkidir, kanıtlanmış bir neden değil: hiçbir şey vakayı aşama değiştirilmiş olarak yeniden yürütmedi.
diagnose bir kara kutuda ne yapar
oloproof diagnose RUN_ID --intervention gold-context --criterion answer_correctSelected: 4 failed cases with gold context (observed; no population claim)
UNRESOLVED: 4 of 4, the system is not staged, so no case was re-executed
Diagnosis sha256:8809e100ab2ec1dad8ffeacc136cd510300081a0edf01ec11f881c543ed104bc
Cases: oloproof inspect sha256:8809e100ab2ec1dad8ffeacc136cd510300081a0edf01ec11f881c543ed104bcHer vaka intervention_unsupported gerekçesiyle UNRESOLVED olur. Oloproof bir kara kutuya kendi getirmesinin yerine altın pasajı veremez, bu yüzden veriyormuş gibi yapmaz. Denetimli müdahaleler B yolunu gerektirir.
Bir aday değişiklik yapın ve karşılaştırın
Kayıt, money_back vakasının getirmede başarısız olduğunu söylüyor. Aday değişiklik, aramadan önce soruyu eş anlamlılarla genişletir. app.py içinde:
EXPAND_QUERY = TrueKodu değiştirmek, çalıştırma için kaydedilen sistem sürümünü değiştirir. Yeniden çalıştırın, sonra adayı temelle karşılaştırın:
oloproof run
oloproof compare CANDIDATE_RUN_ID BASELINE_RUN_ID --policy compare.yamlYalnızca aday çalıştırma: citations-valid artık PASS olur, hit_rate_at_2 100.0% [75.2%, 100.0%] gösterir ve answer-floor ile retrieval-floor INSUFFICIENT_EVIDENCE kaldığı için kapı hâlâ 3 çıkışıyla engeller. Karşılaştırma:
Comparison sha256:2feb024c… of run_01M4FCCJYCVVYA8NB4XZDV6YMB against run_01M4FCCHVBG9WHDP7G5HFX7RDT · 15 paired cases
answer_correct: +6.7 points [-26.5, +40.8] · 15 paired · 0 missing · 0 excluded
hit_rate_at_2: +7.7 points [-29.8, +45.5] · 13 paired · 0 missing · 2 excluded
excluded 2: no_relevance_labels
recall_at_2: +7.7 points [-29.8, +45.5] · 13 paired · 0 missing · 2 excluded
excluded 2: no_relevance_labels
citations_valid: +6.7 points [-26.5, +40.8] · 15 paired · 0 missing · 0 excluded
20 exploratory slice differences not shown; add --slices to list them
Decisions
answers-not-worse answer_correct non-inferiority, margin 5.0 points INSUFFICIENT_EVIDENCE interval_overlaps_margin
about 38 more paired cases would decide it, if the difference holds (53 in total at 7% discordance)
citations-not-worse citations_valid non-inferiority, margin 2.0 points INSUFFICIENT_EVIDENCE interval_overlaps_margin
about 68 more paired cases would decide it, if the difference holds (83 in total at 7% discordance)
Gate: BLOCK (exit 3)Değişiklik hedeflediği vakayı düzeltti (bir yanıt daha, 15 eşleştirilmiş vakada +6,7 puan). Karşılaştırma yine de adayın temelden marjdan daha fazla kötü olmadığını ortaya koyamaz: 15 eşleştirilmiş vaka yaklaşık 67 puan genişliğinde bir aralık bırakır. Planlama satırı, fark sürerse kaç eşleştirilmiş vakanın daha bunu karara bağlayacağını söyler. Sonraki eylem farklı bir marj değil, daha büyük bir pakettir. Bkz. İki çalıştırmayı karşılaştırma ve Karşılaştırma kuralları.
B yolu: teşhisli aşamalı bir uygulama
Aşamalı dosyalar
B yolu, RAG değerlendirmesi sayfasında anlatılan support_rag örneğini çalıştırır. Onu kopyalayın:
oloproof init --example support_rag my-staged-rag
cd my-staged-rag| Dosya | Nedir |
|---|---|
| app.py | @rag_system ile süslenmiş bir sınıf olan SupportRag: retrieve(input, depth), generate(input, context), count_tokens(passage) |
| data/corpus.jsonl, data/support.jsonl | Bilgi tabanı ve her biri relevant ve gold_context içeren 13 vaka |
| oloproof.yaml | system.rag sınıfı gösterir ve depth, top_k, token_budget, index_version ayarlar |
| release.yaml, compare.yaml | A yolundakiyle aynı politikalar |
A yolundan farkı, bağlamı kimin kurduğudur. Burada Oloproof retrieve çağırır, ilk top_k adayı tutar, token_budget ötesindeki pasajları düşürür ve kalanı generate fonksiyonuna verir. Aşamaları ayrı tuttuğu için onları ayrı ayrı önbelleğe alabilir ve üretimi farklı bir bağlamla yeniden yürütebilir. Kendi uygulamanızı uyarlamak için retrieve gövdesini (dizininizi çağırın, getiricinizin sırasıyla Retrieval(candidates=[Passage(...)]) döndürün) ve generate gövdesini (modelinizi verilen pasajlarla çağırın) değiştirin. index_version değerini dizininiz değiştiğinde değişen bir şeye ayarlayın: getirmenin kimliğinin parçasıdır ve eskimiş bir değer, önbellekteki getirmeleri artık onları döndürmeyen bir dizine karşı yeniden kullanır.
Aynı yapılandırma ayrıca relevant_position ve context_truncated dilimlerine ve tam getirme derinliği üzerinde bir ndcg değerlendiricisine izin verir.
Aşamalı paketi çalıştırın
oloproof runGate: BLOCK (exit 3)
│ answer-floor │ answer_correct │ INSUFFICIENT_EVIDENCE │ interval_overlaps_threshold │
│ retrieval-floor │ hit_rate_at_2 │ INSUFFICIENT_EVIDENCE │ interval_overlaps_threshold │
│ citations-valid │ citations_valid │ PASS │ observed_failures_within_limit │
│ answer_correct │ 69.2% │ [38.5%, 91.0%] │ 9 / 13 observed · 0 missing · 0 excluded │
│ hit_rate_at_2 │ 92.3% │ [63.9%, 99.9%] │ 12 / 13 observed · 0 missing · 0 excluded │
│ recall_at_2 │ 92.3% │ [63.9%, 99.9%] │ 12 / 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 │
Cache: execution 0 hit/13 miss; judgment 0 hit/65 miss
Stages: retrieve 0 hit/13 miss; generate 0 hit/13 missStages satırı aşamalı sistemin kendi önbelleğidir. 3 çıkışı: hiçbir şey FAIL olmadı, ama iki kuralın PASS olmak için kanıtı eksik.
Bir kontrolün yanında altın bağlamla teşhis
oloproof diagnose RUN_ID --intervention gold-context --criterion answer_correctSelected: 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:50a6124f…
Child runs: gold context run_…, control run_…
Cases: oloproof inspect sha256:50a6124f…Başarısız vakalardan iki alt çalıştırma yapılır: biri getirilen bağlamın yerine vakanın gold_context değeriyle, diğeri onları değiştirmeden yeniden yürüten bir kontrol. Okumayı güvenli kılan kontroldür: düz bir yeniden çalıştırmada geçen bir vaka teşhis edilmiş değil, kararsızdır. diagnose ne bulursa bulsun 0 ile çıkar; sürüm hakkında hiçbir karar vermez.
oloproof inspect DIAGNOSIS_IDmoney_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 2Etiketleri okuma
| Etiket | Ne gözlendi | Neyi ortaya koymaz |
|---|---|---|
| RETRIEVAL_MISS | Hiçbir ilgili pasaj getirilmedi ve vaka altın pasajla geçti | Tek sorunun getirme olduğunu ya da belirli bir getirme değişikliğinin onu düzelteceğini |
| RANKED_OUT | İlgili bir pasaj top_k altında getirildi ve vaka altın pasajla geçti | top-k'yı genişletmenin diğer vakalara yardım edeceğini |
| CONTEXT_ASSEMBLY_LOSS | top-k içindeki ilgili bir pasaj bağlamdan düşürüldü ve vaka altın pasajla geçti | Hangi bütçenin yeterli olacağını |
| GENERATION_FAILURE | Vaka altın pasaj elindeyken bile başarısız oldu | Kusurun istemde ya da beklentide değil modelde olduğunu |
| UNRESOLVED | Hiçbir sonuca varılamadı: sistem aşamalı değil (intervention_unsupported), vaka kontrol altında düzeldi (unstable_under_control), ilgililik etiketi yok (no_relevance_labels) ya da kanıt eksik | Vaka hakkında herhangi bir şeyi |
Her etiket, bu vakalarda tek bir müdahale altında bir başarısızlıkla bir aşama arasındaki bir ilişkidir. Kanıtlanmış bir neden değildir: "Implicated" ve "Candidate experiment" çıktının kullandığı en güçlü sözcüklerdir ve sayılar yalnızca seçilen vakaları tarif eder ("no population claim"). seat_count iyi bir hatırlatmadır: doğru pasajla başarısız olur, çünkü bilgi tabanı "five" der ve vaka "5" bekler; bunu hiçbir getirme değişikliği düzeltemez.
Altın pasajlı ve altın pasajsız vakalar
Yalnızca expected.gold_context bildiren başarısız vakalar yeniden yürütülebilir. Altın pasajı seat_count ve money_back vakalarından (ve ilgililik etiketini money_back vakasından) kaldırın; aynı komut şunu bildirir:
Selected: 2 failed cases with gold context (observed; no population claim)
Excluded: 2 failed cases, no_gold_context - declare the passages that would have answered the case in its `expected.gold_context`, as a list of `{doc_id, text}` objects; an intervention needs them to tell a retrieval failure from a generation one
Control: 0 of 2 passed when re-executed without the intervention
Recovered under gold context: 2 of 2
CONTEXT_ASSEMBLY_LOSS: 2 of 2, recovered; relevant evidence within top-k was left out of the contextDışlanan vakalar listelenir, sessizce atılmaz. Bir ilgililik etiketini kaldırmanın çalıştırmanın kendisine ne yaptığına da dikkat edin: getirmenin kaçırdığı tek vaka artık ölçülmediği için hit_rate_at_2 100.0%'a yükseldi (12 / 12 observed, 1 excluded). Etiketsiz vakalar paydadan çıkar; geçiş sayılmazlar ve daha az vaka üzerindeki bir metrik uygulamanın olduğundan daha iyi görünebilir. Önce zor vakaları etiketleyin.
Bir düzeltmeyi yapmadan önce test edin: top-k ve bir yeniden sıralayıcı
İki müdahale daha, kaydedilen getirmeyi farklı bir ayarla yeniden oynatır, bu yüzden getirici yeniden çağrılmaz:
oloproof diagnose RUN_ID --intervention top-k --top-k 4 --criterion answer_correctRecovered 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:50a6124f…): 3 of 4 recoveredBir yeniden sıralayıcı, sizin yazdığınız (input, candidates) -> candidates biçiminde bir fonksiyondur. Onu app.py yanına rerank.py olarak kaydedin:
"""A candidate reranker: shorter passages first, so more of them fit the token budget."""
from oloproof import Passage
def shortest_first(input: dict, candidates: list[Passage]) -> list[Passage]:
return sorted(candidates, key=lambda passage: len((passage.text or "").split()))oloproof diagnose RUN_ID --intervention reranker --reranker rerank:shortest_first --criterion answer_correctRecovered under reranker rerank:shortest_first: 0 of 4
Confirmed under reranker rerank:shortest_first: 0 of 0 RANKED_OUT cases also recoveredİkisi de hiçbir şeyi düzeltmez; altın bağlam etiketlerinin öngördüğü de buydu: buradaki hiçbir başarısızlık, kesimin hemen altında sıralanmış bir pasaj değildi. Her yeniden oynatma altın bağlam etiketlerini ileri taşır, böylece teşhisler birlikte okunur.
Teşhisin adlandırdığı deneyi çalıştırın ve karşılaştırın
oloproof.yaml içinde token_budget değerini 120 yapın, sonra:
oloproof run
oloproof compare CANDIDATE_RUN_ID BASELINE_RUN_ID --policy compare.yamlStages: retrieve 13 hit/0 miss; generate 7 hit/6 missHer getirme yeniden kullanıldı, çünkü top_k ve bütçe getirmenin kimliğinin dışındadır; yalnızca bağlamı değişen altı vaka yeniden üretildi.
answer_correct: +0.0 points [-33.6, +33.6] · 13 paired · 0 missing · 0 excluded
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ı: tek bir vaka bile hükmünü değiştirmedi, bu yüzden teşhisin önerdiği hipotez bu vakalar için desteklenmiyor. Bu yararlı bir sonuçtur. Sonraki deney daha küçük parçalar ya da iki bağlam kurma vakasının istemleridir; seat_count vakasının beklentisinin düzeltilmesi gerekir.
Sorun giderme
| Belirti | Neden | Çözüm |
|---|---|---|
| Configuration error: slice 'relevant_position' ... needs a staged system | Bir callable ya da HTTP sistemi üzerinde bir konum dilimi | Dilimi kaldırın ya da B yoluna geçin |
| Çalıştırma 2 çıkışı ve malformed retrieval/v1 artifact ile duruyor | Şemanın izin vermediği bir alan ya da depth değerinden fazla aday | Yalnızca belgelenmiş alanları eşleyin; depth değerini en az döndürülen sayıya ayarlayın |
| citations_valid, 0 / 0 observed · 15 missing gösteriyor ve kuralı no_observations ile INSUFFICIENT_EVIDENCE | Bağdaştırıcı citations/v1 (ya da context/v1) kaydetmedi; böyle her vaka geçmiş değil eksiktir | İkisini de "yanıt yok" dahil bağdaştırıcıdaki her yolda kaydedin; oloproof inspect RUN_ID --failures hatayı vaka başına gösterir |
| Bir getirme metriği çok sayıda excluded gösteriyor | expected.relevant olmayan vakalar | Onları etiketleyin ya da daha küçük paydayı bilerek kabul edin |
| diagnose, UNRESOLVED ... not staged diyor | A yolu | Beklenen durum; müdahaleler için B yolunu kullanın |
| diagnose, an intervention must re-execute the same system ile reddediyor | Çalıştırmadan bu yana kod ya da yapılandırma değişti | Geçerli sürümün bir çalıştırmasını teşhis edin ya da çalışan sürümü geri getirin |
| Teşhis, başarısız olandan daha az vaka seçiyor | expected.gold_context olmayan başarısız vakalar | Altın pasajları ekleyin; dışlanan vakalar çıktıda adlandırılır |
| Dizin değiştikten sonra getirmeler yeniden kullanılıyor | index_version değişmedi | Dizin değiştiğinde index_version değerini değiştirin |
Sınırlamalar
- Oloproof uygulamanızı çağırır; onu barındırmaz, yalıtmaz ya da sıfırlamaz. Dizini, önbellekleri ve tuttuğu her durum sizindir.
- Bir kara kutuda müdahaleler kullanılamaz: diagnose her vakayı UNRESOLVED olarak etiketler ve hiçbir şeyi yeniden yürütmez.
- Müdahaleler altın bağlam, top-k ve bir yeniden sıralayıcıdır. Parçalama, gömme ya da istem müdahalesi yoktur.
- Teşhis etiketleri, bir kontrolün yanında tek bir müdahale altında seçilen başarısız vakaları tarif eder. Bir başarısızlığı bir aşamayla ilişkilendirirler; bir nedeni kanıtlamazlar ve seçilmeyen vakalar hakkında hiçbir iddiada bulunmazlar.
- Getirme metrikleri ilgililik etiketleri, teşhis ise altın pasajlar gerektirir; Oloproof ikisini de oluşturmaz.
- Deterministik örnekler gerçek bir getiricinin ve modelin yerine geçer. generate içindeki canlı bir model ya da bir hakem değerlendirici bir sağlayıcıyı çağırır, kimlik bilgisi gerektirir ve vaka başına para tutar.
- Neyin nerede çalıştığı, SDK, YAML ve tarayıcı karşılaştırmalı olarak, Bugün neler çalışıyor sayfasındadır.