Teilen über

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

  • Artikel

Die Spracherkennungs-REST-API wird für die Batch-Transkription und für Custom Speech verwendet. In diesem Artikel werden Änderungen von Version 3.1 zu Version 3.2 beschrieben.

Wichtig

Die Spracherkennungs-REST-API v3.2 ist die neueste Version mit allgemeiner Verfügbarkeit. Die Vorschauversionen 3.2-preview.1 und 3.2-preview.2* werden im September 2024 entfernt. Die Spracherkennungs-REST-API v3.1 wird am Veröffentlichungsdatum eingestellt. Die Spracherkennungs-REST-API v3.0 wird am 1. April 2026 eingestellt.

Basispfad

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

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

Batch-Transkription

Wichtig

Für die Batchtranskription mithilfe von REST-API v3.2 für die Spracherkennung gelten neue Preise. Weitere Informationen hierzu finden Sie in der Preisübersicht.

Einschränkungen hinsichtlich der Abwärtskompatibilität

Verwenden Sie nicht REST-API v3.0 oder v3.1 für die Spracherkennung, um eine mit REST-API v3.2 für die Spracherkennung erstellte Transkription abzurufen. Möglicherweise wird eine Fehlermeldung ähnlich dieser angezeigt: „Die API-Version kann nicht für den Zugriff auf diese Transkription verwendet werden. Verwenden Sie API-Version 3.2 oder höher.“

Modus für die Sprachenerkennung

LanguageIdentificationMode wird LanguageIdentificationProperties gleichgeordnet zu candidateLocales und speechModelMapping hinzugefügt. Für die Sprachenerkennung stehen die Modi Continuous oder Single zur Verfügung. In der Standardeinstellung wird eine fortlaufende Sprachenerkennung durchgeführt. Weitere Informationen finden Sie unter Sprachenerkennung.

Whisper-Modelle

Azure KI Speech unterstützt über REST-API v3.2 für die Spracherkennung ab sofort das Whisper-Modell von OpenAI. Weitere Informationen finden Sie im Leitfaden Erstellen einer Batchtranskription.

Hinweis

Azure OpenAI Service unterstützt mit einer synchronen REST-API ebenfalls das OpenAI-Whisper-Modell für die Spracherkennung. Weitere Informationen finden Sie unter Schnellstart. Im Artikel Was ist das Whisper-Modell? erfahren Sie mehr darüber, wann Azure KI Speech bzw. wann Azure OpenAI Service verwendet werden sollte.

Custom Speech

Wichtig

Ihnen werden Gebühren für das Training des benutzerdefinierten Sprachmodells in Rechnung gestellt, wenn das Basismodell am 1. Oktober 2023 oder nach diesem Datum erstellt wurde. Wenn das Basismodell vor Oktober 2023 erstellt wurde, fallen keine Kosten für das Training an. Weitere Informationen finden Sie unter Azure KI Speech – Preise.

Um programmgesteuert zu bestimmen, ob ein Modell vor oder nach dem 1. Oktober 2023 erstellt wurde, verwenden Sie die in Version 3.2 neu eingeführte chargedForAdaptation-Eigenschaft.

Benutzerdefinierte Anzeigetextformatierung

Zur Unterstützung der Modellanpassung mit benutzerdefinierter Anzeigetextformatierung für -Daten unterstützt der Vorgang Datasets_Create die Datenart OutputFormatting. Weitere Informationen finden Sie unter Hochladen von Datasets.

Eine Definition für OutputFormatType mit Lexical und Display Enumerationswerten hinzugefügt.

"OutputFormatType": {
    "title": "OutputFormatType",
    "enum": [
        "Lexical",
        "Display"
    ],
    "type": "string",
    "x-ms-enum": {
        "name": "OutputFormatType",
        "modelAsString": true,
        "values": [
            {
                "value": "Lexical",
                "description": "Model provides the transcription output without formatting."
            },
            {
                "value": "Display",
                "description": "Model supports display formatting transcriptions output or endpoints."
            }
        ]
    }
},

Der Enumerationswert OutputFormattingData wurde zu FileKind hinzugefügt (Typ der Eingabedaten).

Die supportedOutputFormat-Eigenschaft wird zu BaseModelFeatures hinzugefügt. Diese Eigenschaft befindet sich in der BaseModel-Definition.

"BaseModelFeatures": {
    "title": "BaseModelFeatures",
    "description": "Features supported by the model.",
    "type": "object",
    "allOf": [
        {
            "$ref": "#/definitions/SharedModelFeatures"
        }
    ],
    "properties": {
        "supportsAdaptationsWith": {
            "description": "Supported dataset kinds to adapt the model.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/DatasetKind"
            },
            "readOnly": true
        },
        "supportedOutputFormat": {
            "description": "Supported output formats.",
            "type": "array",
            "items": {
                "$ref": "#/definitions/OutputFormatType"
            },
            "readOnly": true
        }
    }
},

Gebühren für die Anpassung

Die chargeForAdaptation-Eigenschaft wird zu BaseModelProperties hinzugefügt. Diese Eigenschaft befindet sich in der BaseModel-Definition.

Wichtig

Ihnen werden Gebühren für das Training des benutzerdefinierten Sprachmodells in Rechnung gestellt, wenn das Basismodell am 1. Oktober 2023 oder nach diesem Datum erstellt wurde. Wenn das Basismodell vor Oktober 2023 erstellt wurde, fallen keine Kosten für das Training an. Weitere Informationen finden Sie unter Azure KI Speech – Preise.

Wenn chargeForAdaptation den Wert true aufweist, werden Ihnen Gebühren für das Modelltraining in Rechnung gestellt. Wenn der Wert false lautet, werden Ihnen keine Gebühren für das Training des Modells in Rechnung gestellt. Verwenden Sie anstelle des Erstellungsdatums die Eigenschaft chargeForAdaptation, um programmgesteuert zu ermitteln, ob für das Training eines Modells Gebühren anfallen.

"BaseModelProperties": {
    "title": "BaseModelProperties",
    "type": "object",
    "properties": {
        "deprecationDates": {
            "$ref": "#/definitions/BaseModelDeprecationDates"
        },
        "features": {
            "$ref": "#/definitions/BaseModelFeatures"
        },
        "chargeForAdaptation": {
            "description": "A value indicating whether model adaptation is charged.",
            "type": "boolean",
            "readOnly": true
        }
    }
},

Textnormalisierung

Die textNormalizationKind-Eigenschaft wird zu DatasetProperties hinzugefügt.

Entitätsdefinition für TextNormalizationKind: Die Art der Textnormalisierung.

  • Default: Standardmäßige Textnormalisierung (z. B. wird für en-US '2 to 3' durch 'two to three' ersetzt).
  • None: Auf den Eingabetext wird keine Textnormalisierung angewendet. Dieser Wert ist eine Überschreibungsoption, die nur verwendet werden sollte, wenn der Text vor dem Hochladen normalisiert wird.

Auswertungseigenschaften

Eigenschaften für Tokenanzahl und Tokenfehler zu den EvaluationProperties-Eigenschaften hinzugefügt:

  • correctTokenCount1: Die Anzahl der von model1 ordnungsgemäß erkannten Token.
  • tokenCount1: Die Anzahl der von model1 verarbeiteten Token.
  • tokenDeletionCount1: Die Anzahl der von model1 erkannten Token, bei denen es sich um Löschungen handelt.
  • tokenErrorRate1: Die Tokenfehlerrate bei der Erkennung mit model1.
  • tokenInsertionCount1: Die Anzahl der von model1 erkannten Token, bei denen es sich um Einfügungen handelt.
  • tokenSubstitutionCount1: Die Anzahl der von model1 erkannten Wörter, bei denen es sich um Ersetzungen handelt.
  • correctTokenCount2: Die Anzahl der von model2 ordnungsgemäß erkannten Token.
  • tokenCount2: Die Anzahl der von model2 verarbeiteten Token.
  • tokenDeletionCount2: Die Anzahl der von model2 erkannten Token, bei denen es sich um Löschungen handelt.
  • tokenErrorRate2: Die Tokenfehlerrate bei der Erkennung mit model2.
  • tokenInsertionCount2: Die Anzahl der von model2 erkannten Token, bei denen es sich um Einfügungen handelt.
  • tokenSubstitutionCount2: Die Anzahl der von model2 erkannten Wörter, bei denen es sich um Ersetzungen handelt.

Modellkopie

Die folgenden Änderungen gelten für das Szenario, in dem Sie ein Modell kopieren.

  • Der neue Models_Copy-Vorgang wurde hinzugefügt. Hier sehen Sie das Schema im neuen Kopiervorgang: "$ref": "#/definitions/ModelCopyAuthorization"
  • Der Models_CopyTo-Vorgang wird nicht mehr unterstützt. Hier ist das Schema im veralteten Kopiervorgang: "$ref": "#/definitions/ModelCopy"
  • Der neue Models_AuthorizeCopy-Vorgang wurde hinzugefügt, der "$ref": "#/definitions/ModelCopyAuthorization" zurückgibt. Diese zurückgegebene Entität kann im neuen Models_Copy-Vorgang verwendet werden.

Neue Entitätsdefinition für ModelCopyAuthorization:

"ModelCopyAuthorization": {
    "title": "ModelCopyAuthorization",
    "required": [
        "expirationDateTime",
        "id",
        "sourceResourceId",
        "targetResourceEndpoint",
        "targetResourceId",
        "targetResourceRegion"
    ],
    "type": "object",
    "properties": {
        "targetResourceRegion": {
            "description": "The region (aka location) of the target speech resource (e.g., westus2).",
            "minLength": 1,
            "type": "string"
        },
        "targetResourceId": {
            "description": "The Azure Resource ID of the target speech resource.",
            "minLength": 1,
            "type": "string"
        },
        "targetResourceEndpoint": {
            "description": "The endpoint (base url) of the target resource (with custom domain name when it is used).",
            "minLength": 1,
            "type": "string"
        },
        "sourceResourceId": {
            "description": "The Azure Resource ID of the source speech resource.",
            "minLength": 1,
            "type": "string"
        },
        "expirationDateTime": {
            "format": "date-time",
            "description": "The expiration date of this copy authorization.",
            "type": "string"
        },
        "id": {
            "description": "The ID of this copy authorization.",
            "minLength": 1,
            "type": "string"
        }
    }
},

Neue Entitätsdefinition für ModelCopyAuthorizationDefinition:

"ModelCopyAuthorizationDefinition": {
    "title": "ModelCopyAuthorizationDefinition",
    "required": [
        "sourceResourceId"
    ],
    "type": "object",
    "properties": {
        "sourceResourceId": {
            "description": "The Azure Resource ID of the source speech resource.",
            "minLength": 1,
            "type": "string"
        }
    }
},

Neue copy-Eigenschaft hinzugefügt.

  • copyTo-URI: Der Speicherort der veralteten Modellkopieraktion. Weitere Informationen finden Sie im Models_CopyTo-Vorgang.
  • copy-URI: Der Speicherort der Modellkopieraktion. Weitere Informationen finden Sie im Models_Copy-Vorgang.
"CustomModelLinks": {
    "title": "CustomModelLinks",
    "type": "object",
    "properties": {
      "copyTo": {
        "format": "uri",
        "description": "The location to the obsolete model copy action. See operation \"Models_CopyTo\" for more details.",
        "type": "string",
        "readOnly": true
      },
      "copy": {
        "format": "uri",
        "description": "The location to the model copy action. See operation \"Models_Copy\" for more details.",
        "type": "string",
        "readOnly": true
      },
      "files": {
        "format": "uri",
        "description": "The location to get all files of this entity. See operation \"Models_ListFiles\" for more details.",
        "type": "string",
        "readOnly": true
      },
      "manifest": {
        "format": "uri",
        "description": "The location to get a manifest for this model to be used in the on-prem container. See operation \"Models_GetCustomModelManifest\" for more details.",
        "type": "string",
        "readOnly": true
      }
    },
    "readOnly": true
},

Vorgangs-IDs

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

Nächste Schritte