Migration von Code von v3.0 zu v3.1 der REST-API

  • Artikel

Die Spracherkennungs-REST-API wird für die Batch-Transkription und für Custom Speech verwendet. Änderungen von Version 3.0 zu 3.1 werden in den folgenden Abschnitten beschrieben.

Wichtig

Die Spracherkennungs-REST-API v3.2 ist in Preview verfügbar. Die Spracherkennungs-REST-API v3.1 ist allgemein verfügbar. Die Spracherkennungs-REST-API v3.0 wird am 1. April 2026 eingestellt. Weitere Informationen finden Sie in den Migrationsleitfäden der Spracherkennungs-REST-API v3.0 zu v3.1 und v3.1 zu v3.2.

Basispfad

Sie müssen den Basispfad in Ihrem Code von /speechtotext/v3.0 auf /speechtotext/v3.1aktualisieren. Verwenden Sie z. B. https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base anstelle von https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base zum Abrufen von Basismodellen in der eastus-Region.

Beachten Sie die folgenden anderen Änderungen:

  • Der Vorgang /models/{id}/copyto (mit „/“) in Version 3.0 wird in Version 3.1 durch den /models/{id}:copyto-Vorgang (mit „:“) ersetzt.
  • Der Vorgang /webhooks/{id}/ping (mit „/“) in Version 3.0 wird in Version 3.1 durch den /webhooks/{id}:ping-Vorgang (mit „:“) ersetzt.
  • Der Vorgang /webhooks/{id}/test (mit „/“) in Version 3.0 wird in Version 3.1 durch den /webhooks/{id}:test-Vorgang (mit „:“) ersetzt.

Weitere Informationen finden Sie unter Vorgangs-IDs weiter unten in diesem Leitfaden.

Batch-Transkription

Hinweis

Verwenden Sie die Spracherkennungs-REST-API v3.0 nicht, um eine mit der Spracherkennungs-REST-API v3.1 erstellte Transkription abzurufen. Es wird eine Fehlermeldung ähnlich der folgenden angezeigt: „Die API-Version kann nicht verwendet werden, um auf diese Transkription zuzugreifen. Verwenden Sie die API-Version v3.1 oder höher.

Dem Transcriptions_Create-Vorgang werden die folgenden drei Eigenschaften hinzugefügt:

  • Die Eigenschaft displayFormWordLevelTimestampsEnabled kann verwendet werden, um im Anzeigeformular der Transkriptionergebnisse die Meldung von Zeitstempeln auf Wortebene zu aktivieren. Die Ergebnisse werden in der displayWords-Eigenschaft der Transkriptionsdatei zurückgegeben.
  • Die Eigenschaft diarization kann verwendet werden, um Hinweise auf die Mindest- und Höchstanzahl der zu generierenden Sprecherbezeichnungen beim Ausführen der optionalen Diarisierung (Sprechertrennung) anzugeben. Mit diesem Feature kann der Dienst jetzt Sprecherbezeichnungen für mehr als zwei Sprecher generieren. Um diese Eigenschaft verwenden zu können, müssen Sie auch die diarizationEnabled-Eigenschaft auf true festlegen. Mit der v3.1-API haben wir die Anzahl der Sprecher, die durch Diarisierung identifiziert werden können, gegenüber den 2 Sprechern, die von der v3.0-API unterstützt werden, erhöht. Es wird empfohlen, die Anzahl der Sprecher unter 30 zu halten, um eine bessere Leistung zu erzielen.
  • Die Eigenschaft languageIdentification kann verwendet werden, um Einstellungen für die Sprachidentifikation in der Eingabe vor der Transkription anzugeben. Bis zu 10 Gebietsschemakandidaten werden für die Spracherkennung unterstützt. Die zurückgegebene Transkription enthält die neue locale-Eigenschaft für die erkannte Sprache oder das angegebene Gebietsschema.

Die filter-Eigenschaft wird den Vorgängen Transcriptions_List, Transcriptions_ListFiles und Projects_ListTranscriptions hinzugefügt. Der filter-Ausdruck kann verwendet werden, um eine Teilmenge der verfügbaren Ressourcen auszuwählen. Sie können nach displayName, description, createdDateTime, lastActionDateTime, status und locale filtern. Beispiel: filter=createdDateTime gt 2022-02-01T11:00:00Z

Wenn Sie einen Webhook verwenden, um Benachrichtigungen zum Transkriptionsstatus zu erhalten, beachten Sie, dass die über die V3.0-API erstellten Webhooks keine Benachrichtigungen für V3.1-Transkriptionsanforderungen empfangen können. Sie müssen einen neuen Webhookendpunkt über die V3.1-API erstellen, um Benachrichtigungen für V3.1-Transkriptionsanforderungen empfangen zu können.

Custom Speech

Datasets

Die folgenden Vorgänge werden zum Hochladen und Verwalten mehrerer Datenblöcke für ein Dataset hinzugefügt:

Um die Modellanpassung mit strukturiertem Text in Markdowndaten zu unterstützen, unterstützt der Datasets_Create-Vorgang jetzt den LanguageMarkdown-Datentyp. Weitere Informationen finden Sie unter Hochladen von Datasets.

Modelle

Die Vorgänge Models_ListBaseModels- und Models_GetBaseModel geben Informationen zur Art der Anpassung zurück, die von dem jeweiligen Basismodell unterstützt wird.

"features": {
    "supportsAdaptationsWith": [
        "Acoustic",
        "Language",
        "LanguageMarkdown",
        "Pronunciation"
    ]
}

Der Models_Create-Vorgang hat eine neue customModelWeightPercent-Eigenschaft, mit der Sie die Gewichtung angeben können, die beim Kombinieren des benutzerdefinierten Sprachmodells (das aus unformatierten oder strukturierten Textdaten trainiert wurde) mit dem Basissprachmodell verwendet wird. Gültige Werte sind ganze Zahlen zwischen 1 und 100. Der Standardwert beträgt zurzeit 30.

Die filter-Eigenschaft wird den folgenden Vorgängen hinzugefügt:

Der filter-Ausdruck kann verwendet werden, um eine Teilmenge der verfügbaren Ressourcen auszuwählen. Sie können nach displayName, description, createdDateTime, lastActionDateTime, status, locale und kind filtern. Beispiel: filter=locale eq 'en-US'

Der Models_ListFiles-Vorgang wurde hinzugefügt, um die Dateien des Modells abzurufen, das von der angegebenen ID identifiziert wurde.

Der Models_GetFile-Vorgang wurde hinzugefügt, um eine bestimmte (mit fileId identifizierte) Datei aus einem (mit ID identifizierten) Modell abzurufen. Dadurch können Sie eine ModelReport-Datei abrufen, die Informationen zu den während des Trainings verarbeiteten Daten zur Verfügung stellt.

Vorgangs-IDs

Sie müssen den Basispfad in Ihrem Code von /speechtotext/v3.0 auf /speechtotext/v3.1aktualisieren. Verwenden Sie z. B. https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base anstelle von https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base zum Abrufen von Basismodellen in der eastus-Region.

Der Name der jeweiligen operationId in Version 3.1 wird mit dem Objektnamen als Präfix versehen. Beispielsweise wurde die operationId für „Modell erstellen“ von CreateModel in Version 3.0 in Version 3.1 in Models_Create geändert.

Der Vorgang /models/{id}/copyto (mit „/“) in Version 3.0 wird in Version 3.1 durch den /models/{id}:copyto-Vorgang (mit „:“) ersetzt.

Der Vorgang /webhooks/{id}/ping (mit „/“) in Version 3.0 wird in Version 3.1 durch den /webhooks/{id}:ping-Vorgang (mit „:“) ersetzt.

Der Vorgang /webhooks/{id}/test (mit „/“) in Version 3.0 wird in Version 3.1 durch den /webhooks/{id}:test-Vorgang (mit „:“) ersetzt.

Nächste Schritte