Promptverziózás élesben: git, registry, címkék és visszaállítás

A legtöbb LLM-funkcióban a prompt gyakrabban változik, mint a kód. Egy support-asszisztens új eszkalációs szabályt kap, egy kinyerési lépés megtanul egy új számlaelrendezést, egy osztályozó eggyel több kategóriát kap. Mindegyik élesbe szállított viselkedésváltozás, és sok kódbázisban a legkevésbé kontrollált: egy dashboardon átírt szöveg, egy konfigurációs fájlba bemásolt sablon, review nélkül, és senki sem tudja, melyik verzió válaszolt egy adott ügyfélnek múlt kedden.

Ez az útmutató bemutatja, mit kell tartalmaznia egy promptverziónak, mikor elég a git és mikor éri meg egy prompt registry, hogyan teszik olcsóvá a címkék a visszaállítást, hogyan védd a promptváltozásokat evallal a CI-ban, és egy mellékhatást, amelyet a csapatok gyakran nem vesznek észre: egy promptkiadás nullázza a szolgáltatói prompt cache-t. Szó lesz egy 2026-os változásról is, amely a vita egy részét eldönti: az OpenAI kivezeti a mentett prompt-objektumait.

Mi tartozik egy promptverzióhoz

Egy sablonszöveg önmagában nem határozza meg a viselkedést. Ugyanaz a szöveg más modellel, más hőmérséklettel, más eszközlistával vagy más kimeneti sémával más kimenetet ad. Ha a verziótörténet csak a szöveget rögzíti, nem tudod megválaszolni azt a kérdést, amely egy incidensnél számít: pontosan mi futott? A csomagot verziózd:

Az alább tárgyalt registryk mindkettő támogatja ezt. A Langfuse-promptoknál a sablon mellett config mező is van, az MLflow pedig verziónként commitüzenetet enged, nagyon hasonlóan a githez. Gitben ezt úgy éred el, hogy a sablon, a paraméterek és a séma ugyanabban a modulban vannak.

Git vagy prompt registry?

2026-ban a git melletti legerősebb érvet egy olyan szolgáltató adta, amely korábban az alternatívát árulta. Az OpenAI kivezeti az API-ja újrahasznosítható prompt-objektumait: a promptok létrehozása 2026. június 3-tól háttérbe szorul, a v1/prompts leállítása pedig 2026. november 30-ra van ütemezve. A migrációs útmutató azt mondja, hogy a prompt tartalmát vidd át az alkalmazás kódjába, hogy a promptváltozások ugyanazon a review- és kiadási folyamaton menjenek át, mint a többi kód, a promptváltozókat cseréld típusos függvényargumentumokra, a verziókat pedig commitokkal, pull requestekkel és CI-ban futó evalokkal kezeld.

A registryk ettől még valódi problémákat oldanak meg. A Langfuse és az MLflow megváltoztathatatlan verziókat tárol áthelyezhető címkékkel, így egy termékmenedzser kipróbálhat egy új megfogalmazást, egy ügyeletes mérnök pedig másodpercek alatt, telepítés nélkül visszaállhat. Az éles metrikákat is verziókhoz kötik. A kérdés nem az, melyik tábornak van igaza, hanem az, hogy ki szerkeszti a promptokat, és milyen gyors visszaállás kell.

Megváltoztathatatlan verziók, áthelyezhető címkék

A hasznos gondolati modell ugyanaz, mint a konténer-registryknél: a verziók megváltoztathatatlanok, a tagek vándorolnak. Az MLflow kimondja, hogy a promptverziók a reprodukálhatóság miatt megváltoztathatatlanok, egy alias, például a production, pedig módosítható hivatkozás, amelyet A/B tesztekhez vagy visszaállításhoz átirányíthatsz. A Langfuse automatikusan oszt verziószámot, karbantart egy latest címkét, amely a legújabb verzióra mutat, és a production címkéjű verziót adja vissza, ha címke és verzió nélkül kérsz le promptot.

A Langfuse dokumentációjából két részletet érdemes a tervezésnél figyelembe venni. Ha olyan címkét kérsz, amely egyetlen verzión sincs rajta, 404-et kapsz; csendes visszaesés a production vagy latest címkére nincs. A védett címkék pedig, amelyek a fizetős és vállalati kiadásokban érhetők el, megakadályozzák, hogy a viewer és member szerepkörök áthelyezzék a production címkét, ez a registry megfelelője egy védett branchnek.

Promptok betöltése futásidőben új hibaforrások nélkül

A registry hálózati hívást tesz a funkció és az utasításai közé. A Langfuse ezt kliensoldali cache-sel kezeli: az alapértelmezett TTL 60 másodperc, és lejárat után az SDK továbbra is a régi promptot szolgálja ki, miközben a háttérben újratölti. Ha a cache üres és az API nem érhető el, egy átadott fallback-prompt jön vissza helyette. Erre az utolsó esetre kell tervezni, mert hidegindításnál éppen abban az incidensben fordul elő, amikor a registry nem működik.

from langfuse import get_client
from prompts.support import SUPPORT_SYSTEM_FALLBACK  # the same text, committed in git

langfuse = get_client()

def support_prompt():
    # label, not version: promotion and rollback happen by moving "production"
    return langfuse.get_prompt(
        "support-assistant",
        label="production",
        cache_ttl_seconds=300,          # default is 60; longer means slower rollbacks
        fallback=SUPPORT_SYSTEM_FALLBACK,
    )

A TTL olyan kompromisszum, amelyet érdemes leírni: minél hosszabb, annál kevesebb a registry-hívás, és annál tovább tart, mire egy visszaállítás minden példányhoz eljut. Batch-feladatokban és evalokban rögzíts konkrét verziót, ott a reprodukálhatóság fontosabb, mint a címke követése.

Ha a promptok a kódban élnek, legyen szerkezetük

Az OpenAI útmutatója konkrét: a promptok egy kis prompts/ modulban legyenek, promptonként egy elnevezett builderrel és könnyű eval-fixture-ökkel, ne szétszórva a kódbázisban. Két szokást tegyél hozzá. Először: a statikus tartalom legyen elöl, a dinamikus a végén, ezt ugyanez az útmutató javasolja, mert a cache-találat pontos előtagegyezésen múlik. Másodszor: minden prompttal exportálj egy verzióazonosítót, hogy a trace-ek registry nélkül is rögzítsék, melyik futott.

// prompts/invoice-extract.ts
import { z } from 'zod'

export const INVOICE_EXTRACT = {
  id: 'invoice-extract',
  version: '2026-10-14.2',          // bump on any change to text, model, params or schema
  model: 'claude-sonnet-5-5',
  params: { max_tokens: 2048 },
  schema: z.object({ supplier: z.string(), total: z.number(), currency: z.string().length(3) }),
  build: (input: { pdfText: string; locale: 'de' | 'en' | 'hu' }) => ({
    system: SYSTEM_RULES,           // static, long, cacheable: first
    messages: [{ role: 'user' as const, content: `Locale: ${input.locale}\n\n${input.pdfText}` }],
  }),
}

Minden promptváltozás elé eval-kapu

A verziózás megmondja, mi változott; csak egy értékelés mondja meg, hogy jobb lett-e. A legolcsóbb működő megoldás minden olyan pull requestnél, amely promptfájlokat érint, egy rögzített tesztkészletet futtat a régi és az új prompton. A Promptfoo GitHub Action pontosan ezt csinálja: a promptútvonalak alatti változásokra indul, összeveti a promptot a változás előtt és után, az eredményt PR-kommentként teszi közzé a nézegetőjére mutató linkkel, és a futások között cache-eli a modellhívásokat a költség miatt.

# .github/workflows/prompt-eval.yml (trimmed)
on:
  pull_request:
    paths: ['prompts/**']
jobs:
  evaluate:
    runs-on: ubuntu-latest
    permissions: { pull-requests: write }
    steps:
      - uses: actions/checkout@v4
      - uses: promptfoo/promptfoo-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          prompts: 'prompts/**/*.json'
          config: 'prompts/promptfooconfig.yaml'
          cache-path: ~/.cache/promptfoo

Az, hogy mi kerül a tesztkészletbe, többet számít az eszköznél. Valódi hibákból indulj, ahogy az LLM-evalok termékfunkciókhoz cikkben leírtam: minden hibajegy, amelyet egy promptváltozás javított, tesztesetté válik, így a következő változás nem hozhatja vissza csendben. Egy modellfrissítés csak egy promptverzió új modellazonosítóval, és ugyanazt a kaput kapja, lásd: modellmigrációk regresszió nélkül.

Kösd össze az éles trace-eket a promptverziókkal

Az offline evalok azokat az eseteket fedik le, amelyekre gondoltál. Az éles üzem a többit, de csak akkor, ha minden generálás rögzíti, melyik promptverzió állította elő. A Langfuse az SDK-n vagy az OpenAI-, LangChain- és AI SDK-integrációin keresztül köti a promptot a generáláshoz, a Metrics fül pedig medián késleltetés, bemeneti és kimeneti tokenek, költség, generálásszám és medián pontszám szerint veti össze a verziókat. Egy megkötés a dokumentációból: ha a fallback-prompt fut, nem jön létre kapcsolat, így az össze nem kötött generálások hirtelen megugrása maga is jelzi, hogy a registry elérhetetlen volt.

Registry nélkül a kódból származó promptazonosítót és verziót írd a span-attribútumokba. Az LLM-ágensek megfigyelhetősége cikk OpenTelemetry-beállítása egy group-byjal ugyanezt az összevetést adja.

A promptkiadás cache-esemény is

A szolgáltatói prompt cache pontos előtagokhoz kötődik. Az Anthropic a tools, aztán a system, aztán a messages részt cache-eli, és egy szinten végzett változtatás azt a szintet és minden utána következőt érvénytelenít: ha egy eszközleírást módosítasz, az egész cache elvész, ha a rendszerpromptot, a system és a messages rész újraépül. A cache-írás drágább a normál bemenetnél (ötperces cache-nél az alapár 1,25-szöröse), az olvasás töredékbe kerül, így közvetlenül egy kiadás után írási árat fizetsz, és hosszabb az első tokenig eltelt idő, amíg az új előtag fel nem melegszik. A mechanikát a prompt caching és modell-routing cikkben írtam le.

Észszerű alapbeállítás kis csapatoknak

Az általam épített projektekben az alapértelmezés: először git. A promptok a modelljükkel, paramétereikkel és sémájukkal együtt egy prompts/ modulban élnek; minden változásnál nő egy verziószöveg; a pull requesten promptfoo- vagy hasonló eval fut; és a verzió minden trace-be bekerül. Registry akkor jön a képbe, ha a fejlesztőcsapaton kívül valakinek promptot kell szerkesztenie, vagy ha a visszaállításnak gyorsabbnak kell lennie egy telepítésnél. Ilyenkor a git marad az igazság forrása, a CI pedig publikál a registrybe, így a címke csak az eval-kapu után mozdul.

• Az éles szöveget soha ne szerkeszd helyben. Hozz létre verziót, értékeld ki, helyezd át a címkét.
• Evalokban és batch-feladatokban rögzítsd a verziót, címkét csak interaktív útvonalakon kövess.
• Minden registryben kezelt prompthoz tarts fallback-promptot a repóban.
• A review-ban kezeld kódként a promptot: egy prompt diffje ugyanannyi figyelmet érdemel, mint egy SQL-lekérdezésé.

Források

1. OpenAI API Docs: Migrate from prompt objects
2. OpenAI API Docs: Prompt engineering (reusable prompts deprecation note)
3. Langfuse Docs: Prompt version control
4. Langfuse Docs: Prompt caching in the SDKs
5. Langfuse Docs: Link prompts to traces
6. MLflow Docs: Prompt Registry
7. Promptfoo Docs: GitHub Action
8. Claude Platform Docs: Prompt caching