Je Python-project integreren: invoer, start, uitvoer

1. Het programma, zijn parameters en de commerciële opvolging scheiden

De code beschrijft het gedrag van het programma. De configuratie bepaalt de werklast: model, data, batch, precisie en bestemming. De secrets geven toegang tot de nodige resources. Houd deze elementen gescheiden om een test te wijzigen zonder de code te herschrijven of een token in een gedeeld bestand te kopiëren.

De Kernodeck-opdrachtreferentie laat je de context van de huur in je account terugvinden. De testidentificatie onderscheidt de uitvoeringen van je programma tijdens die periode. Koppel ze in je notities als dat je helpt, maar vraag je script niet om de status van de berekening af te leiden uit de betaalstatus.

Neem een project voor documentclassificatie dat meerdere keren op dezelfde steekproef moet worden gestart. Het contract van het programma beschrijft het invoerbestand, de toegestane parameters, de uitvoermap en de manier waarop fouten worden weergegeven. De gids over de data preciseert de validatie van de inhoud; hier organiseren we de interface die deze stappen met elkaar verbindt.

2. Een expliciet en geversioneerd invoercontract schrijven

Documenteer de verplichte velden en de aanvaarde waarden. Vermijd stille standaardwaarden voor een beslissing die het resultaat verandert, zoals het model of het apparaat. Een schemanummer onderscheidt de vorm van de configuratie van de versie van de code; het vervangt die laatste niet.

In dit didactische voorbeeld bevat het JSON-bestand een schema, een invoerpad, een batch en het gevraagde apparaat. Relatieve paden worden gelezen vanaf de configuratiemap. Deze regel, gekozen voor het voorbeeld, vermijdt afhankelijkheid van de map van waaruit een collega de opdracht start.

Geldige JSON lezen controleert alleen de syntax. Je programma moet vervolgens de types, de velden en de beperkingen van het project verifiëren. Bij een fout moet het stoppen vóór het laden van een kostbare resource, met een bericht dat de aan te passen parameter benoemt.

config/pilote.json — voorbeeld van een minimaal contract

{
  "schema_version": 1,
  "input": "../data/pilote.jsonl",
  "batch_size": 4,
  "device": "cuda"
}

3. Een startpunt voorbereiden dat eenvoudige fouten weigert

argparse laat je opties declareren en een help voor je opdracht genereren. Het volgende voorbeeld is enkel een precontrole: het leest de configuratie, verifieert de velden en detecteert een al gebruikte uitvoermap. Het laadt noch model noch data in het geheugen en test niet de beschikbaarheid van de GPU.

Bewaar deze didactische code in prepare_run.py als je ze wilt aanpassen. Ze wordt aangeboden zonder bewezen uitvoering. Voeg vervolgens je domeincontroles toe in de applicatie, in plaats van het eindbericht te beschouwen als een rekenresultaat. Het apparaat cuda blijft een verzoek; PyTorch gebruikt deze naam ook met ROCm.

Het weigeren van een bestaande uitvoermap is hier een conventie om te vermijden dat tests door elkaar lopen. Een echte herstelopdracht moet een optie en afzonderlijke controles krijgen. Maak van een nieuwe start geen impliciet herstel omdat er bestanden aanwezig zijn.

Didactische precontrole van de interface van het project

import argparse
import json
from pathlib import Path

parser = argparse.ArgumentParser(description="Een projectstart valideren")
parser.add_argument("--config", type=Path, required=True)
parser.add_argument("--run-dir", type=Path, required=True)
args = parser.parse_args()

try:
    config_path = args.config.resolve()
    config = json.loads(config_path.read_text(encoding="utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
    parser.error(f"Configuratie onleesbaar: {exc}")

expected = {"schema_version", "input", "batch_size", "device"}
if not isinstance(config, dict) or set(config) != expected:
    parser.error("Verwachte velden: schema_version, input, batch_size, device")
if type(config["schema_version"]) is not int or config["schema_version"] != 1:
    parser.error("schema_version moet 1 zijn")
if type(config["batch_size"]) is not int or config["batch_size"] < 1:
    parser.error("batch_size moet een positief geheel getal zijn")
if config["device"] not in ("cpu", "cuda"):
    parser.error("device moet cpu of cuda zijn")
if not isinstance(config["input"], str) or not config["input"]:
    parser.error("input moet een niet-lege padwaarde zijn")

input_path = (config_path.parent / config["input"]).resolve()
run_dir = args.run_dir.resolve()
if not input_path.is_file():
    parser.error("Invoerbestand ontbreekt")
if run_dir.exists():
    parser.error("Kies een nieuwe uitvoermap")

print(json.dumps({
    "status": "configuration_validated",
    "input": str(input_path),
    "run_dir": str(run_dir),
    "device_requested": config["device"],
    "batch_size": config["batch_size"]
}, ensure_ascii=False))

Voorgestelde aanroep van de precheck

python prepare_run.py --config config/pilote.json --run-dir runs/pilote-001

4. Geef uitvoeringen en hun resultaten een identiteit

Koppel elke start aan een korte identificatie die uniek is binnen je campagne. Noteer de coderevisie, het schema en de daadwerkelijk gebruikte parameters, en daarna de referentie van de data en het model. Bewaar deze waarden samen met de uitvoer, zodat een resultaat niet afhangt van een configuratiebestand dat later is gewijzigd.

Maak voor het vergelijken van twee batchgroottes twee proeven en twee mappen. Houd dezelfde steekproef aan en identificeer het bewuste verschil. De namen pilote-001 en pilote-002 verklaren op zichzelf niet wat er is veranderd: het manifest verbindt de naam met de parameters.

Reserveer een balansformaat dat leesbaar is voor je tools. Het kan onderscheid maken tussen ontvangen, geslaagde, geweigerde en nog te verwerken elementen. Kies een volledige succesregel en markeer een proef niet als afgerond zodra het eerste resultaat is weggeschreven. De returncode van het programma moet consistent blijven met deze conclusie.

Scroll door de tabel om alle kolommen te lezen.

Een uitvoercontract voor verwerking per document
Bestand of status	Rol	Verwachte controle
manifest.json	Identiteit van de code, de data en de parameters	Daadwerkelijk gebruikte waarden, zonder secrets.
results.jsonl	Één uitvoer per geaccepteerd element	Bekende identificaties en conform formaat.
errors.jsonl	Geweigerde elementen en nuttige reden	Geen stille verdwijning en geen onnodige gevoelige inhoud.
summary.json	Conclusie van de proef en tellers	Kloppende som, bestanden opnieuw gelezen vóór de eindstatus.

Verkennend werk omzetten in een toegangspunt

5. Stel nuttige gebeurtenissen beschikbaar voor je tools

Maak een paar overgangen zichtbaar: configuratie geaccepteerd, data toegankelijk, model geladen, eerste uitvoer weggeschreven en einde van de verwerking. Een log moet de vraag "waar staat deze uitvoering?" kunnen beantwoorden zonder documenten of prompts te kopiëren. Koppel de stap en de proefidentificatie aan het bericht.

De module logging van Python laat je berichten ordenen naar niveau en bestemming. Kies daarna je eigen gebeurtenisconventie en documenteer die. Een applicatie die een fout wegschrijft en daarna met succes eindigt, maakt automatisering misleidend; omgekeerd betekent niet elke waarschuwing dat het resultaat onbruikbaar is.

Verwar een verzonden gebeurtenis niet met een duurzaam resultaat: een bericht "back-up gestart" bewijst niet dat een bestand opnieuw is gelezen. Voor een langdurige uitvoering legt de speciale gids het verband uit tussen proces en sessie. Je interface moet vooral een conclusie bewaren die toegankelijk blijft nadat de interactieve verbinding is beëindigd.

6. Definieer het falen, het hervatten en de eindcontrole

Classificeer nuttige fouten: ongeldige configuratie, ontbrekende resource, rekenfout en niet-conforme uitvoer. Geef voor elk een volgende actie. Installeer geen automatische herstart zonder te beslissen welke effecten herhaald mogen worden: een al geaccepteerde uitvoer herschrijven en een checkpoint hervatten vragen verschillende regels.

Je definitieve procedure legt uit hoe je start, observeert, stopt, hervat en exporteert. Houd voor documentverwerking de lijst bij van voltooide identifiers en die welke opnieuw verwerkt moeten worden. Gebruik voor een training een protocol dat de opgeslagen staten in een nieuw proces verifieert. Een niet-lege map is geen bewijs van een correcte hervatting.

Controleer het project ten slotte vanuit een nieuwe aanroep, met een bekende configuratie en een aparte bestemming. Verifieer de verwachte weigeringen en daarna een kleine volledige doorloop. De precheck van deze pagina dekt geen gelijktijdige toegang, geen publieke blootstelling van een service en geen opslagmachtigingen: die onderwerpen vragen hun eigen ontwerp.

Geef je project een interface die je kunt beheren.