Passer au contenu principal
Un guardrail est la couche de politique de contenu de la passerelle OrcaRouter. Vous rédigez une politique nommée dans votre espace de travail, l’attachez à une clé API, et chaque appel /v1/* que cette clé effectue est filtré — avant que le modèle ne voie le prompt et après que le modèle a répondu — sans redéploiement et sans changement de SDK. Cette page est le hub de la section Guardrails : ce qu’est un guardrail, les types de règles, les étapes et les actions, et comment une politique s’attache à une clé. Chaque branche va plus en profondeur. Pour la référence complète du moteur, voir Guardrails.

​
1. Ce que font les guardrails IA sur la passerelle

La plupart des équipes recourent aux guardrails pour garder les données sensibles hors des prompts (PII, secrets), pour contrôler le contenu non sûr (jailbreaks, intention d’injection de prompt), ou pour satisfaire un contrôle de conformité. Un guardrail est la réponse de la passerelle : une politique nommée, à portée d’espace de travail — une liste ordonnée de règles que la passerelle exécute contre l’entrée de la requête et la sortie du modèle. Parce que la liaison vit sur la clé API dans la passerelle — pas dans votre application — modifier un guardrail déplace chaque clé attachée dès le prochain appel. Votre code continue d’appeler /v1/chat/completions exactement comme avant.
Les guardrails sont une politique de contenu (texte en entrée, texte en sortie). Le compagnon Agent Firewall est une politique d’outils — il gouverne quels appels d’outils un agent peut faire. Les deux se composent ; voir Guardrails vs. firewall.

​
2. Un exemple concret

Créez un guardrail nommé pii-shield dans la console (/console/guardrails), ajoutez une seule règle PII — étape input, action mask, entités email, ssn — et attachez-la à une clé. À partir de là : 
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"}
    ]
  }'
La passerelle réécrit le prompt en Reply to [EMAIL] please avant la transmission — le modèle en amont ne voit jamais l’adresse. Basculez cette entité ssn sur block et la prochaine requête transportant un SSN est rejetée avec une HTTP 400. Aucun changement applicatif.
La rédaction est une action de console / API de gestion sur votre session — la clé de relais sk-orca-... ne sert qu’au trafic /v1/*, jamais à modifier la politique. Créer ou modifier un guardrail nécessite le rôle Developer+.

​
3. Règles : type, étape, action

Chaque règle répond à trois questions. Le moteur exécute toutes les règles applicables et les fond en une seule décision.
Sept types de règles. Les règles intégrées sont déterministes (pur string/regex, sans réseau) ; les règles avancées font des appels sortants vers un modèle ou un fournisseur et s’exécutent en concurrence.
  • keyword — liste de mots interdits littérale, correspondance de sous-chaîne insensible à la casse.
  • regex — un motif RE2 (temps linéaire, sans backreferences).
  • pii — détecteurs d’entités intégrés plus les vôtres. Voir §5.
  • max_chars — plafonne le nombre de caractères à une étape.
  • external — délègue à un fournisseur connecté (Aporia, Averta, ou votre propre webhook).
  • llm_judge — une vérification sémantique contre un modèle de votre espace de travail.
  • grounding — score la fidélité de la réponse par rapport aux sources récupérées sur la requête (RAG).
input (la requête), output (la réponse du modèle), ou both. Les règles d’entrée s’exécutent avant l’appel amont ; les règles de sortie s’exécutent après que le modèle a répondu. Voir étape input et étape output.
Cinq actions apparaissent dans le constructeur de règles :
  • block — rejeter l’appel avec une HTTP 400.
  • mask — redacter la correspondance et laisser passer le texte assaini.
  • flag — ne rien changer au trafic ; enregistrer seulement la correspondance.
  • annotate — laisser le texte intact mais injecter une note de sécurité en amont (par exemple un avis de CVE avant que le modèle ne réponde).
  • spotlight — encadrer le texte non fiable correspondant dans des délimiteurs et indiquer au modèle de le traiter comme des données, pas des instructions.
Voir Actions. Utilisez flag pour mesurer une règle sur le trafic réel avant de l’appliquer.

​
4. Comment un guardrail s’attache et se résout

Un guardrail se lie à une clé via guardrail_id, ou un espace de travail peut marquer un guardrail comme son défaut. Pour toute requête, la passerelle résout dans cet ordre :
  1. Attachement explicite — si le guardrail_id de la clé pointe vers un guardrail qui existe et est activé, c’est celui-là qui s’applique. Un attachement explicite ne retombe jamais : le désactiver est l’interrupteur d’arrêt.
  2. Défaut de l’espace de travail — si la clé n’a pas d’attachement, le guardrail par défaut activé s’applique.
  3. Ni l’un ni l’autre — aucune application ; la requête est identique octet pour octet à un espace de travail qui n’a jamais activé la fonctionnalité.
Cela diffère du firewall. Une politique firewall attachée désactivée retombe sur le défaut de l’espace de travail ; un guardrail attaché désactivé ne va vers rien. L’interrupteur d’arrêt est littéral pour les guardrails.
Visites guidées : créer votre premier guardrail, attacher à une clé, définir un défaut de compte.

​
5. Détecteurs de PII

Une règle pii livre un ensemble fermé de détecteurs intégrés : email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address — plus les détecteurs régionaux jp_mynumber, kr_rrn et cn_resident_id. Sur une action mask, chaque correspondance devient une balise typée — un email devient [EMAIL], un SSN devient [SSN]. Vous pouvez superposer jusqu’à 25 entités personnalisées par règle (une regex avec checksum Luhn optionnel), et router différentes entités vers différentes actions dans une seule règle via des overrides par entité.
Le point de départ clé en main est le preset PII Shield — une seule règle pii, mask, étape both. Le masquage à l’étape input réécrit la requête avant le modèle (streaming ou non) ; le masquage de sortie réécrit la réponse sur les réponses non-streaming uniquement — la réécriture de sortie in-stream est sur la feuille de route. Voir PII Shield, entités personnalisées, et formats de masquage.

​
6. Le sélecteur de presets

New guardrail ouvre dans un template. Les presets sont rédigés côté serveur, donc la console, le sandbox et cette documentation décrivent le même comportement. Le sélecteur les groupe en catégories :
CatégoriePresets d’exempleBranche
pii / secretsPII Shield, bloqueurs de credentials secretsbloquer les secrets
safetyinjection de prompt, jailbreak, automutilationinjection de prompt
complianceGDPR, PCI, HIPAA, compliance loggercompliance logger
brand / costgrossièretés, mentions de concurrents, plafonds de taillebrand safety · cost
agentfiltres URL / outil shell / SQL-en-sortieagentic
code_securityblocs de fichiers secrets, revue de licence copyleftsécurité du code
Un preset est une graine, pas un verrou — appliquez-le, puis modifiez librement. Davantage de points de départ vivent sous templates.

​
7. Quand un guardrail bloque

Une requête bloquée renvoie une HTTP 400 avec le code d’erreur guardrail_blocked et un message nommant le guardrail et la règle qui s’est déclenchée.
  • Aucun quota n’est facturé. Un block à l’étape input se déclenche avant la mesure ; un block à l’étape output rembourse le quota pré-consommé.
  • La requête est marquée skip-retry — ré-exécuter le même prompt ne ferait que bloquer à nouveau, donc la passerelle ne gaspillera pas un retry sur un autre canal.
En streaming, block est appliqué au mieux — un scanner met en tampon un petit lookahead et coupe le flux quand une règle se déclenche, donc les octets déjà émis ne peuvent pas être rétractés. Mask sur la sortie ne s’applique qu’aux réponses non-streaming — sur une réponse streaming, la passerelle calcule le masque mais ne transmet pas le texte redacté ; la réécriture de sortie in-stream est sur la feuille de route. (Le masquage à l’étape input est actif en streaming comme en non-streaming.) Voir l’erreur guardrail_blocked et couverture du streaming.

​
8. Une fois en production

Flux des correspondances

Chaque règle qui se déclenche enregistre le type, l’action, l’étape et le détail. Groupez, filtrez, exportez et plongez dans une seule correspondance.

Journalisation & confidentialité

La sous-chaîne correspondante n’est enregistrée que lorsque Log raw content est activé — désactivé par défaut, la posture conservatrice en matière de confidentialité.

Versioning

Chaque changement écrit une ligne d’historique. Faites le diff de deux versions quelconques et revenez en arrière comme une nouvelle version — l’historique n’est jamais muté.

Test & éval

Un onglet Test en sandbox évalue la politique actuelle sans appel en amont, et un harnais d’évaluation la score contre des corpus fournis ou personnalisés.
Un faux positif est un signal d’ajustement, pas une raison de désactiver la règle. Marquez-le dans le flux Matches et resserrez le motif — voir ajuster les faux positifs.

​
9. Où aller ensuite

Guardrails — chaque champ, chaque route, les règles de juge LLM et d’ancrage, et les fournisseurs externes en profondeur.