Prompttien versionointi ja luettelohallinta
Tällä sivulla
Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: parametrit
temperaturejatop_phyväksytään vain, kun päättelypyrkimys onnone, 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) taireasoning_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