Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
Die Richtlinie „SanitizeModelResponse“ schützt KI-Clients vor schädlichen oder anstößigen Inhalten, indem Antworten von generativen KI-Modellen bereinigt werden. In der Richtlinie wird Model Armor verwendet, um Modellantworten auf derartige Inhalte zu prüfen und so einen nativen Schutz für KI-Clients und ‑Arbeitslasten mit Apigee herzustellen. Model Armor ist ein Dienst von Google Cloud , der KI-Sicherheitsmaßnahmen bietet, um die Risiken zu minimieren, die mit Large Language Models (LLMs) verbunden sind.
Diese Richtlinie wird in Verbindung mit der Richtlinie „SanitizeUserPrompt“ verwendet.
Diese Richtlinie ist eine erweiterbare Richtlinie, deren Verwendung je nach Apigee-Lizenz Auswirkungen auf die Kosten oder die Nutzung haben kann. Informationen zu Richtlinientypen und Auswirkungen auf die Nutzung finden Sie unter Richtlinienkategorien und -typen.
Hinweis
Bevor Sie die Richtlinie „SanitizeModelResponse“ verwenden können, müssen Sie die folgenden Aufgaben ausführen:
- Erstellen Sie eine Model Armor-Vorlage. Dieser Schritt muss abgeschlossen sein, bevor Sie eine Richtlinie „SanitizeModelResponse“ erstellen.
- Legen Sie den API-Endpunkt für den Model Armor-Dienst fest.
Erforderliche Rollen
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Dienstkonto zuzuweisen, mit dem Sie Apigee-Proxys bereitstellen, um die Berechtigungen zu erhalten, die Sie zum Anwenden und Verwenden der Richtlinie „SanitizeModelResponse“ benötigen:
- Model Armor User (
roles/modelarmor.user
) - Model Armor Viewer (
roles/modelarmor.viewer
)
Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.
Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.
APIs aktivieren
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.
Element <SanitizeModelResponse>
Definiert eine Richtlinie „SanitizeModelResponse“.
Standardwert | Siehe Tab Standardrichtlinie unten. |
Erforderlich? | Erforderlich |
Typ | Komplexes Objekt |
Übergeordnetes Element | – |
Untergeordnete Elemente |
<DisplayName> <IgnoreUnresolvedVariables> <TemplateName> <UserPromptSource> <LLMResponseSource> |
Das Element <SanitizeModelResponse>
verwendet die folgende Syntax:
Syntax
<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>
Standardrichtlinie
Das folgende Beispiel zeigt die Standardeinstellungen, die gelten, wenn Sie Ihrem Anfrageablauf in der Apigee-Benutzeroberfläche eine Richtlinie „SanitizeModelResponse“ hinzufügen:
<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>
Wenn Sie eine neue Richtlinie „SanitizeModelResponse“ über die Apigee-Benutzeroberfläche einfügen, enthält die Vorlage Stubs für alle möglichen Vorgänge. Informationen zu den erforderlichen Elementen finden Sie unten.
Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:
Attribut | Standard | Erforderlich? | Beschreibung |
---|---|---|---|
name |
- | Erforderlich |
Der interne Name der Richtlinie. Der Wert des Attributs Optional können Sie das Element |
continueOnError |
false | Optional | Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen:
|
enabled |
wahr | Optional | Setzen Sie den Wert auf true , um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist. |
async |
false | Verworfen | Dieses Attribut wurde verworfen. |
Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <SanitizeModelResponse>
:
Untergeordnetes Element | Erforderlich? | Beschreibung |
---|---|---|
<DisplayName> |
Optional | Der Name der Richtlinie. |
<IgnoreUnresolvedVariables> |
Optional | Gibt an, ob die Verarbeitung beendet wird, wenn die für den Vorlagennamen oder die Model Armor-Nutzlast verwendete Variable nicht aufgelöst werden kann. |
<TemplateName> |
Erforderlich | Die Model Armor-Vorlage, die zum Bereinigen der LLM-Antwort verwendet wird.
Die folgenden Apigee-Ablaufvariablen können verwendet werden, um mit diesem Wert eine Vorlage zu erstellen: projects/{organization.name}/locations/{system.region.name}/templates/{id} |
<UserPromptSource> |
Erforderlich | Der Speicherort der Nutzlast, aus der der Text für den Nutzer-Prompt extrahiert werden soll. Es werden nur String-Textwerte unterstützt.
Dieses Feld unterstützt die Apigee-Syntax für Nachrichtenvorlagen, einschließlich der Verwendung von Variablen oder JSON-Pfadfunktionen. {jsonpath('$.contents[-1].parts[-1].text',request.content,false)} |
<LLMResponseSource> |
Erforderlich | Der Speicherort der Nutzlast, aus der der LLM-Antworttext extrahiert werden soll. Es werden nur String-Textwerte unterstützt.
Dieses Feld unterstützt die Apigee-Syntax für Nachrichtenvorlagen, einschließlich der Verwendung von Variablen oder JSON-Pfadfunktionen. {jsonpath('$.input.prompt.text',request.content,false)} |
Referenz zu untergeordneten Elementen
In diesem Abschnitt werden die untergeordneten Elemente von <SanitizeModelResponse>
beschrieben.
<DisplayName>
Wird zusätzlich zum Attribut name
verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen, natürlicher klingenden Namen zu versehen.
Das Element <DisplayName>
ist für alle Richtlinien gleich.
Standardwert | – |
Erforderlich? | Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet. |
Typ | String |
Übergeordnetes Element | <PolicyElement> |
Untergeordnete Elemente | Keine |
Das <DisplayName>
-Element verwendet die folgende Syntax:
Syntax
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
Beispiel
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
Das <DisplayName>
-Element hat keine Attribute oder untergeordneten Elemente.
<IgnoreUnresolvedVariables>
Bestimmt, ob die Verarbeitung beendet wird, wenn eine Variable nicht aufgelöst werden kann. Legen Sie sie auf true
fest, um nicht aufgelöste Variablen zu ignorieren und die Verarbeitung fortzusetzen.
Standardwert | False |
Erforderlich? | Optional |
Typ | Boolescher Wert |
Übergeordnetes Element |
<SanitizeModelResponse>
|
Untergeordnete Elemente | Keine |
<TemplateName>
Die Model Armor-Vorlage.
Standardwert | – |
Erforderlich? | Erforderlich |
Typ | String |
Übergeordnetes Element |
<SanitizeModelResponse>
|
Untergeordnete Elemente | Keine |
Das Element <TemplateName>
verwendet die folgende Syntax:
Syntax
<ModelArmor> <TemplateName>projects/{project}/locations/{location}/templates/{template-name}</TemplateName> </ModelArmor>
Beispiel
In diesem Beispiel werden Apigee-Ablaufvariablen verwendet, um die erforderlichen Informationen automatisch einzufügen.
<ModelArmor> <TemplateName>projects/{organization.name}/locations/{system.region.name}/templates/{id}</TemplateName> </ModelArmor>
<UserPromptSource>
Der Speicherort der Nutzlast, aus der der Text für den Nutzer-Prompt extrahiert werden soll. Es werden nur String-Textwerte unterstützt.
Dieses Feld unterstützt die Apigee-Syntax für Nachrichtenvorlagen, einschließlich der Verwendung von Variablen oder JSON-Pfadfunktionen. Beispiel:
{jsonpath('$.input.prompt.text',request.content,false)}
Standardwert | {jsonPath('$.contents[-1].parts[-1].text',request.content,true)} |
Erforderlich? | Erforderlich |
Typ | String |
Übergeordnetes Element |
<SanitizeModelResponse>
|
Untergeordnete Elemente | Keine |
<LLMResponseSource>
Der Speicherort der Nutzlast, aus der die LLM-Antwort extrahiert werden soll. Es werden nur String-Textwerte unterstützt.
Dieses Feld unterstützt die Apigee-Syntax für Nachrichtenvorlagen, einschließlich der Verwendung von Variablen oder JSON-Pfadfunktionen. Beispiel:
{jsonpath('$.input.prompt.text',request.content,false)}
Standardwert | {jsonPath($.candidates[-1].content.parts,response.content,true)} |
Erforderlich? | Erforderlich |
Typ | String |
Übergeordnetes Element |
<SanitizeModelResponse>
|
Untergeordnete Elemente | Keine |
Ablaufvariablen
Ablaufvariablen können verwendet werden, um das dynamische Laufzeitverhalten für Richtlinien und Abläufe auf der Grundlage von HTTP-Headern, Nachrichteninhalten oder dem Kontext zu konfigurieren, der im Ablauf verfügbar ist. Weitere Informationen zu Ablaufvariablen finden Sie in der Referenz zu Ablaufvariablen.
Diese Richtlinie stellt während der Ausführung die folgenden schreibgeschützten Ablaufvariablen bereit. Sie können diese Ablaufvariablen mit der Richtlinie „DataCapture“ verwenden, um benutzerdefinierte Analyseberichte zu erstellen. Weitere Informationen finden Sie unter Benutzerdefinierte Daten mit der Data Capture-Richtlinie erfassen.
Variablenname | Beschreibung |
---|---|
SanitizeModelResponse.POLICY_NAME.templateUsed |
Gibt an, welche Model Armor-Vorlage verwendet wird. Beispiel: projects/myproject/locations/us-west1/templates/mytemplate |
SanitizeModelResponse.POLICY_NAME.userPrompt |
Gibt den Prompt-Inhalt für den Bereinigungsaufruf von Model Armor an. |
SanitizeModelResponse.POLICY_NAME.modelResponse |
Gibt den Inhalt der LLM-Antwort für den Bereinigungsaufruf von Model Armor an. |
SanitizeModelResponse.POLICY_NAME.responseFromModelArmor |
Gibt die JSON-Antwort von Model Armor an. |
SanitizeModelResponse.POLICY_NAME.filterMatchState |
Gibt an, ob mit dem Filter Ergebnisse gefunden wurden. Gültige Werte sind MATCH_FOUND und NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.invocationResult |
Gibt das Ergebnis des Aufrufs an, unabhängig davon, ob Ergebnisse gefunden wurden. Gültige Werte:
|
SanitizeModelResponse.POLICY_NAME.raiFilterResult.executionState |
Gibt das Ergebnis der Ausführung des RAI-Filters an. Gültige Werte sind EXECUTION_SUCCESS und EXECUTION_SKIPPED . |
SanitizeModelResponse.POLICY_NAME.raiFilterResult.matchState |
Gibt an, ob mit dem RAI-Filter Ergebnisse gefunden wurden. Gültige Werte sind MATCH_FOUND und NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.executionState |
Gibt das Ergebnis der Ausführung des SDP-Filters zur Prüfung an. Gültige Werte sind EXECUTION_SUCCESS und EXECUTION_SKIPPED . |
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.inspectResult.matchState |
Gibt an, ob mit dem SDP-Filter zur Prüfung Ergebnisse gefunden wurden. Gültige Werte sind MATCH_FOUND und NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.executionState |
Gibt das Ergebnis der Ausführung des SDP-Filters zur De-Identifikation an. Gültige Werte sind EXECUTION_SUCCESS und EXECUTION_SKIPPED . |
SanitizeModelResponse.POLICY_NAME.sdpFilterResult.deidentifyResult.matchState |
Gibt an, ob mit dem SDP-Filter zur De-Identifikation Ergebnisse gefunden wurden. Gültige Werte sind MATCH_FOUND und NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.executionState |
Gibt das Ergebnis der Ausführung des Prompt-Injection- und Jailbreaking-Filters an. Gültige Werte sind EXECUTION_SUCCESS und EXECUTION_SKIPPED . |
SanitizeModelResponse.POLICY_NAME.piAndJailbreakFilterResult.matchState |
Gibt an, ob mit dem Prompt-Injection- und Jailbreaking-Filter Ergebnisse gefunden wurden. Gültige Werte sind MATCH_FOUND und NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.executionState |
Gibt den Status der Ausführung des Filters für Darstellungen des sexuellen Missbrauchs von Kindern an. Gültige Werte sind EXECUTION_SUCCESS und EXECUTION_SKIPPED . |
SanitizeModelResponse.POLICY_NAME.csamFilterFilterResult.matchState |
Gibt an, ob mit dem Filter für Darstellungen des sexuellen Missbrauchs von Kindern Ergebnisse gefunden wurden. Gültige Werte sind MATCH_FOUND und NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.executionState |
Gibt den Status Ausführung des Filters für schädliche URIs an. Gültige Werte sind EXECUTION_SUCCESS und EXECUTION_SKIPPED . |
SanitizeModelResponse.POLICY_NAME.maliciousUriFilterResult.matchState |
Gibt an, ob mit dem Filter für schädliche URIs Ergebnisse gefunden wurden. Gültige Werte sind MATCH_FOUND und NO_MATCH_FOUND . |
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorCode |
Benutzerdefinierter überschriebener Fehlercode, falls in der Model Armor-Antwort vorhanden. |
SanitizeModelResponse.POLICY_NAME.sanitizationMetadata.errorMessage |
Benutzerdefinierter überschriebener Fehlercode, falls in der Model Armor-Antwort vorhanden. |
SanitizeModelResponse.POLICY_NAME.csamFilterMatched/code> |
Boolescher Wert, der angibt, ob mit dem Filter für Darstellungen des sexuellen Missbrauchs von Kindern Ergebnisse gefunden wurden. |
SanitizeModelResponse.POLICY_NAME.maliciousURIs |
Angehängte Liste der schädlichen URIs, die vom Filter für schädliche URIs erkannt wurden. |
SanitizeModelResponse.POLICY_NAME.maliciousURIsDetected |
Boolescher Wert, der angibt, ob mit dem Filter für schädliche URIs Ergebnisse gefunden wurden. |
SanitizeModelResponse.POLICY_NAME.matchesFound |
Boolescher Wert, der angibt, ob mit einem der Filter Ergebnisse gefunden wurden. |
SanitizeModelResponse.POLICY_NAME.promptInjectionDetected |
Boolescher Wert, der angibt, ob mit dem Prompt-Injection-Filter Ergebnisse gefunden wurden. |
SanitizeModelResponse.POLICY_NAME.promptInjectionConfidence |
Konfidenzniveau für die Prompt-Injection-Erkennung. |
SanitizeModelResponse.POLICY_NAME.raiMatchesFound |
Boolescher Wert, der angibt, ob mit dem RAI-Filter Ergebnisse gefunden wurden. |
SanitizeModelResponse.POLICY_NAME.requestSentToModelArmor |
Boolescher Wert, der angibt, ob eine Anfrage an Model Armor gesendet wurde. |
SanitizeModelResponse.POLICY_NAME.sanitizeOperation |
Gibt den Vorgang an, der von der Richtlinie ausgeführt wird. Gültige Werte sind SANITIZE_USER_PROMPT und SANITIZE_MODEL_RESPONSE . |
Fehlerreferenz
In diesem Abschnitt werden die zurückgegebenen Fehlercodes und die Fehlervariablen beschrieben, die von Apigee für die Richtlinie <SanitizeModelResponse>
festgelegt werden.
Diese Informationen sind wichtig, wenn Sie Regeln zum Umgang mit Fehlern entwickeln. Weitere Informationen finden Sie unter Wissenswertes über Richtlinienfehler und Umgang mit Fehlern.
Laufzeitfehler
Fehlercode | HTTP-Status | Ursache |
---|---|---|
steps.sanitize.model.response.FilterMatched |
400 |
Dieser Fehler tritt auf, wenn der Nutzer-Prompt die Vorlagenprüfung von Model Armor nicht besteht. |
steps.sanitize.model.response.SanitizationResponseParsingFailed |
500 |
Dieser Fehler tritt auf, wenn die Model Armor-Antwort nicht geparst werden kann. |
steps.sanitize.model.response.FailedToExtractUserPrompt |
500 |
Dieser Fehler tritt auf, wenn die automatische Extraktion des Nutzer-Prompts für den Standardwert fehlschlägt. |
steps.sanitize.model.response.FailedToExtractLLMResponse |
500 |
Dieser Fehler tritt auf, wenn die automatische Extraktion der Modellantwort für den Standardwert fehlschlägt. |
steps.sanitize.model.response.InternalError |
500 |
Dieser Fehler tritt auf, wenn ein interner Serverfehler vorliegt. |
steps.sanitize.model.response.ModelArmorTemplateNameExtractionFailed |
500 |
Dieser Fehler tritt auf, wenn der Vorlagenname nicht aufgelöst werden kann. |
steps.sanitize.model.response.AuthenticationFailure |
500 |
Dieser Fehler tritt auf, wenn das Dienstkonto keine Berechtigung zum Aufrufen der Model Armor API hat. |
steps.sanitize.model.response.ModelArmorAPIFailed |
500 |
Dieser Fehler tritt auf, wenn die Model Armor API einen Fehler ausgibt. |
steps.sanitize.model.response.ModelArmorCalloutError |
500 |
Dieser Fehler tritt auf, wenn der Model Armor API-Aufruf fehlschlägt. |
steps.sanitize.modelarmor.ServiceUnavailable |
500 |
Dieser Fehler tritt auf, wenn der Model Armor-Dienst nicht verfügbar ist. |
Bereitstellungsfehler
Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.
Fehlername | Ursache |
---|---|
The ModelArmor/TemplateName element is required. |
Tritt auf, wenn das Element <TemplateName> in <ModelArmor> nicht vorhanden ist. |
The TemplateName element value is required. |
Tritt auf, wenn der Wert <TemplateName> leer ist. |
Fehlervariablen
Diese Variablen werden festgelegt, wenn die Richtlinie zur Laufzeit einen Fehler auslöst. Weitere Informationen finden Sie unter Wissenswertes über Richtlinienfehler.
Variablen | Definition | Beispiel |
---|---|---|
fault.name="FAULT_NAME" |
FAULT_NAME ist der Name des Fehlers, wie in der obigen Tabelle Laufzeitfehler aufgeführt. Der Fehlername ist der letzte Teil des Fehlercodes. | fault.name Matches "UnresolvedVariable" |
SanitizeModelResponse.POLICY_NAME.failed |
POLICY_NAME ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgegeben hat. | SanitizeModelResponse.sanitize-response.failed = true |
Beispiel für eine Fehlerantwort
{ "fault": { "faultstring": "SanitizeModelResponse[sanitize-response]: unable to resolve variable [variable_name]", "detail": { "errorcode": "steps.sanitizemodelresponse.UnresolvedVariable" } } }
Beispiel für eine Fehlerregel
<FaultRule name="SanitizeModelResponse Faults"> <Step> <Name>SMR-CustomSetVariableErrorResponse</Name> <Condition>(fault.name = "SetVariableFailed")</Condition> </Step> <Condition>(sanitizemodelresponse.failed = true)</Condition> </FaultRule>
Fehlercodes und Fehlermeldungen für Model Armor-Vorlagen
Model Armor-Vorlagen unterstützen das Überschreiben von Fehlercodes und Fehlermeldungen, die von den API-Anfragen der Richtlinie „SanitizeModelResponse“ ausgegeben werden. Wenn der Nutzer Überschreibungen festlegt, werden die Fehlercodes und Fehlermeldungen von Model Armor in die Ablaufvariablen eingefügt.
Eine Antwort mit Model Armor-Fehlercodes und ‑meldungen könnte beispielsweise so aussehen:
{ "sanitizationResult": { "filterMatchState": "MATCH_FOUND", "filterResults": {...}, "sanitizationMetadata": { "errorCode": "890", "errorMessage": "get out" }, "invocationResult": "SUCCESS" } }
Schemas
Jeder Richtlinientyp wird durch ein XML-Schema (.xsd
) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.