Tham chiếu SDK

Mọi tên mà các gói oloproof và oloproof.evaluators xuất ra, kèm chữ ký, việc nó là đồng bộ hay bất đồng bộ, và những gì nó trả về. Để có phần giới thiệu có hướng dẫn, hãy đọc API Python trước.

Chỉ hai gói này là bề mặt công khai. Bất cứ thứ gì được import từ oloproof_core đều là phần nội bộ của engine và có thể thay đổi mà không báo trước. Mọi hàm bên dưới chạy cục bộ trên kho lưu trữ của dự án; không hàm nào gửi dữ liệu đi đâu trừ khi một bộ đánh giá bạn truyền vào gọi một nhà cung cấp mô hình.

Chạy một lần đánh giá

evaluate và aevaluate

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

evaluate là đồng bộ. Khi được gọi mà không có vòng lặp sự kiện nào đang chạy, nó dùng asyncio.run; khi được gọi từ bên trong một vòng lặp đang chạy (một notebook, một bài kiểm thử async), nó chạy việc đánh giá trên một luồng riêng và chặn cho tới khi xong, nên nó an toàn ở cả hai nơi. aevaluate là coroutine; hãy await nó từ mã async.

Các đối số từ khóa còn lại (metrics, store, predictive, event_sink, retry_policy, traffic_draw_id) nhận các kiểu của engine từ oloproof_core và không thuộc bề mặt ổn định.

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)

Chạy trên một bộ kiểm thử hai trường hợp không có chính sách, đoạn này đã in ra:

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

Ý nghĩa của các trạng thái, mã lý do và số đếm nằm trong Kết quả và thực thi.

evaluate_comparison và 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

Chạy cả hai hệ thống trên cùng một bộ kiểm thử theo một thứ tự có seed duy nhất và quyết định các quy tắc so sánh của chính sách. policy là bắt buộc và phải chứa ít nhất một quy tắc superiority, non_inferiority hoặc equivalence, nếu không lời gọi sẽ ném một lỗi cấu hình. Các đối số từ khóa thêm: concurrency, replicates, và các đối số kiểu engine metrics, store và retry_policy. Hành vi đồng bộ và bất đồng bộ giống như với evaluate.

ComparisonEvaluationResult có candidate và baseline (mỗi cái là một EvaluationResult) và comparison, mang các khác biệt ghép cặp và các quyết định của chúng. Xem So sánh hai phiên bản.

Khai báo một hệ thống

@system

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

Có thể dùng trần (@system) hoặc với đối số (@system(name=..., version=...)), hoặc gọi trên một đối tượng (system(model.answer, version="v2")). Hàm nhận đối tượng input của trường hợp, không phải toàn bộ trường hợp, và trả về đầu ra mà các bộ đánh giá đọc. Nó có thể là def hoặc async def; một hàm đồng bộ chạy trên một luồng worker.

Mã nguồn module của chính hàm đi vào digest phiên bản, nên việc sửa nó làm mất hiệu lực các lần thực thi đã lưu đệm. Xem Tham chiếu cấu hình để biết những gì khác có và không có tác dụng đó.

current_case

def current_case() -> CaseRecorder

Chỉ khả dụng khi Oloproof đang gọi hệ thống của bạn; ở bất cứ đâu khác nó ném RuntimeError. Các phương thức của bộ ghi:

Mỗi phương thức trả về một ArtifactRef (trừ usage, không trả về gì). Các payload có kiểu được xuất ra để xây dựng các bản ghi này: Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck, và tên loại 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")

Một decorator cho lớp. Lớp cung cấp retrieve(input, depth) và generate(input, context), cùng với count_tokens(passage) khi nó đặt một token_budget. context là danh sách các đối tượng Passage còn lại sau top_k và ngân sách, theo thứ tự xếp hạng. Oloproof tự ghi lại retrieval/v1, context/v1, citations/v1 và stage_timings/v1, và lưu đệm từng tầng riêng. citations_path nêu trường đầu ra chứa các id mà câu trả lời trích dẫn. Xem RAG.

Bộ đánh giá

Mọi lớp đều nằm trong oloproof.evaluators. criterion của mỗi lớp nêu chỉ số mà nó tạo ra. Mỗi lớp đọc những artifact nào, và tương đương YAML của nó, nằm trong bảng bộ đánh giá của Tham chiếu cấu hình.

provider là "anthropic", "openai" hoặc "openai_compatible". Một giám khảo đọc khóa của nó từ biến môi trường mà api_key_env nêu (mặc định là ANTHROPIC_API_KEY hoặc OPENAI_API_KEY) và được nhà cung cấp đó tính phí. Groundedness và CitationSupport nhận các thiết lập còn lại của RubricJudge qua **options. Giám khảo xác suất, bộ phân loại mô hình và cascade không có lớp SDK nào; chúng chỉ tồn tại trong YAML.

ConversationCompleted và ConversationJudge đọc một artifact conversation/v1 mà hệ thống của bạn ghi lại. Oloproof không điều khiển cuộc hội thoại: ứng dụng của bạn chạy mọi lượt và ghi lại bản ghi hội thoại. Xem Agent.

@evaluator

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

Bọc một hàm một đối số, trường hợp, thành một CustomEvaluator. Trường hợp có output, expected và scenario, và artifacts(name) trả về các payload của một loại đã ghi. Hàm có thể là def hoặc async def. Một bộ đánh giá nhị phân trả về True hoặc False; một bộ đánh giá điểm số khai báo value_type="score" và score_range=(low, high) và trả về một con số. Một ngoại lệ do hàm ném ra ghi trường hợp là bị thiếu cho tiêu chí đó, không bao giờ là thất bại.

reads phải liệt kê mọi trường mà hàm đọc (input, output, expected, metadata, metadata.<key> hoặc artifacts.<name>), vì phán quyết đã lưu đệm được lập khóa chính xác theo các trường đó. Phán quyết chỉ được tái sử dụng giữa các lần chạy với cacheable=True. Mã nguồn của module định nghĩa đi vào phiên bản, nên việc sửa nó làm mất hiệu lực chúng. YAML không thể nêu một bộ đánh giá tùy chỉnh.

Chẩn đoán

diagnose và 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

Thực thi lại các trường hợp thất bại của một lần chạy đã lưu dưới một can thiệp: "gold-context", "top-k" (với top_k) hoặc "reranker" (với reranker). system và evaluators phải là các phiên bản mà lần chạy đã dùng; một phiên bản khác bị từ chối trước khi bất cứ thứ gì được thực thi. Với control=True, một mẫu đối chứng mới chạy bên cạnh can thiệp, để một thay đổi có thể được phân biệt với biến động giữa các lần chạy. diagnose là dạng đồng bộ và hành xử bên trong một vòng lặp đang chạy như evaluate. Xem RAG để biết quy trình.

InterventionResult chứa mã lần chạy cha, can thiệp, việc nó có được hỗ trợ hay không, các lần chạy can thiệp và đối chứng, một kết quả theo từng trường hợp, và một DiagnosisReport gồm các mục CaseDiagnosis khi có một báo cáo được tạo ra.

Phát lại agent

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, ...]

Phát lại là điều hệ thống của bạn làm, không phải điều Oloproof mô phỏng. Một hệ thống chỉ hỗ trợ nó khi hiện thực async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory, trả về những gì agent đã làm từ checkpoint trở đi; Oloproof ghép nối phần đầu đã ghi và so sánh. Ứng dụng của bạn sở hữu trạng thái, phiên và các tác dụng phụ của công cụ, bao gồm việc đặt lại chúng trước một lần phát lại. supports_replay báo một hệ thống có khai báo phương thức đó hay không.

replay_case là một coroutine: hãy await nó, hoặc gọi nó qua asyncio.run. Nó chạy một nhóm đối chứng (cùng checkpoint với ReplayChange(kind="resume")) trước lần phát lại, và không thử phát lại khi nhóm đối chứng không tái tạo được bản ghi. change là ReplayChange(kind="drop_step", step_index=...) hoặc ReplayChange(kind="resume"). checkpoint_for chọn checkpoint đã ghi gần nhất nằm hẳn trước một bước, hoặc None, khi đó kết quả bị loại bỏ với no_checkpoint_recorded mà không chạm tới hệ thống.

ReplayOutcome mang scenario_id, change, các trạng thái kết thúc của lần phát lại và nhóm đối chứng, và discarded kèm một lý do khi trường hợp không cho ra bằng chứng nào. Một trường hợp bị loại bỏ không phải là một trường hợp thất bại. label_case biến một kết quả thành một CaseDiagnosis với một FailureLabel và LabelReason của nó; unnecessary_steps liệt kê các bước mà việc bỏ chúng vẫn giữ nguyên kết quả. Xem Agent.

Nhãn của con người và độ tin cậy của bộ đánh giá

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

Lưu phán quyết đạt/không đạt của một người trên một trường hợp của một lần chạy đã lưu. Các nhãn cung cấp cho oloproof evaluators validate, lệnh đo mức đồng thuận của một giám khảo so với chúng (AgreementResult) và ghi lại trạng thái của nó (RegistryEntry). Các đối số measurement_sample_* khác gắn một nhãn với một mẫu đo lường; oloproof labels export và oloproof labels import của CLI điền chúng cho bạn. Xem Giám khảo.

Chính sách trong mã

ReleasePolicy, IntervalThresholdRule, ObservedCountRule và DecisionRule (hợp của hai loại kia) xây dựng một chính sách mà không cần tệp. Các trường của chúng là các trường release.yaml của Tham chiếu cấu hình; một quy tắc khoảng nhận direction (min hoặc max) và threshold thay vì min: hoặc max:. Các quy tắc so sánh không có lớp được xuất ra; hãy viết chúng trong release.yaml và truyền đường dẫn của nó.

from oloproof import IntervalThresholdRule, ReleasePolicy

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

Các tên được xuất khác