Заміна моделі, шаблону промпту, значення температури, опису інструмента або конфігурації пошуку може змінити поведінку системи навіть без змін у коді застосунку. Тому такі зміни слід перевіряти як реліз: порівнювати кандидата з відомою базовою версією на тому самому версіонованому наборі тестів і зберігати докази для кожного рішення.
У цій статті ми створимо невеликий незалежний від постачальника регресійний шлюз на Python. Він перевірятиме JSON і бізнес-правила, повторюватиме запуски для виявлення нестабільності, вимірюватиме затримку, порівнюватиме кандидата з базовою версією та повертатиме ненульовий код завершення, якщо бюджет регресії перевищено. Для цього не потрібні комерційний API або справжні облікові дані.
1. Визначте критерії рішення до написання засобу запуску
Спочатку зафіксуйте політику релізу. Для невеликого структурованого завдання вона може бути такою:
- кожна відповідь має бути валідним JSON і відповідати схемі тестового випадку;
- детерміновані бізнес-правила мають виконуватися під час кожного запуску;
- частка успішних перевірок кандидата не може бути нижчою, ніж у базової версії;
- затримка p95 не може перевищувати показник базової версії більш ніж на 20% і водночас має залишатися нижчою за абсолютну межу;
- помилки транспорту, тайм-аути й обмеження частоти запитів слід обліковувати окремо від помилок якості;
- фіксовану вибірку результатів має перевірити людина.
Автоматизований шлюз відповідає на запитання «чи порушили ми вимірювані вимоги?». Експертна перевірка відповідає на інше запитання: «чи залишається результат корисним, коректним і безпечним для користувача?». Для моделей ШІ потрібні обидва види контролю.
2. Версіонуйте тестові випадки та очікувану поведінку
Зберігайте тестові випадки в репозиторії поруч із засобом оцінювання. Формат JSON Lines (JSONL) зручний, оскільки кожен рядок є окремим випадком і легко переглядається у змінах.
{"case_id":"ticket-001","prompt":"Classify: Payment failed twice","schema":{"type":"object","required":["category","priority"],"properties":{"category":{"type":"string","enum":["billing","technical","other"]},"priority":{"type":"string","enum":["low","medium","high"]}},"additionalProperties":false},"contains":["billing"]}
{"case_id":"ticket-002","prompt":"Classify: How do I change my password?","schema":{"type":"object","required":["category","priority"],"properties":{"category":{"type":"string"},"priority":{"type":"string"}},"additionalProperties":false},"contains":["technical"]}Версіонуйте файл разом із кодом і зберігайте хеш кожного випадку в доказах виконання. Це дає змогу з’ясувати, чи змінився результат моделі, сам тест або обидва компоненти.
Документація Python застерігає, що недовірені JSON-дані можуть споживати значні ресурси процесора й пам’яті. Тому обмежуйте розмір файлу та окремого рядка до виклику json.loads.
import hashlib
import json
from pathlib import Path
from typing import Any
MAX_FILE_BYTES = 1_000_000
MAX_LINE_BYTES = 16_384
def load_cases(path: Path) -> list[dict[str, Any]]:
if path.stat().st_size > MAX_FILE_BYTES:
raise ValueError("case file is too large")
cases: list[dict[str, Any]] = []
with path.open(encoding="utf-8") as source:
for number, line in enumerate(source, start=1):
if not line.strip():
continue
if len(line.encode("utf-8")) > MAX_LINE_BYTES:
raise ValueError(f"line {number} is too large")
case = json.loads(line)
if not {"case_id", "prompt", "schema"} <= case.keys():
raise ValueError(f"line {number} misses required case fields")
cases.append(case)
return cases
def case_hash(case: dict[str, Any]) -> str:
canonical = json.dumps(case, sort_keys=True, separators=(",", ":"))
return hashlib.sha256(canonical.encode("utf-8")).hexdigest()3. Приховайте постачальника за адаптером
Засіб оцінювання має працювати з викликом, який не залежить від конкретного постачальника. Адаптер відповідає за автентифікацію, тайм-аут, розбір відповіді й параметри постачальника. Завдяки цьому логіка оцінювання не змінюється, коли ви порівнюєте іншу модель або кінцеву точку.
Не записуйте в журнали заголовки автентифікації або необроблені промпти з персональними даними. Зберігайте секрети в змінних середовища чи сховищі секретів CI та вилучайте чутливі дані з доказів.
Для вимірювання тривалості використовуйте time.perf_counter(): це монотонний високоточний лічильник, призначений для вимірювання коротких інтервалів.
import time
from collections.abc import Callable
ModelCall = Callable[[str], dict[str, Any]]
def timed_call(call: ModelCall, prompt: str) -> tuple[dict[str, Any], float]:
started = time.perf_counter()
result = call(prompt)
return result, time.perf_counter() - started4. Застосовуйте незалежні детерміновані оракули
Для структурованих результатів JSON Schema є сильним першим оракулом. Бібліотека jsonschema надає валідатори для різних чернеток специфікації; Draft202012Validator підтримує чернетку 2020-12, а iter_errors дає змогу зібрати всі помилки, а не лише першу. Спочатку перевіряйте саму схему, а потім — результат моделі.
import re
from jsonschema import Draft202012Validator
def deterministic_errors(output: dict[str, Any], case: dict[str, Any]) -> list[str]:
schema = case["schema"]
Draft202012Validator.check_schema(schema)
validator = Draft202012Validator(schema)
errors = [error.message for error in validator.iter_errors(output)]
rendered = json.dumps(output, ensure_ascii=False)
for fragment in case.get("contains", []):
if fragment.casefold() not in rendered.casefold():
errors.append(f"missing required fragment: {fragment}")
pattern = case.get("regex")
if pattern and re.search(pattern, rendered) is None:
errors.append("response does not match the required regex")
return errorsОракули мають бути незалежними від системи, яку вони оцінюють. Якщо та сама модель генерує відповідь і безконтрольно оцінює її, спільні упередження можуть приховати дефект. Якщо ви додаєте оцінювання іншою моделлю, використовуйте його як окремий калібрований сигнал і регулярно звіряйте з рішеннями людей.
5. Повторюйте тестові випадки й обчислюйте зіставні метрики
Запускайте кожен тестовий випадок кілька разів з однаковою конфігурацією для базової версії та кандидата. Записуйте категорії помилок окремо. Обмежені повторні спроби можуть бути доречними для відповідей 429 або 5xx, але зберігайте початкову помилку та кількість спроб: повторні спроби не повинні приховувати проблеми з доступністю.
Для невеликої спостережуваної вибірки нижче використано інклюзивний метод обчислення процентилів.
from statistics import quantiles
def evaluate(call: ModelCall, cases: list[dict[str, Any]], repeats: int = 5) -> dict:
latencies: list[float] = []
passed = 0
total = 0
evidence: list[dict[str, Any]] = []
for case in cases:
for run_number in range(1, repeats + 1):
total += 1
try:
output, elapsed = timed_call(call, case["prompt"])
problems = deterministic_errors(output, case)
latencies.append(elapsed)
passed += int(not problems)
evidence.append({
"case_id": case["case_id"],
"case_hash": case_hash(case),
"run": run_number,
"elapsed_s": round(elapsed, 4),
"problems": problems,
})
except Exception as exc:
evidence.append({
"case_id": case["case_id"],
"case_hash": case_hash(case),
"run": run_number,
"error_type": type(exc).__name__,
})
p95 = quantiles(latencies, n=100, method="inclusive")[94] if len(latencies) >= 2 else (latencies[0] if latencies else float("inf"))
return {"pass_rate": passed / total, "p95_s": p95, "evidence": evidence}Хеші точних результатів вимірюють однаковість, а не коректність. Надавайте перевагу повторним перевіркам оракулами, каліброваним семантичним оцінкам і експертному перегляду. Записуйте значення seed, якщо постачальник його приймає, але не обіцяйте відтворюваність, якщо постачальник її не гарантує.
6. Порівнюйте базову версію та кандидата за явними бюджетами
Запускайте базову версію та кандидата на тому самому корпусі даних через той самий адаптер, з однаковою кількістю повторів, тайм-аутом і середовищем. Тоді застосовуйте явні правила.
def release_allowed(baseline: dict, candidate: dict) -> tuple[bool, list[str]]:
reasons: list[str] = []
if candidate["pass_rate"] < baseline["pass_rate"]:
reasons.append("candidate pass rate is below baseline")
absolute_limit_s = 2.0
relative_limit_s = baseline["p95_s"] * 1.20
if candidate["p95_s"] > min(absolute_limit_s, relative_limit_s):
reasons.append("candidate p95 latency exceeds the regression budget")
return not reasons, reasonsПорогові значення мають відповідати ризикам продукту та історичним показникам. Класифікатор платіжних звернень потребує суворішої політики, ніж помічник для пошуку творчих ідей.
Зберігайте очищений звіт JSON з ідентифікаторами моделі й конфігурації, комітом набору тестів, хешами тестових випадків, кількістю повторів, описом середовища, метриками, помилками та остаточним рішенням. Не включайте секрети або клієнтський вміст.
7. Повторно використовуйте тестові випадки в pytest
Ті самі випадки можна параметризувати в pytest. Ідентифікатори тестів мають походити зі стабільного case_id. Не змінюйте об’єкти тестових випадків усередині тесту, оскільки pytest передає значення параметрів без копіювання.
import os
import pytest
CASES = load_cases(Path("tests/cases.jsonl"))
@pytest.fixture
def candidate_model():
return build_model_adapter(
endpoint=os.environ["CANDIDATE_ENDPOINT"],
token=os.environ["CANDIDATE_TOKEN"],
)
@pytest.mark.parametrize("case", CASES, ids=lambda case: case["case_id"])
def test_candidate_contract(case, candidate_model):
output, _ = timed_call(candidate_model, case["prompt"])
assert deterministic_errors(output, case) == []Порівняння з базовою версією краще залишити в окремому засобі запуску для CI. Якщо release_allowed повертає False, виведіть стислий перелік причин і завершіть процес із кодом 1. Такий машинозчитуваний шлюз можна однаково використовувати в GitHub Actions, Jenkins, Azure DevOps або n8n.
8. Обробка помилок і докази
Розділяйте результати за категоріями:
- помилка валідації означає, що результат порушив відомий контракт;
- помилка транспорту означає, що виклик не завершився;
- тайм-аут або обмеження частоти запитів вказує на проблему доступності чи пропускної здатності;
- помилка інфраструктури означає, що оцінювання не заслуговує на довіру;
- помилка семантичної перевірки означає, що структура пройшла перевірку, але зміст — ні.
Для високоризикових змін блокуйте реліз, якщо докази неповні. Для низькоризикових змін можна дозволити попередження, але це рішення має бути явним у політиці, а не прихованим у коді повторних спроб.
9. Контрольний список релізу
- Переконайтеся, що корпус тестів, схеми, промпти й порогові значення перевірено та версіоновано.
- Запустіть базову версію та кандидата з однаковою конфігурацією й у зіставному середовищі.
- Переконайтеся, що секрети зберігаються безпечно, а журнали не містять чутливих даних.
- Перегляньте детерміновані помилки, транспортні помилки, повторні спроби, різницю в частці успішних перевірок і затримку p95.
- Проведіть експертну перевірку фіксованої вибірки щодо фактичної коректності, безпеки та впливу на користувача.
- Збережіть очищений звіт із комітом і ідентифікаторами конфігурації.
- Просувайте кандидата лише після успішного проходження всіх обов’язкових шлюзів.
10. Усунення несправностей
Якщо всі перевірки схеми завершуються невдало, перевірте, чи схема відповідає фактичному формату відповіді та чи адаптер повертає вже розібраний об’єкт JSON. Якщо зростає лише затримка p95, порівняйте середовище, тайм-аут і кількість повторних спроб, перш ніж звинувачувати модель. Якщо результати відрізняються навіть за нульової температури, перевірте документацію постачальника щодо детермінізму та значення seed. Якщо CI не знаходить секрет, перевірте його назву й область дії, але не виводьте значення в журнал. Якщо розбір JSONL зупиняється на одному рядку, повідомте номер рядка та відхиліть файл замість пропуску пошкодженого тестового випадку.
Висновок
Надійний регресійний шлюз для моделей ШІ не намагається звести якість до одного показника. Він поєднує версіоновані тестові випадки, незалежні детерміновані оракули, повторні запуски, зіставні метрики, явні бюджети регресії, безпечні докази та експертний перегляд. Невеликий засіб запуску на Python уже може зробити зміни моделі контрольованими, відтворюваними настільки, наскільки це дозволяє постачальник, і придатними для автоматизованого рішення в CI.
Залишити коментар
Поділіться думкою про статтю. Реєстрація не потрібна.
Коментарі
Завантаження коментарів…