Zum Hauptinhalt springen
Ein Guardrail ist die Content-Policy-Ebene des OrcaRouter-Gateways. Sie verfassen eine benannte Policy in Ihrem Workspace, hängen sie an einen API-Key an, und jeder /v1/*-Aufruf, den dieser Key tätigt, wird geprüft — bevor das Modell den Prompt sieht und nachdem das Modell geantwortet hat — ohne Redeploy und ohne SDK-Änderung. Diese Seite ist der Hub für den Guardrails-Bereich: was ein Guardrail ist, die Regeltypen, die Stages und Actions und wie eine Policy an einen Key angehängt wird. Jede Verzweigung geht tiefer. Die vollständige Engine-Referenz finden Sie unter Guardrails.

​
1. Was KI-Guardrails am Gateway tun

Die meisten Teams greifen zu Guardrails, um sensible Daten aus Prompts herauszuhalten (PII, Secrets), um unsichere Inhalte zu gaten (Jailbreaks, Prompt-Injection-Absicht) oder um eine Compliance-Kontrolle zu erfüllen. Ein Guardrail ist die Antwort des Gateways: eine workspace-bezogene, benannte Policy — eine geordnete Liste von Regeln, die das Gateway gegen den Request-Input und den Modell-Output ausführt. Weil die Bindung am API-Key im Gateway lebt — nicht in Ihrer Anwendung — verschiebt das Bearbeiten eines Guardrails jeden angehängten Key beim nächsten Aufruf. Ihr Code ruft /v1/chat/completions weiterhin genau wie zuvor auf.
Guardrails sind Content-Policy (Text rein, Text raus). Die ergänzende Agent-Firewall ist Tool-Policy — sie steuert, welche Tool-Calls ein Agent tätigen darf. Beide komponieren; siehe Guardrails vs. Firewall.

​
2. Ein konkretes Beispiel

Erstellen Sie in der Konsole (/console/guardrails) ein Guardrail namens pii-shield, fügen Sie eine einzelne PII-Regel hinzu — Stage input, Action mask, Entities email, ssn — und hängen Sie es an einen Key an. Von da an: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'
Das Gateway schreibt den Prompt vor dem Weiterleiten zu Reply to [EMAIL] please um — das Upstream-Modell sieht die Adresse nie. Stellen Sie diese ssn-Entity auf block, und der nächste Request, der eine SSN trägt, wird mit HTTP 400 abgelehnt. Keine Änderung in der Anwendung.
Das Verfassen ist eine Konsolen-/Management-API-Aktion auf Ihrer Session — der sk-orca-...-Relay-Key ist nur für /v1/*-Traffic, nie zum Bearbeiten von Policy. Das Erstellen oder Bearbeiten eines Guardrails erfordert die Rolle Developer+.

​
3. Regeln: Type, Stage, Action

Jede Regel beantwortet drei Fragen. Die Engine führt alle zutreffenden Regeln aus und fasst sie zu einer Entscheidung zusammen.
Sieben Regeltypen. Die eingebauten sind deterministisch (reines String-/Regex-Matching, kein Netzwerk); die erweiterten rufen ein Modell oder einen Anbieter auf und laufen nebenläufig.
  • keyword — literale Denylist, Teilstring-Match ohne Beachtung der Groß-/Kleinschreibung.
  • regex — ein RE2-Muster (lineare Zeit, keine Backreferences).
  • pii — eingebaute Entity-Detektoren plus Ihre eigenen. Siehe §5.
  • max_chars — begrenzt die Zeichenzahl an einer Stage.
  • external — delegiert an einen verbundenen Anbieter (Aporia, Averta oder Ihren eigenen Webhook).
  • llm_judge — eine semantische Prüfung gegen ein Modell in Ihrem Workspace.
  • grounding — bewertet die Treue der Antwort gegenüber den auf der Anfrage abgerufenen Quellen (RAG).
input (die Anfrage), output (die Antwort des Modells) oder both. Input-Regeln laufen vor dem Upstream-Call; Output-Regeln laufen, nachdem das Modell geantwortet hat. Siehe Input-Stage und Output-Stage.
Fünf Actions tauchen im Rule-Builder auf:
  • block — den Aufruf mit HTTP 400 ablehnen.
  • mask — den Treffer redigieren und den bereinigten Text durchlassen.
  • flag — nichts am Traffic ändern; nur den Match aufzeichnen.
  • annotate — den Text unangetastet lassen, aber eine Sicherheitsnotiz nach Upstream injizieren (z. B. ein CVE-Advisory, bevor das Modell antwortet).
  • spotlight — den gematchten nicht vertrauenswürdigen Text in Delimiter einfassen und dem Modell sagen, ihn als Daten zu behandeln, nicht als Anweisungen.
Siehe Actions. Verwenden Sie flag, um eine Regel auf Live-Traffic zu messen, bevor Sie sie durchsetzen.

​
4. Wie ein Guardrail angehängt und aufgelöst wird

Ein Guardrail bindet sich via guardrail_id an einen Key, oder ein Workspace kann ein Guardrail als seinen Default markieren. Für jede Anfrage löst das Gateway in dieser Reihenfolge auf:
  1. Explizite Bindung — wenn die guardrail_id des Keys auf ein Guardrail zeigt, das existiert und aktiviert ist, gilt dieses. Eine explizite Bindung fällt nie zurück: das Deaktivieren ist der Aus-Schalter.
  2. Workspace-Default — wenn der Key keine Bindung hat, gilt das aktivierte Default-Guardrail.
  3. Keines von beiden — keine Durchsetzung; die Anfrage ist byte-identisch zu einem Workspace, der das Feature nie aktiviert hat.
Dies unterscheidet sich von der Firewall. Eine deaktivierte angehängte Firewall-Policy fällt auf den Workspace-Default zurück; ein deaktiviertes angehängtes Guardrail geht auf keines. Der Aus-Schalter ist bei Guardrails wörtlich gemeint.
Walkthroughs: Ihr erstes Guardrail erstellen, an einen Key anhängen, einen Account-Default setzen.

​
5. PII-Detektoren

Eine pii-Regel liefert einen geschlossenen Satz eingebauter Detektoren mit: email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address — plus die regionalen jp_mynumber, kr_rrn und cn_resident_id. Bei einer mask-Action wird jeder Treffer zu einem typisierten Tag — aus einer E-Mail wird [EMAIL], aus einer SSN wird [SSN]. Sie können bis zu 25 benutzerdefinierte Entities pro Regel schichten (eine Regex mit optionaler Luhn-Prüfsumme) und in einer Regel verschiedene Entities via Pro-Entity-Overrides an verschiedene Actions routen.
Der schlüsselfertige Ausgangspunkt ist das PII Shield-Preset — eine einzelne pii-Regel, mask, Stage both. Input-Stage-Masking schreibt die Anfrage vor dem Modell um (streamend oder nicht); Output-Masking schreibt die Antwort nur bei nicht-streamenden Responses um — In-Stream-Output- Rewriting ist auf der Roadmap. Siehe PII Shield, benutzerdefinierte Entities und Masking-Formate.

​
6. Der Preset-Picker

New guardrail öffnet in ein Template. Presets werden serverseitig verfasst, sodass die Konsole, die Sandbox und diese Doku dasselbe Verhalten beschreiben. Der Picker gruppiert sie in Kategorien:
KategorieBeispiel-PresetsVerzweigung
pii / secretsPII Shield, Secret-Credential-BlockerSecrets blockieren
safetyPrompt-Injection, Jailbreak, SelbstverletzungPrompt-Injection
complianceGDPR, PCI, HIPAA, Compliance-LoggerCompliance-Logger
brand / costProfanität, Erwähnungen von Wettbewerbern, GrößenlimitsBrand Safety · Cost
agentURL- / Shell-Tool- / SQL-in-Output-FilterAgentisch
code_securitySecret-File-Blocks, Copyleft-Lizenz-ReviewCode-Sicherheit
Ein Preset ist ein Keim, keine Sperre — wenden Sie es an und bearbeiten Sie dann frei. Weitere Ausgangspunkte leben unter Templates.

​
7. Wenn ein Guardrail blockiert

Ein blockierter Request gibt HTTP 400 mit dem Fehlercode guardrail_blocked und einer Nachricht zurück, die das Guardrail und die ausgelöste Regel benennt.
  • Kein Kontingent wird berechnet. Ein Block der Input-Stage feuert vor der Messung; ein Block der Output-Stage erstattet das vorab verbrauchte Kontingent zurück.
  • Die Anfrage wird als skip-retry markiert — das erneute Ausführen desselben Prompts würde einfach wieder blockieren, sodass das Gateway keinen Retry an einen anderen Channel verschwendet.
Beim Streaming wird block best-effort durchgesetzt — ein Scanner puffert einen kleinen Lookahead und kappt den Stream, wenn eine Regel feuert, sodass bereits geflushte Bytes nicht zurückgezogen werden können. Mask auf dem Output gilt nur für nicht-streamende Responses — bei einer streamenden Response berechnet das Gateway die Maske, leitet aber den redigierten Text nicht weiter; In-Stream-Output-Rewriting ist auf der Roadmap. (Input-Stage-Masking ist beim Streaming und nicht-streamend gleichermaßen live.) Siehe den guardrail_blocked-Fehler und Streaming-Abdeckung.

​
8. Nachdem es live ist

Matches-Feed

Jede Regel, die feuert, zeichnet Type, Action, Stage und Detail auf. Gruppieren, filtern, exportieren und in einen einzelnen Match eintauchen.

Logging & Datenschutz

Der gematchte Teilstring wird nur aufgezeichnet, wenn Log raw content an ist — standardmäßig aus, die datenschutzfreundliche Haltung.

Versionierung

Jede Änderung schreibt eine Historie-Zeile. Diffen Sie beliebige zwei Versionen und reverten Sie als neue Version — die Historie wird nie mutiert.

Testing & Eval

Ein Sandbox-Tab Test evaluiert die aktuelle Policy ohne Upstream-Aufruf, und ein Eval-Harness bewertet sie gegen mitgelieferte oder benutzerdefinierte Korpora.
Ein Fehlalarm ist ein Tuning-Signal, kein Grund, die Regel zu deaktivieren. Markieren Sie ihn im Matches-Feed und verengen Sie das Muster — siehe Fehlalarme tunen.

​
9. Wohin als Nächstes

Guardrails — jedes Feld, jede Route, die LLM-Judge- und Grounding-Regeln und externe Anbieter im Detail.