Saltar al contenido principal
Una vez que tienes un espacio de trabajo y una clave API (ver Introducción), los guardrails son la forma de poner una política de contenido delante de cada modelo. Esta página es la referencia canónica del motor de guardrails de OrcaRouter — qué es, cómo usarlo y cómo se compone con el resto del gateway.

1. Qué es el motor de guardrails

Un guardrail es una política de contenido 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. Guardas un guardrail una vez, vinculas cualquier clave API a él (o estableces uno como el valor por defecto del espacio de trabajo), y el gateway filtra cada llamada antes y después del modelo upstream. Cada regla decide una cosa — qué buscar (un tipo de regla), dónde buscar (una etapa: entrada de la solicitud o salida del modelo) y qué hacer al respecto (una acción: block, mask o flag). El motor ejecuta cada regla aplicable y pliega los resultados en una sola decisión. Editar un guardrail surte efecto en cada clave vinculada a él en la siguiente llamada. Sin redespliegue. Sin cambio de código. Sin actualización del SDK. La política vive en el gateway, no en tu aplicación — tu aplicación sigue llamando a /v1/chat/completions exactamente como antes. El motor es determinista y sin dependencias para los tipos de regla integrados: coincidencia pura de cadenas y regex sin llamada de red, seguro de ejecutar en la ruta de relay caliente. Las reglas avanzadas (proveedores externos, LLM judge, contextual grounding) hacen llamadas externas y se despachan de forma concurrente para que una verificación lenta nunca se serialice detrás de otra. Los guardrails tienen alcance de espacio de trabajo — cada miembro ve los guardrails del espacio de trabajo; nada cruza límites de tenant.

2. Inicio rápido — filtra tu primera solicitud en 5 pasos

1

Crear un guardrail

En la consola, ve a /console/guardrails y haz clic en New guardrail. Nómbralo pii-shield. Añade una regla:
  • Tipo: PII detection
  • Etapa: Input (request)
  • Acción: Mask — redactar la coincidencia
  • Entidades: email, phone, ssn
Guarda.
2

Pruébalo en el sandbox

Abre la pestaña Test dentro del editor, pega “email me at jane@acme.com, elige la etapa input y ejecuta. El sandbox muestra el veredicto y el texto renderizado — email me at [EMAIL] — sin enviar nada upstream.
3

Vincular una clave

Ve a /console/token, crea o edita una clave API y elige pii-shield del desplegable Guardrail. La vinculación vive en la clave dentro del gateway.
4

Enviar una solicitud

Usando esa clave, llama a OrcaRouter exactamente como antes:
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 enmascara el email a [EMAIL] antes de reenviar. El modelo upstream nunca ve la dirección.
5

Endurecer la política

De vuelta en /console/guardrails, edita pii-shield — cambia la acción de ssn a Block vía sobrescritura por entidad. Guarda. La siguiente solicitud que contenga un SSN es rechazada con HTTP 400 guardrail_blocked. Sin cambios en la aplicación.
Ese es el valor titular.

3. Conceptos: guardrails, reglas, etapas, acciones

ConceptoDefinición
GuardrailUna política nombrada, con alcance de espacio de trabajo. Identificador: name (≤ 64 caracteres). Tiene enabled, is_default y un blob JSON de rules.
ReglaUna verificación dentro de una política: un type, una stage, una action, más campos específicos del tipo. Las reglas se ejecutan en orden.
Etapainput (la solicitud), output (la respuesta del modelo) o both.
Acciónblock (rechazar la llamada), mask (redactar la coincidencia) o flag (solo registrar — observar sin cambiar el tráfico).

Alcance y el valor por defecto del espacio de trabajo

Los guardrails tienen exactamente el mismo alcance que las claves API: compartidos en el espacio de trabajo cuando tienes uno activo, por usuario en caso contrario. Resolución para cualquier solicitud:
  1. Vinculación de clave — si la clave tiene un guardrail_id explícito, ese guardrail aplica (cuando existe y está habilitado). Una vinculación explícita nunca hace fallback silencioso; deshabilitarla es el interruptor de apagado.
  2. Valor por defecto del espacio de trabajo — si la clave no tiene vinculación, aplica el guardrail habilitado is_default del espacio de trabajo.
  3. Ninguno — sin aplicación. La solicitud es idéntica byte a byte a un espacio de trabajo que nunca habilitó la función.
A lo sumo un guardrail por espacio de trabajo puede ser el valor por defecto. Promover un nuevo valor por defecto degrada al anterior en la misma transacción.
Fail-open por diseño. Si la resolución de guardrails encuentra un error transitorio (p. ej. un hipo de la DB), el gateway degrada a sin aplicación en vez de tumbar el tráfico. La seguridad se degrada; la disponibilidad se preserva.

Cómo se ve un block

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ó. Una solicitud bloqueada no te cuesta cuota — un bloqueo en la etapa de entrada se dispara antes de la medición, y un bloqueo en la etapa de salida reembolsa la cuota preconsumida — y se marca como skip-retry (reejecutar el mismo prompt simplemente volvería a bloquear).

4. Tipos de regla

Las reglas se dividen en dos grupos: integradas (deterministas, sin red) y avanzadas (hacen llamadas a un modelo o proveedor).
TipoGrupoQué hace
Keyword denylist (keyword)IntegradaCoincide con cualquiera de una lista de términos literales — sin distinguir mayúsculas y minúsculas, coincidencia por subcadena (así class también coincide con classic).
Regular expression (regex)IntegradaCoincide con un patrón RE2 (tiempo lineal, sin backreferences).
PII detection (pii)IntegradaDetecta tipos de entidad integrados (y los tuyos personalizados). Ver §5.
Maximum length (max_chars)IntegradaLimita el conteo de caracteres del texto en una etapa.
External vendor (external)AvanzadaDelega la verificación a un proveedor conectado (Aporia, Averta, BYO-webhook, …). Ver §9.
LLM judge (llm_judge)AvanzadaEjecuta una verificación semántica contra un modelo de tu espacio de trabajo. Ver §6.
Contextual grounding (grounding)AvanzadaPuntúa la fidelidad de la respuesta contra las fuentes recuperadas en la solicitud (RAG). Ver §7.
Un guardrail mezcla cualquier número de reglas de cualquier tipo. Las reglas avanzadas (external, llm_judge, grounding) se despachan de forma concurrente para que una verificación lenta no se serialice detrás de otra.

5. PII detection a fondo

Una regla pii detecta entidades sensibles y aplica la acción de la regla a cada coincidencia. El conjunto de detectores integrados es cerrado y compartido por el motor, el validador y el constructor de reglas: email, phone, credit_card, ssn, ip, iban, mac_address, api_key_openai, aws_access_key, jwt, bitcoin_address. En una acción mask, cada coincidencia se reemplaza con una etiqueta tipada — un email se convierte en [EMAIL], un SSN se convierte en [SSN], y así sucesivamente.

Entidades personalizadas

Superpón tus propios detectores sobre el conjunto integrado. Una entidad personalizada es:
  • name — ASCII en minúsculas / dígitos / guion bajo, debe empezar con una letra (p. ej. employee_id). Fluye sin comillas a los registros de auditoría y la telemetría.
  • pattern — un regex RE2 de Go (tiempo lineal, sin backreferences).
  • checksum — opcional; luhn valida la coincidencia con el algoritmo de Luhn (p. ej. para números tipo tarjeta).
  • mask_with — reemplazo literal opcional; por defecto [<UPPERCASE_NAME>].
Hasta 25 entidades personalizadas por regla (cada una es un escaneo regex sobre el texto completo, así que el tope mantiene la ruta caliente lineal). Los patrones compilados se cachean entre solicitudes.

Sobrescrituras de acción por entidad

Una sola regla PII puede aplicar diferentes acciones a diferentes entidades vía entity_actions. Una regla que enmascara emails / teléfonos / IPs por defecto pero bloquea en credit_card o ssn — en vez de tres reglas solapadas:
{
  "type": "pii",
  "stage": "input",
  "action": "mask",
  "entities": ["email", "phone", "ip", "credit_card", "ssn"],
  "entity_actions": {
    "credit_card": "block",
    "ssn": "block"
  }
}
Las claves deben ser una entidad habilitada en la regla; los valores deben ser block / mask / flag. El validador rechaza cualquier otra cosa.

6. LLM judge

Una regla llm_judge ejecuta una verificación semántica contra un modelo que tu espacio de trabajo ya puede llamar. Úsala para políticas difusas que ningún regex captura — toxicidad, acoso, fuera de tema, intención de inyección de prompts.
CampoSignificado
judge_modelEl modelo o alias de router con el que evaluar (p. ej. gpt-4o-mini, orcarouter/cheap). Se resuelve contra los canales de tu espacio de trabajo.
judge_rubricEl mensaje de sistema que describe qué marcar.
judge_formatUno de yes_no, score o category (obligatorio; la consola preselecciona yes_no).
judge_thresholdPara score: bloquear/marcar cuando la puntuación está en o por encima de este valor.
judge_categoriesPara category: la lista denegada.
judge_timeout_msAcota la llamada al juez. 0 → valor por defecto del motor.
judge_fail_opentrue (por defecto) → un error del juez se observa pero la solicitud continúa; false → tratar error/timeout como un block.
La llamada al juez se enruta a través de los canales de tu espacio de trabajo, así que sus tokens se facturan y atribuyen como cualquier otra llamada (como una sub-línea de juez). El motor anexa un apéndice de esquema JSON a tu rúbrica para que el modelo devuelva una salida parseable.

7. Contextual grounding

Una regla grounding mide la respuesta del asistente contra las fuentes recuperadas en la solicitud (tu contexto RAG) y marca o bloquea respuestas que no son fieles a ellas. Reutiliza la costura del juez — mismos canales del espacio de trabajo, misma atribución de coste.
CampoPor defectoSignificado
grounding_modelelección del espacio de trabajoEl modelo al que el runner resuelve la verificación de fidelidad.
grounding_rubricintegradaSobrescribe la rúbrica de fidelidad por defecto.
grounding_threshold0.7Piso de fidelidad, 0.01.0. Por debajo, la acción se dispara.
grounding_strictfalseCuando es true, “no sources provided” se trata como un block (vs el allow por defecto).
grounding_max_bytes100000Limita el contexto de fuentes concatenado entregado al juez.
grounding_timeout_ms3000Acota la llamada al juez.

8. Plantillas, el sandbox y el arnés de eval

Biblioteca de plantillas

El botón dividido New guardrail abre directamente en una plantilla, y la biblioteca completa está a un clic. Los presets se crean del lado del servidor para que la consola, el sandbox y estos docs describan exactamente el mismo comportamiento. Las categorías incluyen:
  • PII (pii) — PII Shield, PII Blocker (estricto), Contact-Info Redactor, redactor de PII en la respuesta.
  • Secrets (secrets) — bloqueadores de credenciales AWS / OpenAI / GitHub, claves privadas y tokens de nube, monederos cripto, secretos en la salida.
  • Compliance (compliance) — GDPR (PII de la UE), PCI (bloqueo completo de tarjetas), HIPAA (PHI), datos financieros, registrador de cumplimiento, aplicación de avisos legales.
  • Brand (brand) — profanidad (block / mask / multilingüe), menciones a competidores, palabras clave de seguridad infantil.
  • Safety (safety) — inyección de prompts, jailbreak, fuga de prompt de sistema, autolesiones.
  • Cost (cost) — topes de tamaño de prompt/respuesta y topes de tokens.
  • Agent (agent) — filtros de URL, imagen-markdown, llamada-a-herramienta-shell e inyección SQL en la salida.
Aplica un preset como punto de partida, luego edita libremente — un preset es una semilla, no un candado.

El sandbox de prueba

Cada editor tiene una pestaña Test. Pega una muestra, elige una etapa y ejecuta la política actual localmente — sin llamada upstream, sin cuota. El sandbox devuelve el veredicto y (para reglas mask) el texto renderizado, para que puedas probar que una regla hace lo que esperas antes de vincular una clave.

Arnés de eval / red-team

La pestaña Eval ejecuta un guardrail contra un corpus de entradas e informa cómo puntuó — útil para afinar una rúbrica de juez o probar que una política captura ataques conocidos antes de lanzarla.
  • Corpora empaquetados vienen con el gateway — conjuntos adversariales y de red-team (prompts de comportamiento dañino, inyección de herramientas, red-teaming multilingüe) más conjuntos benignos para medir falsos positivos.
  • Corpora personalizados — sube tu propio JSONL para probar contra las formas de tu tráfico real.
  • Ejecuciones se listan con sus puntuaciones; abre una ejecución para inspeccionar los fallos muestra por muestra.

9. External vendors

Una regla external delega la verificación a un proveedor conectado. Conecta un proveedor una vez bajo Integrations (el CTA de cabecera en la página de Guardrails), luego referencia la conexión desde una regla.

Proveedores soportados

ProveedorQué es
Aporia Guardrails (aporia)Motor de política de ensamble de SLM para prompts y respuestas.
Averta (averta)Endpoint genérico de clasificador SLM (POST de texto → safe / unsafe + reescritura opcional).
BYO Webhook (webhook)Tu propia URL — recibe prompts y devuelve veredictos allow / block / mask / flag.
Aporia y Averta toman una URL base + clave API; el webhook toma una URL + cabecera de autenticación + secreto HMAC.

Campos de la regla

CampoSignificado
connection_idLa integración conectada a usar (ruta recomendada — proveedor + secretos se resuelven desde la integración del espacio de trabajo en tiempo de ejecución).
timeout_msAcota la única llamada al proveedor. 0 → por defecto.
fail_opentrue (por defecto) → un error del proveedor se observa pero la solicitud continúa; false → tratar error de transporte / timeout / proveedor desconocido como un block.
Los secretos se almacenan cifrados y enmascarados en lectura. La llamada de verificación lleva la cancelación de la solicitud de relay, así que una solicitud cancelada no deja una llamada al proveedor colgada.

10. Observabilidad

Los guardrails dejan migas de pan sobre las que puedes actuar.

Feed de coincidencias

Cada regla que se dispara registra una coincidencia — tipo de regla, acción, una cadena de detalle, la etapa y (cuando está habilitado) la subcadena coincidente. La pestaña Matches en la página de Guardrails es el feed a nivel de todo el espacio de trabajo: listar, agrupar, filtrar, profundizar en una sola coincidencia, exportar a CSV y marcar falsos positivos.
La captura de contenido en bruto es opt-in. El toggle Log raw content de un guardrail está apagado por defecto — la postura conservadora con la privacidad. Con él apagado, el feed de Matches registra que una regla se disparó y su meta-cadena de detalle, pero no la subcadena coincidente real (p. ej. la propia dirección de email). Actívalo por guardrail cuando necesites la subcadena para triaje; el ajuste no es retroactivo.

Estadísticas

El feed de Matches alimenta estadísticas por guardrail — cada tarjeta de guardrail muestra un sparkline y conteo de coincidencias de 7 días, y la pestaña Matches lleva un total del espacio de trabajo. Para segmentar la actividad por política, usa la vista agrupada y los filtros del feed de Matches (por guardrail, tipo de regla, acción) — ahí es donde viven el uso por guardrail, la mezcla de acciones y la tasa de falsos positivos.

Historial de versiones y auditoría

Cada creación, actualización y eliminación escribe una fila de historial versionada en la misma transacción que el cambio. Abre History en la fila de un guardrail para:
  • Ver cada versión con quién la cambió y cuándo.
  • Diff de dos versiones cualesquiera.
  • Revert a una versión más antigua (registrado como una nueva versión — el historial nunca se muta).

11. Relación con el resto del gateway

Superficie¿Cómo se compone con Guardrails?
ModelosLos guardrails son agnósticos del modelo. La misma política viaja sobre GPT-5, Claude, Gemini — filtra texto, no la elección de modelo.
EnrutamientoIndependiente. El enrutamiento decide qué modelo/canal atiende la solicitud; los guardrails filtran el mismo texto de solicitud/respuesta de todos modos y nunca anulan la selección de modelo. El filtrado de entrada se ejecuta antes de la llamada upstream, el filtrado de salida después de que el modelo responde. Las reglas de juez y de fundamentación (grounding) resuelven su propio modelo a través de los canales de tu espacio de trabajo, separado del enrutamiento de la solicitud.
PromptsIndependientes y complementarios. Prompts inyecta un mensaje de sistema; los guardrails inspeccionan y gobiernan el contenido. Ambos pueden aplicarse a una solicitud y los guardrails siempre se ejecutan. El orden importa: las reglas de entrada filtran la solicitud del llamador antes de que se inyecte un prompt del registro (la inyección ocurre más tarde, en la etapa de enrutamiento), por lo que las reglas de entrada ven los mensajes del llamador, no el prompt de sistema inyectado; las reglas de salida filtran la respuesta del modelo en cualquier caso.
Claves APIUna clave se vincula a un guardrail vía guardrail_id. La vinculación vive en la clave dentro del gateway, así que editar el guardrail cambia todas las claves vinculadas a la vez; sin vinculación se hace fallback al valor por defecto del espacio de trabajo.
Feed de MatchesCada regla que se dispara aterriza en el feed de Matches del espacio de trabajo (su propio almacén, separado del log de solicitud). Agrúpalo y fíltralo por guardrail, tipo de regla y acción para ver el uso, la mezcla de acciones y la tasa de falsos positivos por guardrail.

12. Referencia de la API

Todas las rutas tienen alcance de espacio de trabajo vía la cabecera X-Workspace-Id. RBAC se aplica de manera consistente: las lecturas y el sandbox de prueba están abiertos a cada miembro; las escrituras requieren Developer+ (y el permiso guardrails:write); los cambios de tráfico de producción (eliminación, revert, configuración de proveedor) están gobernados en consecuencia.

Guardrails

Método y rutaRolPropósito
GET /api/guardrail/MemberLista guardrails (con conteos de claves vinculadas).
GET /api/guardrail/metaMemberVocabulario del motor — tipos de regla, etapas, acciones, entidades PII, presets, categorías de preset.
GET /api/guardrail/my-permissionsMemberLos permisos de guardrail del llamador (para gobernar la UI).
GET /api/guardrail/:idMemberDetalle de un solo guardrail.
GET /api/guardrail/:id/tokensMemberClaves API vinculadas a este guardrail (limitadas, con el total verdadero).
POST /api/guardrail/testMemberSandbox — evaluar una política sobre texto de muestra en una etapa. Nada se persiste.
POST /api/guardrail/Developer+Crear un guardrail.
PUT /api/guardrail/Developer+Actualizar un guardrail (escribe una nueva versión de historial).
DELETE /api/guardrail/:idDeveloper+Eliminar un guardrail.

History

Método y rutaRolPropósito
GET /api/guardrail/:id/historyMemberHistorial de versiones (más nueva primero).
GET /api/guardrail/:id/history/diffMemberDiff de dos versiones.
GET /api/guardrail/:id/history/:versionMemberUna sola versión histórica.
POST /api/guardrail/:id/revertDeveloper+Restaurar una versión más antigua como una nueva versión.

Eval y corpora

Método y rutaRolPropósito
POST /api/guardrail/:id/evalMemberEjecutar una eval sobre un corpus (nombre empaquetado o JSONL subido).
GET /api/guardrail/:id/eval/runsMemberLista ejecuciones de eval para un guardrail (paginado).
GET /api/guardrail/eval/runs/:run_idMemberDetalle de una sola ejecución de eval.
GET /api/guardrail/eval/corporaMemberLista corpora del espacio de trabajo + corpora empaquetados.
POST /api/guardrail/eval/corporaDeveloper+Subir un corpus JSONL.
GET /api/guardrail/eval/corpora/:idMemberDetalle de un corpus.
DELETE /api/guardrail/eval/corpora/:idDeveloper+Eliminar un corpus.

Matches

Método y rutaRolPropósito
GET /api/guardrail/matchMemberLista coincidencias (con alcance de espacio de trabajo).
GET /api/guardrail/match/groupedMemberCoincidencias agrupadas (p. ej. por regla o guardrail).
GET /api/guardrail/match/statsMemberEstadísticas de coincidencias (soporta ?days= y ?group_by=).
GET /api/guardrail/match/exportMemberExportar coincidencias como CSV.
GET /api/guardrail/match/:idMemberDetalle de una sola coincidencia.
POST /api/guardrail/match/:id/mark-fpAdminMarcar una coincidencia como falso positivo (rate-limited).
DELETE /api/guardrail/match/:id/mark-fpAdminDesmarcar un falso positivo (rate-limited).

Vincular una clave

Establece guardrail_id en la clave API (vía el editor de claves o la API de tokens). 0/null significa sin vinculación explícita — la clave hace fallback al guardrail por defecto del espacio de trabajo, si hay uno establecido.

13. FAQ

El comportamiento es idéntico byte a byte a un espacio de trabajo que nunca habilitó la función. Si la clave no está vinculada y no hay valor por defecto del espacio de trabajo establecido, el gateway no hace modificaciones. Nada se bloquea, enmascara o registra en el feed de Matches.
No. Un bloqueo en la etapa de entrada se dispara antes de que se mida el uso; un bloqueo en la etapa de salida reembolsa la cuota preconsumida después de que la respuesta es rechazada. En cualquier caso el llamador no paga cuota, obtiene HTTP 400 guardrail_blocked y la solicitud se marca como skip-retry (reejecutar el mismo prompt contra otro canal simplemente volvería a bloquear).
Depende de la acción. Block se aplica en ambos casos: en una respuesta sin streaming la respuesta se examina antes de devolverse, y en una respuesta con streaming un escáner corta el stream en pleno vuelo y emite un mensaje de reemplazo antes de que cualquier contenido bloqueado llegue al cliente. Mask en la salida actualmente solo se aplica a respuestas sin streaming — en una respuesta con streaming el chunk original pasa sin enmascarar (la reescritura del stream en banda es una mejora planificada). Para enmascarar la salida hoy, usa solicitudes sin streaming o apóyate en el enmascarado en la etapa de input. Comprueba tu combinación específica de etapa/stream en el sandbox y con una ejecución de eval antes de confiar en ella.
Mask redacta la coincidencia (p. ej. jane@acme.com[EMAIL]) y deja pasar la solicitud con el texto saneado — el modelo upstream nunca ve el original. Block rechaza toda la solicitud con HTTP 400. Flag no cambia nada del tráfico y solo registra una coincidencia — úsalo para medir una regla antes de aplicarla.
Una regla integrada (keyword / regex / PII / max_chars) no hace ninguna llamada a modelo y no factura nada. Una regla llm_judge o grounding llama a un modelo a través de los canales de tu espacio de trabajo, así que esos tokens se facturan y atribuyen como una sub-línea de juez.
Activa Log raw content para el guardrail. Con él apagado (el valor por defecto), el feed de Matches registra que una regla se disparó y su meta-cadena de detalle pero no la subcadena coincidente — la postura conservadora con la privacidad. El toggle no es retroactivo: solo afecta a las coincidencias registradas después de que lo habilites.
Sí. Abre History en el guardrail, haz diff de las versiones y Revert a la que quieras. Revert copia el contenido de esa versión hacia adelante como una nueva versión — el historial nunca se muta — y el cambio surte efecto en la siguiente solicitud.
Por defecto, las reglas avanzadas fallan abiertas: un timeout o error de transporte se registra como telemetría y la solicitud continúa. Establece fail_open (external) o judge_fail_open (judge) a false para fallar cerradas — tratar el error como un block — para políticas donde una verificación perdida es inaceptable.