トピック管理

1. トピックを定義します。 各トピックに名前を付けます。説明を追加して、範囲とラベル付きの例を明確にし、一致するテキストまたは一致しないテキストを示します。
2. テキストおよびトピックの構成を送信します。 multimodalInputにテキストを含めて、guardrailConfigs.topicConfigを追加し、サポートされているGuardrailsシステム・バージョンを選択します。
3. 結果を読みます。 results.topicModeration.topicsを使用して、構成されているすべてのトピックの結果を検索します。複数のトピックが同じテキストと一致する可能性があります。
4. アプリケーションのポリシーを適用します。 たとえば、アプリケーションで相互作用を許可したり、サポートされているサブジェクトにユーザーをリダイレクトしたり、コンテンツがモデルに渡されたり、ユーザーに表示されないようにすることができます。

ユーザー入力を評価するには、モデルに送信する前に送信します。モデル出力を評価するには、その出力を個別のApplyGuardrailsリクエスト内のテキストとして送信してから表示します。

一致するトピックは、テキストの件名を示します。これは、テキストが安全でないことを意味するものではなく、結果によって推論リクエストが自動的にブロックされることはありません。アプリケーションは、アクションが必要なトピックを決定します。

既存のエンドポイントへのリクエストの送信:

POST /20231130/actions/applyGuardrails

リクエスト署名および完全なAPI契約については、ApplyGuardrailsを参照してください。

• guardrailVersionConfig.guardrailVersionを1.2.0またはそれ以降のサポートされているバージョンに設定します。トピック管理には、明示的なバージョン選択が必要です。ListGuardrailVersionsを使用して、使用可能なバージョン、説明およびライフサイクルの状態を確認します。要件およびPATCHバージョンの選択をリストするには、バージョン選択ワークフローを参照してください。Guardrailsシステム・バージョンは、エンドポイント・パスおよびSDKバージョンのAPIバージョンとは異なります。
• multimodalInputに1つのTEXT項目を含めて、分類するテキストをcontentに配置します。languageCodeフィールドはオプションです。指定する場合は、enまたは英語の地域バリアント(en-USなど)を使用します。
• inputを省略します。multimodalInputも指定されている場合でも、inputを含むtopicConfigを指定すると、HTTP 400になります。
• guardrailConfigsの下にtopicConfigを追加します。topicConfig.topicsに少なくとも1つのトピックを指定してください。
• compartmentIdにコンパートメントのOCIDを指定します。

トピック管理では、英語テキストのみが評価されます。リクエストにイメージも含まれている場合、トピック分類では無視されます。イメージのみのリクエスト、複数のテキスト項目、および無効または英語以外の言語コードは、トピック分類ではサポートされていません。languageCodeは省略できます。

コンテンツ・モデレーション、プロンプト・インジェクション検出およびPII検出構成を同じリクエストに含めることができます。トピック管理を追加しても、これらの保護は変更されません。topicConfigを省略すると、既存のリクエスト動作が保持され、レスポンスにresults.topicModerationは含まれません。

guardrailConfigs.topicConfig.topicsでトピックを定義します。オプションで、ラベル付きの例をguardrailConfigs.topicConfig.fewShotExamplesに追加します。

たとえば、トピックがExhibit LoansおよびAfter-Hours Accessの場合、1つのトピックのみが該当する場合でも、すべての例でclassificationオブジェクトに両方のキーが含まれている必要があります。

重複名の検証では、トピック名が比較されます。その意味が重複しているため、単にトピックを拒否するわけではありません。たとえば、大文字と小文字のみが異なる名前は重複しますが、類似した意味を持つ異なる名前は自動的には重複しません。

定義を明確にするには:

• 特定のトピック名と説明を使用します。たとえば、「展示ローン」は、別の会場での展示用に博物館のオブジェクトを借用する要求を検出する場合、「展示」よりも具体的です。
• 説明を使用して、目的の範囲を説明し、関連トピックを区別します。
• 一貫したラベルを持つ代表的な例を提供します。すべての例のトピックにラベルを付けます。
• 一致するテキスト、一致しないテキストおよび複数のトピックに一致する可能性のあるテキストでテストします。結果に基づいて説明と例を絞り込みます。

例では、現在のリクエストの分類を示します。改訂された定義を評価するには、改訂されたトピック構成で別のリクエストを送信します。

この例では、架空の博物館の助手に、展示ローンと開館時間外のアクセスについてメッセージをチェックします。アプリケーションは、いずれかの照合を使用して、博物館スタッフに要求を参照できます。<your-compartment-ocid>をコンパートメント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>"
}

このリクエストはトピック分類のみを有効にします。同じテキストを他の保護と評価するには、topicConfigとともに構成オブジェクトを追加します。「ApplyGuardrails APIの使用」を参照してください。

トピック分類が成功すると、results.topicModeration.topicsには、構成済のトピックごとにリクエストと同じ順序で1つの結果が含まれます。一致しないトピックが含まれます。

スコアはバイナリ分類結果であり、段階的な信頼度スコアではありません。結果は、テキスト全体を分類し、一致したテキスト、オフセットまたは長さを返しません。

次の説明的なレスポンスは、サンプル・メッセージと一致する両方のトピックを示しています。

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

アプリケーションは、ポリシーに従っていずれかの照合を処理できます。一致しないトピックの場合、レスポンスにはscore: 0.0およびisMatched: "false"を含む名前が含まれます。

リクエストにサポートされているGuardrailsシステム・バージョンが含まれ、トピックおよび入力要件を満たしていることを確認します。input、イメージのみのリクエスト、複数のテキスト・アイテム、無効または英語以外の言語コード、またはサポートされていないガードレール・バージョンを指定すると、HTTP 400になります。languageCodeは省略できます。

結果に目的のトピックが反映されない場合は、トピックの説明とラベルの例を確認してください。結果を使用してポリシーを適用する前に、改訂された定義を代表的なアプリケーション・テキストでテストします。