Migración de código de la versión v3.1 a v3.2 de la API REST

  • Artículo

La API REST de conversión de voz en texto se usa para transcripción de Batch y devoz personalizada. En este artículo se describen los cambios de la versión 3.1 a la 3.2.

Importante

La API de REST de la conversión de voz en texto v3.2 está disponible en versión preliminar. La API de REST de la conversión de voz en texto v3.1 está disponible con carácter general. La API de REST de la conversión de voz en texto v3.0 se retirará el 1 de abril de 2026. Para obtener más información, consulte las guías de migración de la API de REST de la conversión de voz en texto v3.0 a v3.1 y v3.1 a v3.2.

Ruta de acceso base

Debe actualizar la ruta de acceso base del código de /speechtotext/v3.1 a /speechtotext/v3.2-preview.2. Por ejemplo, para obtener modelos base en la región eastus, use https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base en lugar de https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base.

Para más información, consulte Identificadores de operación más adelante en esta guía.

Transcripción de Azure Batch

Importante

Los nuevos precios están en vigor para la transcripción por lotes a través de la API REST de conversión de voz en texto v3.2. Para obtener más información, consulte la guía de precios.

Limitaciones de compatibilidad con versiones anteriores

No use la API REST de Conversión de voz en texto v3.0 o v3.1 para recuperar una transcripción creada a través de la API REST de Conversión de voz en texto v3.2. Es posible que vea un mensaje de error como el siguiente "La versión de la API no se puede usar para acceder a esta transcripción. Use la versión de la API v3.2 o posterior".

Modelo de identificación de lenguaje

LanguageIdentificationMode se agrega a LanguageIdentificationProperties como elemento del mismo nivel de candidateLocales y speechModelMapping. Los modos disponibles para la identificación de lenguaje son Continuous o Single. La identificación continua de lenguaje es el valor predeterminado. Para obtener más información, consulte Identificación de idiomas.

Modelos de Whisper

Voz de Azure AI ahora admite el modelo de Whisper de OpenAI mediante la versión v3.2 de la API REST de Conversión de voz en texto. Para más información, consulte la guía Creación de una transcripción por lotes.

Nota:

Azure OpenAI Service también admite el modelo Whisper de OpenAI para la conversión de voz en texto con una API de REST sincrónica. Para obtener más información, consulte el inicio rápido. Consulte ¿Qué es el modelo Whisper? para obtener más información sobre cuándo usar Voz de Azure AI frente a Azure OpenAI Service.

Voz personalizada

Importante

Se le cargará por el entrenamiento del modelo de voz personalizado si el modelo base se creó el 1 de octubre de 2023 y más tarde. No se le cobrará por el entrenamiento si el modelo base se creó antes de octubre de 2023. Para obtener más información, consulte Precios de Voz de Azure AI.

Para determinar mediante programación si un modelo se creó antes o después del 1 de octubre de 2023, use la propiedad chargedForAdaptation que es nueva en la versión 3.2.

Formato de texto para mostrar personalizado

Para admitir la adaptación de modelos con datos de formato de texto para mostrar personalizado, la operación Datasets_Create admite el tipo de datos OutputFormatting. Para más información, consulte Carga de cuadernos.

Se ha agregado una definición para OutputFormatType con valores de enumeración Lexical y Display.

"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."
            }
        ]
    }
},

El valor de enumeración OutputFormattingData se agrega a FileKind (tipo de datos de entrada).

Se agregó la propiedad supportedOutputFormat a BaseModelFeatures. Esta propiedad está dentro de la definición de BaseModel.

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

Cargo por adaptación

Se agregó la propiedad chargeForAdaptation a BaseModelProperties. Esta propiedad está dentro de la definición de BaseModel.

Importante

Se le cargará por el entrenamiento del modelo de voz personalizado si el modelo base se creó el 1 de octubre de 2023 y más tarde. No se le cobrará por el entrenamiento si el modelo base se creó antes de octubre de 2023. Para obtener más información, consulte Precios de Voz de Azure AI.

Si el valor de chargeForAdaptation es true, se le cobrará por entrenar el modelo. Si el valor es false, se le cobrará por entrenar el modelo. Use la propiedad chargeForAdaptation en lugar de la fecha de creación para determinar mediante programación si se le cobrará por entrenar un modelo.

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

Normalización de texto

Se agregó la propiedad textNormalizationKind a DatasetProperties.

Definición de entidad para TextNormalizationKind: el tipo de normalización de texto.

  • Valor predeterminado: normalización de texto predeterminada (por ejemplo, "dos a tres" reemplaza a "2 a 3" en-US).
  • Ninguno: no se aplica ninguna normalización de texto al texto de entrada. Este valor es una opción de invalidación que solo se debe usar cuando el texto se normaliza antes de la carga.

Propiedades de evaluación

Se agregaron las propiedades de recuento de tokens y error de token a las propiedades EvaluationProperties:

  • correctTokenCount1: número de tokens reconocidos correctamente por model1.
  • tokenCount1: número de tokens procesados por model1.
  • tokenDeletionCount1: número de tokens reconocidos por model1 que son eliminaciones.
  • tokenErrorRate1: tasa de errores de token de reconocimiento con model1.
  • tokenInsertionCount1: número de tokens reconocidos por model1 que son inserciones.
  • tokenSubstitutionCount1: número de palabras reconocidas por model1 que son sustituciones.
  • correctTokenCount2: número de tokens reconocidos correctamente por model2.
  • tokenCount2: número de tokens procesados por model2.
  • tokenDeletionCount2: número de tokens reconocidos por model2 que son eliminaciones.
  • tokenErrorRate2: tasa de errores de tokens de reconocimiento con model2.
  • tokenInsertionCount2: número de tokens reconocidos por model2 que son inserciones.
  • tokenSubstitutionCount2: número de palabras reconocidas por model2 que son sustituciones.

Copia del modelo

Los cambios siguientes son para el escenario en el que se copia un modelo.

  • Se agregó la nueva operación de Models_Copy. Este es el esquema de la nueva operación de copia: "$ref": "#/definitions/ModelCopyAuthorization"
  • La operación de Models_CopyTo ha quedado en desuso. Este es el esquema de la operación de copia en desuso: "$ref": "#/definitions/ModelCopy"
  • Se ha agregado la nueva operación Models_AuthorizeCopy que devuelve "$ref": "#/definitions/ModelCopyAuthorization". Esta entidad devuelta se puede usar en la nueva operación Models_Copy.

Se ha agregado una nueva definición de entidad para 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"
        }
    }
},

Se ha agregado una nueva definición de entidad para ModelCopyAuthorizationDefinition:

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

Se agregó una nueva propiedad copy.

  • URI de copyTo: ubicación de la acción de copia del modelo obsoleto. Consulte la operación Models_CopyTo para obtener más información.
  • URI de copy: ubicación de la acción de copia del modelo. Consulte la operación Models_Copy para obtener más detalles.
"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
},

Identificadores de operación

Debe actualizar la ruta de acceso base del código de /speechtotext/v3.1 a /speechtotext/v3.2-preview.2. Por ejemplo, para obtener modelos base en la región eastus, use https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base en lugar de https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base.

Pasos siguientes