Saltar al contenido principal
El detector pii integrado cubre las entidades comunes — email, teléfono, tarjeta de crédito, SSN, IBAN, JWT, claves de nube. Pero tus datos sensibles son tuyos: IDs de empleado, números de caso internos, referencias de cuenta de cliente, el formato de pedido de un socio. Una entidad PII personalizada te permite enseñar a la misma regla de enmascarado a reconocer esas formas, para que el gateway las redacte antes de que el modelo — o cualquier herramienta downstream — las vea jamás. Esta página cubre lo único que las entidades personalizadas añaden a la regla de PII detection: tus propios detectores. Para el motor completo — cada tipo de regla, etapa y ruta — ver la referencia de Guardrails.
Cada paso aquí es una acción de consola sobre el gateway alojado (api.orcarouter.ai). Creas el guardrail bajo tu propia sesión; solo la llamada final /v1/* usa una clave de relay sk-orca-.... Crear y editar guardrails requiere Developer+ en el espacio de trabajo.

​
1. Cuándo necesitas un guardrail de detector de PII personalizado para LLM

El conjunto de entidades integradas es cerrado y compartido a través del motor, el validador y el constructor de reglas. Es la herramienta correcta para identificadores estándar. Recurre a una entidad personalizada cuando los datos que quieres redactar tienen una forma predecible que ningún integrado cubre:

Identificadores internos

IDs de empleado (EMP482915), números de caso, refs de ticket, SKUs internos — cualquier cosa con un prefijo fijo y una serie de dígitos.

Números de cuenta y pedido

Referencias de cuenta de cliente o el formato de pedido de un socio que nunca debería llegar a un modelo de terceros textualmente.

Números con checksum

Números tipo tarjeta o de membresía que pasan una verificación Luhn — añade el checksum para reducir falsos positivos en series de dígitos parecidas.

Códigos específicos del dominio

Números de póliza, IDs de reclamación, seriales de dispositivo — cualquier token que tu industria trata como sensible pero que los detectores genéricos no conocen.
Una entidad personalizada se superpone encima del conjunto integrado dentro de una regla pii. Detecta coincidencias y aplica la acción de la regla — mask, block o flag — exactamente como lo hace una entidad integrada.

​
2. Anatomía de una entidad personalizada

Una entidad personalizada son tres campos pequeños más una etiqueta de enmascarado opcional. Los añades en el editor de la regla pii bajo Custom entities:
CampoObligatorioQué hace
namesíID estable, p. ej. employee_id. ASCII en minúsculas / dígitos / _, debe empezar con una letra. Fluye al feed de Matches y los logs de auditoría.
patternsíUn regex RE2 de Go (tiempo lineal, sin backreferences). Debe compilar.
checksumnoluhn valida cada coincidencia con el algoritmo de Luhn. Solo se aceptan "" (ninguno) o "luhn".
mask_withnoReemplazo literal en una acción mask. Por defecto [<UPPERCASE_NAME>].
El name sigue la misma convención de claves que el resto del gateway — minúsculas, empieza con una letra, sin espacios ni guiones. Elige uno claro (case_number, partner_order_id); es lo que verás en el Feed de coincidencias cuando la regla se dispara.

​
El checksum Luhn opcional

Muchos identificadores “con forma de número” — tarjetas de pago, algunos números de membresía y cuenta — llevan un dígito de control Luhn (mod-10). Un regex desnudo como \d{16} coincide con cualquier serie de 16 dígitos, incluyendo números de teléfono, marcas de tiempo y totales de pedido. Establecer checksum: "luhn" hace que el detector se dispare solo cuando los dígitos coincidentes también pasan la verificación Luhn, así que las series parecidas pasan limpiamente y tu tasa de falsos positivos se mantiene baja. Déjalo vacío para tokens sin checksum como un ID de empleado.

​
Tu propia etiqueta de enmascarado

En una acción mask, un email integrado se renderiza como [EMAIL]. Una entidad personalizada se renderiza como [<UPPERCASE_NAME>] por defecto — una coincidencia de employee_id se convierte en [EMPLOYEE_ID]. Establece mask_with para sobrescribir eso literalmente (p. ej. <id> o ***) cuando quieras un token de reemplazo específico en el texto que el modelo recibe. Ver Formatos de enmascarado para las reglas de renderizado a través de los tipos de entidad.

​
3. Un ejemplo concreto

Supón que tus prompts llevan IDs de empleado con la forma EMP seguido de seis dígitos, y quieres que se enmascaren en la etapa de entrada para que el modelo upstream nunca vea un ID real. Añade una sola entidad personalizada a una regla pii: 
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email"],
  "custom_entities": [
    {
      "name": "employee_id",
      "pattern": "EMP\\d{6}",
      "mask_with": "[EMPLOYEE_ID]"
    }
  ]
}
Esa regla enmascara tanto los emails estándar como tus IDs de empleado en la misma pasada. Pruébala en la pestaña Test antes de vincular una clave: 
Forward EMP482915's note to jane@acme.com

Forward [EMPLOYEE_ID]'s note to [EMAIL]
Nada se envía upstream y nada se mide. Luego vincula el guardrail a una clave (ver Vincular a una clave) y llama a /v1/chat/completions exactamente como antes — el gateway enmascara la solicitud antes de reenviar, sin cambio de SDK.
El enmascarado se ejecuta en ambas etapas: una regla de entrada redacta la solicitud antes de que el modelo la vea, y una regla de salida redacta la respuesta del modelo — incluyendo respuestas con streaming, donde el escáner reescribe coincidencias en banda. Las acciones de bloqueo se aplican también en ambas etapas. Para vetar las respuestas del modelo, ver Reglas de la etapa de salida.

​
Un ejemplo con checksum

Para un número de membresía tipo tarjeta, añade la verificación Luhn para que las series de 16 dígitos que no son números válidos no coincidan: 
{
  "name": "member_card",
  "pattern": "\\d{16}",
  "checksum": "luhn",
  "mask_with": "[MEMBER_CARD]"
}

​
4. Límites y validación

El constructor de reglas valida cada entidad personalizada al guardar — un detector malo nunca llega a la ruta caliente.
Cada entidad personalizada es un escaneo regex sobre el texto completo, así que el tope por regla es 25. El tope mantiene la ruta caliente lineal; los patrones compilados se cachean entre solicitudes. ¿Necesitas más formas? Divídelas entre múltiples reglas pii en el mismo guardrail.
pattern es un regex RE2 de Go — tiempo lineal, sin backreferences. El validador rechaza un patrón que no compila, con la entidad ofensiva nombrada en el error.
Solo se aceptan "" (sin verificación) y "luhn". Cualquier otra cosa — "sha256", "mod10", incluso "LUHN" — se rechaza al guardar.
Un name debe empezar con una letra y usar solo ASCII en minúsculas, dígitos y guiones bajos. Dos entidades personalizadas en una regla no pueden compartir un nombre.

​
5. Sobrescrituras de acción por entidad

Una entidad personalizada participa en el mismo mapa entity_actions que una entidad integrada. Una regla pii puede enmascarar la mayoría de las cosas pero bloquear en un detector personalizado de alta sensibilidad — referencia la entidad por su 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"
  }
}
Las claves en entity_actions deben referenciar una entidad integrada habilitada en la regla o el name de una entidad personalizada; los valores deben ser block, mask, flag o annotate. El validador rechaza cualquier otra cosa.

​
6. Dónde ir a continuación

PII Shield

La sola regla de enmascarado sobre la que se superponen las entidades personalizadas — el conjunto de detectores integrados y las etiquetas de enmascarado tipadas.

Formatos de enmascarado

Cómo se renderiza cada entidad en una acción mask, y cómo mask_with la sobrescribe.

Detectores regex

Cuándo una regla regex simple encaja mejor que una entidad PII tipada.

Afinar falsos positivos

Usa el feed de Matches y el checksum para afinar la precisión.
Lee la referencia de Guardrails para la regla PII completa — cada campo, el arnés de eval y la API completa — o Crea tu primer guardrail para recorrer el ciclo de extremo a extremo desde cero.