ADK 的 Model Armor 插件¶

Supported in ADKPython v2.8.0

Model Armor 是一项 Google Cloud 服务，用于检查文本中是否存在提示词注入和越狱尝试、有害内容以及敏感数据。你在一个名为模板的服务端策略中定义要查找的内容，该服务会为你发送的每段文本返回一个判定结果。 ModelArmorPlugin 类随 ADK 一起提供，并从模型回调中调用该服务。它会在模型看到用户输入之前筛查用户输入，并在模型输出交付之前或交付过程中进行筛查，将匹配到的内容替换为安全消息。

用例¶

提示词注入与越狱防护：在模型据此行动之前，使用提示词模板筛查每一轮用户消息，使得被检测到的尝试会被阻止，而不是让智能体照做。
敏感数据与有害内容过滤：使用响应模板筛查模型输出，在交付之前捕获会泄露数据或违反内容政策的回答。
跨智能体的统一策略：在 App 上注册一个插件，它运行的每个智能体都会继承相同的筛查能力，包括实时语音智能体。

前提条件¶

一个已启用 Model Armor API 的 Google Cloud 项目，并且至少已创建一个模板。参见 Model Armor 文档。
具备 Model Armor 访问权限的应用程序默认凭据，通过 gcloud auth application-default login 设置。
ADK >= 2.8.0

安装¶

pip install 'google-adk[gcp]'

没有单独的 model-armor extra。该插件随 ADK 一起提供，而 gcp extra 会提供它所需的 google-cloud-modelarmor 客户端。

与智能体一起使用¶

在 App 上注册插件，并指定它应使用的筛查模板：

from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.integrations.model_armor import ModelArmorConfig
from google.adk.integrations.model_armor import ModelArmorPlugin

agent = LlmAgent(
    model="gemini-flash-latest",
    name="screened_agent",
    instruction="你是一个得力助手。",
)

app = App(
    name="model_armor_demo",
    root_agent=agent,
    plugins=[
        ModelArmorPlugin(
            config=ModelArmorConfig(
                prompt_template_name=(
                    "projects/my-project/locations/us-central1/templates/my-prompt-template"
                ),
                response_template_name=(
                    "projects/my-project/locations/us-central1/templates/my-response-template"
                ),
            )
        )
    ],
)

模板名称必须是 projects/{project}/locations/{location}/templates/{template} 形式的完整资源路径。插件会从路径中读取区域以选择区域端点，因此两个模板必须位于同一区域。使用简短名称或区域不匹配的一对名称会在构造插件时抛出 ValueError。

每个模板都是可选的，只设置其中一个则只筛查该方向：

config = ModelArmorConfig(
    prompt_template_name=(
        "projects/my-project/locations/us-central1/templates/my-prompt-template"
    ),
)

筛查覆盖最近的用户内容和模型的回复。工具结果以 function_response 部件的形式进入请求，插件会跳过它们。

配置¶

选项	默认值	描述
`prompt_template_name`	`None`	用于筛查用户输入的模板。未设置表示不筛查输入。
`response_template_name`	`None`	用于筛查模型输出的模板。未设置表示不筛查输出。
`input_blocked_message`	见下文	阻止用户输入时显示的替换文本。
`output_blocked_message`	见下文	阻止模型输出时显示的替换文本。
`block_on_screening_failure`	`True`	是否阻止无法完成筛查的内容。

两条消息的默认值都是 "I'm sorry, but I can't help with that request."，并且你必须至少设置一个模板名称，否则配置会抛出验证错误。

当 Model Armor 调用抛出异常，或服务返回 SUCCESS 以外的任何判定结果时，筛查即视为失败。默认情况下会阻止未经筛查的内容。设置 block_on_screening_failure=False 可在 Model Armor 不可用时让智能体继续回答。

被阻止的轮次会带上 custom_metadata['model_armor_blocked']，因此应用程序可以区分策略阻止与真实回答。

ADK 的 Model Armor 插件¶

用例¶

前提条件¶

安装¶

与智能体一起使用¶

配置¶

其他资源¶