Modération

Moderation est une capacité de sécurité du contenu appelable qui classe du texte selon les catégories haine, harcèlement, automutilation, violence et d'autres catégories nuisibles. Elle est complémentaire de la couche de prévention des pertes de données (DLP) intégrée à la plateforme — et ne la remplace jamais.

Un pipeline typique combine les deux : la DLP retire les PII de l'entrée avant qu'elle ne quitte votre tenant ; la modération évalue ensuite le contenu obtenu au regard de votre politique.

Appeler la capacité

Avec un jeton capabilities:write (compte de service ou session de notebook), appelez l'opération de modération typée de Base Platform :

curl -X POST "https://<your-host>/api/platform/v1/ai/moderation/evaluate" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "input": "This is the text to classify."
  }'

Entrée par lot : passez un tableau ; les résultats sont alignés par index :

curl -X POST "https://<your-host>/api/platform/v1/ai/moderation/evaluate" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "input": [
      "First message to classify.",
      "Second message to classify."
    ]
  }'

Surcharge facultative du modèle :

{
  "input": "...",
  "model": "omni-moderation-latest"
}

409 — non configuré

L'API renvoie une erreur Platform typée CAPABILITY_NOT_CONFIGURED.

Cela signifie que l'organisation n'a activé aucune extension de modération. Un administrateur d'organisation peut en ajouter une sous Settings → Platform → Extensions. Voir Configuration du fournisseur ci-dessous.

Forme de la réponse

{
  "results": [
    {
      "flagged": true,
      "categories": {
        "hate": false,
        "violence": true,
        "self-harm": false
      },
      "categoryScores": {
        "hate": 0.01,
        "violence": 0.93,
        "self-harm": 0.02
      },
      "orgVerdict": "fail",
      "triggeredCategories": ["violence"]
    }
  ],
  "provider": "openai",
  "model": "omni-moderation-latest",
  "usage": { "inputTokens": 8 },
  "executionId": "exec_..."
}

Champs

Sémantique de orgVerdict

Le orgVerdict est la décision que la politique de l'organisation (voir Configurer la politique) prend au sujet de ce résultat — indépendamment du signal flagged du fournisseur.

La plateforme évalue orgVerdict exactement dans cet ordre, en s'arrêtant à la première correspondance :

1. Aucune politique configurée — le verdict reflète le signal flagged du fournisseur (true → "fail", false → "pass").
2. Seuil atteint — toute catégorie configurée dont le score est ≥ à son seuil → "fail" (les catégories déclenchées sont listées dans triggeredCategories).
3. Signalement fournisseur non couvert — aucun seuil ne s'est déclenché, mais le fournisseur a signalé au moins une catégorie qui n'a aucun seuil configuré et defaultFlagBehavior = "fail" (la valeur par défaut) → "fail" (ces catégories non couvertes sont listées dans triggeredCategories). Une catégorie couverte en dessous de son seuil constitue une dérogation de l'organisation pour cette catégorie uniquement ; une catégorie signalée non couverte peut tout de même échouer ici.
4. Réussite — aucune des conditions ci-dessus n'a été remplie.

Exemple : la politique contient { hate: 0.8 }, le fournisseur renvoie flagged: true avec violence à 0.93 et hate à 0.4. L'étape 2 vérifie hate — 0.4 < 0.8, aucun déclenchement. L'étape 3 constate que violence est signalée par le fournisseur et n'a aucun seuil configuré → orgVerdict: "fail", triggeredCategories: ["violence"]. Le seuil hate: 0.8 était une dérogation de l'organisation pour la haine spécifiquement ; violence a tout de même échoué via defaultFlagBehavior.

SDK Python

Depuis un notebook Marimo ou tout environnement Python disposant du paquet scrydon :

from scrydon import moderation

# Classify one string — returns the list of result dicts by default.
results = moderation.moderate("Text to classify.")
for r in results:
    if r["orgVerdict"] == "fail":
        print("Flagged:", r.get("triggeredCategories", []))

# Batch — results align by index.
results = moderation.moderate(["First text.", "Second text."])

# Optional model override.
results = moderation.moderate("Text.", model="omni-moderation-latest")

# Full response (provider, model, usage) with detail=True.
payload = moderation.moderate("Text.", detail=True)
print(payload["provider"], payload["model"])

Si l'organisation n'a configuré aucune extension de modération, l'appel lève ModerationNotConfiguredError — un administrateur d'organisation peut en activer une sous Settings → Platform → Extensions.

Configuration du fournisseur

Un administrateur d'organisation ajoute une extension de modération depuis Settings → Platform → Extensions → Add extension — lorsqu'aucun fournisseur ne propose encore Moderation, la phrase en haut du catalogue l'indique et nomme les fournisseurs qui l'ajouteraient ; cliquez sur Moderation à cet endroit pour n'afficher que ceux-ci.

OpenAI

Sélectionnez OpenAI et saisissez votre clé d'API. La modération avec OpenAI (omni-moderation-latest) est gratuite — le point de terminaison n'entraîne aucun frais d'utilisation.

Le modèle par défaut est omni-moderation-latest, qui classe le texte et les images. Cette capacité utilise une entrée texte uniquement en v1.

Tout point de terminaison compatible OpenAI

Sélectionnez Generic → OpenAI Compatible, saisissez la Base URL (par ex. https://my-server/v1) et cochez Moderation à l'étape des capacités. La plateforme appelle POST {baseUrl}/moderations et prend en charge les points de terminaison sans clé (sans authentification).

Configurer la politique

Les administrateurs IT régissent la manière dont la modération décide pour toute l'organisation, et pas seulement quel fournisseur la sert.

Accédez à Settings → Governance → DLP → Moderation tab.

Seuils par catégorie

Ajoutez une ligne par catégorie de contenu que vous souhaitez ajuster. Lorsqu'un fournisseur renvoie un score pour cette catégorie, la plateforme le compare à votre seuil :

• Score ≥ seuil → orgVerdict: "fail" (la catégorie apparaît dans triggeredCategories).
• Score inférieur au seuil → orgVerdict: "pass" — une dérogation explicite de l'organisation, même si le fournisseur a signalé cette catégorie.

Les clés de catégorie correspondent à la forme neutre du fournisseur (par ex. "violence", "hate", "self-harm"). Omettez une catégorie de la table pour laisser defaultFlagBehavior la régir.

Comportement par défaut en cas de signalement

Détermine ce qui se passe lorsqu'un fournisseur signale une catégorie (flagged: true) mais que l'organisation n'a aucun seuil configuré pour celle-ci.

Détections de gouvernance

Chaque appel dont au moins un résultat produit orgVerdict: "fail" émet un événement d'audit moderation.policy.hit. Ces événements apparaissent dans Settings → Governance à côté des détections DLP et egress, filtrables par catégorie.

Modération automatique des appels LLM de la plateforme

En plus de la capacité appelable ci-dessus, un administrateur d'organisation peut activer le garde-fou de modération — un juge automatique qui inspecte les appels LLM effectués par la plateforme via ses principaux chemins de traitement (chat, copilot et la plupart des étapes d'agent de workflow) au regard des seuils par catégorie de l'organisation. Certains appels LLM internes à la plateforme, utilisés pour l'ingestion et la condensation des bases de connaissances, sortent du périmètre du garde-fou.

Activer le garde-fou

Accédez à Settings → Governance → DLP → Moderation tab.

Cliquez sur Enable pour activer le garde-fou. La plateforme démarre en mode Audit : le juge s'exécute sur chaque appel du périmètre, les détections sont enregistrées et rien n'est bloqué. Examinez l'onglet Hits pour comprendre votre trafic avant de passer en Enforce.

Lorsque vous avez confiance dans vos seuils, passez en mode Enforce. Les appels bloqués échouent avec LLM_BLOCKED_BY_MODERATION (voir ci-dessous). Vous pouvez revenir au mode Audit à tout moment.

Choisir un juge

Le garde-fou prend en charge deux backends de juge :

Les deux backends appliquent les mêmes seuils de la politique de l'organisation (categoryThresholds, defaultFlagBehavior) et produisent la même sémantique de verdict.

Déploiement en audit d'abord

L'activation du garde-fou démarre toujours en mode Audit. En mode audit, le juge s'exécute sur chaque appel du périmètre, des événements moderation.policy.hit sont émis pour les appels en échec et rien n'est jamais bloqué. Utilisez l'onglet DLP Hits (filtre Moderation) pour observer le volume de détections et ajuster vos seuils avant de passer en Enforce.

Le réglage On judge error (visible en mode Enforce) détermine ce qui se passe si le juge lui-même devient injoignable ou renvoie un verdict mal formé. La valeur par défaut est Block the call — un juge qui ne peut pas répondre échoue en mode fermé. Choisissez Allow and audit si vous préférez la disponibilité à l'application stricte lors de défaillances passagères du juge.

À quoi ressemble un appel bloqué

Lorsque le garde-fou est en mode Enforce et que le juge trouve une catégorie en échec, l'appel LLM est bloqué avant qu'aucun contenu ne soit renvoyé à l'appelant :

HTTP 422 Unprocessable Entity

{
  "error": "llm_blocked_by_moderation",
  "triggeredCategories": ["violence"]
}

• Les surfaces de chat et de copilot reçoivent l'erreur à la place de la réponse du modèle.
• Les étapes d'agent de workflow font échouer l'étape avec cette sentinelle ; l'erreur est visible dans l'interface d'exécution.
• Les appelants notebook et SDK reçoivent la réponse 422.

Réponses en streaming et unaires

Le garde-fou traite différemment les réponses en streaming et les réponses unaires :

• Les réponses unaires (sans streaming) sont jugées avant que la réponse ne soit délivrée à l'appelant. En mode Enforce, une réponse en échec est retenue et l'appelant reçoit llm_blocked_by_moderation.
• Les réponses en streaming sont jugées une fois le flux entièrement terminé. Dans tous les modes (Audit et Enforce), une réponse diffusée en échec produit une détection d'audit — elle n'est pas bloquée et n'est pas interrompue. L'interruption en cours de flux est une amélioration prévue.

La section de périmètre de l'onglet Moderation affiche cette réserve directement pour la direction Output.

Détections dans le panneau DLP

Les détections de modération apparaissent dans Settings → Governance → DLP → Hits tab aux côtés des détections DLP et egress. Utilisez la puce de filtre Moderation pour n'afficher que les événements de modération.

Chaque ligne de détection de modération indique la direction (Input / Output), l'action (Audited / Blocked), le backend du juge, et si le texte jugé a été tronqué ou provenait d'un flux. Aucun contenu brut n'est stocké.

Relation avec la DLP

La DLP et la modération sont complémentaires et indépendantes :

• La DLP est obligatoire et appliquée automatiquement à chaque appel de capacité. Elle analyse les entrées à la recherche de secrets, de PII et de motifs d'injection avant qu'elles n'atteignent un fournisseur.
• La modération est appelable et régie par l'organisation. Appelez-la lorsque vous avez spécifiquement besoin d'un score de sécurité du contenu — dans un pipeline qui traite du contenu généré par les utilisateurs, avant d'exposer du texte à un public plus large, ou dans le cadre d'une porte de workflow.

Lorsque le garde-fou de modération est activé, l'ordre entre la DLP et le juge du garde-fou dépend du chemin de dispatch qui traite l'appel. Sur le chemin sans streaming (unaire) — qui couvre la plupart des étapes d'agent de workflow, copilot et le chat sans streaming — la DLP s'exécute sur l'entrée avant le juge du garde-fou, de sorte que le juge voit le contenu après que les secrets et les PII ont déjà été traités par la DLP. Sur le chemin de réponse en streaming qui alimente les réponses de chat en streaming, le traitement des entrées par la DLP n'est pas encore appliqué avant le juge ; le garde-fou audite le flux terminé, mais sur du texte non expurgé. Il s'agit d'une limitation connue et d'une amélioration prévue.

Un même appel peut produire à la fois une ligne d'audit dlp.scan.input (issue de l'analyse de l'entrée par la DLP) et une ligne moderation.policy.hit (issue de l'évaluation du résultat par la politique de l'organisation).