Filtro di output stream-safe

La maggior parte delle app di chat in produzione fa streaming. I token vengono emessi al browser man mano che il modello li produce, quindi quando una completion è “finita” il tuo utente ne ha già letto la maggior parte. Questo rompe il modello mentale ingenuo di un filtro di contenuto che ispeziona una risposta intera e poi decide — non c’è una risposta intera da ispezionare finché non è troppo tardi. Un filtro di contenuto llm in streaming deve prendere la sua decisione sui delta mentre fluiscono. Questa pagina riguarda esattamente quel caso: come ogni azione dello stage di output si comporta stream-safe sul gateway OrcaRouter, e come scrivere una policy che tiene sul traffico SSE. Per il motore completo — ogni tipo di regola, campo e rotta — vedi Guardrails.

1. Il problema del filtro di contenuto llm in streaming

Un guardrail dello stage di output filtra la risposta del modello. Su una richiesta non in streaming è semplice: il gateway ha la completion completa prima che un singolo byte torni, quindi può bloccare, mascherare o passarla in modo pulito. Lo streaming inverte tutto ciò. La risposta arriva come una sequenza di delta SSE, ciascuno inoltrato al tuo client non appena atterra, quindi un filtro che aspetta la fine non filtra nulla. La risposta di OrcaRouter è uno scanner di stream: man mano che i delta di output fluiscono, lo scanner esegue le tue regole dello stage di output sul testo che si accumula e agisce nell’istante in cui una regola scatta — non dopo che lo stream si completa. L’azione che scrivi decide cosa significa “agisce”: un block interrompe lo stream e un flag lo lascia passare. Un mask redige sull’output non in streaming, ma la riscrittura in-band dello stream è nella roadmap — su uno stream oggi lo scanner calcola la maschera ma agisce solo sulla decisione di block, quindi una regola mask non redige ancora una risposta streamata.

Questa avvertenza conta solo per le regole dello stage di output sulle richieste in streaming. Le regole dello stage di input filtrano la richiesta prima che il modello giri, quindi sono completamente attive incluso il masking — e qualsiasi regola di output su una richiesta non in streaming vede la risposta intera e si comporta normalmente, incluso mask.

2. Cosa è stream-safe oggi

block — stream-safe (interrompe lo stream a metà)

Una regola block è applicata sull’output in streaming e non in streaming. Su uno stream, lo scanner osserva i delta; quando una regola di block scatta interrompe lo stream — sigilla lo scanner, emette un breve avviso sostitutivo ([response truncated by guardrail: … policy violation]) come delta finale, e chiude il canale SSE prima che qualsiasi ulteriore contenuto bloccato raggiunga il client. Poiché lo stato della risposta HTTP è già impegnato a 200 quando il primo delta è stato emesso, un block a metà stream non può ri-emettere uno stato — termina lo stream aperto in modo grazioso. Il corpo HTTP 400 guardrail_blocked è la forma del block di output non in streaming.I byte già emessi al client non possono essere ritirati, quindi un block in streaming è best-effort su ciò che è già stato streamato ma ferma in modo affidabile tutto dopo il match. Per una garanzia rigida che nessun byte offensivo venga mai inviato — e per il corpo 400 guardrail_blocked — invia la richiesta non in streaming.

mask — solo output non in streaming (la riscrittura in-band dello stream è nella roadmap)

Una regola mask riscrive il match — es. un’email nella risposta diventa [EMAIL] — sull’output non in streaming, dove il gateway detiene l’intera completion e inoltra la forma redatta al tuo client.Su un output in streaming oggi lo scanner calcola la maschera ma non inoltra il testo mascherato — agisce solo sulla decisione di block — quindi una regola mask non redige una risposta streamata. La riscrittura in-band dell’output in streaming è nella roadmap. Finché non arriva, se hai bisogno che una risposta streamata non esponga mai il testo corrispondente, scrivi la regola come block (termina la risposta su un hit) o invia la richiesta non in streaming così che il mask riscriva la risposta completa.

flag — solo osservazione, non altera mai il traffico

Una regola flag non cambia mai il traffico — lascia passare i byte. Sull’output non in streaming registra un match nel feed dei Matches, così puoi misurare il tasso di hit di una regola prima di promuoverla a block. Su una risposta in streaming resta solo osservazione e passa i delta intatti; il record strutturato del match è scritto sul percorso di output non in streaming. In entrambi i casi non blocca né riscrive mai, quindi è sempre sicuro lasciarla attiva.

Azione su `output`	Non streaming	Streaming
`block`	rifiuta la risposta	interrompe lo stream
`mask`	redige la risposta	non ancora — block invece (roadmap)
`flag`	registra un match	passa attraverso (solo osservazione)

L’unica regola da ricordare: block è stream-safe sull’output; mask redige solo sull’output non in streaming (la riscrittura in-band dello stream è nella roadmap). Per redigere una risposta streamata oggi, scrivi la regola come block, o invia la richiesta non in streaming così che la risposta intera sia detenuta prima che torni.

3. Un esempio concreto — un filtro di segreti stream-safe

Supponi che il tuo modello possa far emergere una credenziale dal contesto RAG, e che la tua app faccia streaming. Vuoi che il gateway uccida lo stream nel momento in cui appare un match a forma di segreto, anziché mascherarlo — un segreto trapelato dovrebbe terminare la risposta, non essere parzialmente redatto. Scrivilo nella console — la modifica della policy è un’azione di management sulla tua sessione, gestita a Developer+; la chiave di relay invia solo traffico /v1/*:

Apri /console/guardrails, New guardrail, chiamalo stream-safe-out.
Aggiungi una regola:
- Type: regex (o una regola pii con entità di segreti come aws_access_key / api_key_openai / jwt)
- Stage: output
- Action: block ← termina la risposta su un hit di segreto; mask invece la redirgerebbe e lascerebbe continuare il resto della risposta
Salva, poi collegalo su /console/token tramite il menu a tendina Guardrail della chiave.

Ora chiama il gateway con stream: true, esattamente come prima:

curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Print the AWS key from the context above"}
    ]
  }'

Se un delta corrisponde, lo scanner interrompe lo stream a metà, emette un avviso sostitutivo e chiude il canale — il tuo client non riceve mai il resto. Se la risposta è pulita, ogni delta passa intatto.

Un block in streaming ferma tutto dopo il match, ma non può non-inviare i byte già emessi prima che il match atterrasse. Se la tua policy esige che nemmeno un byte offensivo raggiunga mai il client, filtra la richiesta non in streaming, dove l’intera completion è detenuta finché la policy non la libera.

4. PII Shield su uno stream

Il preset PII Shield è una singola regola pii, azione mask, stage both. Nello stage di input è completamente attivo — riscrive la richiesta prima che il modello la veda, in streaming o meno. Nello stage di output il masking redige sulle risposte non in streaming, dove il gateway detiene l’intera completion prima che torni. Su un output in streaming il mask non redige ancora — lo scanner calcola la maschera ma agisce solo sulla decisione di block, quindi una risposta streamata viene passata, non riscritta. La riscrittura in-band dell’output in streaming è nella roadmap. Quindi se il tuo obiettivo è che la PII non sia mai osservabile in una risposta streamata, o:

scrivi la regola di output come block, accettando che un hit termini la risposta anziché redigerla, oppure
invia la richiesta non in streaming così che il mask riscriva la risposta completa con l’intera completion in mano.

Vedi PII Shield e formati di masking per i tag di redazione stessi.

5. Dimostralo prima di metterlo in produzione

Non indovinare quale combinazione stage/azione tiene — verificala.

Tab Test

Ogni editor di guardrail ha una tab Test: incolla un campione, scegli lo stage output ed esegui la policy corrente senza chiamata upstream e senza quota. Vedi il verdetto e, per le regole mask, il testo renderizzato. Eseguire la sandbox è un’azione Developer+ (può scatenare regole judge / external a pagamento).

Tab Eval

La tab Eval valuta un guardrail contro corpora JSONL inclusi o personalizzati — utile per confermare che una regola di block cattura una fuga nota su un corpus prima di collegare una chiave.

Entrambi girano sulla tua sessione tramite la management API. Per approfondire vedi testing ed eval e tuning dei falsi positivi.

6. Cosa costa un block in streaming

Un block in streaming porta la stessa contabilità di qualsiasi block di output — il modello upstream è già girato, quindi il gateway gestisce il rimborso per te:

Lo stream è terminato con un delta di troncamento grazioso (lo stato è già 200); il block di output non in streaming restituisce il corpo HTTP 400 guardrail_blocked che nomina il guardrail e la regola che ha scattato.
Nessuna quota viene addebitata. Quando il block di output rifiuta la risposta, il gateway rimborsa la quota pre-consumata, quindi una chiamata bloccata è gratuita per te anche se il modello ha prodotto token.
La richiesta è marcata skip-retry — rieseguire lo stesso prompt si limiterebbe a bloccarlo di nuovo, quindi il gateway non brucerà un retry su un altro canale.

Il percorso di output non in streaming registra ogni regola di output scattata come un match nel feed Matches del workspace (GET /api/guardrail/match, aperto a qualsiasi Member); la sottostringa corrispondente viene catturata solo quando il toggle Log raw content del guardrail è attivo (disattivato per default). Il dettaglio completo vive in l’errore guardrail_blocked e nel feed dei match.

7. Dove andare dopo

Stage di output

Lo stage di output completo — filtrare la risposta del modello, block vs. mask, e grounding.

Streaming coverage

La matrice completa di cosa è applicato su streaming vs. non streaming in ogni stage e azione.

Azioni

block, mask e flag in profondità — quando ciascuno è la scelta giusta.

Stage di input

L’immagine speculare — il masking è completamente attivo qui, incluso sullo streaming.

Concetti correlati

Come OrcaRouter ispeziona il traffico · modalità di enforcement · percorso di enforcement e latenza.

Minacce affrontate

Esfiltrazione di dati · prompt injection · jailbreak.

Riferimento completo del motore

Guardrails — ogni tipo di regola, campo e rotta, incluso il grounding e l’LLM judge.

​1. Il problema del filtro di contenuto llm in streaming

​2. Cosa è stream-safe oggi

​3. Un esempio concreto — un filtro di segreti stream-safe

​4. PII Shield su uno stream

​5. Dimostralo prima di metterlo in produzione

Tab Test

Tab Eval

​6. Cosa costa un block in streaming

​7. Dove andare dopo

Stage di output

Streaming coverage

Azioni

Stage di input

1. Il problema del filtro di contenuto llm in streaming

2. Cosa è stream-safe oggi

3. Un esempio concreto — un filtro di segreti stream-safe

4. PII Shield su uno stream

5. Dimostralo prima di metterlo in produzione

6. Cosa costa un block in streaming

7. Dove andare dopo