Creación y gestión de modelos personalizados

El primer paso para trabajar con cualquier modelo personalizado es crearlo. Una vez que existe, puede gestionar el modelo consultando o actualizando sus metadatos y entradas, y suprimirlo si ya no se necesita. Antes de empezar, revise la siguiente información de uso general sobre modelos personalizados.

Notas de uso sobre la personalización

Tenga en cuenta las siguientes directrices al trabajar con la interfaz de personalización.

Propiedad de los modelos personalizados

Un modelo personalizado es propiedad de la instancia del servicio Text to Speech cuyas credenciales se utilizan para crearlo. Debe utilizar las credenciales para dicha instancia de servicio con los métodos de la interfaz de personalización para cualquier trabajo que realice con el modelo personalizado.

Todas las credenciales obtenidas para la misma instancia del servicio Text to Speech comparten el acceso a todos los modelos personalizados creados para esa instancia de servicio. Para restringir el acceso a un modelo personalizado, cree una instancia de servicio aparte y utilice únicamente las credenciales de esa instancia de servicio para crear y trabajar con el modelo. Las credenciales de otras instancias de servicio no pueden afectar al modelo personalizado.

Una ventaja de compartir la propiedad entre las credenciales es que se puede cancelar un conjunto de credenciales, por ejemplo, si están en riesgo. A continuación, puede crear nuevas credenciales para la misma instancia de servicio y seguir manteniendo la propiedad y el acceso a los modelos personalizados creados con las credenciales originales.

Seguridad de la información

El servicio le permite asociar un ID de cliente con los datos que se añaden o actualizan para los modelos personalizados. Puede asociar un ID de cliente a palabras personalizadas pasando la cabecera X-Watson-Metadata con los métodos siguientes. Si es necesario, después puede suprimir los datos asociados al ID de cliente utilizando el método DELETE /v1/user_data.

  • POST /v1/customizations/{customization_id}
  • POST /v1/customizations/{customization_id}/words
  • PUT /v1/customizations/{customization_id}/words/{word}

Además, si suprime una instancia del servicio Text to Speech desde la consola de IBM Cloud, todos los datos asociados con dicha instancia de servicio se suprimirán automáticamente. Esto incluye todos los modelos personalizados y los pares palabra/traducción. Estos datos se depuran automáticamente e independientemente de si hay algún ID de cliente asociado a los datos.

Para obtener más información, consulte Seguridad de la información.

Registro de solicitudes y privacidad de datos

IBM Cloud

La forma en que el servicio maneja el registro de solicitudes para las llamadas a la interfaz de personalización depende de la solicitud:

  • El servicio no registra los datos (palabras y traducciones) que se utilizan para crear modelos personalizados. No es necesario que defina la cabecera de la solicitud X-Watson-Learning-Opt-Out cuando utilice la interfaz de personalización para gestionar las palabras y las conversiones en un modelo personalizado. Los datos de entrenamiento nunca se utilizan para mejorar los modelos base del servicio.
  • El servicio si registra los datos cuando se utiliza un modelo personalizado con una solicitud de síntesis. Puede optar por no participar en el registro de solicitudes a nivel de cuenta o configurando el encabezado de solicitud X-Watson-Learning-Opt-Out en true.

Para obtener más información, consulte Registro de solicitudes.

Crear un modelo personalizado

Para crear un modelo personalizado nuevo, utilice el método POST /v1/customizations. Un modelo nuevo siempre está vacío en el momento en que se crea. Se deben utilizar otros métodos para llenarlo con pares de palabra/conversión. El nuevo modelo personalizado es propiedad de la instancia de servicio cuyas credenciales se han utilizado para crearlo. Para obtener más información, consulte Propiedad de modelos personalizados.

Se pasan los atributos siguientes como un objeto JSON con el cuerpo de una solicitud POST /v1/customizations:

name (serie obligatoria)
Un nombre definido por el usuario para el nuevo modelo personalizado. Utilice un nombre localizado que coincida con el idioma del modelo personalizado y describa el dominio del modelo, como Medical custom model o Legal custom model.
  • Incluya un máximo de 256 caracteres en el nombre.
  • No utilice barras invertidas, barras, dos puntos, signos de igualdad, símbolos de unión o signos de interrogación en el nombre.
  • Utiliza un nombre que sea único entre todos los modelos personalizados que poseas.
language (serie opcional)
Un identificador del idioma del modelo personalizado. El valor predeterminado es en-US para inglés de Estados Unidos. El modelo personalizado se puede utilizar con cualquier voz que esté disponible en el idioma especificado. Por ejemplo, un modelo personalizado que se crea para el idioma en-US se puede utilizar con cualquier voz en inglés de EE. UU. Sin embargo, no se puede utilizar con una voz de en-GB.
description (serie opcional)
Una descripción recomendada del nuevo modelo personalizado.
  • Utilice una descripción en el idioma del modelo personalizado.
  • Incluya un máximo de 128 caracteres en la descripción.

El siguiente ejemplo crea un nuevo modelo personalizado en inglés de EE.UU. denominado Test. El encabezado obligatorio Content-Type identifica el tipo de entrada como application/json.

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test\", \"language\":\"en-US\", \"description\":\"Customization test\"}" \
"{url}/v1/customizations"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test\", \"language\":\"en-US\", \"description\":\"Customization test\"}" \
"{url}/v1/customizations"

El método devuelve un objeto JSON que contiene un identificador exclusivo global (GUID) para el nuevo modelo. El GUID se utiliza como el parámetro customization_id en las llamadas para acceder al modelo, como por ejemplo, para consultar, modificar y utilizar el modelo y sus palabras.

{
  "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97"
}

Consultar un modelo personalizado

Para consultar información sobre un modelo personalizado existente, utilice el método GET /v1/customizations/{customization_id}. Este es el medio más directo de ver toda la información sobre un modelo, incluyendo sus metadatos y los pares palabra/traducción y las solicitudes personalizadas que contiene.

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"

El método devuelve sus resultados como un objeto JSON con el formato siguiente:

{
  "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97",
  "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
  "created": "2016-07-15T18:12:31.743Z",
  "name": "Test",
  "language": "en-US",
  "description": "Customization test",
  "last_modified": "2016-07-15T18:12:31.743Z",
  "words": [],
  "prompts": []
}

Además de la información especificada al crear el modelo, la salida incluye las credenciales del propietario del modelo, el idioma del modelo y las horas en las que se creó el modelo y se modificó por última vez. Dado que el modelo no se ha modificado desde su creación, en el ejemplo las dos horas son la misma.

La salida también incluye una matriz words que lista las palabras personalizadas del modelo y una matriz prompts que lista las solicitudes personalizadas del modelo. Dado que el modelo aún no se ha actualizado, las matrices del ejemplo están vacías.

Consultar todos los modelos personalizados

Para ver información sobre todos los modelos personalizados de los que es propietario, utilice el método GET /v1/customizations:

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/customizations"

IBM Cloud Pak for Data IBM Software Hub

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations"

El método devuelve una matriz JSON que incluye un objeto para cada modelo personalizado propiedad del solicitante. En el campo owner se muestran las credenciales del propietario.

{
  "customizations": [
    {
      "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97",
      "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-07-15T19:15:17.926Z",
      "name": "Test",
      "language": "en-US",
      "description": "Customization test",
      "last_modified": "2016-07-15T19:15:17.926Z"
    },
    {
      "customization_id": "63f5807f-a4f2-5766-914e-7abb1a84fe97",
      "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-07-15T18:12:31.743Z",
      "name": "Test Two",
      "language": "en-US",
      "description": "Second customization test",
      "last_modified": "2016-07-15T18:23:50.912Z"
    }
  ]
}

Las horas de created y last_modified del primer modelo son la misma porque todavía no se ha actualizado. En el segundo modelo las horas son distintas, lo que indica que se ha modificado desde su creación. La información no incluye las entradas personalizadas definidas para los modelos.

Actualizar un modelo personalizado

Para actualizar la información sobre un modelo personalizado, utilice el método POST /v1/customizations/{customization_id}. Debe especificar las actualizaciones como un objeto JSON. Además de modificar el nombre y la descripción, también puede utilizar este método para añadir o actualizar pares de palabra/conversión en el modelo. No se puede cambiar el idioma de un modelo una vez que se ha creado.

En el ejemplo siguiente se actualiza el nombre y la descripción de un modelo personalizado. Se envía una matriz JSON vacía con el parámetro words para indicar que las entradas del modelo se mantienen sin cambios.

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test Update\", \"description\":\"Customization test update\", \"words\":[]}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: application/json" \
--data "{\"name\":\"Test Update\", \"description\":\"Customization test update\", \"words\":[]}" \
"{url}/v1/customizations/{customization_id}"

Para obtener información sobre cómo actualizar las palabras de un modelo, consulte Añadir varias palabras a un modelo personalizado.

Suprimir un modelo personalizado

Para descartar un modelo personalizado que ya no se necesita, utilice el método DELETE /v1/customizations/{customization_id}. Utilice este método sólo si está seguro de que ya no necesita el modelo, ya que la supresión es permanente.

IBM Cloud

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/customizations/{customization_id}"

IBM Cloud Pak for Data IBM Software Hub

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/customizations/{customization_id}"