You use Model Armor templates to configure the screening of prompts and responses for your AI applications. The templates provide customized filters and thresholds for multiple safety and security categories. This document explains how to create and manage Model Armor templates. For more information, see Model Armor templates.
Before you begin
Before you begin, complete the following tasks.
Obtain the required permissions
To get the permissions that
you need to manage Model Armor templates,
ask your administrator to grant you the
Model Armor Admin (roles/modelarmor.admin
)
IAM role on Model Armor templates.
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Enable APIs
You must enable Model Armor APIs before you can use Model Armor.
Console
Enable the Model Armor API.
Select the project where you want to activate Model Armor.
gcloud
Before you begin, follow these steps using the Google Cloud CLI with the Model Armor API:
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Run the following command to set the API endpoint for the Model Armor service.
gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"
Replace
LOCATION
with the region where you want to use Model Armor.
Run the following command to enable Model Armor.
gcloud services enable modelarmor.googleapis.com --project=PROJECT_ID
Replace PROJECT_ID
with the ID of the project.
Create a Model Armor template
Model Armor templates define the specific filters and thresholds that Model Armor uses to screen prompts and responses for safety and security risks. To create a Model Armor template, follow these steps:
Console
In the Google Cloud console, go to the Model Armor page.
Verify that you are viewing the project that you activated Model Armor on.
On the Model Armor page, click Create Template. The Create Template page is displayed.
Specify the Template ID. The template ID can have letters, digits, or hyphens. It cannot exceed 63 characters, contain spaces, or start with a hyphen.
Select a Region where the Model Armor templates will run. You cannot change the region later.
Optional: Add Labels. Labels are key-value pairs that you can use to group related templates.
In the Detections section, configure the detection settings.
Optional: If you select Sensitive Data Protection detection, you need to configure the Sensitive Data Protection settings.
In the Responsible AI section, set the confidence level for each content filter
Select Enable multi-language support to use the multi-language detection settings.
Click Create.
gcloud
Run the following command:
gcloud model-armor templates create TEMPLATE_ID --project=PROJECT_ID --___location=LOCATION \
--rai-settings-filters='[{ "filterType": "HATE_SPEECH", "confidenceLevel": "MEDIUM_AND_ABOVE" },{ "filterType": "HARASSMENT", "confidenceLevel": "MEDIUM_AND_ABOVE" },{ "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "MEDIUM_AND_ABOVE" }]' \
--basic-config-filter-enforcement=enabled \
--pi-and-jailbreak-filter-settings-enforcement=enabled \
--pi-and-jailbreak-filter-settings-confidence-level=LOW_AND_ABOVE \
--malicious-uri-filter-settings-enforcement=enabled \
--template-metadata-custom-llm-response-safety-error-code=798 \
--template-metadata-custom-llm-response-safety-error-message="test template llm response evaluation failed" \
--template-metadata-custom-prompt-safety-error-code=799 \
--template-metadata-custom-prompt-safety-error-message="test template prompt evaluation failed" \
--template-metadata-ignore-partial-invocation-failures \
--template-metadata-log-operations \
--template-metadata-log-sanitize-operations
Replace the following:
LOCATION
: the ___location of the template.TEMPLATE_ID
: the ID of the template.PROJECT_ID
: the ID of the project that the template belongs to.
REST
Use the following command to create a new Model Armor template.
curl -X POST \
-d "{'FILTER_CONFIG': {} }" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"
Replace the following:
FILTER_CONFIG
: the filter configuration for the template.PROJECT_ID
: the ID of the project that the template belongs to.TEMPLATE_ID
: the ID of the template to be created.LOCATION
: the ___location of the template.
The following example shows the Model Armor template
configuration. In this example, the Responsible AI filters are configured for hate speech, harassment, dangerous content, and sexually explicit content with varying
confidence levels.
The prompt injection and jailbreak detection filter is enabled with a LOW_AND_ABOVE
confidence level which means any content with a likelihood
of low, medium, or high will be flagged. The malicious URI filter is enabled.
export FILTER_CONFIG='{
"filterConfig": {
"raiSettings": {
"raiFilters": [{
"filterType": "HATE_SPEECH",
"confidenceLevel": "MEDIUM_AND_ABOVE"
}, {
"filterType": "HARASSMENT",
"confidenceLevel": "HIGH"
}, {
"filterType": "DANGEROUS",
"confidenceLevel": "MEDIUM_AND_ABOVE"
},{
"filterType": "SEXUALLY_EXPLICIT",
"confidenceLevel": "MEDIUM_AND_ABOVE"
}]
},
"piAndJailbreakFilterSettings": {
"filterEnforcement": "ENABLED",
"confidenceLevel": "LOW_AND_ABOVE"
},
"maliciousUriFilterSettings": {
"filterEnforcement": "ENABLED"
}
}
}'
curl -X POST \
-d "$FILTER_CONFIG" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/templates?template_id=TEMPLATE_ID"
To create a Model Armor template with multi-language detection
enabled, you need to pass the TEMPLATE_CONFIG
parameter in your command.
This parameter defines the configuration for the language detection settings.
Use the following command to create a new Model Armor template with multi-language detection enabled.
curl -X POST \
-d "{'TEMPLATE_CONFIG': {} }" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"
The following example shows the Model Armor template configuration with multi-language detection enabled.
export TEMPLATE_CONFIG='{
"filterConfig": {
"raiSettings": {
"raiFilters": [{
"filterType": "HATE_SPEECH",
"confidenceLevel": "MEDIUM_AND_ABOVE"
}, {
"filterType": "HARASSMENT",
"confidenceLevel": "HIGH"
}, {
"filterType": "DANGEROUS",
"confidenceLevel": "MEDIUM_AND_ABOVE"
},{
"filterType": "SEXUALLY_EXPLICIT",
"confidenceLevel": "MEDIUM_AND_ABOVE"
}]
},
"piAndJailbreakFilterSettings": {
"filterEnforcement": "ENABLED",
"confidenceLevel": "LOW_AND_ABOVE"
},
"maliciousUriFilterSettings": {
"filterEnforcement": "ENABLED"
}
},
"templateMetadata": {
"multiLanguageDetectionMetadata": {
"enableMultiLanguageDetection": true
}
}
}'
curl -X POST \
-d "$TEMPLATE_CONFIG" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/templates?template_id=TEMPLATE_ID"
Go
Java
Node.js
PHP
Python
To run this code, first set up a Python development environment and install the Model Armor Python SDK.
Configure detections
Detections are the specific checks that Model Armor performs on prompts and responses. Model Armor offers a flexible system for configuring detections, allowing you to tailor the level of protection for your AI applications. You configure detections when creating templates. Model Armor performs the following detection checks on prompts and responses:
Malicious URL detection: Identifies web addresses (URLs) that are designed to harm users or systems. These URLs might lead to phishing sites, malware downloads, or other cyberattacks. For more information, see Malicious URL detection.
Prompt injection and jailbreak detection: Detects malicious content and jailbreak attempts in a prompt. For stricter enforcement, set the confidence level to Low and above to detect most content that is likely to be a prompt injection and jailbreak attempt. For more information, see Prompt injection and jailbreak detection.
Sensitive Data Protection: Detects sensitive data and helps prevent its accidental exposure from attacks like prompt injection. For more information, see Sensitive Data Protection.
Set Sensitive Data Protection settings
Model Armor leverages Sensitive Data Protection to identify and prevent the exposure of sensitive information in your LLM interactions. For more information, see Sensitive Data Protection.
Model Armor offers two modes for configuring Sensitive Data Protection:
Basic: A simpler approach that uses predefined infoTypes to detect sensitive data. For more information about the predefined infoType, see Basic Sensitive Data Protection configuration.
Advanced: A more configurable option that uses an inspection template defined in the Sensitive Data Protection service as a single source for sensitive data infoTypes.
If you select the Advanced mode, you need to specify the following parameters:
Inspect template: Templates for saving configuration information for inspection scan jobs, including what predefined or custom detectors to use. Enter the template name in the following format:
projects/projectName/locations/locationID/inspectTemplates/templateName
Optional: De-identify template: Templates for saving configuration information for de-identification jobs, including both infoType and structured dataset transformations. Enter an identifier for the de-identification template in the following format:
projects/projectName/locations/locationID/deidentifyTemplates/templateName
Verify that the Inspect template and De-identify template exist
in Sensitive Data Protection. If the template resides in a
different project, the Model Armor service agent must be
granted the DLP User role
(roles/dlp.user
) and DLP Reader role
(roles/dlp.reader
) for that project.
Set confidence level
Confidence level represents how likely the findings match a content filter type. You can set the confidence level for each content filter. The possible values are as follows:
- None: No content type is detected.
- Low and above: Content is detected with a low, medium, or high confidence level.
- Medium and above: Content is detected with a medium or high confidence level.
- High: Content is detected with a high confidence level.
For stricter enforcement, set the confidence level to Low and above to detect most content that falls into a content filter type. You can also select the confidence level
To enable comprehensive logging on a template, see Model Armor audit and platform logging.
View a Model Armor template
View existing templates to understand what configurations are available and to troubleshoot and resolve problems with screening prompts and responses.
Console
In the Google Cloud console, go to the Model Armor page.
Verify that you are viewing the project that you activated Model Armor on. The Model Armor page is displayed listing the templates created for your project.
Click any template from the list to view its details.
gcloud
Run the following command:
gcloud model-armor templates describe TEMPLATE_ID --project=PROJECT_ID --___location=LOCATION
Replace the following:
LOCATION
: the ___location of the template.TEMPLATE_ID
: the ID of the template.PROJECT_ID
: the ID of the project that the template belongs to.
REST
Run the following command:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://modelarmor.LOCATION_ID.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
Replace the following:
PROJECT_ID
: the ID of the project that the template belongs to.TEMPLATE_ID
: the ID of the template to be viewed.LOCATION
: the ___location of the template.
Go
Java
Node.js
PHP
Python
To run this code, first set up a Python development environment and install the Model Armor Python SDK.
Update a Model Armor template
Regularly update your templates to maintain a robust and effective security posture for your AI applications.
Console
In the Google Cloud console, go to the Model Armor page.
Verify that you are viewing the project that you activated Model Armor on. The Model Armor page is displayed listing the templates created for your organization.
Click the template that you want to update from the list. The Template details page is displayed.
Click Edit.
Update the required parameters and click Save.
gcloud
Run the following command:
gcloud model-armor templates update TEMPLATE_ID --project=PROJECT_ID --___location=LOCATION
Replace the following:
LOCATION
: the ___location of the template.TEMPLATE_ID
: the ID of the template.PROJECT_ID
: the ID of the project that the template belongs to.
REST
Run the following command:
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d "$FILTER_CONFIG" \ "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID?updateMask=FILTER_CONFIG"
Replace the following:
PROJECT_ID
: the ID of the project that the template belongs to.LOCATION
: the ___location of the template.TEMPLATE_ID
: the ID of the template.FILTER_CONFIG
: the JSON representation of the filter configuration.
All other fields are immutable. Attempts made to update other fields (for example, attempts to update the template name) result in an error.
Go
Java
Node.js
PHP
Python
To run this code, first set up a Python development environment and install the Model Armor Python SDK.
Delete a Model Armor template
Delete a template when it is no longer being used, is replaced by a new template, or when the security policies change.
Console
In the Google Cloud console, go to the Model Armor page.
Verify that you are viewing the project that you activated Model Armor on. The Model Armor page is displayed listing the templates created for your organization.
Click the template that you want to delete from the list. The Template details page is displayed.
Click Delete. A confirmation dialog is displayed.
Enter the template name to confirm the deletion and click Delete.
gcloud
Run the following command:
gcloud model-armor templates delete TEMPLATE_ID --project=PROJECT_ID --___location=LOCATION
Replace the following:
LOCATION
: the ___location of the template.TEMPLATE_ID
: the ID of the template.PROJECT_ID
: the ID of the project that the template belongs to.
REST
Run the following command:
curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://modelarmor.LOCATION_ID.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
Replace the following:
PROJECT_ID
: the ID of the project that the template belongs to.LOCATION
: the ___location of the template.TEMPLATE_ID
: the ID of the template.
Go
Java
Node.js
PHP
Python
To run this code, first set up a Python development environment and install the Model Armor Python SDK.
Templates metadata
Model Armor template metadata helps you configure the behavior of Model Armor, including safety and security checks handling, error handling, and logging behavior.
The template metadata for Model Armor includes the following fields:
Metadata | Type | Description |
---|---|---|
multiLanguageDetection | Boolean | Enables multi-language detection. |
enforcement_type | Enum |
Defines the enforcement type. Use one of the following values:
|
log_template_operations | Boolean | Enables logging of template operations. |
log_sanitize_operations | Boolean | Enables logging of sanitize operations. |
What's next
- Learn about Model Armor overview.
- Learn about Model Armor floor settings.
- Sanitize prompts and responses.
- Troubleshoot Model Armor issues.