Премини към основното съдържание
Български— Изберете език
Меню

Версиониране на промптове и управление на каталог

Урок 14 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Версиониране на промптове и управление на каталог
  2. Защо да версионирате промптовете
  3. Структура на каталога
  4. Използване на каталога във Вашето приложение
  5. Версиониране с Git
  6. Най-добри практики
  7. Тестване на каталога с връщане назад
  8. Ключови изводи

Урокът е актуализиран на 3 ноември 2026 г. въз основа на документацията на OpenAI: параметрите temperature и top_p се приемат само при усилие за разсъждение (reasoning effort) със стойност none, докато моделите GPT-5.6 разсъждават по подразбиране (medium). Заявките, които задават тези параметри, следователно трябва да уточняват reasoning={"effort": "none"} (Responses API) или reasoning_effort="none" (Chat Completions). Източници: Използване на GPT-6 · GPT-5.6 Terra.

Версиониране на промптове и управление на каталог

В производствена среда Вашите промптове еволюират точно толкова, колкото и Вашият код. Без версиониране губите следа за промените, не можете да се върнете към предишно състояние и нямате представа коя версия работи в момента. Този урок Ви показва как да управлявате промптовете като софтуерни артефакти.

Защо да версионирате промптовете

Промяната в промпт може радикално да промени поведението на Вашето приложение. За разлика от кода, тези промени често са тънки и трудни за откриване без автоматизирани тестове: едно препратено изречение, една преместена дума и моделът започва да класифицира грешно един от десет гранични случая. Никой стандартен юнит тест няма да хване тази разлика, но екипът за поддръжка ще я сигнализира три седмици по-късно като неясна жалба за пренасочени грешно билети.

Версионирането отговаря на четири различни нужди. Първо, проследимост: знанието кой какво е променил и кога превръща безплодния екипен дебат в проста проверка на историята. Второ, връщане назад (rollback): когато се появи регресия, непосредствената цел не е да разберете защо, а да възстановите известно поведение. Трето, сравнение на производителността: това изисква по-старите версии да остават изпълними точно както са били, с оригиналния модел и настройки. Накрая, одит: за системи, подлежащи на GDPR (Общ регламент за защита на данните) или други рамки за съответствие, трябва да демонстрирате кои инструкции са били в сила на дадена дата – скрийншот няма да е достатъчен.

Структура на каталога

Класът PromptCatalog отговаря на тези нужди с минимална инфраструктура: една папка за промпт, един JSON файл за версия, номерирани последователно. Всеки файл групира текста на системния промпт заедно с асоциирания модел и температура – промпт, настроен на 0.1, и същият промпт на 0.7 не са едно и също нещо, а заключването им заедно предотвратява възстановяването на текста, докато настройките му са забравени.

Полето status проследява жизнения цикъл. Една версия започва като draft (чернова), което позволява подготовка и тестване без влияние върху живия трафик. Извикването на activate я превключва в active (активна) и автоматично понижава предишната версия до deprecated (остаряла), гарантирайки, че само една версия обслужва трафика във всеки момент. Този метод прави връщането назад тривиално: реактивирането на предишна версия е едно извикване, а не ново разполагане (deployment). Вашето приложение извиква get_active в продукция, докато list_versions поддържа прегледи и одити.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Prompt catalog manager with versioning."""

    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:
        """Saves a new version of a prompt."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

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

        # Save
        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:
        """Retrieves a prompt by name and version."""
        prompt_dir = self.catalog_dir / name

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

        return json.loads(filepath.read_text())

    def get_active(self, name: str) -> dict:
        """Retrieves the active version of a prompt."""
        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"No active version for '{name}'"
        )

    def activate(self, name: str, version: str):
        """Activates a version and deactivates others."""
        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]:
        """Lists all versions of a prompt."""
        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

Използване на каталога във Вашето приложение

От страната на извикващия правилото е просто: Вашият код не съдържа текст на промпт; той заявява активната версия от каталога. Това позволява промптовете да бъдат модифицирани без докосване на кода на приложението и предотвратява заравянето на тридесетредови низове в средата на функция. Метаданните, запазени по време на съхранението – автор, описание, дневник на промените – нямат ефект върху изпълнението, но правят историята четима шест месеца по-късно, когато никой не си спомня защо формулировката е променена.

Критичният детайл се намира в края на classifier_ticket: върнатият отговор включва prompt_version. Регистрирайте това поле с всеки резултат и анализът на инциденти става възможен – ще знаете, че грешно класифицираните билети от вторник следобед всички идват от v004, без да кръстосвате времеви печати на разполагане.

from openai import OpenAI

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

# Save a prompt
catalog.save_prompt(
    name="ticket-classifier",
    system_prompt="""You are a support ticket classifier.
Categorize each ticket as: bug, feature, question, billing.
Respond in JSON with category, priority (1-5), summary.""",
    model="gpt-5.6-terra",
    temperature=0.1,
    metadata={
        "author": "marie.dupont",
        "description": "Automatic classification of Zendesk tickets",
        "changelog": "Initial version"
    }
)

# In production: use the active version
def classifier_ticket(ticket_text: str) -> dict:
    """Classifies a ticket using the active prompt."""
    prompt_config = catalog.get_active("ticket-classifier")

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

Версиониране с Git

За екипи съхранявайте промптовете си в отделно Git хранилище. Дървото по-долу следва проста конвенция: една папка на промпт, съдържаща неговата дефиниция, тестови случаи и дневник на промените. Съхраняването на тестовете заедно с промпта, който verificат, не е козметично – пул реквест модифицира и двете заедно, а ревизорът преценява промяната въз основа на доказателства, а не на декларирано намерение.

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

YAML замества JSON тук по конкретна причина: промптовете са многоредови текстове и синтаксисът | ги показва точно както са изпратени, без екраниране или излишни символи \n. Git diff на този файл се чете като diff на проза – ревизорът вижда, че е добавено изречение. Схемата на изхода пътува в същия файл, така че пълната конфигурация за едно извикване се побира в един артефакт.

# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
  You are a support ticket classifier.
  Categorize each ticket as: bug, feature, question, billing.
  Respond in JSON with 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

Най-добри практики

Това, което разделя жив каталог от архивна папка, се свежда до няколко правила за поддръжка. Пазете един промпт на файл: смесването на множество промптове в един документ прави diff-овете нечетими и връщането назад невъзможно за точно насочване. Наложете дневник на промените, документиращ не какво се е променило – diff-ът показва това – а защо: „добавена инструкция за многоезични билети след обратна връзка от поддръжката“ струва десет реда техническо описание.

Асоциирайте систематично тестови набор с всеки промпт; в противен случай потребителите ще бъдат първите, които ще Ви кажат кога модификация нарушава установено поведение. Насочвайте промените в промптовете през същия процес на код ревю като самия код: промпт, който отива в продукция без ревю, произвежда същите изненади като неревизиран код. Уверете се, че връщането назад отнема по-малко от минута, и го тествайте в тих ден, а не по време на инцидент. Накрая, маркирайте разположените версии с тагове, за да свържете недвусмислено наблюдаваното поведение с конкретно състояние на хранилището.

Тестване на каталога с връщане назад

Настройте PromptCatalog за три реални промпта от Вашето приложение, след което запишете две или три версии на всеки, като развивате инструкциите на малки стъпки – инструкция за тон, добавена категория. Версионирането доказва стойността си при тези фино гранулирани промени, защото те са онези, които няма да помните, че сте направили. Настройте активиране и деактивиране и прикачете тестови набор към всеки промпт.

Завършете с най-поучителното упражнение: умишлено активирайте влошена версия, наблюдавайте регресията чрез тестове и изпълнете връщането назад, като засечете времето. Ако операцията надвишава една минута, поправете процедурата, преди да добавите един-единствен промпт в каталога – бавното връщане назад не е връщане назад, то е продължителен инцидент.

Ключови изводи

  • Промптовете са софтуерни артефакти, които изискват версиониране
  • Всяка версия е JSON или YAML файл с метаданни
  • Статусът (draft, active, deprecated) позволява постепенно разполагане
  • Съхранявайте промптовете в Git с тестове и дневник на промените
  • Връщането назад трябва да е мигновено в случай на регресия