1. Qué registra el log de coincidencias de guardrail
Cada regla disparada escribe una coincidencia en un feed con alcance de espacio de trabajo (GET /api/guardrail/match, abierto a cualquier Member). El feed
está separado de tu log de solicitud — almacena solo lo que hizo un guardrail, no
el cuerpo completo de la solicitud. Cada coincidencia registra:
El veredicto
El veredicto
rule_type (keyword, regex, pii, max_chars, external,
llm_judge, grounding), la action efectiva (block / mask /
flag / annotate / spotlight) y la stage (input o output) — así
puedes saber al instante qué se disparó y qué hizo.Dónde se disparó
Dónde se disparó
guardrail_name, el rule_label que se disparó, más el contexto de la
solicitud: model_name, el token con el que viajó, la ip del llamador, y
el request_id que une de vuelta a tu log de solicitud.Una cadena de detalle
Una cadena de detalle
detail — la nota corta legible por humanos del motor para la violación
(p. ej. qué entidad o patrón se activó), siempre registrada.La subcadena coincidente — solo cuando optas por ello
La subcadena coincidente — solo cuando optas por ello
matched se rellena solo cuando el toggle Log raw content del
guardrail está activado. Está apagado por defecto, así que por defecto el
feed te dice que una regla se disparó y por qué, pero nunca almacena la
propia cadena sensible.2. Lista y filtra el log de coincidencias
La vista de lista por defecto está paginada por cursor, la más nueva primero, y con alcance de tu espacio de trabajo. Acótala con query params — la consola los expone como chips de filtro:| Param | Filtra por |
|---|---|
guardrail_id, rule_type, action, stage | El veredicto |
token_id, model_name, request_id | El contexto de la solicitud |
days / start_at + end_at, hide_fp | Ventana y estado de falso positivo |
Las rutas de gestión como
/api/guardrail/* se autentican con tu token de
sesión / acceso de consola, no una clave de relay. Las claves sk-orca-... son
solo para llamadas a modelo /v1/*. En el uso diario leerás el feed directamente
desde la pestaña Matches en la página de Guardrails.3. Agrupar por solicitud
Una sola solicitud puede activar varias reglas a la vez — un mask de PII de entrada y un tope de longitud máxima, digamos. La vista agrupada (GET /api/guardrail/match/grouped, Member) colapsa coincidencias por
request_id para que veas una fila por solicitud ofensiva con sus coincidencias
plegadas en línea, en vez de desplazarte pasando cinco filas para la misma
llamada. Ajusta cuántas coincidencias se muestran en línea por grupo con
inline_limit (por defecto 5).
4. Estadísticas y la franja de tendencia
El endpoint de estadísticas (GET /api/guardrail/match/stats, Member) impulsa la
franja de conteo y el gráfico en la pestaña Matches — totales sobre una ventana
days, opcionalmente desglosados con group_by:
group_by | Desglose |
|---|---|
| (omitido) | Solo totales |
rule_type | Qué tipos de regla se disparan más |
guardrail_id | Qué guardrail explica la actividad |
request_id para obtener un conteo de coincidencias de tiempo constante
para una solicitud (usado por el enlace cruzado del log de solicitud). Aquí es
donde viven el uso por guardrail, la mezcla de acciones y la tasa de falsos
positivos — segméntalo en vez de paginar la lista en bruto.
5. Exportar para un rastro de auditoría
Cuando necesites coincidencias fuera de la consola — un paquete de evidencia, una hoja de cálculo, un SIEM downstream —GET /api/guardrail/match/export (Member)
transmite tu conjunto de filtros actual como CSV o JSON:
6. Triagar falsos positivos
No toda coincidencia es un acierto real. Cuando una regla se dispara sobre tráfico benigno, un Admin del espacio de trabajo puede marcar la coincidencia como falso positivo (POST /api/guardrail/match/:id/mark-fp); el inverso
DELETE /api/guardrail/match/:id/mark-fp la des-marca. Marcar es solo Admin
aunque el resto del feed sea legible por Member — el triaje es una acción
privilegiada.
Marcar un falso positivo hace dos cosas: etiqueta la coincidencia (para que
hide_fp=true la filtre fuera del feed) y recuerda el hallazgo para que la misma
regla sobre el mismo contenido se salte en solicitudes futuras. Des-marca para
restaurar la aplicación. Para el flujo más amplio de afinar una regla ruidosa,
ver Afinar falsos positivos.
Una coincidencia es datos diagnósticos, no una decisión de aplicación. Si una
solicitud fue bloqueada, enmascarada o solo marcada ya lo decide la
acción en el momento de la solicitud — el feed
es el registro después del hecho. Marcar un falso positivo cambia el
comportamiento futuro, nunca la llamada que ya ocurrió.
7. De dónde vienen las coincidencias
Las coincidencias las produce el motor de guardrails en la ruta de relay, así que el feed refleja exactamente lo que hicieron tus políticas vinculadas:- Las coincidencias de la etapa de entrada registran lo que el gateway examinó antes de que el modelo lo viera — ver Etapa de entrada.
- Las coincidencias de la etapa de salida registran lo que examinó en la respuesta — ver Etapa de salida.
- Una solicitud bloqueada también aparece como un
HTTP 400
guardrail_blockedpara el llamador; la coincidencia es el registro del lado del servidor de ello.
8. Relacionado
Referencia de Guardrails
El motor completo: tipos de regla, etapas, acciones, presets, arnés de eval.
Registro y privacidad
El toggle Log raw content y qué almacena — y qué no — el feed.
Afinar falsos positivos
Usa el feed para encontrar y silenciar reglas ruidosas sin debilitar la
política.
Versionado
Haz diff y revierte un guardrail cuando el feed muestra que un cambio falló.