Angepasste Modelle erstellen und verwalten

Wenn Sie mit einem angepassten Modell arbeiten wollen, müssen Sie das Modell zunächst erstellen. Nachdem Sie das Modell erstellt haben, können Sie es verwalten, indem Sie seine Metadaten und Einträge abfragen oder aktualisieren bzw. das Modell löschen, wenn Sie es nicht mehr benötigen. In diesem Abschnitt können Sie sich vor dem Einstieg über die allgemeine Verwendung von angepassten Modellen informieren.

Verwendungshinweise für die Anpassung

Beachten Sie bei der Arbeit mit der Anpassungsschnittstelle die folgenden Richtlinien.

Eigentumsrecht an angepassten Modellen

Eigner eines angepassten Modells ist die Instanz des Text to Speech-Service, deren Berechtigungsnachweise zur Erstellung des Modells verwendet wurden. Bei jeder Arbeit mit dem angepassten Modell müssen Sie die Berechtigungsnachweise für diese Serviceinstanz mit Methoden der Anpassungsschnittstelle verwenden.

Alle für dieselbe Instanz des Text to Speech-Service angeforderten Berechtigungsnachweise nutzen gemeinsam den Zugriff auf alle angepassten Modelle, die für die Serviceinstanz erstellt werden. Um den Zugriff auf ein angepasstes Modell einzuschränken, erstellen Sie eine separate Instanz des Service und verwenden Sie ausschließlich die Berechtigungsnachweise für diesen Service, um das Modell zu erstellen und mit ihm zu arbeiten. Berechtigungsnachweise für andere Services haben keinen Einfluss auf das angepasste Modell.

Ein Vorteil der gemeinsamen Nutzung des Eigentumsrechts durch mehrere Berechtigungsnachweise besteht darin, dass Sie beispielsweise eine Reihe von Berechtigungsnachweisen stornieren können, falls diese beeinträchtigt werden. Anschließend können Sie neue Berechtigungsnachweise für die gleiche Serviceinstanz erstellen und trotzdem das Eigentumsrecht an angepassten Modellen und den Zugriff auf angepasste Modelle verwalten, die mit den ursprünglichen Berechtigungsnachweisen erstellt wurden.

Informationssicherheit

Der Service ermöglicht Ihnen die Zuordnung einer Kunden-ID zu Daten, die für angepasste Modelle hinzugefügt oder aktualisiert werden. Sie können eine Kunden-ID zu angepassten Wörtern zuordnen, indem Sie den Header X-Watson-Metadata mit den folgenden Methoden übergeben. Bei Bedarf können Sie dann die Daten, die der Kunden-ID zugeordnet sind, mit der Methode DELETE /v1/user_data löschen.

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

Wenn Sie eine Instanz des Text to Speech-Service aus der IBM Cloud-Konsole löschen, werden zudem alle Daten, die dieser Serviceinstanz zugeordnet sind, automatisch gelöscht. Dazu gehören alle angepassten Modelle und Paare aus Wort und Umsetzung. Diese Daten werden automatisch und unabhängig davon gelöscht, ob den Daten eine Kunden-ID zugeordnet ist.

Weitere Informationen finden Sie unter Informationssicherheit.

Protokollierung von Anforderungen und Datenschutz

IBM Cloud

Wie der Service die Anforderungsprotokollierung für Aufrufe der Anpassungsschnittstelle abwickelt, ist von der Anforderung abhängig:

  • Daten (Wörter und Umsetzungen), die zum Erstellen angepasster Modelle verwendet werden, werden vom Service nicht aufgezeichnet, Wenn Sie die Anpassungsschnittstelle verwenden, um die Wörter und Umsetzungen in einem angepassten Modell zu verwalten, müssen Sie nicht den Anforderungsheader X-Watson-Learning-Opt-Out festlegen. Ihre Trainingsdaten werden in keinem Fall verwendet, um die Basismodelle des Service zu verbessern.
  • Der Service protokolliert Daten, wenn ein angepasstes Modell im Zusammenhang mit einer Anforderung für die synthetische Erstellung genutzt wird. Sie können die Protokollierung von Anfragen auf Kontoebene deaktivieren oder indem Sie den Anfrageleiter X-Watson-Learning-Opt-Out auf true setzen.

Weitere Informationen finden Sie im Abschnitt Anforderungsprotokollierung.

Angepasstes Modell erstellen

Zum Erstellen eines neuen angepassten Modells verwenden Sie die Methode POST /v1/customizations. Bei seiner erstmaligen Erstellung ist ein neues Modell immer leer. Sie müssen andere Methoden verwenden, um es mit Paaren aus Wort und Umsetzung zu füllen. Eigner des neuen angepassten Modells ist die Serviceinstanz, deren Berechtigungsnachweise für die Erstellung verwendet werden. Weitere Informationen finden Sie unter Eigentumsrecht an angepassten Modellen.

Mit dem Hauptteil der einer Anforderung POST /v1/customizations übergeben Sie die folgenden Attribute als JSON-Objekt:

name (erforderliche Zeichenfolge)
Ein benutzerdefinierter Name für das neue angepasste Modell. Verwenden Sie einen lokalisierten Namen, der der Sprache des benutzerdefinierten Modells entspricht und den Bereich des Modells beschreibt, z. B. Medical custom model oder Legal custom model.
  • Der Name darf maximal 256 Zeichen lang sein.
  • Verwenden Sie im Namen keine umgekehrten Schrägstriche, Schrägstriche, Doppelpunkte, Gleichheitszeichen, kaufmännischen Und-Zeichen oder Fragezeichen.
  • Verwenden Sie einen Namen, der für alle benutzerdefinierten Modelle, die Sie besitzen, eindeutig ist.
language (optionale Zeichenfolge)
Eine ID für die Sprache des angepassten Modells. Der Standardwert ist en-US für amerikanisches Englisch. Das benutzerdefinierte Modell kann mit einer beliebigen Stimme verwendet werden, die in der angegebenen Sprache verfügbar ist. Ein angepasstes Modell, das für die Sprache en-US erstellt wird, kann zum Beispiel mit jeder beliebigen Stimme für amerikanisches Englisch verwendet werden. Seine Verwendung mit einer Stimme für britisches Englisch (en-GB) ist jedoch nicht möglich.
description (optionale Zeichenfolge)
Eine empfohlene Beschreibung des neuen benutzerdefinierten Modells.
  • Verwenden Sie eine Beschreibung in der Sprache des angepassten Modells.
  • Die Beschreibung darf maximal 128 Zeichen umfassen.

Im folgenden Beispiel wird ein neues benutzerdefiniertes Modell für US-Englisch mit dem Namen Test erstellt. Die erforderliche Kopfzeile Content-Type kennzeichnet den Typ der Eingabe als 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"

Die Methode gibt ein JSON-Objekt zurück, das eine global eindeutige ID (GUID) für das neue Modell enthält. Die GUID wird im Parameter customization_id bei Aufrufen für den Zugriff auf das Modell verwendet, beispielsweise zum Abfragen, Ändern und Verwenden des Modells und seiner Wörter.

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

Angepasstes Modell abfragen

Mit der Methode GET /v1/customizations/{customization_id} können Sie Informationen zu einem vorhandenen angepassten Modell abfragen. Dies ist der direkteste Weg zum Anzeigen aller Informationen zu einem Modell, einschließlich der zugehörigen Metadaten, der Paare aus Wort und Umsetzung und der angepassten Prompts, die das Modell enthält.

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

Die Methode gibt ihre Ergebnisse als JSON-Objekt mit dem folgenden Format zurück:

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

Neben den Informationen, die bei der Erstellung des Modells eingegeben wurden, enthält die Ausgabe die Berechtigungsnachweise für den Eigner des Modells, die Sprache des Modells und die Zeitpunkte für die Erstellung sowie die letzte Änderung des Modells. Da das Modell seit seiner Erstellung nicht geändert wurde, sind die beiden Zeitangaben im Beispiel identisch.

Die Ausgabe enthält außerdem ein Array words mit einer Auflistung der angepassten Wörter des Modells sowie ein Array prompts mit einer Auflistung der angepassten Prompts des Modells. Da das Modell noch aktualisiert werden muss, sind die Arrays im Beispiel leer.

Alle angepassten Modelle abfragen

Mit der Methode GET /v1/customizations können Sie Informationen zu allen angepassten Modellen anzeigen, deren Eigner Sie sind:

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"

Die Methode gibt für jedes angepasste Modell, dessen Eigner der anfordernde Benutzer ist, ein Objekt in einem JSON-Array zurück. Die Berechtigungsnachweise des Eigners sind im Feld owner angegeben.

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

Die Zeitangaben bei created und last_modified für das erste Modell sind identisch, weil es noch aktualisiert werden muss. Bei dem zweiten Modell sind die Zeitangaben unterschiedlich, woraus hervorgeht, dass das Modell nach seiner erstmaligen Erstellung geändert wurde. Die für die Modelle definierten angepassten Einträge sind in den Informationen nicht enthalten.

Angepasstes Modell aktualisieren

Mit der Methode POST /v1/customizations/{customization_id} können Sie Informationen zu einem angepassten Modell aktualisieren. Die Aktualisierungen geben Sie in Form eines JSON-Objekts an. Mit dieser Methode können Sie nicht nur den Namen und die Beschreibung des Modells ändern, sondern auch Paare aus Wort und Umsetzung im Modell hinzufügen oder ändern. Die Sprache eines Modells kann nach seiner Erstellung nicht mehr geändert werden.

Im folgenden Beispiel werden der Name und die Beschreibung eines angepassten Modells aktualisiert. Mit dem Parameter words wird ein leeres JSON-Array gesendet; dies gibt an, dass die Einträge des Modells nicht geändert werden sollen.

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

Weitere Informationen zum Aktualisieren der Wörter in einem Modell finden Sie im Abschnitt Mehrere Wörter zu einem angepassten Modell hinzufügen.

Angepasstes Modell löschen

Mit der Methode DELETE /v1/customizations/{customization_id} können Sie ein angepasstes Modell, das Sie nicht mehr benötigen, löschen. Verwenden Sie diese Methode nur, wenn Sie ganz sicher sind, dass Sie das Modell nicht mehr benötigen, denn mit dieser Methode wird das Modell endgültig gelöscht.

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