Prompttien automaattinen arviointi
Tällä sivulla
Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella: parametrit
temperaturejatop_phyväksytään vain, kun päättelypyrkimys (reasoning effort) 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 automaattinen arviointi
Automaattinen arviointi on kypsän promptien suunnitteluputken kulmakivi. Sen avulla voit havaita regressiot, verrata malleja ja validoida muutokset ennen käyttöönottoa. Ilman sitä jokainen promptin muutos on sokkoarvaus.
Arviointityypit
Kolme arvioijaryhmää jakaa työn odotetun tulosteen luonteen perusteella, ja yhdistät niitä lähes aina useita samanaikaisesti.
Täsmällinen vastaavuus (Exact Match)
Tehtävissä, joissa on vain yksi odotettu vastaus, suora vertailu riittää. eval_exact_match normalisoi kirjainkoon ja välilyönnit ennen vertailua: ilman tätä varotoimea “Bug” ja “bug” laskettaisiin virheeksi, mikä pakottaisi sinut korjaamaan ongelmaa, jota ei ole olemassa.
eval_set_match käsittelee tapauksia, joissa vastaus on joukko – esimerkiksi asiakirjasta löydetyt entiteetit tai artikkelille määritetyt kategoriat. Se johtaa tarkkuuden (precision) ja kattavuuden (recall), kaksi lukua, jotka kertovat erilaisia tarinoita: korkea tarkkuus ja alhainen kattavuus viittaavat liian varovaiseen malliin, joka poimii vain sen, mistä on varma; päinvastainen tilanne paljastaa mallin, joka hallusinoi täyttääkseen aukot. F1-mittari tiivistää ne kätevästi, mutta ei korvaa niitä vianmäärityksessä.
def eval_exact_match(prediction: str, reference: str) -> bool:
"""Exact match after normalization."""
return prediction.strip().lower() == reference.strip().lower()
def eval_set_match(prediction: set, reference: set) -> dict:
"""Set match (entities, categories)."""
tp = len(prediction & reference)
fp = len(prediction - reference)
fn = len(reference - prediction)
precision = tp / (tp + fp) if (tp + fp) > 0 else 0
recall = tp / (tp + fn) if (tp + fn) > 0 else 0
f1 = (2 * precision * recall / (precision + recall)
if (precision + recall) > 0 else 0)
return {"precision": precision, "recall": recall, "f1": f1}
Semanttinen arviointi (Embedding)
Tekstivastauksissa, joissa sanamuoto voi vaihdella, täsmällinen vastaavuus muuttuu absurdiksi: lauseet “Tilauksesi toimitetaan huomenna” ja “Toimitus on ajoitettu huomiseksi” tarkoittavat samaa asiaa, mutta saisivat nollapisteen. Upotusten (embeddings) välinen kosinisimilaarisuus mittaa semanttista läheisyyttä merkkien sijaan ja palauttaa jatkuvan pistemäärän.
Asetat kynnyksen, jonka ylittävä vastaus katsotaan hyväksyttäväksi. Kalibroi se muutaman kymmenen manuaalisesti “vastaaviksi” tai “erilaisiksi” luokitellun parin perusteella ja valitse arvo, joka erottaa kaksi ryhmää parhaiten: mututuntumalla valittu kynnys tuottaa yhtä mielivaltaisia tuloksia kuin mittauksen puuttuminen kokonaan, vain harhan luoden tiukkuutta.
from openai import OpenAI
import numpy as np
client = OpenAI()
def eval_semantic_similarity(prediction: str,
reference: str) -> float:
"""Cosine similarity between embeddings."""
response = client.embeddings.create(
model="text-embedding-3-large",
input=[prediction, reference]
)
emb_pred = np.array(response.data[0].embedding)
emb_ref = np.array(response.data[1].embedding)
similarity = float(
np.dot(emb_pred, emb_ref) /
(np.linalg.norm(emb_pred) * np.linalg.norm(emb_ref))
)
return similarity
LLM-arviointi (LLM-as-Judge)
Malli arvioi vastauksen laadun. Tämä on ainoa toimiva lähestymistapa, kun vertailukohtaa ei ole: kukaan ei kirjoita käsin “oikeaa” tukivastausta kahteensataan tikettiin.
Arvioijan käyttökelpoisuus riippuu muutamasta asiasta. Ensinnäkin käytettävä malli: valitset arvioijaksi kyvykkäämmän mallin, tässä gpt-5.6-sol, koska arvioitavaa tasoa oleva arvioija pyrkii validoimaan omat virheensä. Toiseksi perustelujen vaatiminen: jokaisen pisteytyksen motivointi vakauttaa arviointia ja antaa sinun havaita, jos arvioija käyttää väärää kriteeriä – perustelu, joka keskustele pituudesta, vaikka kriteerinä oli selkeys, on hälytysmerkki. Lopuksi temperature arvolla 0.1 varmistaa pisteiden pysyvyyden ajojen välillä.
def eval_llm_judge(question: str, prediction: str,
criteria: list[str]) -> dict:
"""Evaluation by a judge model."""
criteria_text = "\n".join(
f"- {c}: score from 1 to 5" for c in criteria
)
response = client.responses.create(
model="gpt-5.6-sol", # More capable model as judge
reasoning={"effort": "none"}, # temperature requires effort none
instructions="You are an expert, impartial evaluator.",
input=f"""Evaluate this response according to the following criteria:
Question asked: {question}
Response to evaluate: {prediction}
Criteria:
{criteria_text}
For each criterion, give a score from 1 to 5 with justification.""",
text={
"format": {
"type": "json_schema",
"name": "evaluation",
"schema": {
"type": "object",
"properties": {
"scores": {
"type": "array",
"items": {
"type": "object",
"properties": {
"criterion": {"type": "string"},
"score": {"type": "integer"},
"justification": {"type": "string"}
},
"required": ["criterion", "score",
"justification"],
"additionalProperties": False
}
},
"overall_score": {"type": "number"},
"verdict": {"type": "string"}
},
"required": ["scores", "overall_score", "verdict"],
"additionalProperties": False
},
"strict": True
}
},
temperature=0.1
)
return json.loads(response.output_text)
Täydellinen arviointiputki
EvalPipeline kokoaa nämä rakennuspalikat: se lataa testisarjan, suorittaa promptin jokaisessa tapauksessa, soveltaa kaikkia annettuja arvioijia ja aggregoi pisteet. Arvioijat välitetään funktioiden listana, ja kaikkia kutsutaan samalla allekirjoituksella; mittarin lisääminen ei siis vaadi putken muokkaamista, ja voit suorittaa täsmällisen vastaavuuden, semanttisen similaarisuuden ja arvioijan samassa suorituksessa maksamatta generoinnista kolme kertaa.
Metodi summary kerää myös kulutetut tokenit. Tämä näennäisesti toissijainen rivi suojaa sinua yleiseltä ansalta: promptiversio, joka nostaa pistemäärää kahdella pisteellä mutta kolminkertaistaa laskun, ei välttämättä ole oikea valinta, ja on parempi oppia se kompromisseja tehdessä kuin kuukausilaskun saapuessa.
import json
from dataclasses import dataclass
from pathlib import Path
@dataclass
class TestCase:
"""A test case for evaluation."""
input_text: str
expected_output: str = None
metadata: dict = None
class EvalPipeline:
"""Automated evaluation pipeline."""
def __init__(self, test_suite_path: str):
"""Loads the test suite from a JSON file."""
data = json.loads(Path(test_suite_path).read_text())
self.test_cases = [TestCase(**tc) for tc in data]
self.results = []
def run(self, prompt_config: dict,
evaluators: list[callable]) -> dict:
"""Runs all tests and evaluates results."""
self.results = []
for tc in self.test_cases:
# Generate response
response = client.responses.create(
model=prompt_config["model"],
reasoning={"effort": "none"}, # temperature requires effort none
instructions=prompt_config["system_prompt"],
input=tc.input_text,
temperature=prompt_config.get("temperature", 0.1)
)
prediction = response.output_text
# Evaluate with each evaluator
scores = {}
for evaluator in evaluators:
score = evaluator(
question=tc.input_text,
prediction=prediction,
reference=tc.expected_output
)
scores[evaluator.__name__] = score
self.results.append({
"input": tc.input_text,
"expected": tc.expected_output,
"prediction": prediction,
"scores": scores,
"tokens": {
"input": response.usage.input_tokens,
"output": response.usage.output_tokens
}
})
return self.summary()
def summary(self) -> dict:
"""Summarizes evaluation results."""
if not self.results:
return {"error": "No results"}
# Aggregate scores by evaluator
all_scores = {}
for result in self.results:
for eval_name, score in result["scores"].items():
if eval_name not in all_scores:
all_scores[eval_name] = []
if isinstance(score, (int, float)):
all_scores[eval_name].append(score)
elif isinstance(score, dict) and "f1" in score:
all_scores[eval_name].append(score["f1"])
summary = {
"total_tests": len(self.results),
"average_scores": {
name: sum(scores) / len(scores)
for name, scores in all_scores.items()
if scores
},
"total_token_cost": sum(
r["tokens"]["input"] + r["tokens"]["output"]
for r in self.results
)
}
return summary
Testisarja: Muotoilu
Testisarjan muotoilu on tarkoituksellisen minimaalinen: syöte, odotettu tuloste ja vapaamuotoinen metadata. Tämä metadata on hyödyllisempää kuin miltä näyttää – luokittelemalla jokaisen tapauksen kategorian mukaan voit purkaa pisteet ja havaita, ettei luokittelijasi epäonnistu satunnaisesti, vaan tietyssä pyyntöryhmässä, mitä 88 %:n globaali keskiarvo ei paljasta. Alla olevat kolme esimerkkiä näyttävät myös, mitä hyvän sarjan tulisi sisältää: selkeitä tapauksia, kuten sovelluksen kaatuminen käynnistyksessä, mutta myös tapauksia, jotka rajaavat toista kategoriaa – kysymys puuttuvasta ominaisuudesta näyttää hyvin paljon bugiraportilta, ja juuri tällä rajapinnalla luokittelijan laatu ratkeaa.
[
{
"input_text": "My package hasn't arrived",
"expected_output": "complaint",
"metadata": {"category": "delivery"}
},
{
"input_text": "How do I enable dark mode?",
"expected_output": "question",
"metadata": {"category": "feature"}
},
{
"input_text": "The app crashes on startup on iOS 18",
"expected_output": "bug",
"metadata": {"category": "technical"}
}
]
CI/CD-integraatio
Suorita arviointi jokaisen promptin muutoksen yhteydessä. Funktio ci_eval_check muuttaa mittauksen suojakaiteeksi: se ajaa putken, vertaa keskipistemäärää kynnysarvoon ja palauttaa totuusarvon, jonka integraatioketjusi tulkitsee buildin onnistumiseksi tai epäonnistumiseksi. Muutos, joka pudottaa tarkkuuden alle 85 %:n, ei enää päädy tuotantoon, aivan kuten rikkoutunut yksikkötesti estää mergen.
Aseta kynnys nykyisen version jo saavuttaman pistemäärän perusteella, äläkä ihanteen mukaan. Jos asetat sen liian korkealle, tuomitset tiimin kiertämään tarkistuksen väliaikaisilla poistoilla, jotka muuttuvat pysyviksi; jos asetat sen liian matalalle, et tarkista mitään näyttäen silti vihreää merkkiä. Muista lopuksi, että sarjan on pysyttävä edustavana todelliselle liikenteelle: kynnys, joka täyttyy kahdenkymmenen kaksi vuotta sitten kirjoitetun tapauksen perusteella, ei todista mitään tämän päivän pyynnöistä.
def ci_eval_check(prompt_config: dict,
test_suite: str,
min_score: float = 0.85) -> bool:
"""CI/CD gate: checks that the prompt meets the minimum score."""
pipeline = EvalPipeline(test_suite)
def accuracy(question, prediction, reference):
return 1.0 if prediction.strip().lower() == reference.strip().lower() else 0.0
results = pipeline.run(prompt_config, [accuracy])
avg_score = results["average_scores"].get("accuracy", 0)
print(f"Average score: {avg_score:.2%}")
print(f"Minimum threshold: {min_score:.2%}")
if avg_score < min_score:
print("FAILURE: score below threshold")
return False
print("SUCCESS: prompt validated")
return True
Arviointidashboard
Seuraa pisteiden kehitystä ajan myötä. Yksi piste ei kerro mitään; sarja kertoo promptisi tarinan ja vastaa kysymykseen, joka nousee aina esiin palavereissa: edistymmekö? Alla oleva funktio tuottaa Markdown-taulukon, joka asettaa vierekkäin jokaiselle versiolle keskipistemäärän, kulutetut tokenit ja arvioidun kustannuksen. Muotoilu ei ole sattumanvarainen: se liimautuu suoraan vetopyyntöön (pull request), mikä tekee vertailusta luettavaa ihmisille, jotka eivät koskaan avaa koodiasi.
def comparison_report(results: dict[str, dict]) -> str:
"""Generates a comparative report between prompt versions."""
report = "# Comparative Evaluation Report\n\n"
report += "| Version | Average Score | Average Tokens | Cost |\n"
report += "|---------|---------------|----------------|------|\n"
for version, data in results.items():
score = data.get("average_scores", {})
score_val = list(score.values())[0] if score else 0
tokens = data.get("total_token_cost", 0)
report += (f"| {version} | {score_val:.2%} | "
f"{tokens} | ${tokens * 5 / 1e6:.4f} |\n")
return report
Suojakaiteidesi rakentaminen
Luo sarja, jossa on kaksikymmentä testitapausta aidolle promptille, sijoittaen joukkoon muutama reunatapaus kahdenkymmenen mukavan esimerkin sijaan: sarja, joka läpäisee testin 100 %:sti ensimmäisellä yrittämällä, ei opeta sinulle mitään. Toteuta kolme arvioijatyyppiä ja suorita ne yhdessä promptisi kahdelle versiolle. Täsmällinen vastaavuus antaa selkeän luvun, semanttinen similaarisuus havaitsee legitimit uudelleenmuotoilut, ja arvioija valaisee tapauksia, joissa kaksi ensimmäistä ovat eri mieltä – nämä erimielisyydet ovat opettavaisimpia siitä, mitä todella odotat mallilta.
Vertaa, tunnista voittava versio ja aseta sitten CI-skripti, joka estää käyttöönoton, jos pisteet laskevat. Tiedät järjestelmän toimivan sinä päivänä, kun se hylkää muutoksen, jonka luulit olevan itsestään selvä.
Keskeiset asiat
- Automaattinen arviointi on välttämätöntä iteroinnille luottamuksella
- Yhdistä tarvittaessa täsmällinen, semanttinen ja LLM-arvioija
- Ylläpidä testisarjaa, joka kehittyy sovelluksesi mukana
- Integroi arviointi CI/CD-putkeen minimikynnyksellä
- Käytä kyvykkäämpää mallia arvioijana arvioidessasi halvempaa mallia
- Dokumentoi jokaisen version pisteet kehityksen seuraamiseksi
Testaa tietämyksesi
Edistyneet tekniikat ja teollistaminen: viimeinen tarkistus.
1. Mitä tehokas järjestelmäprompti sisältää?
Vastaus: Roolin, laajuuden, käyttäytymissäännöt, tulostemuodon ja reunatapausten käsittelyn – kirjoitettuna spesifikaation tavoin, testattuna koodin tavoin.
2. Milloin tulisi käyttää itsejohdonmukaisuutta (self-consistency)?
Vastaus: Päättelyongelmissa, joissa on varmennettavia vastauksia: generoi useita riippumattomia päättelyketjuja ja pidä enemmistön vastausta – varianssista tulee liittolainen.
3. Mitä JSON-tila skeeman valvonnalla takaa?
Vastaus: Tulosteen, joka noudattaa ehdottomasti skeemaa (tyypit, vaaditut kentät, enumit) – validoitu API-tasolla ja uudelleenvalidoitu koodissa (JSON Schema, Zod) yllätyksettömän ketjun varmistamiseksi.
4. Mikä on grounding?
Vastaus: Vastausten ankkurointi annettuihin faktoihin (asiakirjat, haettu data) mallin muistin sijaan – vaatimuksena lainata lähteitä tai pidättäytyä vastaamasta niiden ulkopuolelta.
5. Mikä on versionoidun prompt-luettelon tarkoitus?
Vastaus: Kohdella promptteja artefakteina: versiot, A/B-testit, automaattiset arvioinnit jokaisesta muutoksesta – tiedät, mitä tuotannossa pyörii ja miksi.
Kurssin viimeinen silmukka – versioi, testaa, arvioi automaattisesti – muuttaa käsityömäisen promptien suunnittelun tiimikäytännöksi.