Passer au contenu principal
Le détecteur pii intégré couvre les entités courantes — email, téléphone, carte de crédit, SSN, IBAN, JWT, clés cloud. Mais vos données sensibles sont les vôtres : identifiants d’employés, numéros de dossier internes, références de compte client, le format de commande d’un partenaire. Une entité PII personnalisée vous permet d’apprendre à la même règle de masquage à reconnaître ces formes, afin que la passerelle les redacte avant que le modèle — ou tout outil en aval — ne les voie jamais. Cette page couvre la seule chose que les entités personnalisées ajoutent à la règle de détection de PII : vos propres détecteurs. Pour le moteur complet — chaque type de règle, étape et route — voir la référence Guardrails.
Chaque étape ici est une action de console sur la passerelle hébergée (api.orcarouter.ai). Vous rédigez le guardrail sous votre propre session ; seul l’appel /v1/* final utilise une clé de relais sk-orca-.... Créer et modifier des guardrails nécessite Developer+ dans l’espace de travail.

​
1. Quand vous avez besoin d’un guardrail détecteur de PII personnalisé pour LLM

L’ensemble d’entités intégrées est fermé et partagé à travers le moteur, le validateur et le constructeur de règles. C’est le bon outil pour les identifiants standards. Recourez à une entité personnalisée quand les données que vous voulez redacter ont une forme prévisible qu’aucun détecteur intégré ne couvre :

Identifiants internes

Identifiants d’employés (EMP482915), numéros de dossier, références de ticket, SKUs internes — tout ce qui a un préfixe fixe et une suite de chiffres.

Numéros de compte & de commande

Références de compte client ou format de commande d’un partenaire qui ne devrait jamais atteindre un modèle tiers tel quel.

Numéros à checksum

Numéros de type carte ou d’adhésion qui passent une vérification Luhn — ajoutez le checksum pour réduire les faux positifs sur les suites de chiffres ressemblantes.

Codes spécifiques au domaine

Numéros de police, identifiants de sinistre, numéros de série d’appareils — tout token que votre industrie traite comme sensible mais que les détecteurs génériques ne connaissent pas.
Une entité personnalisée se superpose par-dessus l’ensemble intégré à l’intérieur d’une règle pii. Elle détecte les correspondances et applique l’action de la règle — mask, block ou flag — exactement comme le fait une entité intégrée.

​
2. Anatomie d’une entité personnalisée

Une entité personnalisée, ce sont trois petits champs plus une balise de masque optionnelle. Vous les ajoutez dans l’éditeur de règle pii sous Custom entities :
ChampRequisCe qu’il fait
nameouiID stable, par exemple employee_id. ASCII minuscule / chiffres / _, doit commencer par une lettre. Circule dans le flux Matches et les journaux d’audit.
patternouiUne regex Go RE2 (temps linéaire, sans backreferences). Doit compiler.
checksumnonluhn valide chaque correspondance avec l’algorithme de Luhn. Seuls "" (aucun) ou "luhn" sont acceptés.
mask_withnonRemplacement verbatim sur une action mask. Par défaut [<UPPERCASE_NAME>].
Le name suit la même convention de clé que le reste de la passerelle — minuscule, commence par une lettre, sans espaces ni tirets. Choisissez-en un clair (case_number, partner_order_id) ; c’est ce que vous verrez dans le flux des correspondances quand la règle se déclenche.

​
Le checksum Luhn optionnel

Beaucoup d’identifiants « en forme de nombre » — cartes de paiement, certains numéros d’adhésion et de compte — portent un chiffre de contrôle Luhn (mod-10). Une regex nue comme \d{16} correspond à n’importe quelle suite de 16 chiffres, y compris les numéros de téléphone, les timestamps et les totaux de commande. Définir checksum: "luhn" fait que le détecteur ne se déclenche que lorsque les chiffres correspondants passent aussi la vérification Luhn, afin que les suites ressemblantes passent proprement et que votre taux de faux positifs reste bas. Laissez-le vide pour les tokens sans checksum comme un identifiant d’employé.

​
Votre propre balise de masque

Sur une action mask, un email intégré est rendu en [EMAIL]. Une entité personnalisée est rendue en [<UPPERCASE_NAME>] par défaut — une correspondance employee_id devient [EMPLOYEE_ID]. Définissez mask_with pour surcharger cela verbatim (par exemple <id> ou ***) quand vous voulez un token de remplacement spécifique dans le texte que le modèle reçoit. Voir Formats de masquage pour les règles de rendu à travers les types d’entités.

​
3. Un exemple concret

Supposons que vos prompts transportent des identifiants d’employés sous la forme EMP suivi de six chiffres, et que vous voulez les masquer à l’étape input afin que le modèle en amont ne voie jamais un vrai ID. Ajoutez une seule entité personnalisée à une règle pii : 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
Cette règle masque à la fois les emails standards et vos identifiants d’employés dans la même passe. Testez-la dans l’onglet Test avant d’attacher une clé : 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
Rien n’est envoyé en amont et rien n’est mesuré. Puis attachez le guardrail à une clé (voir Attacher à une clé) et appelez /v1/chat/completions exactement comme avant — la passerelle masque la requête avant la transmission, sans changement de SDK.
Le masquage s’exécute aux deux étapes : une règle input redacte la requête avant que le modèle ne la voie, et une règle output redacte la réponse du modèle — y compris les réponses streaming, où le scanner réécrit les correspondances in-band. Les actions block sont appliquées sur les deux étapes également. Pour contrôler les réponses du modèle, voir Règles à l’étape output.

​
Un exemple à checksum

Pour un numéro d’adhésion de type carte, ajoutez la vérification Luhn afin que les suites de 16 chiffres qui ne sont pas des numéros valides ne correspondent pas : 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. Limites et validation

Le constructeur de règles valide chaque entité personnalisée à l’enregistrement — un mauvais détecteur n’atteint jamais le chemin à chaud.
Chaque entité personnalisée est un scan regex sur l’intégralité du texte, donc le plafond par règle est de 25. Le plafond garde le chemin à chaud linéaire ; les motifs compilés sont mis en cache à travers les requêtes. Besoin de plus de formes ? Répartissez-les sur plusieurs règles pii dans le même guardrail.
pattern est une regex Go RE2 — temps linéaire, sans backreferences. Le validateur rejette un motif qui ne compile pas, avec l’entité fautive nommée dans l’erreur.
Seuls "" (aucune vérification) et "luhn" sont acceptés. Tout le reste — "sha256", "mod10", même "LUHN" — est rejeté à l’enregistrement.
Un name doit commencer par une lettre et n’utiliser que de l’ASCII minuscule, des chiffres et des underscores. Deux entités personnalisées dans une même règle ne peuvent pas partager un nom.

​
5. Overrides d’action par entité

Une entité personnalisée participe à la même map entity_actions qu’une entité intégrée. Une règle pii peut masquer la plupart des choses mais bloquer sur un détecteur personnalisé à haute sensibilité — référencez l’entité par son name : 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone"],
  "custom_entities": [
    { "name": "ssn_internal", "pattern": "ID-\\d{9}", "checksum": "luhn" }
  ],
  "entity_actions": {
    "ssn_internal": "block"
  }
}
Les clés dans entity_actions doivent référencer une entité intégrée activée sur la règle ou le name d’une entité personnalisée ; les valeurs doivent être block, mask, flag ou annotate. Le validateur rejette tout le reste.

​
6. Où aller ensuite

PII Shield

La seule règle de masquage sur laquelle les entités personnalisées se superposent — l’ensemble de détecteurs intégrés et les balises de masque typées.

Formats de masquage

Comment chaque entité est rendue sur une action mask, et comment mask_with la surcharge.

Détecteurs regex

Quand une simple règle regex convient mieux qu’une entité PII typée.

Ajuster les faux positifs

Utilisez le flux Matches et le checksum pour affiner la précision.
Lisez la référence Guardrails pour la règle PII complète — chaque champ, le harnais d’évaluation et l’API complète — ou Créer votre premier guardrail pour parcourir la boucle de bout en bout depuis zéro.