SanitizeUserPrompt ポリシー

このページの内容は Apigee を対象としています。Apigee ハイブリッドは対象としていません。

Apigee Edge のドキュメントを表示する。

概要

SanitizeUserPrompt ポリシーは、生成 AI モデルに送信されるユーザー プロンプトをサニタイズすることで、AI アプリケーションを有害なコンテンツから保護します。このポリシーは、ユーザー プロンプトに有害なコンテンツが含まれていないかを Model Armor を使って評価し、Apigee を使った AI ワークロードに対してネイティブな保護を実現します。Model Armor は、大規模言語モデル（LLM）に関連するリスクを軽減するための AI セキュリティと安全対策を提供する Google Cloud サービスです。

このポリシーは、SanitizeModelResponse ポリシーと組み合わせて使用します。

このポリシーは拡張可能なポリシーです。Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

始める前に

SanitizeUserPrompt ポリシーを使用する前に、次のタスクを完了します。

• Model Armor テンプレートを作成する。SanitizeUserPrompt ポリシーを作成する前に、この手順を完了してください。
• Model Armor サービスの API エンドポイントを設定する。
• SanitizeModelResponse ポリシーを作成する。SanitizeUserPrompt ポリシーをデプロイする前に、このタスクを完了してください。

必要なロール

SanitizeUserPrompt ポリシーを適用して使用するために必要な権限を取得するには、Apigee プロキシのデプロイに使用しているサービス アカウントに次の IAM ロールを付与するよう管理者に依頼してください。

• Model Armor ユーザー（roles/modelarmor.user)）
• Model Armor 閲覧者（roles/modelarmor.viewer）

ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

API を有効にする

Enable the Model Armor API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

<SanitizeUserPrompt> 要素

SanitizeUserPrompt ポリシーを定義します。

デフォルト値	下記の [デフォルト ポリシー] タブをご覧ください。
必須かどうか	必須
型	複合オブジェクト
親要素	なし
子要素	<DisplayName> <IgnoreUnresolvedVariables> <TemplateName> <UserPromptSource>

<SanitizeUserPrompt> 要素の構文は次のとおりです。

構文

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

デフォルト ポリシー

次の例は、Apigee UI でリクエスト フローに SanitizeUserPrompt ポリシーを追加したときのデフォルト設定を示したものです。

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
  <UserPromptSource>{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}</UserPromptSource>
</SanitizeUserPrompt>

Apigee UI を使って新しい SanitizeUserPrompt ポリシーを挿入すると、テンプレートには使用可能なすべてのオペレーションに対応するスタブが含まれています。必須要素の詳細については、下記をご覧ください。

この要素には、すべてのポリシーに共通する次の属性があります。

属性	デフォルト	必須かどうか	説明
name	なし	必須	ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。 管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
continueOnError	false	省略可	ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について） 現在のフローにおける障害処理
enabled	true	省略可	ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async	false	非推奨	この属性は非推奨となりました。

次の表は、<SanitizeUserPrompt> の子要素の概要をまとめたものです。

子要素	必須かどうか	説明
<DisplayName>	省略可	ポリシーの名前。
<IgnoreUnresolvedVariables>	省略可	テンプレート名または Model Armor ペイロードに使用される変数が未解決の場合に、処理を停止するかどうかを指定します。
<ModelArmor>	必須	Model Armor テンプレートの指定に必要な情報が含まれています。
<UserPromptSource>	省略可	ユーザー プロンプト テキストを抽出するペイロードの場所。文字列テキスト値のみがサポートされています。 このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージ テンプレートの構文をサポートしています。 次に例を示します。 {jsonpath('$.input.prompt.text',request.content,false)}

例

このセクションでは、<SanitizeUserPrompt> の使用例を見ていきます。

この例では、モデルの検出とプロンプトの抽出にすべてのデフォルト値を使用します。

<SanitizeUserPrompt async="false" continueOnError="false" enabled="true" name="sanitize-text">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <DisplayName>Sanitize-Text-sample</DisplayName>
  <ModelArmor>
    <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
  </ModelArmor>
</SanitizeUserPrompt>

子要素のリファレンス

このセクションでは、<SanitizeUserPrompt> の子要素について説明します。

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値	なし
必須かどうか	省略可。<DisplayName> を省略した場合、ポリシーの name 属性の値が使用されます。
型	文字列
親要素	<PolicyElement>
子要素	なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

<IgnoreUnresolvedVariables>

変数が解決されない場合に処理を停止するかどうかを決定します。true を設定すると、未解決の変数を無視して処理を続行できます。

デフォルト値	False
必須かどうか	省略可
型	ブール値
親要素	<SanitizeUserPrompt>
子要素	なし

<ModelArmor>

Model Armor テンプレートの指定に必要な情報が含まれています。

デフォルト値	なし
必須かどうか	必須
型	文字列
親要素
子要素	<TemplateName>

<ModelArmor> 要素の構文は次のとおりです。

構文

<ModelArmor>
  <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName>
</ModelArmor>

例

この例では、Apigee フロー変数を使用して必要な情報を入力します。

<ModelArmor>
  <TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName>
</ModelArmor>

次の表は、<ModelArmor> の子要素の概要をまとめたものです。

子要素	必須かどうか	説明
<TemplateName>	必須	文字列 ユーザー プロンプトのサニタイズに使用される Model Armor テンプレート。 この値は、次の Apigee フロー変数を使用してテンプレート化できます。 projects/{organization.name}/locations/{system.region.name}/templates/{id}

<UserPromptSource>

ユーザー プロンプト テキストを抽出するペイロードの場所。このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージ テンプレートの構文をサポートしています。次に例を示します。

{jsonpath('$.input.prompt.text',request.content,false)}

デフォルト値	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
必須かどうか	省略可
型	文字列
親要素	<SanitizeUserPrompt>
子要素	なし

フロー変数

フロー変数を使用すると、HTTP ヘッダー コンテンツ、メッセージ コンテンツ、またはフローのコンテキストに基づいて、ポリシーとフローが実行時に動的に動作するよう構成できます。フロー変数の詳細については、フロー変数のリファレンスをご覧ください。

このポリシーは、実行時に次の読み取り専用フロー変数のセットを提供します。これらのフロー変数と DataCapture ポリシーを使用して、カスタム分析レポートを作成できます。詳細については、DataCapture ポリシーを使用した顧客データの収集をご覧ください。

変数名	説明
SanitizeUserPrompt.POLICY_NAME.templateUsed	どの Model Armor が使用されるかを指定します。例: projects/myproject/locations/us-west1/templates/mytemplate。
SanitizeUserPrompt.POLICY_NAME.userPrompt	コンテンツをサニタイズするために Model Armor の呼び出しに使用されるプロンプト コンテンツを指定します。
SanitizeUserPrompt.POLICY_NAME.modelResponse	コンテンツをサニタイズするために Model Armor の呼び出しに使用される LLM レスポンス コンテンツを指定します。
SanitizeUserPrompt.POLICY_NAME.responseFromModelArmor	Model Armor からの JSON レスポンスを指定します。
SanitizeUserPrompt.POLICY_NAME.filterMatchState	フィルタが一致したかどうかを指定します。有効な値として、MATCH_FOUND、NO_MATCH_FOUND があります。
SanitizeUserPrompt.POLICY_NAME.invocationResult	一致ステータスに関係なく、呼び出しの結果を示すフィールド。次のような値を指定できます。 SUCCESS: すべてのフィルタが正常に実行されました。 PARTIAL: 一部のフィルタがスキップされたか、実行に失敗しました。 FAILURE: すべてのフィルタがスキップされたか、実行に失敗しました。
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.executionState	RAI フィルタの実行結果。有効な値として、EXECUTION_SUCCESS、EXECUTION_SKIPPED があります。
SanitizeUserPrompt.POLICY_NAME.raiFilterResult.matchState	RAI フィルタのマッチ状態。有効な値として、MATCH_FOUND、NO_MATCH_FOUND があります。
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.executionState	Sdp フィルタが結果の実行状態を検査します。有効な値として、EXECUTION_SUCCESS、EXECUTION_SKIPPED があります。
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.inspectResult.matchState	Sdp フィルタ検査結果の一致状態。有効な値として、MATCH_FOUND、NO_MATCH_FOUND があります。
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState	Sdp フィルタで結果の実行状態を特定します。有効な値として、EXECUTION_SUCCESS、EXECUTION_SKIPPED があります。
SanitizeUserPrompt.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState	Sdp フィルタで結果の一致状態を特定します。有効な値として、MATCH_FOUND、NO_MATCH_FOUND があります。
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.executionState	プロンプト インジェクションとジェイルブレイク フィルタの結果の実行状態。有効な値として、EXECUTION_SUCCESS、EXECUTION_SKIPPED があります。
SanitizeUserPrompt.POLICY_NAME.piAndJailbreakFilterResult.matchState	プロンプト インジェクションとジェイルブレイク フィルタの結果が状態と一致しています。有効な値として、MATCH_FOUND、NO_MATCH_FOUND があります。
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.executionState	CSAM フィルタの実行ステータス。有効な値として、EXECUTION_SUCCESS、EXECUTION_SKIPPED があります。
SanitizeUserPrompt.POLICY_NAME.csamFilterFilterResult.matchState	CSAM フィルタのマッチ状態。有効な値として、MATCH_FOUND、NO_MATCH_FOUND があります。
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.executionState	悪意のある URI フィルタの実行ステータス。有効な値として、EXECUTION_SUCCESS、EXECUTION_SKIPPED があります。
SanitizeUserPrompt.POLICY_NAME.maliciousUriFilterResult.matchState	悪意のある URI フィルタの一致状態。有効な値として、MATCH_FOUND、NO_MATCH_FOUND があります。
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorCode	Model Armor レスポンスに存在する場合のカスタム オーバーライド エラーコード。
SanitizeUserPrompt.POLICY_NAME.sanitizationMetadata.errorMessage	Model Armor レスポンスに存在する場合のカスタム オーバーライド エラーコード。
SanitizeUserPrompt.POLICY_NAME.csamFilterMatched/code>	CSAM フィルタが一致したかどうかを示すブール値。
SanitizeUserPrompt.POLICY_NAME.maliciousURIs	悪意のある URI フィルタによって検出された悪意のある URI のリストが追加されます。
SanitizeUserPrompt.POLICY_NAME.maliciousURIsDetected	悪意のある URI フィルタが一致したかどうかを示すブール値。
SanitizeUserPrompt.POLICY_NAME.matchesFound	いずれかのフィルタが一致したかどうかを示すブール値。
SanitizeUserPrompt.POLICY_NAME.promptInjectionDetected	プロンプト挿入フィルタが一致したかどうかを示すブール値。
SanitizeUserPrompt.POLICY_NAME.promptInjectionConfidence	プロンプト インジェクション検出の信頼度。
SanitizeUserPrompt.POLICY_NAME.raiMatchesFound	RAI フィルタが一致したかどうかを示すブール値。
SanitizeUserPrompt.POLICY_NAME.requestSentToModelArmor	Model Armor にリクエストが送信されたかどうかを示すブール値。
SanitizeUserPrompt.POLICY_NAME.sanitizeOperation	ポリシーによって実行されるオペレーションを指定します。有効な値として、SANITIZE_USER_PROMPT、SANITIZE_MODEL_RESPONSE などがあります。

エラー リファレンス

このセクションでは、Apigee が返す障害コードとエラー メッセージ、および Apigee が SanitizeUserPrompt ポリシーに設定する障害変数について説明します。これは、障害に対処するための障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイム エラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード	HTTP ステータス	原因
steps.sanitize.user.prompt.response.FilterMatched	400	このエラーは、ユーザー プロンプトが Model Armor テンプレートのチェックに合格しなかった場合に発生します。
steps.sanitize.user.prompt.SanitizationResponseParsingFailed	500	このエラーは、Model Armor のレスポンスを解析できない場合に発生します。
steps.sanitize.user.prompt.FailedToExtractUserPrompt	500	このエラーは、デフォルト値の自動ユーザー プロンプトの抽出に失敗した場合に発生します。
steps.sanitize.user.prompt.InternalError	500	このエラーは、内部サーバーエラーがあった場合に発生します。
steps.sanitize.modelarmor.ModelArmorTemplateNameExtractionFailed	500	このエラーは、テンプレート名を解決できない場合に発生します。
steps.sanitize.modelarmor.AuthenticationFailure	500	このエラーは、サービス アカウントに Model Armor API を呼び出す権限がない場合に発生します。
steps.sanitize.modelarmor.ModelArmorAPIFailed	500	このエラーは、Model Armor API がエラーをスローした場合に発生します。
steps.sanitize.modelarmor.ModelArmorCalloutError	500	このエラーは、Model Armor API 呼び出しが失敗した場合に発生します。
steps.sanitize.modelarmor.ServiceUnavailable	500	このエラーは、Model Armor サービスが利用できない場合に発生します。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

エラー名	原因
The ModelArmor/TemplateName element is required.	<ModelArmor> の <TemplateName> 要素が存在しない場合。
The TemplateName element value is required.	<TemplateName> の値が空の場合に発生します。

障害変数

このポリシーは、ランタイム エラーが発生したときに次の変数を設定します。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数	説明	例
fault.name="FAULT_NAME"	FAULT_NAME は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。	fault.name Matches "UnresolvedVariable"
SanitizeUserPrompt.POLICY_NAME.failed	POLICY_NAME は、障害をスローしたポリシーのユーザー指定の名前です。	SanitizeUserPrompt.sanitize-prompt.failed = true

エラー レスポンスの例

注: ベスト プラクティスとして、エラー処理でエラー レスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

{
  "fault": {
    "faultstring": "SanitizeUserPrompt[sanitize-prompt]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizeuserprompt.UnresolvedVariable"
    }
  }
}

障害ルールの例

<FaultRule name="SanitizeUserPrompt Faults">
    <Step>
        <Name>SUP-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizeuserprompt.failed = true)</Condition>
</FaultRule>

Model Armor テンプレートのエラーコードとエラー メッセージ

Model Armor テンプレートは、SanitizeUserPrompt ポリシーの API リクエストによってスローされるエラーコードとエラー メッセージのオーバーライドをサポートしています。ユーザーがオーバーライドを設定すると、Model Armor のエラーコードとエラー メッセージがフロー変数に入力されます。

たとえば、Model Armor のエラーコードとメッセージを含むレスポンスは次のようになります。

{
  "sanitizationResult": {
    "filterMatchState": "MATCH_FOUND",
    "filterResults": {...},
    "sanitizationMetadata": {
      "errorCode": "890",
      "errorMessage": "get out"
      },
    "invocationResult": "SUCCESS"
  }
}

スキーマ

各ポリシータイプは XML スキーマ（.xsd）によって定義されます。参照用のポリシー スキーマは GitHub から入手できます。