Creazione e gestione di modelli personalizzati

Il primo passo per utilizzare un qualsiasi modello personalizzato è crearlo. Una volta creato, puoi gestire il modello eseguendo query o aggiornando i suoi metadati e le sue voci e, infine, eliminandolo quando non più necessario. Prima di iniziare, esamina le seguenti informazioni generali sull'utilizzo dei modelli personalizzati.

Note sull'utilizzo della personalizzazione

Considera le seguenti linee guida quando lavori con l'interfaccia di personalizzazione.

Proprietà di modelli personalizzati

Un modello personalizzato è di proprietà dell'istanza del servizio Text to Speech di cui vengono utilizzate le credenziali per crearlo. Per lavorare in qualsiasi modo con il modello personalizzato, devi utilizzare le credenziali per tale istanza del servizio con i metodi dell'interfaccia di personalizzazione.

Tutte le credenziali ottenute per la stessa istanza del servizio Text to Speech condividono l'accesso a tutti i modelli personalizzati creati per tale istanza. Per limitare l'accesso a un modello personalizzato, crea un'istanza separata del servizio e utilizza solo le credenziali per tale istanza del servizio per creare e utilizzare il modello. Le credenziali per altre istanze del servizio non possono influire sul modello personalizzato.

Un vantaggio della condivisione della proprietà tra le credenziali è che puoi annullare un insieme di credenziali, ad esempio, se vengono compromesse. Puoi quindi creare nuove credenziali per la stessa istanza del servizio e mantenere comunque la proprietà e l'accesso ai modelli personalizzati creati con le credenziali originali.

Sicurezza delle informazioni

Il servizio consente di associare un ID cliente ai dati aggiunti o aggiornati per i modelli personalizzati. Puoi associare un ID cliente a parole personalizzate passando l'intestazione X-Watson-Metadata con i seguenti metodi. Se necessario, puoi quindi eliminare i dati associati all'ID cliente utilizzando il metodo DELETE /v1/user_data.

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

Inoltre, se elimini un'istanza del servizio Text to Speech dalla console IBM Cloud, verranno eliminati automaticamente tutti i dati associati a tale istanza del servizio. Questo include tutti i modelli personalizzati e le coppie parola/traduzione. Questi dati vengono eliminati automaticamente e indipendentemente dal fatto che un ID cliente sia associato ai dati.

Per ulteriori informazioni, vedi Sicurezza delle informazioni.

Registrazione delle richieste e privacy dei dati

IBM Cloud

Il modo in cui il servizio gestisce la registrazione delle richieste per le chiamate all'interfaccia di personalizzazione dipende dalla richiesta:

Il servizio non registra i dati (parole e traduzioni) utilizzati per costruire modelli personalizzati. Non devi impostare l'intestazione della richiesta X-Watson-Learning-Opt-Out quando utilizzi l'interfaccia di personalizzazione per gestire le parole e le traduzioni in un modello personalizzato. I tuoi dati di addestramento non vengono mai utilizzati per migliorare i modelli di base del servizio.
Il servizio registra i dati quando un modello di dati viene utilizzato con una richiesta di sintesi. È possibile disattivare la registrazione delle richieste a livello di account o impostando l'intestazione della richiesta X-Watson-Learning-Opt-Out su true.

Per ulteriori informazioni, vedi Registrazione delle richieste.

Creazione di un modello personalizzato

Per creare un nuovo modello personalizzato, utilizza il metodo POST /v1/customizations. Un nuovo modello è sempre vuoto quando lo crei la prima volta. Devi utilizzare altri metodi per popolarlo con coppie di parole/traduzioni. Il nuovo modello personalizzato è di proprietà dell'istanza del servizio di cui vengono utilizzate le credenziali per crearlo. Per ulteriori informazioni, vedi Proprietà di modelli personalizzati.

Passa i seguenti attributi come un oggetto JSON con il corpo di una richiesta POST /v1/customizations:

name (stringa obbligatoria )

Un nome definito dall'utente per il nuovo modello personalizzato. Utilizza un nome localizzato che corrisponda alla lingua del modello personalizzato e descriva il dominio del modello, come Medical custom model o Legal custom model.

Includere un massimo di 256 caratteri nel nome.
Non utilizzare barre rovesciate, barre, due punti, segni di uguale, e commerciale o punti interrogativi nel nome.
Utilizzate un nome unico tra tutti i modelli personalizzati che possedete.

language (stringa opzionale )

Un identificativo per la lingua del modello personalizzato. L'impostazione predefinita è en-US per l'inglese statunitense. Il modello personalizzato può essere utilizzato con qualsiasi voce disponibile nella lingua specificata. Ad esempio, un modello personalizzato creato per la lingua en-US può essere utilizzato con qualsiasi voce in inglese (Stati Uniti). Non può, tuttavia, essere utilizzato con una voce en-GB.

description (stringa opzionale )

Una descrizione consigliata del nuovo modello personalizzato.

Utilizza una descrizione localizzata che corrisponda alla lingua del modello personalizzato.
Includere un massimo di 128 caratteri nella descrizione.

L'esempio seguente crea un nuovo modello personalizzato in inglese americano denominato " Test". L'intestazione richiesta Content-Type identifica il tipo di input come 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"

Il metodo restituisce un oggetto JSON che contiene un GUID (globally unique identifier) per il nuovo modello. Il GUID viene utilizzato come parametro customization_id nelle chiamate per accedere al modello, ad esempio per l'esecuzione di query, la modifica e l'utilizzo del modello e delle sue parole.

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

Esecuzione di query di un modello personalizzato

Per eseguire la query sulle informazioni relative a un modello personalizzato esistente, utilizza il metodo GET /v1/customizations/{customization_id}. Questo è il modo più diretto per vedere tutte le informazioni su un modello, compresi i suoi metadati e le coppie parola/traduzione e i prompt personalizzati che 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}"

Il metodo restituisce i suoi risultati come oggetto JSON del seguente formato:

{
  "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": []
}

Oltre alle informazioni immesse al momento della creazione del modello, l'output include le credenziali del proprietario del modello, la lingua e le ore di creazione e ultima modifica del modello. Poiché il modello non è stato modificato dalla sua creazione, le due ore nell'esempio sono uguali.

L'output include anche un array " words " che elenca le parole personalizzate del modello e un array " prompts " che elenca i prompt personalizzati del modello. Poiché il modello non è ancora stato aggiornato, gli array dell'esempio sono vuoti.

Esecuzione di query di tutti i modelli personalizzati

Per visualizzare informazioni su tutti i modelli personalizzati di tua proprietà, utilizza il metodo 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"

Il metodo restituisce un array JSON che include un oggetto per ciascun modello personalizzato di proprietà del richiedente. Le credenziali del proprietario sono mostrate nel campo owner.

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

Le ore nei campi created e last_modified per il primo modello sono le stesse perché non è stato ancora aggiornato. Le ore per il secondo modello sono diverse, a indicare che è stato modificato dalla sua creazione iniziale. Le informazioni non includono le voci personalizzate definite per i modelli.

Aggiornamento di un modello personalizzato

Per aggiornare le informazioni relative a un modello personalizzato, utilizza il metodo POST /v1/customizations/{customization_id}. Specifica gli aggiornamenti come oggetto JSON. Oltre a modificarne il nome e la descrizione, puoi utilizzare questo metodo anche per aggiungere o aggiornare coppie di parole/traduzioni nel modello. Non puoi modificare la lingua di un modello una volta creato.

Il seguente esempio aggiorna il nome e la descrizione di un modello personalizzato. Viene inviato un array JSON vuoto con il parametro words per indicare che le voci del modello devono rimanere invariate.

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

Per informazioni sull'aggiornamento delle parole in un modello, vedi Aggiunta di più parole a un modello personalizzato.

Eliminazione di un modello personalizzato

Per eliminare un modello personalizzato che non ti serve più, utilizza il metodo DELETE /v1/customizations/{customization_id}. Utilizza questo metodo solo se sei certo di non aver più bisogno del modello, poiché l'eliminazione è 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}"