Usklađenost i revizijski trag
Na ovoj stranici
Usklađenost i revizijski trag
Za AI aplikacije u proizvodnji, mogućnost praćenja je ključna. Potpun revizijski trag štiti te tijekom inspekcije, spora ili incidenta. Ova lekcija pokazuje ti kako implementirati robustan sustav revizije, zaokružujući tečaj spajanjem svega što si do sada izgradio—bilježenja, moderacije i zaštite podataka—u jedinstven, obranjiv okvir.
Zašto revizijski trag?
Četiri različite potrebe konvergiraju na istu infrastrukturu. Prvo, regulatorna usklađenost: GDPR, Europski zakon o umjetnoj inteligenciji i industrijski standardi zahtijevaju da dokažeš što tvoj sustav radi, a demonstracija bez zapisa je bezvrijedna. Drugo, mogućnost praćenja u strogom smislu—znati tko je što učinio, kada, s kojim rezultatom, čak i šest mjeseci kasnije. Otklanjanje grešaka svakodnevno ima koristi od ovoga, jer razumijevanje neočekivanog ponašanja modela zahtijeva oporavak točnih uvjeta poziva. Konačno, odgovornost: dokumentiranje odluka koje donosi AI ono je što će ti omogućiti da, kada dođe vrijeme, pokažeš da je osporena preporuka počivala na kontroliranom procesu.
Struktura revizijskog zapisa
dataclass u nastavku je jednako ugovor koliko i struktura podataka. Grupira identifikatore, kontekst aplikacije, zahtjev, odgovor, presudu moderacije i tehničke metapodatke. Dva izbora zaslužuju tvoju pozornost. Identifikator korisnika pojavljuje se samo u hashiranom obliku, nikada u čistom tekstu. I upit (prompt) se ne pohranjuje: samo njegov hash i duljina. To čuva tvoju sposobnost da dokažeš da su dva poziva odnosila na isti sadržaj, a da pritom nikada ne stvoriš arhivu onoga što su tvoji korisnici napisali.
from dataclasses import dataclass, field, asdict
from datetime import datetime
from typing import Optional
import json
import uuid
import hashlib
@dataclass
class AuditRecord:
"""Audit record for an API call."""
# Identifiers
audit_id: str = field(default_factory=lambda: str(uuid.uuid4()))
timestamp: str = field(
default_factory=lambda: datetime.now().isoformat()
)
# Context
user_id_hash: str = "" # Never the plain ID
session_id: str = ""
application: str = ""
# Request (no sensitive data)
model: str = ""
prompt_hash: str = "" # Hash of the prompt, not the prompt itself
prompt_length: int = 0
# Response
response_id: str = ""
output_length: int = 0
input_tokens: int = 0
output_tokens: int = 0
# Moderation
input_flagged: bool = False
output_flagged: bool = False
# Metadata
duration_ms: int = 0
status: str = "success"
error: Optional[str] = None
def to_json(self) -> str:
return json.dumps(asdict(self), ensure_ascii=False)
Potpun sustav revizije
Klijent koji koristi ovu strukturu lančano povezuje moderaciju ulaza, API poziv, moderaciju izlaza i zapisuje u svakom slučaju. Važna riječ je samo dodavanje (append-only): JSONL datoteka se otvara u načinu dodavanja, nikada se ne prepisuje, što je uvjet da zapis ima dokaznu vrijednost. Obrati pozornost na putanju označenog unosa—zapis se sprema prije nego što se podigne iznimka, sa statusom blocked_input. Blokada stoga ostavlja trag baš kao i uspjeh, a konačni blok except jamči da nijedna greška, bez obzira na podrijetlo, ne promakne pažnji.
import time
from openai import OpenAI
class AuditedClient:
"""OpenAI client with integrated audit trail."""
def __init__(self, application: str, audit_store: str = "audit.jsonl"):
self.client = OpenAI()
self.application = application
self.audit_store = audit_store
def _hash(self, text: str) -> str:
"""Truncated SHA-256 hash for auditing."""
return hashlib.sha256(text.encode()).hexdigest()[:16]
def _save_audit(self, record: AuditRecord):
"""Saves an audit record (append-only)."""
with open(self.audit_store, "a", encoding="utf-8") as f:
f.write(record.to_json() + "\n")
def create(self, user_id: str, session_id: str,
model: str, input: str, **kwargs) -> object:
"""API call with automatic auditing."""
record = AuditRecord(
user_id_hash=self._hash(user_id),
session_id=session_id,
application=self.application,
model=model,
prompt_hash=self._hash(input),
prompt_length=len(input),
)
start = time.monotonic()
try:
# Input moderation
mod = self.client.moderations.create(
model="omni-moderation-latest",
input=input
)
record.input_flagged = mod.results[0].flagged
if record.input_flagged:
record.status = "blocked_input"
self._save_audit(record)
raise ValueError("Inappropriate input content")
# API call
response = self.client.responses.create(
model=model,
input=input,
**kwargs
)
# Output moderation
mod_out = self.client.moderations.create(
model="omni-moderation-latest",
input=response.output_text
)
record.output_flagged = mod_out.results[0].flagged
# Fill metrics
record.response_id = response.id
record.output_length = len(response.output_text)
record.input_tokens = response.usage.input_tokens
record.output_tokens = response.usage.output_tokens
record.duration_ms = round((time.monotonic() - start) * 1000)
record.status = "success"
self._save_audit(record)
return response
except Exception as e:
record.duration_ms = round((time.monotonic() - start) * 1000)
record.status = "error"
record.error = type(e).__name__
self._save_audit(record)
raise
# Usage
audited = AuditedClient(application="support-chatbot")
response = audited.create(
user_id="[email protected]",
session_id="sess-abc123",
model="gpt-5.6-terra",
input="How do I return a product?"
)
print(response.output_text)
U ovom primjeru, adresa e-pošte proslijeđena kao user_id nikada ne dospijeva u datoteku: hashira se čim se zapis konstruira. JSONL datoteka dobro funkcionira za početak i za jednu instancu; čim više procesa piše paralelno, usmjeri ovaj tok u bazu podataka ili skupljač zapisa (log collector).
Upiti za reviziju
Zapis koji ne možeš upitati služi samo za zauzimanje prostora na disku. Čitanje JSONL formata redak po redak čini iskorištavanje trivijalnim, a izvještaj u nastavku sažima pokriveno razdoblje, raspodjelu između uspjeha, grešaka i blokada, potrošnju tokena i prosječnu latenciju. Broj jedinstvenih korisnika oslanja se na hasheve, što usputno dokazuje da pseudonimizirani zapis ostaje savršeno analizabilan.
import json
def read_audit(file: str = "audit.jsonl") -> list[dict]:
"""Reads all audit records."""
records = []
try:
with open(file, "r", encoding="utf-8") as f:
for line in f:
if line.strip():
records.append(json.loads(line))
except FileNotFoundError:
pass
return records
def audit_report(file: str = "audit.jsonl") -> dict:
"""Generates an audit report."""
records = read_audit(file)
if not records:
return {"message": "No records"}
total = len(records)
errors = sum(1 for r in records if r["status"] == "error")
blocked = sum(1 for r in records if r["status"] == "blocked_input")
tokens_total = sum(
r.get("input_tokens", 0) + r.get("output_tokens", 0)
for r in records
)
durations = [r["duration_ms"] for r in records if r["duration_ms"] > 0]
return {
"period": {
"start": records[0]["timestamp"],
"end": records[-1]["timestamp"],
},
"total_calls": total,
"successes": total - errors - blocked,
"errors": errors,
"moderation_blocks": blocked,
"tokens_consumed": tokens_total,
"avg_latency_ms": round(sum(durations) / max(len(durations), 1)),
"unique_users": len(set(r["user_id_hash"] for r in records)),
}
print(json.dumps(audit_report(), indent=2, ensure_ascii=False))
Zadržavanje i arhiviranje
Beskonačno čuvanje podataka protivi se načelu ograničenja pohrane; prerano brisanje lišava te dokaza koji bi ti mogli zatrebati. Rotacija rješava ovu dilemu: nakon trajanja koje odrediš—ovdje devedeset dana—zapisi napuštaju aktivnu datoteku za datirani arhiv, dok se trenutni zapis prepisuje samo s nedavnima. Zakaži ovu funkciju kao periodični zadatak i uskladi retention_days s politikom koju je potvrdio tvoj pravni savjetnik, a ne s vrijednošću odabranom nasumično.
from datetime import datetime, timedelta
import shutil
import os
def archive_audit(file: str = "audit.jsonl",
retention_days: int = 90):
"""Archives and purges old records."""
records = read_audit(file)
limit = datetime.now() - timedelta(days=retention_days)
recent = []
archives = []
for record in records:
date_record = datetime.fromisoformat(record["timestamp"])
if date_record > limit:
recent.append(record)
else:
archives.append(record)
if archives:
# Archive old ones
archive_name = f"audit_archive_{datetime.now().strftime('%Y%m%d')}.jsonl"
with open(archive_name, "w", encoding="utf-8") as f:
for record in archives:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
# Rewrite main file with recent ones
with open(file, "w", encoding="utf-8") as f:
for record in recent:
f.write(json.dumps(record, ensure_ascii=False) + "\n")
print(f"Archived {len(archives)} records to {archive_name}")
print(f"Kept {len(recent)} recent records")
Europski zakon o umjetnoj inteligenciji: Što se mijenja
Europski zakon o umjetnoj inteligenciji (AI Act) nameće obveze temeljene na razini rizika tvoje aplikacije. Logika je stupnjevita: što tvoj sustav više utječe na živote ljudi, to su zahtjevi stroži. FAQ chatbot, sažetak ili prijevod spadaju pod minimalni rizik i zahtijevaju samo osnovnu transparentnost. Čim postoji razgovor ili analiza sentimenta, prelaziš na ograničeni rizik, s obvezom informiranja korisnika da komunicira s AI-jem. Skok je nagao za visoki rizik—bodovanje kreditne sposobnosti, zapošljavanje, medicinska dijagnoza—gdje se dodaju procjena sukladnosti, upravljanje rizicima, dokumentacija podataka za obuku, potpuna mogućnost praćenja, ljudski nadzor i dokazivanje točnosti. Određene uporabe, poput društvenog bodovanja ili subliminalne manipulacije, strogo su zabranjene.
# Assess the risk level of your application
RISK_LEVELS = {
"minimal": {
"examples": ["FAQ chatbot", "text summary", "translation"],
"obligations": ["Basic transparency"]
},
"limited": {
"examples": ["customer service chatbot", "sentiment analysis"],
"obligations": ["Inform the user they are interacting with an AI"]
},
"high": {
"examples": ["credit scoring", "recruitment", "medical diagnosis"],
"obligations": [
"Conformity assessment",
"Risk management system",
"Documented training data",
"Logging and complete traceability",
"Mandatory human supervision",
"Demonstrated accuracy and robustness"
]
},
"unacceptable": {
"examples": ["social scoring", "subliminal manipulation"],
"obligations": ["PROHIBITED"]
}
}
Iskreno smjesti svoj projekt u ovu mrežu prije nego napišeš prvi redak koda: aplikacija klasificirana kao visokorizična nameće arhitektonska ograničenja—iscrpno bilježenje, točka ljudske kontrole—koja se ne mogu naknadno dodati sustavu dizajniranom bez njih.
Kontrolni popis usklađenosti
- Revizijski trag samo za dodavanje s vremenskom oznakom
- Hashiranje osobnih podataka u zapisima (nikada u čistom tekstu)
- Sustavna moderacija ulaza i izlaza
- Ažurirani GDPR zapis o aktivnostima obrade
- Definirana politika zadržavanja i arhiviranja
- Provedena procjena razine rizika prema AI Aktu
- Informiranje korisnika da komuniciraju s AI-jem
- Ljudski nadzor za odluke s utjecajem
Ključne točke
- Revizijski trag je obavezan za regulatornu usklađenost
- Bilježi u načinu samo za dodavanje: nikada ne mijenjaj postojeće zapise
- Hashiraj sve osobne podatke u revizijskim zapisima
- Europski zakon o umjetnoj inteligenciji klasificira aplikacije prema razini rizika
- Implementiraj automatsku moderaciju I ljudski nadzor
- Definiraj politiku zadržavanja i redovito arhiviraj
Provjeri svoje znanje
Dvadeset i dvije lekcije o API-ju: validiraj mehanizme koji drže proizvodnju na okupu.
1. Zašto migrirati na Responses API umjesto ostati na Chat Completions?
Odgovor: To je moderni API OpenAI-ja: integrirano upravljanje stanjem razgovora, izvorni alati i evolucija usmjerena na njega—Chat Completions ostaje podržan, ali je zastario.
2. Kako odabrati između Sol, Terra i Luna na strani API-ja?
Odgovor: gpt-5.6-sol za zahtjevne zadatke, terra za balans cijene i kvalitete, luna za ekonomski obujam—a razina rezoniranja (none→max) se zatim prilagođava po zahtjevu.
3. Što Structured Output jamči?
Odgovor: Izlaz koji odgovara pruženoj JSON shemi—polja, tipovi, struktura—iskoristiv od strane programa bez obrambenog parsiranja ili popravaka.
4. Što učiniti pred greškom 429?
Odgovor: Poštuj ograničenja stope: ponovi pokušaj s eksponencijalnim kašnjenjem (i jitterom), ograniči pokušaje i planiraj prekidač kruga (circuit breaker)—nikada petlju trenutnog ponavljanja.
5. Navedi dvije neophodne zaštite na strani sigurnosti aplikacije.
Odgovor: Moderacija dolaznog/odlaznog sadržaja putem namjenskog API-ja i obrana od ubrizgavanja upita (prompt injection): izoliraj upute od podataka, validiraj izlaze, ograniči izložene mogućnosti.
Proizvodnja, sigurnost, usklađenost: posljednja tri bloka tečaja čine razliku između prototipa i usluge—zadrži ih kao kontrolni popis.