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
Crear un guardrail
/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
Pruébalo en el sandbox
input y ejecuta. El sandbox muestra
el veredicto y el texto renderizado — email me at [EMAIL] — sin
enviar nada upstream.Vincular una clave
/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.Enviar una solicitud
[EMAIL] antes de reenviar. El
modelo upstream nunca ve la dirección.3. Conceptos: guardrails, reglas, etapas, acciones
| Concepto | Definición |
|---|---|
| Guardrail | Una política nombrada, con alcance de espacio de trabajo. Identificador: name (≤ 64 caracteres). Tiene enabled, is_default y un blob JSON de rules. |
| Regla | Una 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. |
| Etapa | input (la solicitud), output (la respuesta del modelo) o both. |
| Acción | block (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:- Vinculación de clave — si la clave tiene un
guardrail_idexplícito, ese guardrail aplica (cuando existe y está habilitado). Una vinculación explícita nunca hace fallback silencioso; deshabilitarla es el interruptor de apagado. - Valor por defecto del espacio de trabajo — si la clave no tiene
vinculación, aplica el guardrail habilitado
is_defaultdel espacio de trabajo. - Ninguno — sin aplicación. La solicitud es idéntica byte a byte a un espacio de trabajo que nunca habilitó la función.
Cómo se ve un block
Una solicitud bloqueada devuelve HTTP 400 con el código de errorguardrail_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).| Tipo | Grupo | Qué hace |
|---|---|---|
Keyword denylist (keyword) | Integrada | Coincide 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) | Integrada | Coincide con un patrón RE2 (tiempo lineal, sin backreferences). |
PII detection (pii) | Integrada | Detecta tipos de entidad integrados (y los tuyos personalizados). Ver §5. |
Maximum length (max_chars) | Integrada | Limita el conteo de caracteres del texto en una etapa. |
External vendor (external) | Avanzada | Delega la verificación a un proveedor conectado (Aporia, Averta, BYO-webhook, …). Ver §9. |
LLM judge (llm_judge) | Avanzada | Ejecuta una verificación semántica contra un modelo de tu espacio de trabajo. Ver §6. |
Contextual grounding (grounding) | Avanzada | Puntúa la fidelidad de la respuesta contra las fuentes recuperadas en la solicitud (RAG). Ver §7. |
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 reglapii 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;luhnvalida la coincidencia con el algoritmo de Luhn (p. ej. para números tipo tarjeta).mask_with— reemplazo literal opcional; por defecto[<UPPERCASE_NAME>].
Sobrescrituras de acción por entidad
Una sola regla PII puede aplicar diferentes acciones a diferentes entidades víaentity_actions. Una regla que enmascara emails / teléfonos / IPs por
defecto pero bloquea en credit_card o ssn — en vez de tres reglas
solapadas:
block / mask / flag. El validador rechaza cualquier otra cosa.
6. LLM judge
Una reglallm_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.
| Campo | Significado |
|---|---|
judge_model | El 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_rubric | El mensaje de sistema que describe qué marcar. |
judge_format | Uno de yes_no, score o category (obligatorio; la consola preselecciona yes_no). |
judge_threshold | Para score: bloquear/marcar cuando la puntuación está en o por encima de este valor. |
judge_categories | Para category: la lista denegada. |
judge_timeout_ms | Acota la llamada al juez. 0 → valor por defecto del motor. |
judge_fail_open | true (por defecto) → un error del juez se observa pero la solicitud continúa; false → tratar error/timeout como un block. |
7. Contextual grounding
Una reglagrounding 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.
| Campo | Por defecto | Significado |
|---|---|---|
grounding_model | elección del espacio de trabajo | El modelo al que el runner resuelve la verificación de fidelidad. |
grounding_rubric | integrada | Sobrescribe la rúbrica de fidelidad por defecto. |
grounding_threshold | 0.7 | Piso de fidelidad, 0.0–1.0. Por debajo, la acción se dispara. |
grounding_strict | false | Cuando es true, “no sources provided” se trata como un block (vs el allow por defecto). |
grounding_max_bytes | 100000 | Limita el contexto de fuentes concatenado entregado al juez. |
grounding_timeout_ms | 3000 | Acota 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.
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 reglaexternal 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
| Proveedor | Qué 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. |
Campos de la regla
| Campo | Significado |
|---|---|
connection_id | La 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_ms | Acota la única llamada al proveedor. 0 → por defecto. |
fail_open | true (por defecto) → un error del proveedor se observa pero la solicitud continúa; false → tratar error de transporte / timeout / proveedor desconocido como un block. |
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.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? |
|---|---|
| Modelos | Los guardrails son agnósticos del modelo. La misma política viaja sobre GPT-5, Claude, Gemini — filtra texto, no la elección de modelo. |
| Enrutamiento | Independiente. 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. |
| Prompts | Independientes 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 API | Una 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 Matches | Cada 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 cabeceraX-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 ruta | Rol | Propósito |
|---|---|---|
GET /api/guardrail/ | Member | Lista guardrails (con conteos de claves vinculadas). |
GET /api/guardrail/meta | Member | Vocabulario del motor — tipos de regla, etapas, acciones, entidades PII, presets, categorías de preset. |
GET /api/guardrail/my-permissions | Member | Los permisos de guardrail del llamador (para gobernar la UI). |
GET /api/guardrail/:id | Member | Detalle de un solo guardrail. |
GET /api/guardrail/:id/tokens | Member | Claves API vinculadas a este guardrail (limitadas, con el total verdadero). |
POST /api/guardrail/test | Member | Sandbox — 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/:id | Developer+ | Eliminar un guardrail. |
History
| Método y ruta | Rol | Propósito |
|---|---|---|
GET /api/guardrail/:id/history | Member | Historial de versiones (más nueva primero). |
GET /api/guardrail/:id/history/diff | Member | Diff de dos versiones. |
GET /api/guardrail/:id/history/:version | Member | Una sola versión histórica. |
POST /api/guardrail/:id/revert | Developer+ | Restaurar una versión más antigua como una nueva versión. |
Eval y corpora
| Método y ruta | Rol | Propósito |
|---|---|---|
POST /api/guardrail/:id/eval | Member | Ejecutar una eval sobre un corpus (nombre empaquetado o JSONL subido). |
GET /api/guardrail/:id/eval/runs | Member | Lista ejecuciones de eval para un guardrail (paginado). |
GET /api/guardrail/eval/runs/:run_id | Member | Detalle de una sola ejecución de eval. |
GET /api/guardrail/eval/corpora | Member | Lista corpora del espacio de trabajo + corpora empaquetados. |
POST /api/guardrail/eval/corpora | Developer+ | Subir un corpus JSONL. |
GET /api/guardrail/eval/corpora/:id | Member | Detalle de un corpus. |
DELETE /api/guardrail/eval/corpora/:id | Developer+ | Eliminar un corpus. |
Matches
| Método y ruta | Rol | Propósito |
|---|---|---|
GET /api/guardrail/match | Member | Lista coincidencias (con alcance de espacio de trabajo). |
GET /api/guardrail/match/grouped | Member | Coincidencias agrupadas (p. ej. por regla o guardrail). |
GET /api/guardrail/match/stats | Member | Estadísticas de coincidencias (soporta ?days= y ?group_by=). |
GET /api/guardrail/match/export | Member | Exportar coincidencias como CSV. |
GET /api/guardrail/match/:id | Member | Detalle de una sola coincidencia. |
POST /api/guardrail/match/:id/mark-fp | Admin | Marcar una coincidencia como falso positivo (rate-limited). |
DELETE /api/guardrail/match/:id/mark-fp | Admin | Desmarcar un falso positivo (rate-limited). |
Vincular una clave
Estableceguardrail_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
¿Qué pasa si no se resuelve ningún guardrail en una solicitud?
¿Qué pasa si no se resuelve ningún guardrail en una solicitud?
¿Cuesta cuota una solicitud bloqueada?
¿Cuesta cuota una solicitud bloqueada?
guardrail_blocked y la solicitud se marca
como skip-retry (reejecutar el mismo prompt contra otro canal simplemente
volvería a bloquear).¿Se aplican las reglas de salida (respuesta) en streaming?
¿Se aplican las reglas de salida (respuesta) en streaming?
¿Cuál es la diferencia entre mask y block?
¿Cuál es la diferencia entre mask y block?
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.¿Se facturan los tokens de prompt inyectados y los tokens de juez?
¿Se facturan los tokens de prompt inyectados y los tokens de juez?
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.¿Cómo veo lo que una regla realmente coincidió?
¿Cómo veo lo que una regla realmente coincidió?
¿Puedo revertir un cambio de guardrail?
¿Puedo revertir un cambio de guardrail?
¿Qué pasa si un proveedor externo o un juez agotan el tiempo?
¿Qué pasa si un proveedor externo o un juez agotan el tiempo?
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.