Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Prompttien versionointi ja luettelohallinta

Oppitunti 14 / 16 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Prompttien versionointi ja luettelohallinta
  2. Miksi promptteja kannattaa versioi da
  3. Luettelon rakenne
  4. Luettelon käyttö sovelluksessasi
  5. Versionointi Gitin kanssa
  6. Parhaat käytännöt
  7. Luettelon testaaminen palautuksella
  8. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: parametrit temperature ja top_p hyväksytään vain, kun päättelypyrkimys on none, kun taas GPT-5.6-mallit käyttävät oletusarvoisesti päättelyä (medium). Näitä parametreja asettavien kutsujen on siksi määritettävä reasoning={"effort": "none"} (Responses API) tai reasoning_effort="none" (Chat Completions). Lähteet: Using GPT-6 · GPT-5.6 Terra.

Prompttien versionointi ja luettelohallinta

Tuotantoympäristössä prompttisi kehittyvät yhtä lailla kuin koodisi. Ilman versionointia menetät muutosten seurannan, et voi palata aiempaan versioon, etkä tiedä, mikä versio on käytössä tuotannossa. Tämä oppitunti näyttää, kuinka hallitset promptteja ohjelmistoartefakteina.

Miksi promptteja kannattaa versioi da

Promptin muutos voi muuttaa sovelluksesi toimintaa radikaalisti. Toisin kuin koodissa, nämä muutokset ovat usein hienovaraisia ja vaikeasti havaittavia ilman automatisoituja testejä: yksi uudelleenmuotoiltu lause tai siirretty sana, ja malli alkaa luokitella väärin yhden kymmenestä reunatapauksesta. Mikään standardi yksikkötesti ei huomaa tätä aukkoa, mutta asiakastuki ilmoittaa siitä kolmen viikon kuluttua epämääräisenä valituksena väärin ohjatuista tiketeistä.

Versionointi vastaa neljään eri tarpeeseen. Ensinnäkin jäljitettävyys: tieto siitä, kuka muutti mitäkin ja milloin, muuttaa steriilin tiimiväittelyn yksinkertaiseksi historiatarkistukseksi. Toiseksi palautus (rollback): kun regressio ilmenee, välitön tavoite ei ole ymmärtää miksi, vaan palauttaa tunnettu toiminta. Kolmanneksi suorituskyvyn vertailu: tämä vaatii, että vanhemmat versiot pysyvät suoritettavina täsmälleen sellaisina kuin ne olivat, alkuperäisine malleineen ja asetuksineen. Viimeiseksi auditointi: järjestelmissä, jotka kuuluvat GDPR:n (yleinen tietosuoja-asetus) tai muiden vaatimustenmukaisuuskehysten piiriin, sinun on pystyttävä osoittamaan, mitkä ohjeet olivat voimassa tiettynä päivämääränä – kuvakaappaus ei riitä.

Luettelon rakenne

PromptCatalog-luokka täyttää nämä tarpeet minimaalisella infrastruktuurilla: yksi kansio prompttia kohden, yksi JSON-tiedosto versiota kohden, numeroituna juoksevasti. Jokainen tiedosto niputtaa järjestelmäpromptin tekstin siihen liittyvän mallin ja lämpötilan kanssa – promptti, joka on viritetty arvoon 0.1, ja sama promptti arvolla 0.7 eivät ole sama asia, ja niiden lukitseminen yhteen estää tekstin palauttamisen unohtaen sen asetukset.

Kenttä status seuraa elinkaarta. Versio alkaa tilassa draft, mikä mahdollistaa valmistelun ja testaamisen vaikuttamatta live-liikenteeseen. Metodinin activate kutsuminen vaihtaa tilan active:ksi ja siirtää edellisen version automaattisesti tilaan deprecated, varmistaen, että vain yksi versio palvelee liikennettä kerrallaan. Tämä tekee palautuksesta triviaalia: aiemman version uudelleenaktivointi on yksi kutsu, ei käyttöönotto. Sovelluksesi kutsuu tuotannossa metodia get_active, kun taas list_versions tukee katselmuksia ja auditointeja.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Prompt-luettelon hallinta versionoinnilla."""

    def __init__(self, catalog_dir: str = "prompts/"):
        self.catalog_dir = Path(catalog_dir)
        self.catalog_dir.mkdir(parents=True, exist_ok=True)

    def save_prompt(self, name: str, system_prompt: str,
                    model: str, temperature: float,
                    metadata: dict = None) -> str:
        """Tallentaa uuden version promptista."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Määritä versionumero
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Tallenna
        prompt_data = {
            "name": name,
            "version": version_str,
            "created_at": datetime.now().isoformat(),
            "model": model,
            "temperature": temperature,
            "system_prompt": system_prompt,
            "metadata": metadata or {},
            "status": "draft"  # draft | active | deprecated
        }

        filepath = prompt_dir / f"{version_str}.json"
        filepath.write_text(json.dumps(prompt_data, indent=2,
                                        ensure_ascii=False))

        return version_str

    def get_prompt(self, name: str,
                   version: str = "latest") -> dict:
        """Hakee promptin nimen ja version perusteella."""
        prompt_dir = self.catalog_dir / name

        if version == "latest":
            versions = sorted(prompt_dir.glob("v*.json"))
            if not versions:
                raise FileNotFoundError(f"Prompttia '{name}' ei löytynyt")
            filepath = versions[-1]
        else:
            filepath = prompt_dir / f"{version}.json"

        return json.loads(filepath.read_text())

    def get_active(self, name: str) -> dict:
        """Hakee promptin aktiivisen version."""
        prompt_dir = self.catalog_dir / name
        for filepath in sorted(prompt_dir.glob("v*.json"),
                               reverse=True):
            data = json.loads(filepath.read_text())
            if data["status"] == "active":
                return data
        raise FileNotFoundError(
            f"Aktiivista versiota ei löytynyt nimelle '{name}'"
        )

    def activate(self, name: str, version: str):
        """Aktivoi version ja poistaa muut käytöstä."""
        prompt_dir = self.catalog_dir / name

        for filepath in prompt_dir.glob("v*.json"):
            data = json.loads(filepath.read_text())
            if data["version"] == version:
                data["status"] = "active"
            elif data["status"] == "active":
                data["status"] = "deprecated"
            filepath.write_text(json.dumps(data, indent=2,
                                            ensure_ascii=False))

    def list_versions(self, name: str) -> list[dict]:
        """Listaa kaikki promptin versiot."""
        prompt_dir = self.catalog_dir / name
        versions = []
        for filepath in sorted(prompt_dir.glob("v*.json")):
            data = json.loads(filepath.read_text())
            versions.append({
                "version": data["version"],
                "status": data["status"],
                "created_at": data["created_at"],
                "model": data["model"]
            })
        return versions

Luettelon käyttö sovelluksessasi

Kutsujan puolella sääntö on yksinkertainen: koodissasi ei ole prompttitekstiä; se pyytää aktiivisen version luettelosta. Tämä pitää promptit muokattavina koskematta sovelluskoodiin ja estää kolmenkymmenen rivin merkkijonojen hautautumisen funktion keskelle. Tallennuksen yhteydessä savedut metadata-tiedot – tekijä, kuvaus, muutosloki – eivät vaikuta suorittamiseen, mutta tekevät historiasta luettavan kuuden kuukauden kuluttua, kun kukaan ei enää muista, miksi sanamuotoa muutettiin.

Kriittinen yksityiskohta löytyy kohdasta classifier_ticket lopusta: palautettu vastaus sisältää kentän prompt_version. Lokita tämä kenttä jokaisen tuloksen yhteydessä, jolloin poikkeamatilanteiden analysointi muuttuu mahdolliseksi – tiedät, että tiistai-iltapäivän väärin luokitellut tiketit tulivat kaikki versiosta v004 ilman käyttöönottoaikaleimojen ristiintarkistusta.

from openai import OpenAI

client = OpenAI()
catalog = PromptCatalog("prompts/")

# Tallenna promptti
catalog.save_prompt(
    name="ticket-classifier",
    system_prompt="""Olet tukitikettien luokittelija.
Luokittele jokainen tiketti seuraavasti: bug, feature, question, billing.
Vastaa JSON-muodossa, jossa on category, priority (1-5), summary.""",
    model="gpt-5.6-terra",
    temperature=0.1,
    metadata={
        "author": "marie.dupont",
        "description": "Zendesk-tikettien automaattinen luokittelu",
        "changelog": "Alkuperäinen versio"
    }
)

# Tuotannossa: käytä aktiivista versiota
def classifier_ticket(ticket_text: str) -> dict:
    """Luokittelee tiketin käyttäen aktiivista prompttia."""
    prompt_config = catalog.get_active("ticket-classifier")

    response = client.responses.create(
        model=prompt_config["model"],
        reasoning={"effort": "none"},  # temperature vaatii effort none
        instructions=prompt_config["system_prompt"],
        input=ticket_text,
        temperature=prompt_config["temperature"]
    )

    return {
        "result": json.loads(response.output_text),
        "prompt_version": prompt_config["version"]
    }

Versionointi Gitin kanssa

Tiemien kannalta tallenna prompttisi omaan Git-varastoon. Alla oleva puurakenne noudattaa yksinkertaista sopimusta: yksi kansio prompttia kohden, sisältäen sen määritelmän, testitapaukset ja muutoslokin. Testien pitäminen niiden varmentaman promptin vieressä ei ole kosmeettista – vetopyyntö muuttaa molempia yhdessä, ja katselmoija arvioi muutosta näytön perusteella eikä ilmoitetun aikomuksen perusteella.

prompts/
  ticket-classifier/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md
  invoice-extractor/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md

YAML korvaa tässä JSONin erityisestä syystä: promptit ovat monirivisiä tekstejä, ja syntaksi | näyttää ne täsmälleen niin kuin ne lähetetään, ilman escape-merkkejä tai harhaanjohtavia \n-merkkejä. Git-diff tälle tiedostolle näyttää proosadiffiltä – katselmoija näkee, että lause on lisätty. Tulostusskeema kulkee samassa tiedostossa, joten koko kutsun konfiguraatio mahtuu yhteen artefaktiin.

# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
  Olet tukitikettien luokittelija.
  Luokittele jokainen tiketti seuraavasti: bug, feature, question, billing.
  Vastaa JSON-muodossa, jossa on category, priority (1-5), summary.
schema:
  type: object
  properties:
    category:
      type: string
      enum: [bug, feature, question, billing]
    priority:
      type: integer
    summary:
      type: string
  required: [category, priority, summary]
  additionalProperties: false

Parhaat käytännöt

Eron elävän luettelon ja arkistokansion välillä tekevät muutamat siivoussäännöt. Pidä yksi promptti tiedostoa kohden: useiden prompttien sekoittaminen samaan asiakirjaan tekee diffeistä lukukelvottomia ja palautuksista mahdottomia kohdistaa. Pakota muutosloki, joka dokumentoi ei niinkään sitä, mitä muuttui – diff näyttää sen – vaan miksi: “lisätty ohje monikielisistä tiketeistä tuen palautteen perusteella” on kymmentä riviä teknistä kuvausta arvokkaampi.

Liitä systemaattisesti testisarja jokaiseen prompttiin; muuten käyttäjät ovat ensimmäisiä kertomaan, kun muutos rikkoo vakiintunutta toimintaa. Ohjaa prompttien muutokset saman koodikatselmusprosessin läpi kuin koodikin: promptti, joka menee tuotantoon ilman katselmusta, tuottaa yhtä paljon yllätyksiä kuin katselmoimaton koodi. Varmista, että palautus vie alle minuutin, ja testaa se hiljaisena päivänä äläkä kesken häiriötilanteen. Lopuksi merkitse käyttöönotetut versiot tageilla, jotta havaittu toiminta voidaan linkittää yksiselitteisesti tiettyyn varaston tilaan.

Luettelon testaaminen palautuksella

Määritä PromptCatalog kolmelle sovelluksesi todelliselle promptille ja tallenna sitten kaksi tai kolme versiota kustakin kehittämällä ohjeita pienin askelin – sävyohje, lisätty kategoria. Versionointi osoittaa arvonsa näissä hienovaraisissa muutoksissa, koska juuri niitä et muista tehneesi. Määritä aktivointi ja deaktivointi ja liitä jokaiseen prompttiin testisarja.

Päätä opettavaisimpaan harjoitukseen: aktivoi tahallisesti heikentynyt versio, havaitse regressio testien kautta ja suorita palautus aikaa mitaten. Jos toimenpide kestää yli minuutin, korjaa menettely ennen kuin lisäät yhtäkään prompttia luetteloon – hidas palautus ei ole palautus, vaan pitkittynyt häiriötilanne.

Keskeiset asiat

  • Promptit ovat ohjelmistoartefakteja, jotka vaativat versionointia
  • Jokainen versio on JSON- tai YAML-tiedosto metatietoineen
  • Tila (draft, active, deprecated) mahdollistaa asteittaisen käyttöönoton
  • Tallenna promptit Gitiin testien ja muutoslokin kanssa
  • Palautuksen on oltava välitön regressiotilanteessa