1. ガードレールエンジンとは
ガードレールはワークスペーススコープの名前付きコンテンツポリシーです — ゲートウェイがリクエスト入力とモデル出力に対して実行する、順序付けられた ルールのリストです。ガードレールを一度保存し、任意の API キーをそれにアタッチ するか(あるいはワークスペースデフォルトに設定し)、ゲートウェイはアップストリーム モデルの前後ですべての呼び出しをスクリーニングします。 各ルールはひとつのことを決定します — 何を探すか(ルールの種類)、どこを 探すか(ステージ:リクエスト入力かモデル出力か)、そしてそれにどう対処するか (アクション:block、mask、flag)。エンジンは適用可能なすべてのルールを実行し、 結果をひとつの判定にまとめます。 ガードレールを編集すると、それにアタッチされたすべてのキーが次の呼び出しで 反映されます。再デプロイ不要。コード変更不要。SDK アップグレード不要。ポリシーは アプリケーションではなくゲートウェイに存在します — アプリは以前と全く同様に/v1/chat/completions を呼び出し続けます。
エンジンは組み込みルールの種類について決定的で依存関係がありません:
純粋な文字列および正規表現マッチングで、ネットワーク呼び出しを伴わず、
ホットなリレーパス上で実行しても安全です。高度なルール(外部ベンダー、
LLM judge、コンテキスト整合性)は外部を呼び出し、並行してディスパッチされる
ため、遅いチェックが別のチェックの背後で直列化することはありません。
ガードレールはワークスペーススコープです — すべてのメンバーがそのワークスペースの
ガードレールを参照でき、テナント境界を越えることはありません。
2. クイックスタート — 5 ステップで最初のリクエストをスクリーニング
ガードレールを作成する
コンソールで
/console/guardrails に移動し、New
guardrail をクリックします。名前を pii-shield にします。ルールを 1 つ
追加します:- Type: PII detection
- Stage: Input (request)
- Action: Mask — マッチをリダクト
- Entities:
email、phone、ssn
サンドボックスでテストする
エディタ内の Test タブを開き、*「email me at
jane@acme.com」*を貼り付け、
input ステージを選んで実行します。サンドボックスは
判定とレンダリングされたテキスト — email me at [EMAIL] — を、アップストリームに
何も送信することなく表示します。キーをアタッチする
/console/token に移動し、API キーを作成または編集し、Guardrail
ドロップダウンから pii-shield を選びます。バインディングはゲートウェイの
キー上に存在します。リクエストを送信する
そのキーを使って、以前と全く同様に OrcaRouter を呼び出します:ゲートウェイは転送前にメールアドレスを
[EMAIL] にマスクします。アップストリーム
モデルがアドレスを目にすることはありません。3. 概念:ガードレール、ルール、ステージ、アクション
| 概念 | 定義 |
|---|---|
| ガードレール | 名前付きの、ワークスペーススコープのポリシー。識別子:name(≤ 64 文字)。enabled、is_default、rules JSON ブロブを持ちます。 |
| ルール | ポリシー内のひとつのチェック:type、stage、action、加えて種類固有のフィールド。ルールは順番に実行されます。 |
| ステージ | input(リクエスト)、output(モデルのレスポンス)、または both。 |
| アクション | block(呼び出しを拒否)、mask(マッチをリダクト)、または flag(ログのみ — トラフィックを変えずに観察)。 |
スコープとワークスペースデフォルト
ガードレールは API キーと全く同様にスコープされます:アクティブなワークスペースが ある場合はワークスペース共有、それ以外の場合はユーザーごとです。任意の リクエストの解決:- キーアタッチメント — キーに明示的な
guardrail_idがある場合、その ガードレールが適用されます(存在し有効である場合)。明示的なアタッチメントが サイレントにフォールバックすることは決してありません。無効化することが オフスイッチです。 - ワークスペースデフォルト — キーにアタッチメントがない場合、ワークスペースの
有効な
is_defaultガードレールが適用されます。 - どちらもなし — 強制なし。リクエストはこの機能を一度も有効化していない ワークスペースとバイト単位で同一です。
設計上のフェイルオープン。 ガードレール解決が一時的なエラー(例:DB の
不調)に遭遇した場合、ゲートウェイはトラフィックを止めるのではなく強制なしに
劣化します。安全性は劣化しますが、可用性は維持されます。
block がどう見えるか
ブロックされたリクエストは、エラーコードguardrail_blocked と、発火した
ガードレールおよびルールを示すメッセージとともに HTTP 400 を返します。
ブロックされたリクエストはクォータを消費しません — input ステージの
ブロックはメータリングの前に発火し、output ステージのブロックは事前消費された
クォータを返金します — そして skip-retry とマークされます(同じプロンプトを
再実行してもまた block されるだけです)。
4. ルールの種類
ルールは 2 つのグループに分かれます:組み込み(決定的、ネットワークなし)と 高度(モデルまたはベンダーを呼び出す)。| 種類 | グループ | 何をするか |
|---|---|---|
Keyword denylist(keyword) | 組み込み | リテラル用語のリストのいずれかにマッチします。大文字小文字を区別せず、部分文字列でマッチします(そのため class は classic にもマッチします)。 |
Regular expression(regex) | 組み込み | RE2 パターンにマッチします(線形時間、後方参照なし)。 |
PII detection(pii) | 組み込み | 組み込みエンティティ種別(およびカスタムのもの)を検出します。§5 を参照。 |
Maximum length(max_chars) | 組み込み | あるステージでのテキストの文字数を制限します。 |
External vendor(external) | 高度 | チェックを接続済みベンダー(Aporia、Averta、独自 webhook、…)に委譲します。§9 を参照。 |
LLM judge(llm_judge) | 高度 | ワークスペース内のモデルに対してセマンティックチェックを実行します。§6 を参照。 |
Contextual grounding(grounding) | 高度 | リクエストで取得されたソース(RAG)に対する回答の忠実性をスコアリングします。§7 を参照。 |
external、llm_judge、grounding)は並行してディスパッチされるため、
ひとつの遅いチェックが別のチェックの背後で直列化することはありません。
5. PII 検出の詳細
pii ルールは機密エンティティを検出し、各マッチにルールのアクションを
適用します。組み込み検出器セットはクローズドで、エンジン、バリデータ、
ルールビルダーで共有されます:
email、phone、credit_card、ssn、ip、iban、mac_address、
api_key_openai、aws_access_key、jwt、bitcoin_address。
mask アクションでは、各マッチが型付きタグで置換されます — email は
[EMAIL] に、SSN は [SSN] に、といった具合です。
カスタムエンティティ
組み込みセットの上に独自の検出器を重ねます。カスタムエンティティは以下です:name— 小文字 ASCII / 数字 / アンダースコア、文字で始まる必要があります (例:employee_id)。引用符なしで監査ログとテレメトリに流れます。pattern— Go RE2 正規表現(線形時間、後方参照なし)。checksum— オプション;luhnは Luhn アルゴリズムでマッチを検証します (例:カード状の番号向け)。mask_with— オプションの逐語置換;デフォルトは[<UPPERCASE_NAME>]。
エンティティごとのアクションオーバーライド
単一の PII ルールはentity_actions を介して、異なるエンティティに異なる
アクションを適用できます。email / phone / IP をデフォルトでマスクしつつ、
credit_card や ssn ではブロックするひとつのルール — 重なり合う 3 つの
ルールの代わりに:
block /
mask / flag でなければなりません。バリデータはそれ以外のものを拒否します。
6. LLM judge
llm_judge ルールは、ワークスペースがすでに呼び出せるモデルに対して
セマンティックチェックを実行します。正規表現が捉えられない曖昧なポリシー —
有害性、ハラスメント、トピック外れ、プロンプトインジェクションの意図 — に
使います。
| フィールド | 意味 |
|---|---|
judge_model | 評価に使うモデルまたはルーターエイリアス(例:gpt-4o-mini、orcarouter/cheap)。ワークスペースのチャネルに対して解決されます。 |
judge_rubric | 何をフラグするかを記述するシステムプロンプト。 |
judge_format | yes_no、score、category のいずれか(必須。コンソールはデフォルトで yes_no を選択します)。 |
judge_threshold | score 用:スコアがこの値以上のとき block/flag します。 |
judge_categories | category 用:拒否リスト。 |
judge_timeout_ms | judge 呼び出しを制限します。0 → エンジンデフォルト。 |
judge_fail_open | true(デフォルト) → judge エラーは観察されるがリクエストは継続。false → エラー/タイムアウトを block として扱う。 |
7. コンテキスト整合性
grounding ルールは、アシスタントの回答をリクエストで取得されたソース
(RAG コンテキスト)に対して測定し、それらに忠実でない回答をフラグまたは
ブロックします。judge の継ぎ目を再利用します — 同じワークスペースチャネル、
同じコスト帰属です。
| フィールド | デフォルト | 意味 |
|---|---|---|
grounding_model | ワークスペース選択 | ランナーが忠実性チェックを解決するモデル。 |
grounding_rubric | 組み込み | デフォルトの忠実性ルーブリックをオーバーライドします。 |
grounding_threshold | 0.7 | 忠実性の下限、0.0–1.0。これを下回ると、アクションが発火します。 |
grounding_strict | false | true のとき、「ソースが提供されていない」を block として扱います(デフォルトの allow に対して)。 |
grounding_max_bytes | 100000 | judge に渡される連結ソースコンテキストを制限します。 |
grounding_timeout_ms | 3000 | judge 呼び出しを制限します。 |
8. テンプレート、サンドボックス、eval ハーネス
テンプレートライブラリ
New guardrail スプリットボタンはテンプレートに直接開き、完全なライブラリは ワンクリックで到達できます。プリセットはサーバーサイドで作成されているため、 コンソール、サンドボックス、そしてこのドキュメントは全く同じ挙動を記述します。 カテゴリには以下が含まれます:- PII(
pii) — PII Shield、PII Blocker(strict)、Contact-Info Redactor、 レスポンス PII redactor。 - Secrets(
secrets) — AWS / OpenAI / GitHub クレデンシャルブロッカー、 秘密鍵とクラウドトークン、暗号通貨ウォレット、出力内のシークレット。 - Compliance(
compliance) — GDPR(EU PII)、PCI(フルカードブロック)、 HIPAA(PHI)、金融データ、コンプライアンスロガー、法的免責事項の強制。 - Brand(
brand) — 冒涜的表現(block / mask / 多言語)、競合他社への言及、 児童安全キーワード。 - Safety(
safety) — プロンプトインジェクション、jailbreak、 システムプロンプト漏洩、自傷。 - Cost(
cost) — プロンプト/レスポンスのサイズ上限とトークン上限。 - Agent(
agent) — URL フィルター、markdown 画像、シェルツール呼び出し、 出力内 SQL インジェクションのフィルター。
テストサンドボックス
すべてのエディタには Test タブがあります。サンプルを貼り付け、ステージを 選び、現在のポリシーをローカルで実行します — アップストリーム呼び出しなし、 クォータなし。サンドボックスは判定と(mask ルールの場合は)レンダリングされた テキストを返すため、キーをアタッチする前に、ルールが期待どおりに動作することを 証明できます。Eval / レッドチームハーネス
Eval タブは、入力のコーパスに対してガードレールを実行し、どうスコアリング されたかを報告します — judge ルーブリックのチューニングや、出荷前にポリシーが 既知の攻撃を捕捉することの証明に役立ちます。- バンドルされたコーパスはゲートウェイに同梱されます — 敵対的および レッドチームセット(有害行動プロンプト、ツールインジェクション、多言語 レッドチーミング)に加え、誤検知を測定するための良性セット。
- カスタムコーパス — 独自の JSONL をアップロードして、実際のトラフィック 形状に対してテストします。
- Runs はスコアとともに一覧表示されます。実行を開くと、サンプルごとに 失敗を検査できます。
9. 外部ベンダー
external ルールは、チェックを接続済みベンダーに委譲します。Integrations
(Guardrails ページのヘッダー CTA)でベンダーを一度接続し、その後ルールから
接続を参照します。
対応ベンダー
| ベンダー | 概要 |
|---|---|
Aporia Guardrails(aporia) | プロンプトとレスポンス向けの SLM アンサンブル型ポリシーエンジン。 |
Averta(averta) | 汎用 SLM 分類エンドポイント(テキストを POST → safe / unsafe + 任意の書き換え)。 |
BYO Webhook(webhook) | 独自の URL — プロンプトを受け取り、allow / block / mask / flag の判定を返します。 |
- HMAC シークレットを使用します。
ルールフィールド
| フィールド | 意味 |
|---|---|
connection_id | 使用する接続済み統合(推奨パス — ベンダー + シークレットは実行時にワークスペースの統合から解決されます)。 |
timeout_ms | 単一のベンダー呼び出しを制限します。0 → デフォルト。 |
fail_open | true(デフォルト) → ベンダーエラーは観察されるがリクエストは継続。false → 転送エラー / タイムアウト / 不明なプロバイダを block として扱う。 |
10. 可観測性
ガードレールは、対処可能なパンくずを残します。マッチフィード
発火したすべてのルールはマッチを記録します — ルールの種類、アクション、 詳細文字列、ステージ、そして(有効な場合)マッチした部分文字列。Guardrails ページの Matches タブはワークスペース全体のフィードです:一覧、グループ化、 フィルター、単一マッチへのドリルダウン、CSV へのエクスポート、誤検知の マーク。生コンテンツのキャプチャはオプトインです。 ガードレールの Log raw content
トグルはデフォルトでオフです — プライバシー保守的な姿勢です。オフの場合、
Matches フィードはルールが発火したことと詳細メタ文字列を記録しますが、
実際にマッチした部分文字列(例:メールアドレスそのもの)は記録しません。
トリアージのために部分文字列が必要なときは、ガードレールごとにオンにします。
設定は非遡及的です。
統計
Matches フィードはガードレールごとの統計を支えます — 各ガードレールカードは 7 日間のマッチスパークラインとカウントを表示し、Matches タブはワークスペース 合計を持ちます。ポリシーごとにアクティビティをスライスするには、Matches フィードのグループ化ビューとフィルター(ガードレール、ルールの種類、アクション別) を使います — そこにガードレールごとの使用量、アクションの構成、誤検知率が 存在します。バージョン履歴と監査
すべての作成、更新、削除は、変更と同じトランザクション内でバージョン付きの 履歴行を書き込みます。ガードレール行の History を開くと:- 誰がいつ変更したかとともに、すべてのバージョンを確認できます。
- 任意の 2 つのバージョンを Diff できます。
- 古いバージョンに Revert できます(新しいバージョンとして記録 — 履歴は 決して変更されません)。
11. ゲートウェイの他部分との関係
| 面 | ガードレールとどう組み合わさるか? |
|---|---|
| Models | ガードレールはモデル非依存です。同じポリシーが GPT-5、Claude、Gemini 上で動作します — テキストをスクリーニングするのであり、モデル選択ではありません。 |
| Routing | 独立しています。ルーティングはどのモデル/チャネルがリクエストを処理するかを決めますが、ガードレールはそれに関わらず同じリクエスト/レスポンスのテキストをスクリーニングし、モデル選択を上書きすることはありません。入力スクリーニングはアップストリーム呼び出しの前に、出力スクリーニングはモデルが応答した後に走ります。judge とグラウンディングのルールは、リクエストのルーティングとは別に、ワークスペースのチャネルを通じて自身のモデルを解決します。 |
| Prompts | 独立かつ補完的です。プロンプトはシステムメッセージを注入し、ガードレールはコンテンツを検査しゲートします。両方を 1 つのリクエストに適用でき、ガードレールは常に走ります。順序が重要です。入力ルールはレジストリプロンプトが注入される前に呼び出し元のリクエストをスクリーニングするため(注入は後段のルーティングステージで起こります)、入力ルールは注入されたシステムプロンプトではなく呼び出し元のメッセージを見ます。出力ルールはいずれの場合もモデルのレスポンスをスクリーニングします。 |
| API Keys | キーは guardrail_id を介してガードレールにアタッチされます。バインディングはゲートウェイのキー上にあるため、ガードレールの編集はアタッチされた全キーを一度にシフトします。アタッチメントがなければワークスペースデフォルトにフォールバックします。 |
| Matches フィード | 発火したすべてのルールは、ワークスペースの Matches フィードに着地します(リクエストログとは別の独自ストアです)。ガードレール、ルールの種類、アクション別にグループ化・フィルターして、ガードレールごとの使用量、アクションの構成、誤検知率を確認できます。 |
12. API リファレンス
すべてのルートはX-Workspace-Id ヘッダーでワークスペーススコープです。RBAC は
一貫して強制されます:読み取りとテストサンドボックスはすべてのメンバーに開放、
書き込みは Developer+(および guardrails:write 権限)が必要、本番トラフィックの
変更(削除、revert、ベンダー設定)はそれに応じてゲートされます。
ガードレール
| メソッドとパス | ロール | 目的 |
|---|---|---|
GET /api/guardrail/ | Member | ガードレール一覧(アタッチ済みキー数つき)。 |
GET /api/guardrail/meta | Member | エンジンの語彙 — ルールの種類、ステージ、アクション、PII エンティティ、プリセット、プリセットカテゴリ。 |
GET /api/guardrail/my-permissions | Member | 呼び出し側のガードレール権限(UI ゲーティング用)。 |
GET /api/guardrail/:id | Member | 単一ガードレール詳細。 |
GET /api/guardrail/:id/tokens | Member | このガードレールにアタッチされた API キー(上限つき、実数合計を含む)。 |
POST /api/guardrail/test | Member | サンドボックス — あるステージでサンプルテキストに対してポリシーを評価。何も永続化されません。 |
POST /api/guardrail/ | Developer+ | ガードレールを作成。 |
PUT /api/guardrail/ | Developer+ | ガードレールを更新(新しい履歴バージョンを書き込み)。 |
DELETE /api/guardrail/:id | Developer+ | ガードレールを削除。 |
履歴
| メソッドとパス | ロール | 目的 |
|---|---|---|
GET /api/guardrail/:id/history | Member | バージョン履歴(新しい順)。 |
GET /api/guardrail/:id/history/diff | Member | 2 つのバージョンを diff。 |
GET /api/guardrail/:id/history/:version | Member | 単一の履歴バージョン。 |
POST /api/guardrail/:id/revert | Developer+ | 古いバージョンを新バージョンとして復元。 |
Eval とコーパス
| メソッドとパス | ロール | 目的 |
|---|---|---|
POST /api/guardrail/:id/eval | Member | コーパス(バンドル名またはアップロードした JSONL)に対して eval を実行。 |
GET /api/guardrail/:id/eval/runs | Member | ガードレールの eval 実行を一覧(ページング)。 |
GET /api/guardrail/eval/runs/:run_id | Member | 単一の eval 実行詳細。 |
GET /api/guardrail/eval/corpora | Member | ワークスペースコーパス + バンドルコーパスを一覧。 |
POST /api/guardrail/eval/corpora | Developer+ | JSONL コーパスをアップロード。 |
GET /api/guardrail/eval/corpora/:id | Member | コーパス詳細。 |
DELETE /api/guardrail/eval/corpora/:id | Developer+ | コーパスを削除。 |
マッチ
| メソッドとパス | ロール | 目的 |
|---|---|---|
GET /api/guardrail/match | Member | マッチ一覧(ワークスペーススコープ)。 |
GET /api/guardrail/match/grouped | Member | グループ化されたマッチ(例:ルールまたはガードレールごと)。 |
GET /api/guardrail/match/stats | Member | マッチ統計(?days= と ?group_by= をサポート)。 |
GET /api/guardrail/match/export | Member | マッチを CSV としてエクスポート。 |
GET /api/guardrail/match/:id | Member | 単一マッチ詳細。 |
POST /api/guardrail/match/:id/mark-fp | Admin | マッチを誤検知としてマーク(レート制限あり)。 |
DELETE /api/guardrail/match/:id/mark-fp | Admin | 誤検知のマークを解除(レート制限あり)。 |
キーのアタッチ
API キーにguardrail_id を設定します(キーエディタまたはトークン API 経由)。
0/null は明示的なアタッチメントなしを意味します — キーは、設定されていれば
ワークスペースデフォルトガードレールにフォールバックします。
13. FAQ
リクエストでガードレールが解決されなかった場合は?
リクエストでガードレールが解決されなかった場合は?
挙動は機能を一度も有効化していないワークスペースとバイト単位で同一です。
キーがアタッチされておらず、ワークスペースデフォルトも設定されていない場合、
ゲートウェイは一切の修正を行いません。何もブロック、マスク、Matches
フィードへのログ記録は行われません。
ブロックされたリクエストはクォータを消費しますか?
ブロックされたリクエストはクォータを消費しますか?
いいえ。
input ステージのブロックは使用量がメータリングされる前に発火し、
output ステージのブロックはレスポンスが拒否された後に事前消費された
クォータを返金します。いずれの場合も呼び出し側はクォータを支払わず、HTTP 400
guardrail_blocked を受け取り、リクエストは skip-retry とマークされます
(同じプロンプトを別のチャネルに対して再実行してもまたブロックされるだけです)。出力(レスポンス)ルールはストリーミングで強制されますか?
出力(レスポンス)ルールはストリーミングで強制されますか?
アクションによって異なります。Block は両方で強制されます。非ストリーミング
レスポンスでは返却前に回答がスクリーニングされ、ストリーミングレスポンスでは
スキャナがストリームを途中で打ち切り、ブロック対象のコンテンツがクライアントに
届く前に置換メッセージを送出します。出力に対する Mask は現在、非ストリーミング
レスポンスにのみ適用されます — ストリーミングレスポンスでは元のチャンクが
マスクされずにそのまま通過します(ストリーム内でのインバンド書き換えは予定されている
拡張機能です)。今のところ出力のマスクには、非ストリーミングリクエストを使うか、
input ステージでのマスクに頼ってください。それに依存する前に、特定の
ステージ/ストリームの組み合わせをサンドボックスと eval 実行で証明してください。
mask と block の違いは何ですか?
mask と block の違いは何ですか?
Mask はマッチをリダクトし(例:
jane@acme.com → [EMAIL])、
サニタイズされたテキストでリクエストを通します — アップストリームモデルが
元のものを目にすることはありません。Block はリクエスト全体を HTTP 400 で
拒否します。Flag はトラフィックについて何も変えず、マッチを記録するだけ
です — 強制前にルールを測定するために使います。注入されたプロンプトトークンと judge トークンは課金されますか?
注入されたプロンプトトークンと judge トークンは課金されますか?
組み込みルール(keyword / regex / PII / max_chars)はモデル呼び出しを
行わず、何も課金しません。
llm_judge または grounding ルールは
ワークスペースのチャネルを通じてモデルを呼び出すため、それらのトークンは
judge サブラインとして課金され帰属されます。ルールが実際に何にマッチしたかを確認するには?
ルールが実際に何にマッチしたかを確認するには?
ガードレールの Log raw content をオンにします。オフの場合(デフォルト)、
Matches フィードはルールが発火したことと詳細メタ文字列を記録しますが、
マッチした部分文字列は記録しません — プライバシー保守的な姿勢です。
トグルは非遡及的です:有効化した後に記録されたマッチにのみ影響します。
ガードレールの変更をロールバックできますか?
ガードレールの変更をロールバックできますか?
はい。ガードレールの History を開き、バージョンを diff し、欲しいものに
Revert します。Revert はそのバージョンの内容を新しいバージョンとして
前進コピーし(履歴は決して変更されません)、変更は次のリクエストで
反映されます。
外部ベンダーまたは judge がタイムアウトした場合はどうなりますか?
外部ベンダーまたは judge がタイムアウトした場合はどうなりますか?
デフォルトでは、高度なルールはフェイルオープンします:タイムアウトまたは
転送エラーはテレメトリとして記録され、リクエストは継続します。見逃された
チェックが許容できないポリシーでは、
fail_open(external)または
judge_fail_open(judge)を false に設定してフェイルクローズ —
エラーを block として扱う — にします。