SDK başvurusu

oloproof ve oloproof.evaluators paketlerinin dışa aktardığı her ad; imzası, eşzamanlı mı eşzamansız mı olduğu ve ne döndürdüğüyle birlikte. Rehberli bir giriş için önce Python API'si sayfasını okuyun.

Herkese açık yüzey yalnızca bu iki pakettir. oloproof_core içinden içe aktarılan her şey motorun iç yapısıdır ve haber verilmeden değişebilir. Aşağıdaki her fonksiyon projenin deposuna karşı yerelde çalışır; verdiğiniz bir değerlendirici bir model sağlayıcısını çağırmadıkça hiçbiri herhangi bir yere veri göndermez.

Bir değerlendirme çalıştırma

evaluate ve aevaluate

def evaluate(*, system, dataset, evaluators, policy=None, **kwargs) -> EvaluationResult
async def aevaluate(*, system, dataset, evaluators, policy=None, **kwargs) -> EvaluationResult

evaluate eşzamanlıdır. Çalışan bir olay döngüsü yokken çağrıldığında asyncio.run kullanır; çalışan bir döngünün içinden (bir not defteri, eşzamansız bir test) çağrıldığında değerlendirmeyi ayrı bir iş parçacığında çalıştırır ve bitene kadar bekler; bu yüzden iki yerde de güvenlidir. aevaluate eşyordamdır; eşzamansız koddan onu await edin.

Kalan anahtar sözcüklü argümanlar (metrics, store, predictive, event_sink, retry_policy, traffic_draw_id) oloproof_core içinden motor türleri alır ve kararlı yüzeyin parçası değildir.

from oloproof import evaluate, system, current_case
from oloproof.evaluators import ExactMatch, evaluator

@system(name="support-bot", version="1")
def answer(case):
    current_case().usage(input_tokens=12, output_tokens=3)
    return {"label": "refund" if "refund" in case["question"].lower() else "other"}

@evaluator(criterion="short_label")
def short_label(case):
    return len(case.output["label"]) <= 6

result = evaluate(
    system=answer,
    dataset="cases.jsonl",
    evaluators=[ExactMatch(criterion="correct_label", field="label"), short_label],
)
for metric in result.metrics:
    print(metric.metric, metric.estimate, metric.interval, metric.n_observed, metric.n_missing)

Politikasız iki vakalık bir pakette çalıştırıldığında şunu yazdırdı:

correct_label 1.0 lower=0.15811388300841903 upper=1.0 2 0
short_label 1.0 lower=0.15811388300841903 upper=1.0 2 0

EvaluationResult

Durumların, neden kodlarının ve sayıların ne anlama geldiği Sonuçlar ve yürütme sayfasındadır.

evaluate_comparison ve aevaluate_comparison

def evaluate_comparison(*, candidate_system, baseline_system, dataset, evaluators, policy, **kwargs) -> ComparisonEvaluationResult
async def aevaluate_comparison(*, candidate_system, baseline_system, dataset, evaluators, policy, **kwargs) -> ComparisonEvaluationResult

İki sistemi aynı paket üzerinde tohumlanmış tek bir sırayla çalıştırır ve politikanın karşılaştırma kurallarına karar verir. policy zorunludur ve en az bir superiority, non_inferiority ya da equivalence kuralı içermelidir; aksi halde çağrı bir yapılandırma hatası fırlatır. Ek anahtar sözcüklü argümanlar: concurrency, replicates ve motor türlü metrics, store ve retry_policy. Eşzamanlı ve eşzamansız davranış evaluate için olduğu gibidir.

ComparisonEvaluationResult, candidate ve baseline (her biri bir EvaluationResult) ile eşleştirilmiş farkları ve kararlarını taşıyan comparison değerine sahiptir. Bkz. İki sürümü karşılaştırma.

Bir sistem bildirme

@system

def system(func=None, *, name=None, version=None, config=None, timeout_s=None, records=())

Yalın (@system) ya da argümanlarla (@system(name=..., version=...)) kullanılabilir veya bir nesne üzerinde çağrılabilir (system(model.answer, version="v2")). Fonksiyon vakanın tamamını değil, vakanın input nesnesini alır ve değerlendiricilerin okuduğu çıktıyı döndürür. def ya da async def olabilir; eşzamanlı bir fonksiyon bir çalışan iş parçacığında çalışır.

Fonksiyonun kendi modül kaynağı sürüm özetine girer, bu yüzden onu düzenlemek önbellekteki yürütmeleri geçersiz kılar. Başka neyin bunu yapıp neyin yapmadığı için Yapılandırma başvurusuna bakın.

current_case

def current_case() -> CaseRecorder

Yalnızca Oloproof sisteminizi çağırırken kullanılabilir; başka her yerde RuntimeError fırlatır. Kaydedicinin yöntemleri:

Her biri bir ArtifactRef döndürür (hiçbir şey döndürmeyen usage hariç). Bu kayıtları oluşturmak için tipli yükler dışa aktarılır: Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck ve tür adı CONVERSATION (conversation/v1).

@rag_system

def rag_system(*, name, depth, top_k, token_budget=None, index_version=None, version=None, config=None, citations_path="citations")

Bir sınıf süsleyicisi. Sınıf retrieve(input, depth) ve generate(input, context) sağlar, bir token_budget ayarladığında ayrıca count_tokens(passage). context, top_k ve bütçeden sağ çıkan Passage nesnelerinin sıralama düzenindeki listesidir. Oloproof retrieval/v1, context/v1, citations/v1 ve stage_timings/v1 kayıtlarını kendisi yapar ve her aşamayı ayrı ayrı önbelleğe alır. citations_path, yanıtın alıntıladığı kimlikleri tutan çıktı alanını adlandırır. Bkz. RAG.

Değerlendiriciler

Tüm sınıflar oloproof.evaluators içindedir. Her birinin criterion değeri ürettiği metriği adlandırır. Her birinin hangi yapıtları okuduğu ve YAML karşılığı, Yapılandırma başvurusundaki değerlendirici tablosundadır.

provider değeri "anthropic", "openai" ya da "openai_compatible" olur. Bir hakem anahtarını api_key_env değerinin adlandırdığı ortam değişkeninden okur (varsayılan olarak ANTHROPIC_API_KEY ya da OPENAI_API_KEY) ve o sağlayıcı tarafından faturalanır. Groundedness ve CitationSupport, RubricJudge ayarlarının geri kalanını **options üzerinden alır. Olasılık hakeminin, model sınıflandırıcının ve kaskadın SDK sınıfı yoktur; yalnızca YAML'da vardırlar.

ConversationCompleted ve ConversationJudge, sisteminizin kaydettiği bir conversation/v1 yapıtını okur. Oloproof konuşmayı yürütmez: uygulamanız her turu çalıştırır ve dökümü kaydeder. Bkz. Ajanlar.

@evaluator

def evaluator(*, criterion, reads=("output", "expected"), cacheable=False, version=None, value_type="binary", score_range=None)

Tek argümanlı, vakayı alan bir fonksiyonu bir CustomEvaluator içine sarar. Vakanın output, expected ve scenario değerleri vardır ve artifacts(name) kaydedilmiş bir türün yüklerini döndürür. Fonksiyon def ya da async def olabilir. İkili bir değerlendirici True ya da False döndürür; bir puan değerlendiricisi value_type="score" ve score_range=(low, high) bildirir ve bir sayı döndürür. Fonksiyonun fırlattığı bir hata, vakayı o kriter için asla başarısız olarak değil, eksik olarak kaydeder.

reads, fonksiyonun okuduğu her alanı (input, output, expected, metadata, metadata.<key> ya da artifacts.<name>) listelemelidir, çünkü önbellekteki yargı tam olarak bunlara göre anahtarlanır. Yargılar çalıştırmalar arasında yalnızca cacheable=True ile yeniden kullanılır. Tanımlayan modülün kaynağı sürüme girer, bu yüzden onu düzenlemek onları geçersiz kılar. YAML özel bir değerlendirici adlandıramaz.

Teşhis

diagnose ve adiagnose

def diagnose(run_id, **kwargs) -> InterventionResult
async def adiagnose(run_id, *, system, evaluators, intervention, criterion, control=True, top_k=None, reranker=None, reranker_root=None, store=None, concurrency=None) -> InterventionResult

Saklanan bir çalıştırmanın başarısız vakalarını tek bir müdahale altında yeniden yürütür: "gold-context", "top-k" (top_k ile) ya da "reranker" (reranker ile). system ve evaluators, çalıştırmanın kullandığı sürümler olmalıdır; farklı bir sürüm hiçbir şey yürütülmeden reddedilir. control=True ile müdahalenin yanında yeni bir kontrol örneklemi çalışır, böylece bir değişiklik çalıştırmadan çalıştırmaya değişkenlikten ayırt edilebilir. diagnose eşzamanlı biçimdir ve çalışan bir döngünün içinde evaluate gibi davranır. İş akışı için RAG sayfasına bakın.

InterventionResult üst çalıştırma kimliğini, müdahaleyi, desteklenip desteklenmediğini, müdahale ve kontrol çalıştırmalarını, vaka başına bir sonucu ve üretildiğinde CaseDiagnosis girdilerinden oluşan bir DiagnosisReport tutar.

Ajan yeniden oynatma

def supports_replay(system) -> bool
def checkpoint_for(trajectory, step_index) -> AgentCheckpoint | None
async def replay_case(system, *, scenario_id, trajectory, checkpoint, change) -> ReplayOutcome
def label_case(outcome) -> CaseDiagnosis
def label_cases(outcomes) -> tuple[CaseDiagnosis, ...]
def unnecessary_steps(labels) -> tuple[UnnecessaryStep, ...]

Yeniden oynatma, Oloproof'un benzettiği bir şey değil, sisteminizin yaptığı bir şeydir. Bir sistem onu yalnızca kontrol noktasından itibaren ajanın yaptığını döndüren async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory yöntemini uygulayarak destekler; Oloproof kaydedilmiş başlangıç kısmını ekler ve karşılaştırır. Uygulamanız durumunun, oturumlarının ve araç yan etkilerinin sahibidir; bir yeniden oynatmadan önce onları sıfırlamak da buna dahildir. supports_replay, bir sistemin bu yöntemi bildirip bildirmediğini söyler.

replay_case bir eşyordamdır: onu await edin ya da asyncio.run üzerinden çağırın. Yeniden oynatmadan önce bir kontrol çalıştırır (ReplayChange(kind="resume") ile aynı kontrol noktası) ve kontrol kaydı yeniden üretmediğinde yeniden oynatmayı denemez. change, ReplayChange(kind="drop_step", step_index=...) ya da ReplayChange(kind="resume") olur. checkpoint_for bir adımdan kesinlikle önceki en son kaydedilmiş kontrol noktasını ya da None seçer; bu durumda sonuç sisteme dokunmadan no_checkpoint_recorded olarak atılır.

ReplayOutcome; scenario_id, change, yeniden oynatmanın ve kontrolün son durumlarını ve vaka hiçbir kanıt vermediğinde gerekçesiyle discarded değerini taşır. Atılan bir vaka başarısız bir vaka değildir. label_case bir sonucu bir FailureLabel ve onun LabelReason değeriyle bir CaseDiagnosis haline getirir; unnecessary_steps, kaldırılması sonucu bozmayan adımları listeler. Bkz. Ajanlar.

İnsan etiketleri ve değerlendirici güveni

def record_label(*, run_id, scenario_id, criterion, passed, labelled_by, note=None, purpose="measurement", sample_index=0, config="oloproof.yaml", store=None, ...) -> HumanLabel

Bir kişinin saklanan bir çalıştırmanın tek bir vakası hakkındaki geçti/kaldı hükmünü saklar. Etiketler, bir hakemin onlarla uyumunu ölçen (AgreementResult) ve durumunu kaydeden (RegistryEntry) oloproof evaluators validate komutunu besler. Diğer measurement_sample_* argümanları bir etiketi bir ölçüm örneklemine bağlar; CLI'ın oloproof labels export ve oloproof labels import komutları onları sizin için doldurur. Bkz. Hakemler.

Kodda politikalar

ReleasePolicy, IntervalThresholdRule, ObservedCountRule ve DecisionRule (ikisinin birleşimi) dosya olmadan bir politika oluşturur. Alanları Yapılandırma başvurusundaki release.yaml alanlarıdır; bir aralık kuralı min: ya da max: yerine direction (min ya da max) ve threshold alır. Karşılaştırma kurallarının dışa aktarılmış bir sınıfı yoktur; onları release.yaml içine yazın ve yolunu verin.

from oloproof import IntervalThresholdRule, ReleasePolicy

policy = ReleasePolicy(
    rules=(IntervalThresholdRule(id="accuracy", metric="correct_label", direction="min", threshold=0.8),),
)

Diğer dışa aktarımlar