このページは Cloud Translation API によって翻訳されました。

SanitizeModelResponse ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

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

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

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

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

始める前に

SanitizeModelResponse ポリシーを使用する前に、次のタスクを完了する必要があります。

Model Armor テンプレートを作成する。SanitizeModelResponse ポリシーを作成する前に、テンプレートを用意しておく必要があります。
Model Armor サービスの API エンドポイントを設定する。

必要なロール

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

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

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

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

API を有効にする

Enable the Model Armor APIs.

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 APIs

`<SanitizeModelResponse>` 要素

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

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

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

構文

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

デフォルトポリシー

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

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

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

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

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

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

子要素	必須かどうか	説明
`<DisplayName>`	省略可	ポリシーの名前。
`<IgnoreUnresolvedVariables>`	省略可	テンプレート名または Model Armor ペイロードに使用される変数が未解決の場合に、処理を停止するかどうかを指定します。
`<TemplateName>`	必須	LLM レスポンスのサニタイズに使用される Model Armor テンプレート。この値は、次の Apigee フロー変数を使用してテンプレート化できます。 projects/{organization.name}/locations/{system.region.name}/templates/{id}
`<UserPromptSource>`	必須	ユーザープロンプトテキストを抽出するペイロードの場所。文字列テキスト値のみがサポートされています。このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージテンプレートの構文をサポートしています。例: {jsonpath('$.contents[-1].parts[-1].text',request.content,false)}
`<LLMResponseSource>`	必須	LLM レスポンスのテキストを抽出するペイロードの場所。文字列テキスト値のみがサポートされています。このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージテンプレートの構文をサポートしています。例: {jsonpath('$.input.prompt.text',request.content,false)}

子要素のリファレンス

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

`<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
必須かどうか	省略可
型	ブール値
親要素	`<SanitizeModelResponse>`
子要素	なし

`<TemplateName>`

Model Armor テンプレート。

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

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

構文

<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>

`<UserPromptSource>`

ユーザープロンプトテキストを抽出するペイロードの場所。文字列テキスト値のみがサポートされています。

このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージテンプレートの構文をサポートしています。次に例を示します。

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

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

`<LLMResponseSource>`

LLM レスポンスを抽出するペイロードの場所。文字列テキスト値のみがサポートされています。

このフィールドは、変数や JSON Path 関数の使用など、Apigee メッセージテンプレートの構文をサポートしています。次に例を示します。

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

デフォルト値	{jsonPath($.candidates[-1].content.parts,response.content,true)}
必須かどうか	必須
型	文字列
親要素	`<SanitizeModelResponse>`
子要素	なし

フロー変数

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

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

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

エラーリファレンス

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

ランタイムエラー

障害コード	HTTP ステータス	原因
`steps.sanitize.model.response.FilterMatched`	`400`	このエラーは、ユーザープロンプトが Model Armor テンプレートのチェックに合格しなかった場合に発生します。
`steps.sanitize.model.response.SanitizationResponseParsingFailed`	`500`	このエラーは、Model Armor のレスポンスを解析できない場合に発生します。
`steps.sanitize.model.response.FailedToExtractUserPrompt`	`500`	このエラーは、デフォルト値の自動ユーザープロンプトの抽出に失敗した場合に発生します。
`steps.sanitize.model.response.FailedToExtractLLMResponse`	`500`	このエラーは、デフォルト値の自動モデルレスポンスの抽出に失敗した場合に発生します。
`steps.sanitize.model.response.InternalError`	`500`	このエラーは、内部サーバーエラーがあった場合に発生します。
`steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed`	`500`	このエラーは、テンプレート名を解決できない場合に発生します。
`steps.sanitize.model.response.AuthenticationFailure`	`500`	このエラーは、サービスアカウントに Model Armor API を呼び出す権限がない場合に発生します。
`steps.sanitize.model.response.ModelArmorAPIFailed`	`500`	このエラーは、Model Armor API がエラーをスローした場合に発生します。
`steps.sanitize.model.response.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"`
`SanitizeModelResponse.POLICY_NAME.failed`	`POLICY_NAME` は、障害をスローしたポリシーのユーザー指定の名前です。	`SanitizeModelResponse.sanitize-response.failed = true`

エラーレスポンスの例

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

{
  "fault": {
    "faultstring": "SanitizeModelResponse[sanitize-response]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.sanitizemodelresponse.UnresolvedVariable"
    }
  }
}

障害ルールの例

<FaultRule name="SanitizeModelResponse Faults">
    <Step>
        <Name>SMR-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(sanitizemodelresponse.failed = true)</Condition>
</FaultRule>

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

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

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

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

スキーマ

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

SanitizeModelResponse ポリシー

始める前に

必要なロール

API を有効にする

<SanitizeModelResponse> 要素

構文

デフォルト ポリシー

子要素のリファレンス

<DisplayName>

構文

例

<IgnoreUnresolvedVariables>

<TemplateName>

構文

例

<UserPromptSource>

<LLMResponseSource>

フロー変数

エラー リファレンス

ランタイム エラー

デプロイエラー

障害変数

エラー レスポンスの例

障害ルールの例

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

スキーマ

`<SanitizeModelResponse>` 要素

デフォルトポリシー

`<DisplayName>`

`<TemplateName>`

`<UserPromptSource>`

`<LLMResponseSource>`

エラーリファレンス

ランタイムエラー

エラーレスポンスの例

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