Przejdź do głównej treści
Polski— Wybierz język
Menu

Wersjonowanie promptów i zarządzanie katalogiem

Lekcja 14 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Wersjonowanie promptów i zarządzanie katalogiem
  2. Dlaczego wersjonować prompty
  3. Struktura katalogu
  4. Używanie katalogu w aplikacji
  5. Wersjonowanie z Git
  6. Najlepsze praktyki
  7. Testowanie katalogu z przywracaniem wersji
  8. Kluczowe wnioski

Lekcja zaktualizowana 3 listopada 2026 na podstawie dokumentacji OpenAI: parametry temperature i top_p są akceptowane wyłącznie przy wysiłku rozumowania (reasoning effort) ustawionym na none, podczas gdy modele GPT-5.6 domyślnie przeprowadzają rozumowanie (medium). Wywołania ustawiające te parametry muszą zatem określać reasoning={"effort": "none"} (Responses API) lub reasoning_effort="none" (Chat Completions). Źródła: Using GPT-6 · GPT-5.6 Terra.

Wersjonowanie promptów i zarządzanie katalogiem

W środowisku produkcyjnym Twoje prompty ewoluują tak samo jak kod. Bez wersjonowania tracisz kontrolę nad zmianami, nie możesz przywrócić poprzedniej wersji i nie wiesz, która wersja działa obecnie w produkcji. Ta lekcja pokaże Ci, jak zarządzać promptami jako artefaktami oprogramowania.

Dlaczego wersjonować prompty

Zmiana promptu może radykalnie zmienić zachowanie Twojej aplikacji. W przeciwieństwie do kodu, zmiany te są często subtelne i trudne do wykrycia bez automatycznych testów: przeformułowane zdanie, przesunięte słowo, a model zaczyna błędnie klasyfikować jeden na dziesięć przypadków brzegowych. Żaden standardowy test jednostkowy nie wychwyci tej luki, ale dział wsparcia zgłosi to trzy tygodnie później jako mglistą skargę na niewłaściwie kierowane zgłoszenia.

Wersjonowanie odpowiada na cztery odrębne potrzeby. Po pierwsze, możliwość śledzenia (traceability): wiedza o tym, kto, co i kiedy zmienił, zamienia jałową debatę zespołową w prostą kontrolę historii. Po drugie, przywracanie wersji (rollback): gdy pojawi się regresja, natychmiastowym celem nie jest zrozumienie przyczyny, lecz przywrócenie znanego zachowania. Po trzecie, porównywanie wydajności: wymaga to, aby starsze wersje pozostały wykonywalne dokładnie tak, jak były, z ich oryginalnym modelem i ustawieniami. Wreszcie, audyt: w systemach podlegających pod RODO (Ogólne Rozporządzenie o Ochronie Danych) lub inne ramy zgodności, musisz udowodnić, jakie instrukcje obowiązywały w danym dniu – zrzut ekranu nie wystarczy.

Struktura katalogu

Klasa PromptCatalog spełnia te potrzeby przy minimalnej infrastrukturze: jeden folder na prompt, jeden plik JSON na wersję, numerowane sekwencyjnie. Każdy plik grupuje tekst promptu systemowego wraz z powiązanym modelem i temperaturą – prompt dostrojony do 0,1 i ten sam prompt przy 0,7 to nie to samo, a zablokowanie ich razem zapobiega przywracaniu tekstu przy jednoczesnym zapomnieniu o jego ustawieniach.

Pole status śledzi cykl życia. Wersja zaczyna jako draft (szkic), co pozwala na przygotowanie i testowanie bez wpływu na ruch produkcyjny. Wywołanie activate przełącza ją na active (aktywna) i automatycznie obniża status poprzedniej wersji do deprecated (przestarzała), zapewniając, że w danym momencie tylko jedna wersja obsługuje ruch. Metoda ta czyni przywracanie wersji trywialnym: reaktywacja wcześniejszej wersji to pojedyncze wywołanie, a nie wdrożenie. Twoja aplikacja wywołuje get_active w produkcji, podczas gdy list_versions wspiera przeglądy i audyty.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Menedżer katalogu promptów z wersjonowaniem."""

    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:
        """Zapisuje nową wersję promptu."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Określenie numeru wersji
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Zapis
        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:
        """Pobiera prompt po nazwie i wersji."""
        prompt_dir = self.catalog_dir / name

        if version == "latest":
            versions = sorted(prompt_dir.glob("v*.json"))
            if not versions:
                raise FileNotFoundError(f"Prompt '{name}' nie znaleziony")
            filepath = versions[-1]
        else:
            filepath = prompt_dir / f"{version}.json"

        return json.loads(filepath.read_text())

    def get_active(self, name: str) -> dict:
        """Pobiera aktywną wersję promptu."""
        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"Brak aktywnej wersji dla '{name}'"
        )

    def activate(self, name: str, version: str):
        """Aktywuje wersję i dezaktywuje inne."""
        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]:
        """Wyświetla listę wszystkich wersji promptu."""
        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

Używanie katalogu w aplikacji

Po stronie wywołującego zasada jest prosta: Twój kod nie zawiera żadnego tekstu promptu; żąda on aktywnej wersji z katalogu. Dzięki temu prompty można modyfikować bez dotykania kodu aplikacji i zapobiega się grzęźnięciu trzydziestoliniowych ciągów znaków w środku funkcji. Metadane zapisywane podczas przechowywania – autor, opis, dziennik zmian – nie mają wpływu na wykonanie, ale sprawiają, że historia jest czytelna sześć miesięcy później, gdy nikt nie pamięta, dlaczego zmieniono sformułowanie.

Kluczowy szczegół znajduje się na końcu funkcji classifier_ticket: zwracana odpowiedź zawiera prompt_version. Loguj to pole przy każdym wyniku, a analiza incydentów stanie się możliwa – będziesz wiedzieć, że wszystkie błędnie sklasyfikowane zgłoszenia z wtorkowego popołudnia pochodziły z wersji v004, bez konieczności krzyżowego odniesienia do znaczników czasu wdrożenia.

from openai import OpenAI

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

# Zapisz prompt
catalog.save_prompt(
    name="ticket-classifier",
    system_prompt="""Jesteś klasyfikatorem zgłoszeń wsparcia.
Skategoryzuj każde zgłoszenie jako: bug, feature, question, billing.
Odpowiedz w formacie JSON zawierającym category, priority (1-5), summary.""",
    model="gpt-5.6-terra",
    temperature=0.1,
    metadata={
        "author": "marie.dupont",
        "description": "Automatyczna klasyfikacja zgłoszeń Zendesk",
        "changelog": "Wersja początkowa"
    }
)

# W produkcji: użyj aktywnej wersji
def classifier_ticket(ticket_text: str) -> dict:
    """Klasyfikuje zgłoszenie przy użyciu aktywnego promptu."""
    prompt_config = catalog.get_active("ticket-classifier")

    response = client.responses.create(
        model=prompt_config["model"],
        reasoning={"effort": "none"},  # temperatura wymaga 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"]
    }

Wersjonowanie z Git

Dla zespołów przechowuj swoje prompty w dedykowanym repozytorium Git. Poniższe drzewo przestrzega prostej konwencji: jeden folder na prompt, zawierający jego definicję, przypadki testowe i dziennik zmian. Przechowywanie testów obok promptu, który weryfikują, nie jest kwestią kosmetyczną – pull request modyfikuje oba elementy razem, a recenzent ocenia zmianę na podstawie dowodów, a nie deklarowanych intencji.

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

YAML zastępuje tutaj JSON z konkretnego powodu: prompty to teksty wieloliniowe, a składnia | wyświetla je dokładnie tak, jak są wysyłane, bez znaków ucieczki czy zbędnych \n. Różnica (diff) w Gicie dla tego pliku czyta się jak różnica w prozie – recenzent widzi, że dodano zdanie. Schemat wyjścia podróżuje w tym samym pliku, więc kompletna konfiguracja wywołania mieści się w jednym artefakcie.

# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
  Jesteś klasyfikatorem zgłoszeń wsparcia.
  Skategoryzuj każde zgłoszenie jako: bug, feature, question, billing.
  Odpowiedz w formacie JSON zawierającym 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

Najlepsze praktyki

O tym, co odróżnia żywy katalog od folderu archiwalnego, decyduje kilka zasad porządkowych. Przestrzegaj zasady jeden prompt na plik: mieszanie wielu promptów w jednym dokumencie czyni różnice (diffy) nieczytelnymi, a przywracanie wersji niemożliwym do precyzyjnego ukierunkowania. Wymuszaj prowadzenie dziennika zmian (changelog), dokumentującego nie co się zmieniło (pokazuje to diff), ale dlaczego: „dodano instrukcję dotyczącą zgłoszeń wielojęzycznych w odpowiedzi na feedback wsparcia“ jest warte dziesięć linii technicznego opisu.

Systematycznie kojarz zestaw testów z każdym promptem; w przeciwnym razie to użytkownicy pierwsi powiedzą Ci, gdy modyfikacja zepsuje ustalone zachowanie. Przeprowadzaj zmiany promptów przez ten sam proces recenzji kodu co sam kod: prompt, który trafia do produkcji bez recenzji, generuje takie same niespodzianki jak nieprzejrzany kod. Upewnij się, że przywracanie wersji zajmuje mniej niż minutę, i przetestuj to w spokojny dzień, a nie podczas incydentu. Na koniec oznaczaj wdrożone wersje tagami, aby jednoznacznie powiązać obserwowane zachowanie z konkretnym stanem repozytorium.

Testowanie katalogu z przywracaniem wersji

Skonfiguruj PromptCatalog dla trzech rzeczywistych promptów z Twojej aplikacji, a następnie nagraj dwie lub trzy wersje każdego z nich, ewoluując instrukcje małymi krokami – instrukcja tonu, dodana kategoria. Wersjonowanie dowodzi swojej wartości przy tych drobnych zmianach, ponieważ to właśnie je zapomnisz, że wprowadziłeś. Skonfiguruj aktywację i dezaktywację oraz dołącz zestaw testów do każdego promptu.

Zakończ najbardziej pouczającym ćwiczeniem: celowo aktywuj zdegradowaną wersję, zaobserwuj regresję poprzez testy i wykonaj przywracanie wersji, mierząc czas jego trwania. Jeśli operacja przekracza jedną minutę, napraw procedurę przed dodaniem choćby jednego promptu do katalogu – wolne przywracanie wersji to nie przywracanie, to przedłużający się incydent.

Kluczowe wnioski

  • Prompty to artefakty oprogramowania wymagające wersjonowania
  • Każda wersja to plik JSON lub YAML z metadanymi
  • Status (draft, active, deprecated) umożliwia stopniowe wdrażanie
  • Przechowuj prompty w Gicie wraz z testami i dziennikiem zmian
  • Przywracanie wersji musi być natychmiastowe w przypadku regresji