Themenverwaltung
Verwenden Sie die Themenverwaltung in OCI Generative AI Guardrails, um Text anhand von Themen zu prüfen, die Sie für Ihre Anwendung definieren.
Das Themenmanagement klassifiziert Text anhand von Themen, die Sie für Ihre Bewerbung definieren, z. B. Ausstellungsdarlehen oder Anfragen, ein Museum außerhalb der Öffnungszeiten zu besuchen.
Ab Guardrails-Systemversion 1.2.0 können Sie Text mit der API ApplyGuardrails anhand von Themen auswerten, die Sie definieren.
Sie senden Themennamen, optionale Beschreibungen und optionale beschriftete Beispiele mit jeder ApplyGuardrails-Anforderung. Der Service wertet den Text für jedes Thema aus und gibt ein Übereinstimmungs- oder Nichtübereinstimmungsergebnis für jedes Thema zurück. Ihre Anwendung verwendet diese Ergebnisse, um zu entscheiden, wie der Inhalt behandelt wird.
Um die Themenverwaltung zu verwenden, nehmen Sie
topicConfig in jede ApplyGuardrails-Anforderung auf. Sie können die Themenverwaltung nicht als Guardrail auswählen, wenn Sie einen Modellendpunkt in der Konsole erstellen oder aktualisieren. Die Themenverwaltung ist nicht über den Pfad der OpenAI-kompatiblen API verfügbar.Themendefinitionen gelten für die aktuelle Anforderung. Der Service erstellt oder speichert sie nicht als wiederverwendbare Themenressourcen. Um eine Themenkonfiguration wiederzuverwenden, behalten Sie sie in Ihrer Anwendung und fügen sie in jede Anforderung ein. Um die ausgewerteten Themen zu ändern, ändern Sie die Konfiguration in nachfolgenden Anforderungen.
Wie das Themenmanagement funktioniert
- Definieren Sie Ihre Themen. Geben Sie jedem Thema einen Namen. Fügen Sie eine Beschreibung hinzu, um den Umfang und beschriftete Beispiele zu verdeutlichen, um Text zu veranschaulichen, der übereinstimmt oder nicht.
- Leiten Sie die Text- und Themenkonfiguration weiter. Fügen Sie den Text in
multimodalInputein, fügen SieguardrailConfigs.topicConfighinzu, und wählen Sie eine unterstützte Guardrails-Systemversion aus. - Lesen Sie die Ergebnisse. Verwenden Sie
results.topicModeration.topics, um das Ergebnis für jedes konfigurierte Thema zu suchen. Mehrere Themen können mit demselben Text übereinstimmen. - Wenden Sie die Policy Ihrer Anwendung an. Beispiel: Ihre Anwendung kann die Interaktion zulassen, den Benutzer an ein unterstütztes Thema umleiten oder verhindern, dass der Inhalt an ein Modell übergeben oder einem Benutzer angezeigt wird.
Um eine Benutzereingabe auszuwerten, leiten Sie sie weiter, bevor Sie sie an das Modell senden. Um eine Modellausgabe auszuwerten, leiten Sie diese Ausgabe als Text in einer separaten ApplyGuardrails-Anforderung weiter, bevor Sie sie anzeigen.
Eine Themenübereinstimmung identifiziert den Betreff des Textes. Dies bedeutet nicht, dass der Text unsicher ist und das Ergebnis eine Inferenzanforderung nicht automatisch blockiert. Ihre Anwendung entscheidet, welche Themen eine Aktion erfordern.
Anforderungen anfordern
Anforderungen an den vorhandenen Endpunkt senden:
POST /20231130/actions/applyGuardrailsInformationen zur Anforderungssignatur und zum vollständigen API-Vertrag finden Sie unter ApplyGuardrails.
- Setzen Sie
guardrailVersionConfig.guardrailVersionauf1.2.0oder eine später unterstützte Version. Für die Themenverwaltung ist eine explizite Versionsauswahl erforderlich. Mit ListGuardrailVersions können Sie die verfügbaren Versionen, Beschreibungen und Lebenszyklusstatus prüfen. Informationen zu Anforderungen und zur Auswahl der PATCH-Version finden Sie unter Workflow zur Versionsauswahl. Die Guardrails-Systemversion ist von der API-Version im Endpunktpfad und der SDK-Version getrennt. - Nehmen Sie genau ein
TEXT-Element inmultimodalInputauf, und setzen Sie den zu klassifizierenden Text incontent. Das FeldlanguageCodeist optional. Wenn Sie es angeben, verwenden Sieenoder eine englische regionale Variante wieen-US. - Lassen Sie
inputaus. WenntopicConfigangegeben wird, einschließlichinput, führt dies zu HTTP 400, auch wennmultimodalInputebenfalls angegeben ist. - Fügen Sie
topicConfigunterguardrailConfigshinzu. Geben Sie mindestens ein Thema intopicConfig.topicsan. - Geben Sie die OCID des Compartments in
compartmentIdan.
Das Themenmanagement bewertet nur englischen Text. Wenn die Anforderung auch Bilder enthält, werden diese bei der Themenklassifizierung ignoriert. Nur-Bild-Anforderungen, mehrere Textelemente und ungültige oder nicht-englische Sprachcodes werden für die Themenklassifizierung nicht unterstützt. Das Weglassen von languageCode ist zulässig.
Sie können Konfigurationen zur Inhaltsmoderation, Prompt-Injection-Erkennung und PII-Erkennung in dieselbe Anforderung aufnehmen. Durch Hinzufügen der Themenverwaltung werden diese Schutzmaßnahmen nicht geändert. Wenn Sie topicConfig weglassen, wird das vorhandene Anforderungsverhalten beibehalten, und die Antwort enthält nicht results.topicModeration.
Themen und Beispiele definieren
Definieren Sie Themen in guardrailConfigs.topicConfig.topics. Fügen Sie optional beschriftete Beispiele in guardrailConfigs.topicConfig.fewShotExamples hinzu.
| Feld | Erforderlich | Anforderungen |
|---|---|---|
topics | Ja | Nehmen Sie 1 bis 25 Themen pro Anfrage auf. |
topics[].name | Ja | Verwenden Sie 1 bis 100 Zeichen, einschließlich mindestens einem Nicht-Leerzeichen. Namen müssen nach dem Trimmen von vor- und nachgestellten Leerzeichen und dem Vergleichen ohne Berücksichtigung der Groß-/Kleinschreibung eindeutig sein. |
topics[].description | Nein | Beschreiben Sie das Thema in bis zu 1.000 Zeichen. |
fewShotExamples | Nein | Nehmen Sie bis zu 15 beschriftete Beispiele auf. |
fewShotExamples[].userText | Ja, für jedes Beispiel | Beispieltext mit 1 bis 1.000 Zeichen. |
fewShotExamples[].classification | Ja, für jedes Beispiel | Fügen Sie einen Eintrag für jedes Thema in die Anforderung ein. Jeder Schlüssel muss genau mit einem weitergeleiteten Themennamen übereinstimmen, einschließlich Groß-/Kleinschreibung. Verwenden Sie die Zeichenfolge "true", wenn das Thema für das Beispiel gilt, und "false", wenn dies nicht der Fall ist. Werte müssen diese kleingeschriebenen Zeichenfolgen sein, nicht boolesche JSON-Werte. Lassen Sie keine Themen aus und fügen Sie keine zusätzlichen Schlüssel hinzu. |
Beispiel: Wenn Ihre Themen Exhibit Loans und After-Hours Access sind, muss jedes Beispiel beide Schlüssel in seinem classification-Objekt enthalten, selbst wenn nur ein Thema zutrifft.
Beispiellabels in
classification und dem Feld isMatched in der Antwort verwenden die kleingeschriebenen Zeichenfolgen "true" und "false".Bei der Validierung von doppelten Namen werden Themennamen verglichen. Es lehnt Themen nicht nur ab, weil sich ihre Bedeutungen überschneiden. Beispiel: Namen, die sich nur in Groß- und Kleinschreibung unterscheiden, sind Duplikate, aber andere Namen mit ähnlicher Bedeutung sind nicht automatisch Duplikate.
So machen Sie Ihre Definitionen klar:
- Verwenden Sie bestimmte Themennamen und Beschreibungen. Beispiel:
Ausstellungsdarlehen
ist spezifischer alsAusstellungen
, wenn Sie Anforderungen zum Ausleihen von Museumsobjekten für die Anzeige an einem anderen Veranstaltungsort ermitteln möchten. - Verwenden Sie Beschreibungen, um den beabsichtigten Geltungsbereich zu erläutern und verwandte Themen zu unterscheiden.
- Stellen Sie repräsentative Beispiele mit konsistenten Labels bereit. Beschriften Sie jedes Thema für jedes Beispiel.
- Testen Sie mit übereinstimmendem Text, nicht übereinstimmendem Text und Text, der mehr als einem Thema entsprechen könnte. Verfeinern Sie Beschreibungen und Beispiele basierend auf den Ergebnissen.
Die Beispiele führen zur Klassifizierung der aktuellen Anforderung. Um eine geänderte Definition auszuwerten, senden Sie eine weitere Anforderung mit der geänderten Themenkonfiguration.
Beispiel für eine Themenmanagementanforderung
In diesem Beispiel wird eine Nachricht an einen fiktiven Museumsassistenten auf Ausstellungsdarlehen und Zugang außerhalb der Öffnungszeiten überprüft. Die Anwendung kann eine Übereinstimmung verwenden, um die Anfrage an das Museumspersonal zu verweisen. Ersetzen Sie <your-compartment-ocid> durch die Compartment-OCID.
{
"multimodalInput": [
{
"type": "TEXT",
"content": "Could our community center borrow the clock exhibit for a local exhibition and collect it after the museum closes?",
"languageCode": "en"
}
],
"guardrailConfigs": {
"topicConfig": {
"topics": [
{
"name": "Exhibit Loans",
"description": "Requests to temporarily borrow museum objects for display at another venue."
},
{
"name": "After-Hours Access",
"description": "Requests to enter museum spaces or collect items outside normal opening hours."
}
],
"fewShotExamples": [
{
"userText": "Can our community center borrow the navigation instruments for a school exhibition?",
"classification": {
"Exhibit Loans": "true",
"After-Hours Access": "false"
}
},
{
"userText": "May the photography club enter the gallery after closing time?",
"classification": {
"Exhibit Loans": "false",
"After-Hours Access": "true"
}
},
{
"userText": "Which gallery displays the restored clock?",
"classification": {
"Exhibit Loans": "false",
"After-Hours Access": "false"
}
}
]
}
},
"guardrailVersionConfig": {
"guardrailVersion": "1.2.0"
},
"compartmentId": "<your-compartment-ocid>"
}Diese Anforderung aktiviert nur die Themenklassifizierung. Um denselben Text mit anderen Schutzfunktionen auszuwerten, fügen Sie die zugehörigen Konfigurationsobjekte neben topicConfig hinzu. Siehe API ApplyGuardrails verwenden.
Erläuterungen zu Themenergebnissen
Wenn die Themenklassifizierung erfolgreich ist, enthält results.topicModeration.topics ein Ergebnis für jedes konfigurierte Thema in derselben Reihenfolge wie die Anforderung. Themen, die nicht übereinstimmen, werden eingeschlossen.
| Feld | Bedeutung |
|---|---|
name | Der Themenname genau wie in der Anforderung angegeben. |
isMatched | Die Zeichenfolge "true", wenn das Thema für den Text gilt, oder "false", wenn dies nicht der Fall ist. |
score | 1.0, wenn isMatched "true" ist, oder 0.0, wenn es "false" ist. Es werden keine Bruchzahlen zurückgegeben. |
Der Score ist ein binäres Klassifizierungsergebnis, kein graduierter Konfidenzscore. Das Ergebnis klassifiziert den Gesamttext und gibt keinen übereinstimmenden Text, keine Offsets oder Längen zurück.
Die folgende illustrative Antwort zeigt beide Themen, die mit der Beispielnachricht übereinstimmen:
{
"results": {
"topicModeration": {
"topics": [
{
"name": "Exhibit Loans",
"score": 1.0,
"isMatched": "true"
},
{
"name": "After-Hours Access",
"score": 1.0,
"isMatched": "true"
}
]
}
},
"guardrailVersion": {
"version": "1.2.0"
}
}Ihre Anwendung kann entsprechend ihrer Policy auf eine Übereinstimmung reagieren. Bei einem Thema, das nicht übereinstimmt, enthält die Antwort weiterhin ihren Namen mit score: 0.0 und isMatched: "false".
Validierung und Fehlerbehebung
Prüfen Sie, ob Ihre Anforderung eine unterstützte Guardrails-Systemversion enthält und die Themen- und Eingabeanforderungen erfüllt. Wenn Sie input, eine Nur-Image-Anforderung, mehrere Textelemente, einen ungültigen oder nicht-englischen Sprachcode oder eine nicht unterstützte Guardrail-Version angeben, wird HTTP 400 angezeigt. Sie können languageCode weglassen.
| Validierungsfehler | Was zu überprüfen ist |
|---|---|
INVALID_TOPIC | Stellen Sie sicher, dass jedes Thema einen nicht leeren Namen hat und dass Namen und Beschreibungen die Längenanforderungen erfüllen. |
DUPLICATE_TOPIC | Prüfen Sie, ob die Namen identisch sind, nachdem Sie die umliegenden Leerzeichen entfernt und ohne Berücksichtigung der Groß-/Kleinschreibung verglichen haben. |
TOPIC_LIMIT_EXCEEDED | Senden Sie nicht mehr als 25 Themen in einer Anfrage. |
INVALID_TOPIC_EXAMPLE | Prüfen Sie die Anzahl und Länge der Beispiele. Jede Klassifizierungszuordnung muss genau die weitergeleiteten Themennamen enthalten, wobei die Zeichenfolge "true" oder "false" für jeden Namen verwendet wird. Boolesche JSON-Werte und andere Zeichenfolgen werden nicht akzeptiert. |
UNSUPPORTED_LANGUAGE | Wenn Sie languageCode angeben, verwenden Sie en oder eine englische regionale Variante. Sie können das Feld auch auslassen. |
UNSUPPORTED_TOPIC_INPUT | Verwenden Sie multimodalInput mit genau einem TEXT-Element. Lassen Sie input aus, und leiten Sie keine Nur-Bild-Anforderung zur Themenklassifizierung weiter. |
Wenn die Ergebnisse nicht Ihre beabsichtigten Themen widerspiegeln, lesen Sie die Themenbeschreibungen und Beispiellabels. Testen Sie geänderte Definitionen mit repräsentativem Anwendungstext, bevor Sie die Ergebnisse zur Durchsetzung Ihrer Policy verwenden.