Gestion des sujets

1. Définissez vos sujets. Donnez un nom à chaque sujet. Ajoutez une description pour clarifier sa portée et des exemples étiquetés pour illustrer le texte qui correspond ou ne correspond pas.
2. Soumettre la configuration du texte et du sujet. Incluez le texte dans multimodalInput, ajoutez guardrailConfigs.topicConfig et sélectionnez une version de système Guardrails prise en charge.
3. Lisez les résultats. Utilisez results.topicModeration.topics pour rechercher le résultat de chaque sujet configuré. Plusieurs sujets peuvent correspondre au même texte.
4. Appliquer la politique de votre application. Par exemple, votre application peut autoriser l'interaction, rediriger l'utilisateur vers un sujet pris en charge ou empêcher la transmission du contenu à un modèle ou à un utilisateur.

Pour évaluer une entrée utilisateur, soumettez-la avant de l'envoyer au modèle. Pour évaluer une sortie de modèle, soumettez cette sortie en tant que texte dans une demande ApplyGuardrails distincte avant de l'afficher.

Une correspondance de sujet identifie l'objet du texte. Cela ne signifie pas que le texte est dangereux, et le résultat ne bloque pas automatiquement une demande d'inférence. Votre application détermine les sujets nécessitant une action.

Envoyer des demandes au point d'extrémité existant :

POST /20231130/actions/applyGuardrails

Pour connaître la signature des demandes et l'intégralité du contrat d'API, consultez la page ApplyGuardrails.

• Réglez guardrailVersionConfig.guardrailVersion à 1.2.0 ou à une version prise en charge ultérieure. La gestion des sujets nécessite une sélection de version explicite. Utilisez ListGuardrailVersions pour vérifier les versions, les descriptions et les états de cycle de vie disponibles. Voir Flux de sélection de version pour obtenir la liste des exigences et la sélection de la version PATCH. La version du système Guardrails est distincte de la version de l'API dans le chemin du point d'extrémité et de la version de la trousse SDK.
• Incluez exactement un élément TEXT dans multimodalInput et placez le texte à classer dans content. Le champ languageCode est facultatif. Si vous le fournissez, utilisez en ou une variante régionale anglaise telle que en-US.
• Omettre input. Lorsque topicConfig est fourni, input inclus entraîne HTTP 400, même si multimodalInput est également fourni.
• Ajoutez topicConfig sous guardrailConfigs. Indiquez au moins un sujet dans topicConfig.topics.
• Indiquez l'OCID de votre compartiment dans compartmentId.

La gestion des sujets évalue uniquement le texte anglais. Si la demande contient également des images, la classification des sujets les ignore. Les demandes d'image seulement, les éléments de texte multiples et les codes de langue non valides ou non anglais ne sont pas pris en charge pour la classification de sujet. L'omission de languageCode est autorisée.

Vous pouvez inclure des configurations de modération de contenu, de détection d'injection d'invite et de détection d'informations d'identification personnelle dans la même demande. L'ajout de la gestion des sujets ne modifie pas ces protections. Si vous omettez topicConfig, le comportement de la demande existante est conservé et la réponse n'inclut pas results.topicModeration.

Définissez les sujets dans guardrailConfigs.topicConfig.topics. Facultativement, ajoutez des exemples étiquetés dans guardrailConfigs.topicConfig.fewShotExamples.

Par exemple, si vos sujets sont Exhibit Loans et After-Hours Access, chaque exemple doit contenir les deux clés dans son objet classification, même si un seul sujet s'applique.

La validation de nom en double compare les noms de sujet. Il ne rejette pas les sujets uniquement parce que leurs significations se chevauchent. Par exemple, les noms qui diffèrent uniquement en cas de lettre sont des doublons, mais les noms différents ayant une signification similaire ne sont pas automatiquement des doublons.

Pour clarifier vos définitions :

• Utilisez des noms et des descriptions de sujet spécifiques. Par exemple, les prêts pour l'annexe sont plus spécifiques que les expositions si vous souhaitez détecter les demandes d'emprunt d'objets de musée pour affichage dans un autre lieu.
• Utilisez les descriptions pour expliquer la portée prévue et distinguer les sujets connexes.
• Fournissez des exemples représentatifs avec des étiquettes cohérentes. Étiquetez chaque sujet pour chaque exemple.
• Effectuez un test avec du texte correspondant, du texte non correspondant et du texte pouvant correspondre à plusieurs sujets. Précisez les descriptions et les exemples en fonction des résultats.

Les exemples guident la classification de la demande courante. Pour évaluer une définition révisée, envoyez une autre demande avec la configuration de sujet révisée.

Cet exemple montre comment vérifier un message à un assistant de musée fictif pour les prêts d'exposition et l'accès en dehors des heures d'ouverture. L'application peut utiliser une correspondance pour renvoyer la demande au personnel du musée. Remplacez <your-compartment-ocid> par l'OCID de votre compartiment.

{
  "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>"
}

Cette demande active uniquement la classification des sujets. Pour évaluer le même texte avec d'autres protections, ajoutez leurs objets de configuration à côté de topicConfig. Voir Utilisation de l'API ApplyGuardrails.

Lorsque la classification de sujet réussit, results.topicModeration.topics contient un résultat pour chaque sujet configuré, dans le même ordre que la demande. Les sujets qui ne correspondent pas sont inclus.

Le score est un résultat de classification binaire, pas un score de confiance gradué. Le résultat classe le texte global et ne retourne pas le texte mis en correspondance, les décalages ou les longueurs.

La réponse illustrative suivante présente les deux rubriques correspondant au message de l'exemple :

{
  "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"
  }
}

Votre application peut agir sur l'un ou l'autre match selon sa politique. Pour un sujet qui ne correspond pas, la réponse inclut toujours son nom avec score: 0.0 et isMatched: "false".

Vérifiez que votre demande comprend une version du système Guardrails prise en charge et qu'elle répond aux exigences de sujet et d'entrée. La prise en charge de input, d'une demande d'image seulement, de plusieurs éléments de texte, d'un code de langue non valide ou non anglais, ou d'une version de garde-corps non prise en charge entraîne l'utilisation de HTTP 400. Vous pouvez omettre languageCode.

Si les résultats ne reflètent pas les rubriques souhaitées, consultez les descriptions des rubriques et les exemples d'étiquettes. Testez les définitions révisées avec du texte d'application représentatif avant d'utiliser les résultats pour appliquer votre politique.