Machine Learning Academy · Oppitunti

Mallien versiointi: tiedostonimien ja metatietojen merkitys

Oppijat suunnittelevat nimeämiskäytännön, joka sisältää koulutuspäivän, aineiston version ja mittarituloksen, sekä kirjoittavat hallintaa varten erillisen JSON-metatietotiedoston.

Oppitunti 2/413 vaihetta

Mallien versiointi: tiedostonimien ja metatietojen merkitys on ilmainen Machine Learning Academy-oppitunti CoddyKitissä. Tämä on oppitunti 2/4. Voit lukea koko oppitunnin alta ilmaiseksi ja harjoitella sen jälkeen käytännössä selaimessa sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla. Oppitunti kuuluu Machine Learning Academy-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Machine Learning Academy-kurssilla on yhteensä 4 oppituntia.

Versioinnin puuttumisen ongelma

Ilman kurinalaista versiointistrategiaa tiimeille kertyy nopeasti tiedostoja, kuten model.pkl, model_v2.pkl, model_final.pkl ja model_FINAL_v2.pkl, eikä ole tietoa siitä, millä aineistolla kukin niistä on koulutettu, minkä metriikan se saavutti tai mikä niistä on todella käytössä tuotannossa. Tämä kaaos johtaa vanhentuneiden mallien käyttöönottoon, parhaan tarkistuspisteen menettämiseen tai aiemman tuloksen toistamisen mahdottomuuteen vianmääritystä varten.

Mitä tiedostonimeen kannattaa koodata

Hyvän mallin tiedostonimen tulee sisältää riittävästi kontekstia, jotta se kuvaa itse itsensä: aineisto, algoritmi, päivämäärä ja valinnaisesti ensisijainen metriikka sekä aineiston versio tai Git SHA. Näin mallirekisterin kansio toimii yhdellä silmäyksellä luettavana tarkastuspolkuna ilman, että jokaista tiedostoa tarvitsee avata.

from datetime import date

def model_filename(dataset, algorithm, metric_name, metric_value,
                   data_version='v1', ext='joblib'):
    today = date.today().strftime('%Y%m%d')
    metric_str = f'{metric_name}{int(metric_value * 100)}'
    return f'{dataset}__{algorithm}__{today}__dv{data_version}__{metric_str}.{ext}'

# Examples
print(model_filename('titanic', 'rf', 'acc', 0.834, data_version='2'))
print(model_filename('fraud', 'xgb', 'auc', 0.971))
print(model_filename('cancer', 'logreg', 'f1', 0.955))

JSON-metatietojen oheistiedosto

Jokaisella mallitiedostolla tulisi olla samaa perusnimeä käyttävä JSON-muotoinen oheistiedosto. Oheistiedostossa dokumentoidaan kaikki se, mitä tiedostonimi ei voi sisältää: kirjastoversiot, hyperparametrit, opetusjoukon koko, testijoukon suorituskyky kaikilla metriikoilla, ominaisuusluettelo ja mahdolliset koulutusajon muistiinpanot. Tämä on vähimmäistason mallikortti.

import json
import sklearn, sys
from datetime import datetime

def save_metadata(path, dataset, algorithm, params, metrics, features, notes=''):
    meta = {
        'model_path': path,
        'dataset': dataset,
        'algorithm': algorithm,
        'hyperparameters': params,
        'metrics': metrics,
        'features': features,
        'sklearn_version': sklearn.__version__,
        'python_version': sys.version.split()[0],
        'trained_at': datetime.utcnow().isoformat(),
        'notes': notes
    }
    meta_path = path.replace('.joblib', '_metadata.json')
    with open(meta_path, 'w') as f:
        json.dump(meta, f, indent=2)
    print('Metadata saved to:', meta_path)
    return meta

# Usage example
save_metadata(
    '/tmp/cancer__logreg__20260620__dv1__acc97.joblib',
    dataset='breast_cancer', algorithm='LogisticRegression',
    params={'C': 1.0, 'max_iter': 300},
    metrics={'accuracy': 0.9789, 'roc_auc': 0.9941, 'f1': 0.9831},
    features=['mean radius', 'mean texture', '... 30 total'],
    notes='Trained on full UCI breast cancer dataset'
)

Aineiston version seuranta

Myös opetusaineisto on versioitava. data_v1.csv-tiedostolla koulutetulla mallilla ja data_v2.csv-tiedostolla koulutetulla mallilla ei saa koskaan olla samaa mallitunnistetta. Aineiston versiointivaihtoehtoja ovat aineistotiedoston Git SHA:n tallentaminen, CSV-tiedoston MD5- tai SHA256-tiivisteen kirjaaminen tai DVC-työkalun (Data Version Control) käyttö. DVC hallitsee aineiston alkuperäketjua samalla tavalla kuin Git hallitsee koodia.

import hashlib

def file_hash(path, algo='sha256'):
    h = hashlib.new(algo)
    with open(path, 'rb') as f:
        for chunk in iter(lambda: f.read(65536), b''):
            h.update(chunk)
    return h.hexdigest()[:12]  # first 12 hex chars as short ID

# Example: hash the model file itself as a unique ID
model_path = '/tmp/cancer_model.joblib'
model_hash = file_hash(model_path)
print('Model hash (short):', model_hash)

Mallien semanttinen versiointi

Ottakaa mallien versioinnissa mallia ohjelmistokehityksestä: käyttäkää semanttista versiointia (MAJOR.MINOR.PATCH). MAJOR tarkoittaa rikkovaa muutosta (eri ominaisuusjoukko tai yhteensopimaton skeema). MINOR tarkoittaa suorituskyvyn parannusta saman rajapinnan yhteydessä. PATCH tarkoittaa virheenkorjausta tai pientä uudelleenkalibrointia. Tämä käytäntö auttaa mallin myöhempiä käyttäjiä ymmärtämään malliriippuvuuden päivittämisen vaikutukset.

model_registry = [
    {'version': '1.0.0', 'algorithm': 'LogisticRegression', 'auc': 0.921,
     'note': 'Initial production model'},
    {'version': '1.1.0', 'algorithm': 'LogisticRegression', 'auc': 0.935,
     'note': 'Retrained on 3 months more data'},
    {'version': '2.0.0', 'algorithm': 'XGBoost', 'auc': 0.971,
     'note': 'New algorithm; feature set changed — incompatible schema'}
]

print('Model Registry:')
for entry in model_registry:
    print(f"  v{entry['version']}  AUC={entry['auc']}  {entry['note']}")

Yksinkertainen paikallinen mallirekisteri

Kevyt mallirekisteri voi olla hakemisto, jossa on kaikki tallennetut mallit indeksoiva registry.json-tiedosto. Kukin tietue sisältää tiedostonimen, version, keskeiset metriikat ja tuotantotilaa ilmaisevan lipun. Käyttöönoton komentosarja lukee tämän tiedoston ja määrittää ladattavan mallin.

import json
import os

REGISTRY_PATH = '/tmp/model_registry.json'

def register_model(filename, version, metrics, is_production=False):
    try:
        with open(REGISTRY_PATH) as f:
            registry = json.load(f)
    except FileNotFoundError:
        registry = []

    # Mark all as not-production if this one is production
    if is_production:
        for entry in registry:
            entry['is_production'] = False

    registry.append({
        'filename': filename,
        'version': version,
        'metrics': metrics,
        'is_production': is_production
    })

    with open(REGISTRY_PATH, 'w') as f:
        json.dump(registry, f, indent=2)
    print(f'Registered v{version} (production={is_production})')

register_model('cancer__logreg__v1.0.0.joblib', '1.0.0',
               {'accuracy': 0.979, 'auc': 0.994}, is_production=True)

Tuotantomallin lukeminen rekisteristä

Ennusteen laskennan aikana palvelu lataa rekisterin, etsii tuotannoksi merkityn mallin ja lataa kyseisen tiedoston. Näin käyttöönoton komentosarja ei ole sidottu kovakoodattuihin tiedostonimiin — tuotantomallin vaihtaminen edellyttää vain rekisterin lipun päivittämistä, ei palvelevan koodin muokkaamista.

import json
import joblib

def load_production_model(registry_path, model_dir='/tmp'):
    with open(registry_path) as f:
        registry = json.load(f)
    prod = next((r for r in registry if r['is_production']), None)
    if prod is None:
        raise RuntimeError('No production model registered!')
    path = f'{model_dir}/{prod["filename"]}'
    print(f'Loading production model: {prod["filename"]} (v{prod["version"]})')
    print(f'Metrics: {prod["metrics"]}')
    # return joblib.load(path)  # would load for real
    return None  # demo

load_production_model('/tmp/model_registry.json')

MLflow: ammattimainen mallirekisteri

MLflow on alan standardityökalu kokeiden seurantaan ja mallirekisteriin. Se kirjaa kunkin koulutusajon parametrit, metriikat ja artefaktit, mahdollistaa ajojen vertailun käyttöliittymässä ja tarjoaa mallirekisterin vaiheilla staging, tuotanto ja arkistoitu. Tiimeille MLflow korvaa manuaaliset JSON-rekisterit vankalla ja kyselyihin soveltuvalla taustajärjestelmällä.

import mlflow
from sklearn.linear_model import LogisticRegression
from sklearn.datasets import load_iris
from sklearn.model_selection import cross_val_score
import numpy as np

X, y = load_iris(return_X_y=True)

with mlflow.start_run(run_name='logreg_iris_v1'):
    model = LogisticRegression(C=1.0, max_iter=200)
    cv_score = cross_val_score(model, X, y, cv=5).mean()

    mlflow.log_param('C', 1.0)
    mlflow.log_param('max_iter', 200)
    mlflow.log_metric('cv_accuracy', cv_score)

    model.fit(X, y)
    mlflow.sklearn.log_model(model, 'model')

    print(f'CV Accuracy: {cv_score:.4f}')
    print('Run logged to MLflow')

Malliversioiden merkitseminen

Tunnisteilla voidaan lisätä malliversioon vapaamuotoisia avain–arvo-merkintöjä. Niitä voi käyttää kokeen kontekstin, analyytikon nimen, tehtävätyypin tai esimerkiksi reiluusauditoinnin läpäisemisen kirjaamiseen. Tunnisteista voi tehdä kyselyjä, joten rekisteristä on helppo suodattaa malleja minkä tahansa ominaisuuden perusteella.

# Simulated registry entry with tags (no MLflow required)
model_entry = {
    'version': '2.1.0',
    'filename': 'fraud__xgb__2.1.0.joblib',
    'tags': {
        'analyst': 'data-science-team',
        'task': 'binary-classification',
        'fairness_audit': 'passed',
        'retrain_trigger': 'monthly-schedule',
        'deployment_region': 'eu-west-1'
    },
    'metrics': {'roc_auc': 0.971, 'precision': 0.83, 'recall': 0.79}
}

print('Model entry:')
print(json.dumps(model_entry, indent=2))

Automaattisen käyttöönoton kriteerit

Määritelkää selkeät käyttöönoton kriteerit ennen minkään mallin siirtämistä tuotantoon: uuden mallin on saavutettava vähintään X prosentin parannus AUC-arvossa, läpäistävä reiluustarkistus, säilytettävä suorituskyky kaikissa seuratuissa demografisissa alaryhmissä ja laskettava ennusteet Y millisekunnissa. Kun nämä kriteerit koodataan dokumentaation sijaan ohjelmakoodiin, CI/CD-putki voi automatisoida käyttöönotosta päättämisen puolueettomasti.

def should_promote(new_metrics, baseline_metrics, min_auc_improvement=0.005):
    if new_metrics['auc'] < baseline_metrics['auc'] + min_auc_improvement:
        return False, 'AUC improvement too small'
    if new_metrics.get('fairness_delta', 0) > 0.05:
        return False, 'Fairness constraint violated'
    if new_metrics.get('latency_ms', 0) > 100:
        return False, 'Latency too high'
    return True, 'All criteria met'

baseline = {'auc': 0.921}
candidate = {'auc': 0.937, 'fairness_delta': 0.02, 'latency_ms': 45}

promote, reason = should_promote(candidate, baseline)
print(f'Promote: {promote} — {reason}')

Mallikortit ja dokumentaatio

Teknisten metatietojen lisäksi mallikortissa (Google-yhtiön käyttöön ottama termi) dokumentoidaan mallin tarkoitettu käyttö, rajoitukset, koulutusaineiston ominaisuudet, suorituskyky demografisissa alaryhmissä ja eettiset näkökohdat. Merkittäviä päätöksiä tekeville malleille (kuten lainapäätöksiin ja lääketieteelliseen hoidon kiireellisyyden arviointiin käytettäville malleille) mallikorteista on tulossa sääntelyvaatimus. Sisällyttäkää vähintään tarkoitettu käyttö, soveltamisalan ulkopuoliset käyttötavat, suorituskykymetriikat ja tunnetut virhetilanteet.

Pikatarkistus

Testatkaa tämän oppitunnin perusteella ymmärrystänne mallien versioinnista ja metatiedoista.

Oppitunnin yhteenveto

Tässä oppitunnissa opitte, että aineiston, algoritmin, päivämäärän ja metriikan sisältävät kuvaavat tiedostonimet tekevät mallihakemistosta itsensä dokumentoivan, JSON-metatietojen oheistiedostot sisältävät hallintaa ja toistettavuutta varten tarvittavat kirjastoversiot, hyperparametrit ja metriikat ja että mallirekisteri (paikallinen JSON tai MLflow) irrottaa palvelevan koodin kovakoodatuista tiedostonimistä. Seuraavaksi käärimme tallennetun mallin FastAPI-päätepisteeseen ennusteiden tarjoamista varten HTTP:n yli.

Aloita maksutta

Opi Python tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit
30
Oppitunnit
120

Usein kysytyt kysymykset

Onko oppitunti ”Mallien versiointi: tiedostonimien ja metatietojen merkitys” ilmainen?

Kyllä – oppitunnin ”Mallien versiointi: tiedostonimien ja metatietojen merkitys” koko tekstin voi lukea täällä verkossa ilmaiseksi. Jos haluat harjoitella interaktiivisesti sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla sekä avata koko Machine Learning Academy-kurssin, päivitä CoddyKit PROhon. Machine Learning Academy-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”Mallien versiointi: tiedostonimien ja metatietojen merkitys”?

Oppijat suunnittelevat nimeämiskäytännön, joka sisältää koulutuspäivän, aineiston version ja mittarituloksen, sekä kirjoittavat hallintaa varten erillisen JSON-metatietotiedoston. Harjoittelet Machine Learning Academy-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Machine Learning Academy-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Machine Learning Academy-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 2/4.

Kuinka kauan ”Mallien versiointi: tiedostonimien ja metatietojen merkitys”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Machine Learning Academy-oppitunnilla?

Kyllä. Jokainen Machine Learning Academy-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

  1. Mallien tallentaminen joblibillä ja picklellä
  2. Mallien versiointi: tiedostonimien ja metatietojen merkitys
  3. Ennusteiden tarjoaminen FastAPI-päätepisteellä
  4. Ennusteiden valvonta: syötteiden ja tulosteiden kirjaaminen
← Takaisin: Machine Learning Academy