Riferimento della configurazione

Ogni campo di oloproof.yaml e release.yaml, con il suo tipo, il suo valore predefinito, i valori che accetta e un esempio, ricavati dai modelli che leggono i file. Usalo per consultare un campo; leggi le pagine della guida rapida e del gating per imparare il flusso di lavoro.

Entrambi i file vengono validati prima che qualsiasi cosa venga eseguita. Un campo sconosciuto, un campo scritto male o un valore del tipo sbagliato è un errore di configurazione e il comando esce con 2 senza eseguire alcun caso. Entrambi i file hanno JSON Schema, che un editor in grado di leggere JSON Schema può usare per il completamento. Il pacchetto installato li scrive, insieme agli schemi dei risultati, in schemas/v1/ sotto la directory corrente: python -m oloproof_core.models.schema_export (i due sono project_config.schema.json e release_policy.schema.json).

Nelle tabelle qui sotto, "obbligatorio" significa che il file viene rifiutato senza il campo; ogni altro campo mostra il valore usato quando è omesso.

oloproof.yaml in sintesi

Un progetto piccolo e completo. Esegue una funzione Python in locale, non richiede rete né chiavi, ed è la forma che genera oloproof init.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label

Campi di primo livello

concurrency

Voci di pricing

Oloproof non include alcuna tabella dei prezzi. Ogni voce nomina un modello esattamente come lo nomina il model: di un valutatore.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label
pricing:
  - model: my-judge-model
    input_per_mtok: 0.15
    output_per_mtok: 0.6
egress: [raw_outputs]

system

Un sistema richiede esattamente uno tra callable, http o rag.

system.http

# oloproof.yaml
version: 1
project: support-api
dataset: datasets/support.jsonl
system:
  name: support-api
  version: "2026-10-08"
  http:
    url: http://localhost:8000/answer
    output_path: answer
    artifacts:
      retrieval/v1: debug.retrieval
evaluators:
  - type: hit_rate
    k: 5

Il contratto di richiesta e risposta, e che cosa accade con timeout ed errori HTTP, sono in Risultati ed esecuzione.

system.rag

Le impostazioni date qui sostituiscono quelle dichiarate dalla classe. Un sistema a stadi registra da sé i propri artefatti retrieval/v1, context/v1 e citations/v1, quindi records viene rifiutato accanto a esso. Vedi RAG.

evaluators

Ogni voce accetta un type e questi due campi comuni:

fail si applica solo ai valutatori a esito positivo o negativo; un valutatore di punteggio con esso è un errore di configurazione. on_execution_error è un campo YAML; le classi di valutatori dell'SDK non accettano un argomento del genere, e un caso andato in errore conta come mancante.

Tipi di valutatore

"Legge" elenca ciò da cui dipende il verdetto del valutatore, che è anche la chiave del suo giudizio in cache. "SDK" nomina la classe in oloproof.evaluators.

Un giudice che chiama un modello ospitato invia il contenuto dei casi a quel provider e viene fatturato da esso. Le chiavi vengono lette dalla variabile d'ambiente indicata in api_key_env; Oloproof non le memorizza mai in questi file.

Valutatori deterministici

Giudici basati su modello

rubric_judge, groundedness_judge e citation_support_judge condividono questi campi. rubric_judge richiede esattamente uno tra rubric_file e rubric_text; i due giudici RAG ne accettano al massimo uno e altrimenti usano una rubrica integrata. Il loro criterion vale per impostazione predefinita groundedness e citation_support.

probability_judge pone una domanda tipizzata e legge le probabilità del modello:

cascade esegue prima un giudice economico e passa oltre i casi incerti:

Gli stadi giudicano il criterion della cascata stessa; uno stadio che ne nomina uno diverso viene rifiutato.

model_classifier assegna un punteggio a un testo con un modello addestrato su un server compatibile con TEI:

Valutatori RAG

Valutatori di agenti

Ogni tipo di agente ha un criterion predefinito, quindi può essere omesso: il nome stesso del tipo, o uno costruito dalla sua impostazione (agent_steps_le_8, agent_tool_lookup_called, agent_handoffs_le_2). Vedi Agenti.

Valutatori predittivi

Un valutatore predittivo che non scrive positive, field o expected_field lo prende dal blocco predictive:; un valore che scrive viene mantenuto.

predictive

metrics

Ogni criterio di valutatore è già una metrica. Una voce metrics: ne aggiunge un'altra, distinta da type.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label
metrics:
  - id: latency_p95
    type: quantile
    source: latency_ms
    quantile: 0.95

release.yaml

La policy di rilascio: quali regole decidono e quali decisioni bloccano. Le impostazioni omesse mantengono i loro valori predefiniti, quindi una policy che nomina solo le sue regole blocca comunque su FAIL, INSUFFICIENT_EVIDENCE e MANUAL_REVIEW.

# release.yaml
version: 1
rules:
  - id: label_accuracy
    metric: correct_label
    min: 0.8

rules

Una sola lista contiene entrambi i tipi. Una regola di esecuzione accetta esattamente uno tra min, max o max_failures. Una regola di confronto nomina il suo kind e decide una differenza tra due esecuzioni; vedi Regole di confronto.

families

# release.yaml
version: 1
warn_on: [INSUFFICIENT_EVIDENCE]
block_on: [FAIL, MANUAL_REVIEW]
rules:
  - id: label_accuracy
    metric: correct_label
    min: 0.8
    max_missing_fraction: 0.05
  - id: no_regression
    metric: correct_label
    kind: non_inferiority
    margin: 0.02

Tipi di artefatto

Un artefatto è un record tipizzato che un sistema scrive accanto al suo output, come ciò che ha recuperato. Un tipo è un nome in minuscolo con una versione facoltativa, conforme a ^[a-z][a-z0-9_]*(/v[1-9][0-9]*)?$. I valutatori che richiedono un artefatto lo nominano, e un'esecuzione il cui sistema non dichiara un tipo richiesto viene rifiutata prima di iniziare, anziché contare ogni caso come mancante.

Un sistema callable dichiara i tipi che registra in records: (o @system(records=...)); un sistema HTTP in http.artifacts; un sistema RAG a stadi registra i propri.

Versioni, chiavi di cache e invalidazione

Oloproof riutilizza il lavoro i cui input non sono cambiati, e decide che cosa significa "invariato" a partire dai digest del contenuto. Ciascuno viene calcolato dal motore e registrato con l'esecuzione.

Ciò che Oloproof non può vedere spetta a te dichiararlo:

• Il comportamento di un sistema HTTP risiede sul server. Cambia system.version ogni volta che cambia ciò che sta dietro l'URL, altrimenti un vecchio output in cache varrà per il nuovo sistema.
• L'hash dei moduli di supporto di un callable viene calcolato solo quando code_paths li include. Senza di esso, modificare un modulo di supporto non cambia la versione.
• Un metodo o un oggetto callable deve dichiarare una versione, e la versione deve cambiare quando cambia lo stato dell'oggetto.
• Un indice RAG è identificato da index_version; cambialo quando l'indice viene ricostruito.
• L'identità di un giudice basato su modello sono le sue impostazioni, non i pesi del provider. Un provider che aggiorna il modello dietro lo stesso nome non viene rilevato dalla cache.
• Un @evaluator personalizzato calcola l'hash del file del modulo che lo definisce, e i suoi giudizi vengono riutilizzati tra le esecuzioni solo quando dichiara cacheable=True. I giudici a rubrica integrati sono memorizzabili in cache; i valutatori deterministici vengono ricalcolati, il che costa poco.

Il lavoro in cache vive nello store locale del progetto, .oloproof/store.sqlite accanto a oloproof.yaml (o sotto OLOPROOF_HOME). Eliminare lo store scarta ogni cache e ogni esecuzione. In uno spazio di lavoro ospitato il motore non riutilizza esecuzioni, giudizi o analisi in cache, perché un push può scriverli; li ricalcola.