Версиониране на промптове и управление на каталог
На тази страница
Урокът е актуализиран на 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 с тестове и дневник на промените
- Връщането назад трябва да е мигновено в случай на регресия