Guardrails: Walidacja danych wejściowych i wyjściowych
Na tej stronie
Czym jest guardrail?
Guardrail to warstwa walidacji umiejscowiona między użytkownikiem a modelem (dla danych wejściowych) lub między modelem a użytkownikiem (dla danych wyjściowych). Różnica względem moderacji omawianej w poprzednim rozdziale jest wyraźna i musisz ją utrzymać: moderacja odpowiada na pytanie „Czy ta treść jest obraźliwa?“ – jest to pytanie uniwersalne, którego odpowiedź nie zależy od Twojej działalności. Guardraile odpowiadają na pytania, które tylko Ty możesz sformułować: Czy wiadomość mieści się w oczekiwanym zakresie? Czy odpowiedź zawiera informacje zabronione? Czy żądana akcja jest autoryzowana dla tej roli? Asystent bankowy i asystent księgarni korzystają z tej samej moderacji, ale nie mają żadnych wspólnych guardraili.
Do 2026 roku guardraile stały się standardowym elementem architektur agentów AI, niezbędnym zawsze, gdy model ma dostęp do narzędzi lub danych wrażliwych.
Architektura potokowa
Wybór strukturalny polega na traktowaniu każdego guardraila jako niezależnego obiektu o pojedynczej odpowiedzialności, a następnie łączeniu ich w wybraną sekwencję. Korzyść ujawnia się podczas konserwacji: dodanie reguły biznesowej nie wymaga zmian w istniejącym kodzie, a regułę, która generuje zbyt wiele fałszywych alarmów, można usunąć jedną linią kodu.
Do werdyktów „zezwól“ i „zablokuj“ dołącza trzeci: „modyfikuj“. Zmienia to naturę zadania. Wiele sytuacji rzeczywistych nie uzasadnia odmowy – odpowiedź zawierająca wewnętrzną ścieżkę serwera pozostaje użyteczna, gdy tylko ta ścieżka zostanie zamaskowana. Zablokowanie spowodowałoby utratę informacji; modyfikacja ją zachowuje, usuwając to, co stanowi problem.
from dataclasses import dataclass
from enum import Enum
class Decision(Enum):
ALLOW = "allow"
BLOCK = "block"
MODIFY = "modify"
@dataclass
class ValidationResult:
decision: Decision
reason: str
modified_content: str | None = None
class Guardrail:
"""Klasa bazowa dla guardraila."""
def validate(self, content: str, context: dict) -> ValidationResult:
raise NotImplementedError
class GuardrailPipeline:
"""Łączy wiele guardraili w sekwencję."""
def __init__(self):
self.input_guardrails: list[Guardrail] = []
self.output_guardrails: list[Guardrail] = []
def add_input(self, guardrail: Guardrail):
self.input_guardrails.append(guardrail)
def add_output(self, guardrail: Guardrail):
self.output_guardrails.append(guardrail)
def validate_input(self, message: str, context: dict) -> ValidationResult:
for g in self.input_guardrails:
result = g.validate(message, context)
if result.decision == Decision.BLOCK:
return result
if result.decision == Decision.MODIFY:
message = result.modified_content
return ValidationResult(Decision.ALLOW, "Wszystkie walidacje zakończone pomyślnie")
def validate_output(self, response: str, context: dict) -> ValidationResult:
for g in self.output_guardrails:
result = g.validate(response, context)
if result.decision == Decision.BLOCK:
return result
if result.decision == Decision.MODIFY:
response = result.modified_content
return ValidationResult(Decision.ALLOW, "OK", response)
Trzy typowe guardraile
Guardrail zakresu utrzymuje rozmowę w jej domenie. Służy zarówno bezpieczeństwu, jak i reputacji: asystent obsługi klienta przeszkolony do odpowiadania na pytania dotyczące dostaw nie ma nic do zyskania, komentując wiadomości polityczne, a zrzut ekranu takiej odpowiedzi szybko się rozprzestrzenia. Listę tematów zabronionych należy omówić z działem biznesowym, nigdy nie powinna być opracowywana wyłącznie przez zespół techniczny.
class ScopeGuardrail(Guardrail):
"""Sprawdza, czy wiadomość pozostaje w dozwolonym zakresie."""
def __init__(self, allowed_topics: list[str], forbidden_topics: list[str]):
self.allowed_topics = allowed_topics
self.forbidden_topics = forbidden_topics
def validate(self, content: str, context: dict) -> ValidationResult:
content_lower = content.lower()
# Sprawdź tematy zabronione
for topic in self.forbidden_topics:
if topic.lower() in content_lower:
return ValidationResult(
Decision.BLOCK,
f"Wykryto temat spoza zakresu: {topic}"
)
return ValidationResult(Decision.ALLOW, "W zakresie")
Guardrail formatu wydaje się trywialny, a jednak przynosi największą codzienną wartość. Kosztuje kilka mikrosekund, nie zależy od wywołań sieciowych i ucina nadmiernie duże wiadomości używane do ataków wolumetrycznych i prób wyczerpania budżetu. Umieść go na początku łańcucha: nie ma sensu płacić za moderację API dla wiadomości liczącej 200 000 znaków, którą i tak odrzucisz.
class FormatGuardrail(Guardrail):
"""Waliduje format i długość wiadomości."""
def __init__(self, max_tokens: int = 4000, max_lines: int = 100):
self.max_tokens = max_tokens
self.max_lines = max_lines
def validate(self, content: str, context: dict) -> ValidationResult:
# Szacunkowe obliczenie tokenów (1 token ~ 4 znaki w języku angielskim)
estimated_tokens = len(content) // 4
if estimated_tokens > self.max_tokens:
return ValidationResult(
Decision.BLOCK,
f"Wiadomość zbyt długa: ~{estimated_tokens} tokenów (maks. {self.max_tokens})"
)
line_count = content.count("\n") + 1
if line_count > self.max_lines:
return ValidationResult(
Decision.BLOCK,
f"Zbyt wiele linii: {line_count} (maks. {self.max_lines})"
)
return ValidationResult(Decision.ALLOW, "Poprawny format")
Trzeci monitoruje dane wyjściowe i ilustruje użycie werdyktu „modyfikuj“. Cztery rodziny, których szuka, mają wspólną, wygodną cechę: posiadają rozpoznawalną formę niezależną od znaczenia. Klucz API, wewnętrzny adres, prywatne IP lub ścieżka serwera są identyfikowane na podstawie swojej struktury, bez konieczności rozumienia zdania, w którym się znajdują.
import re
class AntiExfiltrationGuardrail(Guardrail):
"""Zapobiega wyciekom wrażliwych danych w danych wyjściowych."""
def __init__(self):
self.sensitive_patterns = {
"api_key": r"(sk|pk|api[_-]?key)[_-][a-zA-Z0-9]{16,}",
"internal_email": r"[a-zA-Z0-9.]+@(company|internal|corp)\.\w+",
"private_ip": r"\b(10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b",
"server_path": r"(/data/|/etc/|/home/|C:\\Users\\)",
}
def validate(self, content: str, context: dict) -> ValidationResult:
for data_type, pattern in self.sensitive_patterns.items():
if re.search(pattern, content):
# Maskuj zamiast blokować
cleaned_content = re.sub(pattern, "[REDACTED]", content)
return ValidationResult(
Decision.MODIFY,
f"Usunięto dane wrażliwe: {data_type}",
cleaned_content,
)
return ValidationResult(Decision.ALLOW, "Nie wykryto wycieku")
Łączenie wszystkiego w całość
Kompletny montaż pokazuje, gdzie pasują poszczególne elementy. Asymetria rzuca się w oczy: dwa guardraile na wejściu, tylko jeden na wyjściu. Jest to częste i zdrowe – filtrujesz intensywnie przed wywołaniem modelu, ponieważ tam koszty można uniknąć, a na wyjściu utrzymujesz absolutne minimum, aby nie uszkodzić poprawnych odpowiedzi. Wiadomość zwracana podczas blokowania na wyjściu podlega tej samej ostrożności: jest celowo niejednoznaczna i nie mówi, co wykryto, gdyż informacja ta służyłaby przede wszystkim osobie próbującej mapować Twoje zabezpieczenia.
from openai import OpenAI
def create_secure_assistant():
"""Tworzy asystenta z kompletnym potokiem guardraili."""
client = OpenAI()
pipeline = GuardrailPipeline()
# Guardraile wejściowe
pipeline.add_input(FormatGuardrail(max_tokens=2000))
pipeline.add_input(ScopeGuardrail(
allowed_topics=["products", "orders", "delivery", "returns"],
forbidden_topics=["politics", "religion", "competitors"],
))
# Guardraile wyjściowe
pipeline.add_output(AntiExfiltrationGuardrail())
def process(message: str) -> str:
context = {"user_role": "customer"}
# Walidacja wejścia
input_check = pipeline.validate_input(message, context)
if input_check.decision == Decision.BLOCK:
return f"Nie mogę przetworzyć tego żądania: {input_check.reason}"
valid_message = input_check.modified_content or message
# Wywołanie modelu
response = client.chat.completions.create(
model="gpt-5.6-sol",
messages=[
{"role": "system", "content": "Asystent obsługi klienta Acme Corp."},
{"role": "user", "content": valid_message},
],
)
reply = response.choices[0].message.content
# Walidacja wyjścia
output_check = pipeline.validate_output(reply, context)
if output_check.decision == Decision.BLOCK:
return "Nie mogę odpowiedzieć na to pytanie."
return output_check.modified_content or reply
return process
Gdy reguły nie da się zapisać jako wyrażenie regularne
Niektóre reguły biznesowe opierają się jakiejkolwiek formalizacji za pomocą wzorców. „Odpowiedź nie może stanowić porady inwestycyjnej“, „wiadomość nie może zawierać danych zdrowotnych“: żadne wyrażenie regularne tego nie uchwyci. Wtedy drugi model, szybki i tani, może działać jako sędzia, z odpowiedzią ograniczoną do formatu JSON, aby pozostać użytecznym dla kodu wywołującego. Kompromis jest oczywisty – zyskujesz precyzję kosztem opóźnienia i determinizmu, co rezerwuje to podejście dla reguł, które naprawdę na to zasługują.
def llm_guardrail(message: str, rule: str) -> ValidationResult:
"""Używa szybkiego modelu do walidacji zgodności."""
client = OpenAI()
response = client.chat.completions.create(
model="gpt-5.6-terra",
messages=[
{"role": "system", "content": f"""Jesteś walidatorem zgodności.
Zasada do sprawdzenia: {rule}
Odpowiedz TYLKO w formacie JSON: {{"compliant": true/false, "reason": "..."}}"""},
{"role": "user", "content": f"Wiadomość do walidacji:\n{message}"},
],
)
import json
result = json.loads(response.choices[0].message.content)
if result["compliant"]:
return ValidationResult(Decision.ALLOW, result["reason"])
return ValidationResult(Decision.BLOCK, result["reason"])
Kluczowe wnioski
- Guardraile walidują zgodność biznesową, a nie tylko obraźliwą treść
- Architektura potokowa pozwala łączyć wiele warstw walidacji
- Każdy guardrail ma pojedynczą odpowiedzialność: zakres, format, eksfiltracja itp.
- Guardraile wyjściowe są tak samo ważne jak wejściowe
- W złożonych przypadkach szybki LLM może pełnić rolę walidatora