Gestión de temas

Utiliza la gestión de temas en OCI Generative AI Guardrails para comprobar el texto con los temas que definas para tu aplicación.

La gestión de temas clasifica el texto en función de los temas que defina para su solicitud, como préstamos para exposiciones o solicitudes para visitar un museo fuera del horario de apertura.

A partir de la versión 1.2.0 del sistema Guardrails, puede utilizar la API ApplyGuardrails para evaluar el texto con respecto a los temas que defina.

Puede enviar nombres de temas, descripciones opcionales y ejemplos con etiquetas opcionales con cada solicitud de ApplyGuardrails. El servicio evalúa el texto con respecto a cada tema y devuelve un resultado de coincidencia o sin coincidencia para cada uno. La aplicación utiliza estos resultados para decidir cómo manejar el contenido.

Importante

Para utilizar la gestión de temas, incluya topicConfig en cada solicitud de ApplyGuardrails. No puede seleccionar la gestión de temas como una guía cuando crea o actualiza un punto final de modelo en la consola. La gestión de temas no está disponible mediante la ruta de acceso de la API compatible con OpenAI.

Las definiciones de temas se aplican a la solicitud actual. El servicio no los crea ni almacena como recursos de temas reutilizables. Para reutilizar una configuración de tema, guárdela en la aplicación e inclúyala en cada solicitud. Para cambiar los temas evaluados, cambie la configuración en las solicitudes posteriores.

Funcionamiento de la gestión de temas

  1. Defina los temas. Asigne un nombre a cada tema. Agregue una descripción para aclarar su ámbito y ejemplos etiquetados para ilustrar texto que coincida o no coincida.
  2. Envíe el texto y la configuración del tema. Incluya el texto en multimodalInput, agregue guardrailConfigs.topicConfig y seleccione una versión del sistema Guardrails soportada.
  3. Lee los resultados. Utilice results.topicModeration.topics para buscar el resultado de cada tema configurado. Más de un tema puede coincidir con el mismo texto.
  4. Aplique la política de la aplicación. Por ejemplo, la aplicación puede permitir la interacción, redirigir al usuario a un tema soportado o evitar que el contenido se transfiera a un modelo o se muestre a un usuario.

Para evaluar la entrada de un usuario, envíela antes de enviarla al modelo. Para evaluar una salida de modelo, ejecute dicha salida como texto en una solicitud ApplyGuardrails independiente antes de mostrarla.

Una coincidencia de tema identifica el tema del texto. Esto no significa que el texto no sea seguro, y el resultado no bloquea automáticamente una solicitud de inferencia. La aplicación decide qué temas requieren una acción.

Requisitos de solicitud

Enviar solicitudes al punto final existente:

POST /20231130/actions/applyGuardrails

Para la firma de solicitudes y el contrato de API completo, consulte ApplyGuardrails.

  • Defina guardrailVersionConfig.guardrailVersion en 1.2.0 o una versión soportada posterior. La gestión de temas requiere una selección explícita de versiones. Utilice ListGuardrailVersions para comprobar las versiones disponibles, las descripciones y los estados del ciclo de vida. Consulte Flujo de trabajo de selección de versiones para obtener una lista de los requisitos y la selección de versión de PATCH. La versión del sistema Guardrails es independiente de la versión de API en la ruta de acceso del punto final y la versión del SDK.
  • Incluya exactamente un elemento TEXT en multimodalInput y coloque el texto para clasificarlo en content. El campo languageCode es opcional. Si lo proporciona, utilice en o una variante regional inglesa como en-US.
  • Omita input. Cuando se proporciona topicConfig, incluyendo input da como resultado HTTP 400, incluso si también se proporciona multimodalInput.
  • Agregue topicConfig en guardrailConfigs. Proporcione al menos un tema en topicConfig.topics.
  • Proporcione el OCID del compartimento en compartmentId.

La gestión de temas evalúa solo el texto en inglés. Si la solicitud también contiene imágenes, la clasificación de temas las ignora. Las solicitudes de solo imagen, varios elementos de texto y códigos de idioma no válidos o que no son de inglés no se admiten para la clasificación de temas. Se permite omitir languageCode.

Puede incluir configuraciones de moderación de contenido, detección de inyección de mensajes y detección de PII en la misma solicitud. La adición de la gestión de temas no cambia esas protecciones. Si omite topicConfig, el comportamiento de la solicitud existente se conserva y la respuesta no incluye results.topicModeration.

Definición de temas y ejemplos

Defina los temas en guardrailConfigs.topicConfig.topics. También puede agregar ejemplos con etiquetas en guardrailConfigs.topicConfig.fewShotExamples.

CampoNecesarioRequisitos
topicsSíIncluya de 1 a 25 temas por solicitud.
topics[].nameSíUtilice de 1 a 100 caracteres, incluido al menos un carácter que no sea un espacio en blanco. Los nombres deben ser únicos después de recortar los espacios en blanco iniciales y finales y comparar sin tener en cuenta las mayúsculas y minúsculas.
topics[].descriptionNºDescriba el tema en hasta 1.000 caracteres.
fewShotExamplesNºIncluya hasta 15 ejemplos etiquetados.
fewShotExamples[].userTextSí, por cada ejemploProporcione un texto de ejemplo de 1 a 1.000 caracteres.
fewShotExamples[].classificationSí, por cada ejemploIncluya una entrada para cada tema en la solicitud. Cada clave debe coincidir exactamente con un nombre de tema enviado, incluidas las mayúsculas y minúsculas. Utilice la cadena "true" si el tema se aplica al ejemplo y "false" si no lo hace. Los valores deben ser estas cadenas en minúscula, no valores booleanos JSON. No omita temas ni incluya claves adicionales.

Por ejemplo, si los temas son Exhibit Loans y After-Hours Access, cada ejemplo debe contener ambas claves en su objeto classification, incluso cuando solo se aplica un tema.

Nota

Las etiquetas de ejemplo de classification y el campo isMatched de la respuesta utilizan las cadenas en minúscula "true" y "false".

La validación de nombres duplicados compara los nombres de temas. No rechaza los temas únicamente porque sus significados se superponen. Por ejemplo, los nombres que difieren solo en mayúsculas y minúsculas son duplicados, pero los nombres diferentes con significados similares no son duplicados automáticamente.

Para aclarar sus definiciones:

  • Utilice nombres y descripciones de temas específicos. Por ejemplo, los préstamos de exposición son más específicos que las exposiciones si desea detectar solicitudes para pedir prestados objetos de museo para su visualización en otro lugar.
  • Utilice descripciones para explicar el ámbito previsto y distinguir los temas relacionados.
  • Proporcione ejemplos representativos con etiquetas coherentes. Etiqueta cada tema para cada ejemplo.
  • Pruebe con texto coincidente, texto no coincidente y texto que pueda coincidir con más de un tema. Acote descripciones y ejemplos en función de los resultados.

Los ejemplos guían la clasificación de la solicitud actual. Para evaluar una definición revisada, envíe otra solicitud con la configuración de tema revisada.

Ejemplo de solicitud de gestión de temas

Este ejemplo comprueba un mensaje a un asistente ficticio del museo para obtener préstamos de exhibición y acceso fuera del horario de apertura. La aplicación puede usar cualquiera de las coincidencias para remitir la solicitud al personal del museo. Sustituya <your-compartment-ocid> por el OCID de su 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 solicitud solo activa la clasificación de temas. Para evaluar el mismo texto con otras protecciones, agregue sus objetos de configuración junto con topicConfig. Consulte Uso de la API ApplyGuardrails.

Descripción de los resultados de temas

Cuando la clasificación de temas se realiza correctamente, results.topicModeration.topics contiene un resultado para cada tema configurado, en el mismo orden que la solicitud. Se incluyen temas que no coinciden.

CampoSignificado
nameEl nombre del tema exactamente como se indica en la solicitud.
isMatchedLa cadena "true" cuando el tema se aplica al texto o "false" cuando no lo hace.
score1.0 cuando isMatched es "true" o 0.0 cuando es "false". No se devuelve ninguna puntuación fraccional.

La puntuación es un resultado de clasificación binaria, no una puntuación de confianza graduada. El resultado clasifica el texto general y no devuelve texto coincidente, desviaciones ni longitudes.

La siguiente respuesta ilustrativa muestra ambos temas que coinciden con el mensaje de ejemplo:

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

La aplicación puede actuar en cualquiera de las coincidencias según su política. Para un tema que no coincide, la respuesta aún incluye su nombre con score: 0.0 y isMatched: "false".

Validación y solución de problemas

Compruebe que la solicitud incluye una versión soportada del sistema Guardrails y cumple los requisitos de entrada y tema. Si se proporciona input, una solicitud de solo imagen, varios elementos de texto, un código de idioma no válido o no inglés o una versión de guía farmacológica no soportada, se generará HTTP 400. Puede omitir languageCode.

Error de ValidaciónQué comprobar
INVALID_TOPICCompruebe que cada tema tenga un nombre que no esté en blanco y que los nombres y las descripciones cumplan los requisitos de longitud.
DUPLICATE_TOPICCompruebe los nombres que se vuelven idénticos después de eliminar el espacio en blanco circundante y comparar sin tener en cuenta las mayúsculas y minúsculas.
TOPIC_LIMIT_EXCEEDEDEnvíe no más de 25 temas en una solicitud.
INVALID_TOPIC_EXAMPLECompruebe el número y la longitud de los ejemplos. Cada asignación de clasificación debe contener exactamente los nombres de tema enviados, con la cadena "true" o "false" para cada nombre. No se aceptan valores booleanos JSON ni otras cadenas.
UNSUPPORTED_LANGUAGESi proporciona languageCode, utilice en o una variante regional inglesa. También puede omitir el campo.
UNSUPPORTED_TOPIC_INPUTUtilice multimodalInput con exactamente un elemento TEXT. Omita input y no envíe una solicitud de solo imagen para la clasificación de temas.

Si los resultados no reflejan los temas previstos, revise las descripciones de los temas y las etiquetas de ejemplo. Pruebe las definiciones revisadas con texto de aplicación representativo antes de utilizar los resultados para aplicar la política.