Gerenciamento de Tópicos

1. Defina seus tópicos. Dê um nome a cada tópico. Adicione uma descrição para esclarecer seu escopo e exemplos rotulados para ilustrar o texto que corresponde ou não.
2. Envie a configuração de texto e tópico. Inclua o texto em multimodalInput, adicione guardrailConfigs.topicConfig e selecione uma versão do sistema Guardrails suportada.
3. Leia os resultados. Use results.topicModeration.topics para localizar o resultado de cada tópico configurado. Mais de um tópico pode corresponder ao mesmo texto.
4. Aplique a política do seu aplicativo. Por exemplo, seu aplicativo pode permitir a interação, redirecionar o usuário para um assunto suportado ou impedir que o conteúdo seja transmitido a um modelo ou mostrado a um usuário.

Para avaliar uma entrada do usuário, envie-a antes de enviá-la ao modelo. Para avaliar uma saída de modelo, submeta essa saída como texto em uma solicitação ApplyGuardrails separada antes de exibi-la.

Uma correspondência de tópico identifica o assunto do texto. Isso não significa que o texto não seja seguro e que o resultado não bloqueie automaticamente uma solicitação de inferência. Seu aplicativo decide quais tópicos exigem uma ação.

Envie solicitações ao ponto final existente:

POST /20231130/actions/applyGuardrails

Para assinar a solicitação e o contrato completo da API, consulte ApplyGuardrails.

• Defina guardrailVersionConfig.guardrailVersion como 1.2.0 ou uma versão mais recente suportada. O gerenciamento de tópicos requer uma seleção de versão explícita. Use ListGuardrailVersions para verificar as versões, descrições e estados de ciclo de vida disponíveis. Consulte Workflow de Seleção de Versão para listar requisitos e seleção de versão PATCH. A versão do sistema Guardrails é separada da versão da API no caminho do ponto final e na versão do SDK.
• Inclua exatamente um item TEXT no multimodalInput e coloque o texto para classificar no content. O campo languageCode é opcional. Se você fornecê-lo, use en ou uma variante regional em inglês, como en-US.
• Omita input. Quando topicConfig é fornecido, a inclusão de input resulta em HTTP 400, mesmo que multimodalInput também seja fornecido.
• Adicione topicConfig em guardrailConfigs. Forneça pelo menos um tópico em topicConfig.topics.
• Informe o OCID do seu compartimento em compartmentId.

O gerenciamento de tópicos avalia apenas o texto em inglês. Se a solicitação também contiver imagens, a classificação do tópico as ignorará. Não há suporte para solicitações somente de imagem, vários itens de texto e códigos de idioma inválidos ou não em inglês para classificação de tópico. Omitindo languageCode é permitido.

Você pode incluir moderação de conteúdo, detecção de injeção de prompt e configurações de detecção de PII na mesma solicitação. Adicionar o gerenciamento de tópicos não altera essas proteções. Se você omitir topicConfig, o comportamento da solicitação existente será preservado e a resposta não incluirá results.topicModeration.

Defina tópicos em guardrailConfigs.topicConfig.topics. Opcionalmente, adicione exemplos rotulados em guardrailConfigs.topicConfig.fewShotExamples.

Por exemplo, se seus tópicos forem Exhibit Loans e After-Hours Access, cada exemplo deverá conter ambas as chaves em seu objeto classification, mesmo quando apenas um tópico se aplica.

A validação de nome duplicado compara os nomes dos tópicos. Não rejeita tópicos apenas porque seus significados se sobrepõem. Por exemplo, nomes que diferem apenas em letras maiúsculas e minúsculas são duplicados, mas nomes diferentes com significados semelhantes não são duplicados automaticamente.

Para tornar suas definições claras:

• Use nomes e descrições de tópicos específicos. Por exemplo, Empréstimos de Exposição é mais específico do que Exposições se você quiser detectar solicitações para emprestar objetos de museu para exibição em outro local.
• Use descrições para explicar o escopo pretendido e distinguir tópicos relacionados.
• Forneça exemplos representativos com rótulos consistentes. Rotule cada tópico para cada exemplo.
• Teste com texto correspondente, texto não correspondente e texto que pode corresponder a mais de um tópico. Refine descrições e exemplos com base nos resultados.

Os exemplos orientam a classificação da solicitação atual. Para avaliar uma definição revisada, envie outra solicitação com a configuração do tópico revisado.

Este exemplo verifica uma mensagem para um assistente de museu fictício para exibir empréstimos e acesso fora do horário de funcionamento. O aplicativo pode usar qualquer uma das correspondências para encaminhar a solicitação à equipe do museu. Substitua <your-compartment-ocid> pelo OCID do compartimento.

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

Esta solicitação só ativa a classificação de tópicos. Para avaliar o mesmo texto com outras proteções, adicione seus objetos de configuração ao lado de topicConfig. Consulte Usando a API ApplyGuardrails.

Quando a classificação do tópico é bem-sucedida, results.topicModeration.topics contém um resultado para cada tópico configurado, na mesma ordem da solicitação. Tópicos que não correspondem são incluídos.

A pontuação é um resultado de classificação binária, não uma pontuação de confiança graduada. O resultado classifica o texto geral e não retorna texto, compensações ou comprimentos correspondentes.

A seguinte resposta ilustrativa mostra os dois tópicos que correspondem à mensagem de exemplo:

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

Seu aplicativo pode agir em qualquer partida de acordo com sua política. Para um tópico que não corresponde, a resposta ainda inclui seu nome com score: 0.0 e isMatched: "false".

Verifique se sua solicitação inclui uma versão suportada do sistema Guardrails e atende aos requisitos de tópico e entrada. Fornecer input, uma solicitação somente para imagem, vários itens de texto, um código de idioma inválido ou não em inglês ou uma versão de guardrail não suportada resulta em HTTP 400. Você pode omitir languageCode.

Se os resultados não refletirem os tópicos pretendidos, revise as descrições dos tópicos e os rótulos de exemplo. Teste as definições revisadas com texto de aplicativo representativo antes de usar os resultados para impor sua política.