個人データをログに残さない AI ゲートウェイ
サポートアシスタントは顧客の氏名やメールアドレスを扱う必要があるため、 呼び出すモデルはそれらを参照できなければなりません。そのモデルの前段にあるゲートウェイは監査とデバッグのためにログを保持しますが、 そのログにはそれらを残してはなりません。このワークスペースは、 そのようなゲートウェイを Kubernetes マニフェストにコンパイルします。
これを担うのはゲートウェイ自体の値、core/gateway/litellm の values.log_masking です。
この値は、ゲートウェイが各呼び出しについてログに渡すコピーをマスクし、それ以外には何もしません。
モデルは呼び出し元が送ったとおりのリクエストを受け取り、呼び出し元はモデルが書いたとおりの応答を受け取ります。
これが、モデル自体からテキストを隠す Feature core/data-masking との違いです。
この 2 つは択一の関係にあり、両者の選び方を扱う後述のセクションでは、
1 つのゲートウェイに両方を設定した場合に何が起こるかを示します。
このワークスペースは独自のカタログエンティティを一切作成しません。 ここにある 3 つのエンティティファイル — Aggregate、Manifest、Release — が、 誰かが書くもののすべてです。
構築されるもの
| インスタンス | カタログの Component | ここでの役割 |
|---|---|---|
router | core/gateway/litellm | AI ゲートウェイ: 公開するエイリアスは assistant の 1 つで、models ソケットに接続されたモデルから提供されます |
gpt | core/ai-model/openai | そのエイリアスの背後にあるモデル。OpenAI 自身の API に参照としてアクセスするため、クラスタ内ではそのために何も実行されません |
analyzer | core/security/presidio-analyzer | テキスト内の機密性の高い箇所を検出します |
anonymizer | core/security/presidio-anonymizer | 渡された箇所を置き換えます |
uses エッジは 3 つあります。ゲートウェイの models ソケットからモデルへのエッジは、ゲートウェイがモデルに提示するキーを credential として運びます。また、ゲートウェイの pii_analyzer ソケットと
pii_anonymizer ソケットから 2 つの認識サービスへのエッジがあります。Aggregate はシークレットを指定せずにその認証情報をアタッチし、Release はアタッチメントの infra でそれを指定します。これは名前空間がすでに保持している Secret で、Manifest の実現はこれを参照しますがレンダリングはしません。ゲートウェイの values.log_masking
にはマスクする対象を列挙します。patterns には社内のチケット番号を表す正規表現を、entities にはエンティティ型 PERSON と EMAIL_ADDRESS を指定します。
デフォルトのリストはありません。どちらも列挙しないゲートウェイはログ内の何もマスクせず、この値がない場合とまったく同じようにレンダリングされます。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example ai-gateway-log-maskingその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd ai-gateway-log-maskingビルド
aggrega build --release release.yaml --auto-pullrelease はビルドの前に lockfile を必要とします。lockfile は同梱されるのではなく生成されるため、クローンした直後には存在しません。先に解決するか、ビルドに作成させてください:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildこのワークスペースは、.aggrega-config.yaml が指定するデフォルトレジストリからカタログのエンティティを解決します。ログのマスキングはゲートウェイ自身の Recipe が書き出すため、ビルドはコンパイラが同梱するもの以外のプラグインを実行しません。
ビルドは次のように出力します。<workspace> はこの例のフォルダを表します。
[… omitted: the resolution's summary, a notice that core/referenced-secret declares origin in both of its pillars, and a total build time, which differs per run]Build completed: 9 files written to <workspace>/distAI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `ai-gateway-log-masking` フォルダーがない場合は、`example` を `ai-gateway-log-masking` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `ai-gateway-log-masking` フォルダーに書き出されます。次に、`workspace_root` を `ai-gateway-log-masking`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き出したファイルを教えてください。ファイルは `ai-gateway-log-masking/dist/` の下にあります。レンダリングされたツリー
dist/helm/├── analyzer-default-service.yaml├── analyzer-deployment.yaml├── anonymizer-default-service.yaml├── anonymizer-deployment.yaml├── gpt-service.yaml├── router-default-service.yaml├── router-deployment.yaml└── router/ ├── litellm-gateway-config/ │ └── configmap.yaml └── request-guard/ └── request-guard.yamlこの値は独自のファイルを持ちません。ゲートウェイの Recipe がこの値をゲートウェイの設定に書き込み、その設定が読み込むモジュールをゲートウェイの ConfigMap に追加します。モデルは 1 つのファイル gpt-service.yaml をレンダリングします。これはクラスタ内の名前を OpenAI の API ホスト api.openai.com に対応付ける Service です。モデルのキーは何もレンダリングしません。キーを保持する Secret がすでに存在するためです。
ルーティングテーブルはゲートウェイの設定本体の先頭部分で、エントリを 1 つ持ちます。このエントリは、モデルが公開するもの(エンドポイント、OpenAI の API ベース URL、モデル名)から書き込まれ、ゲートウェイの Recipe が接続のキーを渡す際に使う変数を指定します。
model_list: - model_name: "assistant" litellm_params: model: "openai/gpt-4o" api_base: "https://api.openai.com/v1" api_key: os.environ/LITELLM_MODEL_ASSISTANT_API_KEYガードレールエントリ
以下は、ゲートウェイの設定本体、すなわち
dist/helm/router/litellm-gateway-config/configmap.yaml の config.yaml キーのうち、
litellm_settings セクション以降の部分です。
[… omitted: the routing table]litellm_settings: callbacks: - /etc/litellm-request-guard/request_field_filter.filter - log_masking.withhold_failed_calls redact_messages_in_exceptions: trueguardrails: - guardrail_name: "router.log-masking" litellm_params: guardrail: log_masking.LogMasking default_on: true mode: logging_only patterns: - pattern_type: regex name: "ticket" pattern: "\\bTCK-[0-9]{6}\\b" action: MASK pii_entities_config: "PERSON": MASK "EMAIL_ADDRESS": MASKgeneral_settings: disable_error_logs: trueゲートウェイの Recipe は、これをすべて values.log_masking から書き出し、
エントリにはゲートウェイにちなんだ名前(ここでは router)を付けます。標準ライブラリの
realization が書き出すガードレールエントリではハイフンが入る位置にドットを使うため、
それらのアタッチメントは、名前が何であっても、このエントリに取って代わることはできません。
ここから読み取るべき点が 5 つあります。
mode: logging_only は、完了した呼び出しがログに渡される箇所でのみ実行され、
それ以外では実行されないガードレールのための、ゲートウェイ自身のモードです。
エントリが読み込むクラスは、エントリが何を指定していてもこれを守るため、リクエストが
転送される前のリクエストや、応答が返される前の応答に対して呼び出されることはありません。
default_on: true により、すべての呼び出しで実行されます。 呼び出し元は
リクエストからこれを無効にできず、ゲートウェイの常時有効なガードレールの無効化を求める
リクエストであっても同様です。
パターンは、記述されたとおりにゲートウェイへ届きます。 パターンはゲートウェイ内部で
大文字・小文字を区別せずに照合され、一致した箇所はすべて、パターン名を大文字にして
角括弧で囲んだもの([TICKET_REDACTED])に恒久的に置き換えられます。ゲートウェイは
起動時に正規表現をコンパイルし、コンパイルできない正規表現があると起動は停止します。
コンパイラは文字列を読まずにそのまま渡します。
エンティティタイプは、2 つの認識サービスによって検出されます。 エントリはアドレスを
指定しません。ゲートウェイは両方のアドレスを環境から読み取り、ゲートウェイの
Recipe がそれを 2 つのエッジから設定します。以下は dist/helm/router-deployment.yaml の、
ゲートウェイのコンテナの env です。
env: - name: LITELLM_MODEL_ASSISTANT_API_KEY valueFrom: secretKeyRef: name: openai-api-key key: api-key - name: PRESIDIO_ANALYZER_API_BASE value: http://analyzer-default:3000 - name: PRESIDIO_ANONYMIZER_API_BASE value: http://anonymizer-default:30001 つ目はモデルのキーで、Release が指定する Secret から参照され、書き出されることは
ありません。残りの 2 つは認識サービスのアドレスです。人名は <PERSON> に、
メールアドレスは <EMAIL_ADDRESS> になります。
失敗した呼び出しは、マスクされるのではなく伏せられます。 ゲートウェイは失敗した
呼び出しに対してロギングガードレールを実行しないため、エントリが読み込むモジュールは
log_masking.withhold_failed_calls も提供します。これはリクエストガードの直後に登録され、
ゲートウェイの Recipe はその横に 2 つの設定を書き出します。このコールバックは、
それより後に登録されたどのコールバックよりも先に、失敗した呼び出しのレコードを受け取り、
呼び出し元またはモデルが書いたすべてのテキストを、一致するかどうかにかかわらず
[TEXT_WITHHELD] に、エラーのテキストを [ERROR_TEXT_WITHHELD] に置き換えます。
再試行で送信される内容はそのまま残します。disable_error_logs は失敗した呼び出しを
利用料ログから除外し、redact_messages_in_exceptions はゲートウェイがエラーに付加する
詳細からリクエストのメッセージを除外します。
同じ ConfigMap には 2 つ目のキー log_masking.py が含まれます。これは、エントリの
guardrail と 2 つ目の callbacks エントリが指定するモジュールです。ゲートウェイの
Recipe は、values.log_masking に何かが列挙されている間だけ、このモジュール、その
callbacks エントリ、ガードレールエントリ、2 つの設定を追加します。そのため、何も
列挙していないゲートウェイは、それらを一切含まない ConfigMap を、この値を持たない
ゲートウェイとバイト単位で同一にレンダリングします。
ログの読み手に見えるもの、モデルに見えるもの
リクエストに次のテキストを含む呼び出し元を例にとります。
My name is David Johnson and my email is david.johnson@example.com, ticket TCK-104882. Call me on 212-555-0147.上のブロックと下の 3 つのブロックは、実行中のゲートウェイがこのテキストをどう扱うかを示すものであり、ビルドの出力ではありません。
モデルのプロバイダーは呼び出し元が送信したとおりのリクエストを受け取り、呼び出し元はモデルの応答を届いたとおりに受け取ります。ゲートウェイが呼び出しを渡すロギング連携は、同じメッセージをマスクされた状態で受け取ります。
My name is <PERSON> and my email is <EMAIL_ADDRESS>, ticket [TICKET_REDACTED]. Call me on 212-555-0147.電話番号は送信されたとおりにログに記録されます。アタッチメントが PHONE_NUMBER を列挙しておらず、どのパターンにも一致しないためです。列挙されたものに一致しないテキストがマスクされることはありません。
ゲートウェイがログに渡す成功した呼び出しのコピーは、すべて同じ方法でマスクされます。対象は、メッセージ、標準ロギングペイロードのメッセージと応答、ゲートウェイが組み立てたストリーミング応答、プロバイダーが見たリクエストと応答、支出ログが保持するリクエスト、そして各連携が受け取る応答です。モデルの応答も、これらのコピーではマスクされます。
Reply for <PERSON> (<EMAIL_ADDRESS>) about [TICKET_REDACTED].マスクされずに残るもの
ログのマスキングは、テキストをログ以外の誰からも隠しません。values.log_masking の説明にもそのように記載されています。
- モデルの provider はすべてをマスクされない状態で受け取ります。ゲートウェイと 2 つの認識サービスも同様です。
- 失敗した呼び出しは、ゲートウェイが書き込むどのログにもリクエストのテキストを残しません。これには 2 つの代償があります。 失敗した呼び出しについてゲートウェイ自身が書く行には、
An error was logged with its text withheld, as log masking is on: BadRequestErrorのようにエラーの種類だけが残るため、provider のメッセージとそのトレースバックはそのログから消えます。また、失敗した呼び出しは支出ログと日次の支出合計から外れます。これらは成功した呼び出しのみを数えるためです。カタログの外で設定されたログ連携は、失敗した呼び出しが持つ例外に含まれる provider 自身のエラーメッセージを引き続き読み取ることができ、ゲートウェイ自身のコールバックより前に登録された連携には、失敗した呼び出しのテキストがそのまま渡されます。 - 対象となるのは、マスキングを経由して書き込まれるログだけです: ゲートウェイのデバッグ出力や provider 自身のログは対象外です。リクエストのメタデータ、ツール定義、ヘッダーは送信されたとおりにログに記録されます。
- コピーをマスクできない呼び出しは、テキストを伏せた状態でログに記録されます。
認識サービスに到達できない場合、一部だけマスクされたコピーがログに記録されることはありません。その呼び出しのすべてのコピーに含まれるすべてのテキストが
[TEXT_WITHHELD]に置き換えられ、レコードは通常どおりログに渡されるため、その呼び出しは引き続き支出ログに計上されます。 ゲートウェイ自身のログには、その呼び出しのテキストが伏せられたことが記録されます。呼び出し自体には通常どおり応答します。
カタログがこのゲートウェイをレンダリングした状態では、ゲートウェイはどのログ連携にもログを渡さず、支出ログにはリクエストや応答のテキストも失敗した呼び出しも残りません。したがって、マスキングが保護するコピーは、ゲートウェイ上に設定された連携、またはテキストを保持する支出ログが受け取るはずのものです。
ログのマスキングかデータのマスキングか
core/data-masking は列挙されたテキストをモデルから隠します。このゲートウェイでは、その実現はアタッチされている間、ゲートウェイによるメッセージ内容のログ記録をオフにします。これと並べると、ログのマスキングには作用する対象が何も残らず、読み手は両者を 1 つの保護と取り違えるおそれがあります。そのため、ゲートウェイは両者の併用を拒否します。values.log_masking に何かが列挙されている間は、ゲートウェイ上の core/data-masking のアタッチメントが、ゲートウェイ自身の Component のアサーションによってビルドを停止させます。masked という名前のものをゲートウェイに追加し、その実現を
Manifest でバインドすると、次のように出力されます。
[… omitted: what resolving the lockfile prints, the same halt among it, and a notice that core/referenced-secret declares origin in both of its pillars][DEVELOPER_ERROR E0033] Component/Feature assertions caused by: Component "core/gateway/litellm" instance "router" assertion "log_masking_not_beside_data_masking": [… omitted: the template position and the assertion's own source]: error calling fail: assertion failed: "router" lists what to mask in its logs under values.log_masking, and the core/data-masking attachment "masked" is on it too: that attachment's realization turns the gateway's logging of message contents off, so log masking would have nothing left to act on, and a reader could take the two for one protection. Remove values.log_masking to mask what travels, or the "masked" attachment to mask only what is loggedモデルがデータを参照する必要があり、ログにはそれを残してはならない場合はログのマスキングを使います。モデルにもデータを参照させてはならない場合はデータのマスキングを使います。どちらも同じ patterns と entities を読むため、リストはどちらでも同じ意味を持ちます。
コンパイラが解釈しない箇所
コンパイラは、パターンとエンティティタイプを文字列としてゲートウェイの設定に渡します。式をコンパイルすることはなく、チケット番号や人物が何であるかを知らず、ゲートウェイが運ぶトラフィックを見ることもありません。このワークスペースで起こり得る停止 — レコグナイザーのソケットが未配線のままのエンティティタイプ、アナライザーが英語で認識しないエンティティタイプ、1 つのゲートウェイ上でのデータマスキングと並ぶログマスキング、認証情報を持たないマネージドモデルへの接続 — はいずれも、カタログ自身のエンティティによって、ゲートウェイの Component またはその Recipe のアサーションとして宣言されており、そのどれもテキストの理解に基づくものではありません。
応用する
- パターンのみをマスクする。
values.log_maskingからentitiesを削除し、2 つの認識器コンポーネントを、そのエッジおよび Release 内のエントリとともに削除します。パターンはゲートウェイ内部で照合されるため、どちらのサービスも必要ありません。 - より多くのエンティティタイプをマスクする。 認識器自身の語彙で
entitiesに追加します。アナライザーが英語で認識しないタイプはビルドを停止させ、認識するタイプを列挙します。 - モデルからもテキストを隠す。
values.log_maskingを、同じpatternsとentitiesを列挙するゲートウェイ上のcore/data-maskingアタッチメントに置き換え、その実現を Manifest でバインドします。 - 2 つ目のモデルを提供する。 別のモデルコンポーネントを独自のエイリアスで
modelsソケットに配線し、その接続でゲートウェイが提示するキーを指定します。values.modelは引き続きゲートウェイが公開するエイリアスを指します。 マスキングは、ゲートウェイが提供するすべてのエイリアスの呼び出しに適用されます。