Saltar al contenido principal
Un guardrail es la capa de política de contenido del gateway de OrcaRouter. Guardas una política nombrada en tu espacio de trabajo, la adjuntas a una clave API, y cada llamada /v1/* que hace esa clave se examina — antes de que el modelo vea el prompt y después de que el modelo responde — sin redespliegue y sin cambio de SDK. Esta página es el hub de la sección Guardrails: qué es un guardrail, los tipos de regla, las etapas y acciones, y cómo una política se adjunta a una clave. Cada radio profundiza más. Para la referencia completa del motor, ver Guardrails.

​
1. Qué hacen los guardrails de IA en el gateway

La mayoría de los equipos recurren a los guardrails para mantener datos sensibles fuera de los prompts (PII, secretos), para vetar contenido inseguro (jailbreaks, intención de inyección de prompts) o para satisfacer un control de cumplimiento. Un guardrail es la respuesta del gateway: una política nombrada, con alcance de espacio de trabajo — una lista ordenada de reglas que el gateway ejecuta contra la entrada de la solicitud y la salida del modelo. Como la vinculación vive en la clave API dentro del gateway — no en tu aplicación — editar un guardrail surte efecto en cada clave vinculada en la siguiente llamada. Tu código sigue llamando a /v1/chat/completions exactamente como antes.
Los guardrails son política de contenido (texto entra, texto sale). El complementario Agent Firewall es política de herramientas — gobierna qué llamadas a herramienta puede hacer un agente. Los dos se componen; ver Guardrails vs. firewall.

​
2. Un ejemplo concreto

Crea un guardrail llamado pii-shield en la consola (/console/guardrails), añade una sola regla PII — etapa input, acción mask, entidades email, ssn — y vincúlala a una clave. A partir de entonces: 
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"}
    ]
  }'
El gateway reescribe el prompt a Reply to [EMAIL] please antes de reenviar — el modelo upstream nunca ve la dirección. Cambia esa entidad ssn a block y la siguiente solicitud que lleve un SSN es rechazada con HTTP 400. Sin cambios en la aplicación.
La autoría es una acción de consola / API de gestión sobre tu sesión — la clave de relay sk-orca-... es solo para tráfico /v1/*, nunca para editar política. Crear o editar un guardrail requiere el rol Developer+.

​
3. Reglas: tipo, etapa, acción

Cada regla responde tres preguntas. El motor ejecuta todas las reglas aplicables y las pliega en una sola decisión.
Siete tipos de regla. Las integradas son deterministas (string/regex puros, sin red); las avanzadas hacen llamadas a un modelo o proveedor y se ejecutan de forma concurrente.
  • keyword — denylist literal, coincidencia por subcadena sin distinguir mayúsculas y minúsculas.
  • regex — un patrón RE2 (tiempo lineal, sin backreferences).
  • pii — detectores de entidad integrados más los tuyos propios. Ver §5.
  • max_chars — limita el conteo de caracteres en una etapa.
  • external — delega a un proveedor conectado (Aporia, Averta o tu propio webhook).
  • llm_judge — una verificación semántica contra un modelo de tu espacio de trabajo.
  • grounding — puntúa la fidelidad de la respuesta contra las fuentes recuperadas en la solicitud (RAG).
input (la solicitud), output (la respuesta del modelo) o both. Las reglas de entrada se ejecutan antes de la llamada upstream; las reglas de salida después de que el modelo responde. Ver etapa de entrada y etapa de salida.
Cinco acciones aparecen en el constructor de reglas:
  • block — rechazar la llamada con HTTP 400.
  • mask — redactar la coincidencia y dejar pasar el texto saneado.
  • flag — no cambiar nada del tráfico; solo registrar la coincidencia.
  • annotate — dejar el texto intacto pero inyectar una nota de seguridad upstream (p. ej. un aviso de CVE antes de que el modelo responda).
  • spotlight — envolver el texto no confiable coincidente en delimitadores y decirle al modelo que lo trate como datos, no como instrucciones.
Ver Acciones. Usa flag para medir una regla sobre tráfico en vivo antes de aplicarla.

​
4. Cómo se adjunta y resuelve un guardrail

Un guardrail se vincula a una clave vía guardrail_id, o un espacio de trabajo puede marcar un guardrail como su valor por defecto. Para cualquier solicitud el gateway resuelve en este orden:
  1. Vinculación explícita — si el guardrail_id de la clave apunta a un guardrail que existe y está habilitado, ese aplica. Una vinculación explícita nunca hace fallback: deshabilitarla es el interruptor de apagado.
  2. Valor por defecto del espacio de trabajo — si la clave no tiene vinculación, aplica el guardrail por defecto habilitado.
  3. Ninguno — sin aplicación; la solicitud es idéntica byte a byte a un espacio de trabajo que nunca habilitó la función.
Esto difiere del firewall. Una política de firewall vinculada deshabilitada hace fallback al valor por defecto del espacio de trabajo; un guardrail vinculado deshabilitado va a ninguno. El interruptor de apagado es literal para los guardrails.
Recorridos: crea tu primer guardrail, vincular a una clave, establecer un valor por defecto de cuenta.

​
5. PII detectors

Una regla pii viene con un conjunto cerrado de detectores integrados: email, phone, credit_card, ssn, ip, iban, mac_address, jwt, aws_access_key, api_key_openai, bitcoin_address — más los regionales jp_mynumber, kr_rrn y cn_resident_id. En una acción mask cada coincidencia se convierte en una etiqueta tipada — un email se renderiza como [EMAIL], un SSN como [SSN]. Puedes superponer hasta 25 entidades personalizadas por regla (un regex con checksum Luhn opcional), y enrutar diferentes entidades a diferentes acciones en una regla vía sobrescrituras por entidad.
El punto de partida llave en mano es el preset PII Shield — una sola regla pii, mask, etapa both. El enmascarado en la etapa de entrada reescribe la solicitud antes del modelo (con o sin streaming); el enmascarado de salida reescribe la respuesta solo en respuestas sin streaming — la reescritura de salida en el stream está en el roadmap. Ver PII Shield, entidades personalizadas y formatos de enmascarado.

​
6. El selector de presets

New guardrail abre directamente en una plantilla. Los presets se crean del lado del servidor, así que la consola, el sandbox y estos docs describen el mismo comportamiento. El selector los agrupa en categorías:
CategoríaPresets de ejemploRadio
pii / secretsPII Shield, bloqueadores de secret-credentialbloquear secretos
safetyinyección de prompts, jailbreak, autolesionesinyección de prompts
complianceGDPR, PCI, HIPAA, registrador de cumplimientoregistrador de cumplimiento
brand / costprofanidad, menciones a competidores, topes de tamañoseguridad de marca · coste
agentfiltros de URL / shell-tool / SQL-en-salidaagéntico
code_securitybloqueos de secret-file, revisión de licencia copyleftseguridad de código
Un preset es una semilla, no un candado — aplícalo, luego edita libremente. Más puntos de partida viven bajo plantillas.

​
7. Cuando un guardrail bloquea

Una solicitud bloqueada devuelve HTTP 400 con el código de error guardrail_blocked y un mensaje que nombra el guardrail y la regla que se disparó.
  • No se cobra cuota. Un bloqueo en la etapa de entrada se dispara antes de la medición; un bloqueo en la etapa de salida reembolsa la cuota preconsumida.
  • La solicitud se marca como skip-retry — reejecutar el mismo prompt simplemente volvería a bloquear, así que el gateway no malgasta un reintento en otro canal.
En streaming, block se aplica con mejor esfuerzo — un escáner almacena un pequeño lookahead y corta el stream cuando una regla se dispara, así que los bytes ya enviados no pueden retraerse. Mask en la salida se aplica solo a respuestas sin streaming — en una respuesta con streaming el gateway computa el enmascarado pero no reenvía el texto redactado; la reescritura de salida en el stream está en el roadmap. (El enmascarado en la etapa de entrada está activo tanto con streaming como sin él.) Ver el error guardrail_blocked y cobertura de streaming.

​
8. Después de que está activo

Feed de coincidencias

Cada regla que se dispara registra tipo, acción, etapa y detalle. Agrupa, filtra, exporta y profundiza en una sola coincidencia.

Registro y privacidad

La subcadena coincidente se registra solo cuando Log raw content está activado — apagado por defecto, la postura conservadora con la privacidad.

Versionado

Cada cambio escribe una fila de historial. Haz diff de dos versiones cualesquiera y revierte como una nueva versión — el historial nunca se muta.

Pruebas y eval

Una pestaña Test del sandbox evalúa la política actual sin llamada upstream, y un arnés de eval la puntúa contra corpora empaquetados o personalizados.
Un falso positivo es una señal de ajuste, no una razón para deshabilitar la regla. Márcalo en el feed de Matches y acota el patrón — ver afinar falsos positivos.

​
9. Dónde ir a continuación

Guardrails — cada campo, cada ruta, las reglas de LLM-judge y grounding, y los proveedores externos en profundidad.