Migrar o código da v3.1 para a v3.2 da API REST

  • Artigo

A API REST de Conversão de fala em texto é usada para a Transcrição em lote e a fala personalizada. Este artigo descreve as alterações da versão 3.1 para 3.2.

Importante

A API REST de conversão de fala em texto v3.2 é a versão mais recente em disponibilidade geral. As versões prévias 3.2-preview.1 e 3.2-preview.2* serão removidas em setembro de 2024. A API REST de conversão de fala em texto v3.1 será desativada em uma data a ser anunciada. A API REST de conversão de fala em texto v3.0 será desativada em 1º de abril de 2026.

Caminho Base

Você deve atualizar o caminho base no código de /speechtotext/v3.1 para /speechtotext/v3.2. Por exemplo, para obter modelos base na região eastus, use https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base em vez de https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base.

Para obter mais informações, consulte IDs de operação mais adiante neste guia.

Transcrição de lote

Importante

Novos preços estão em vigor para transcrição em lote por meio da API REST de Conversão de Fala em Texto v3.2. Para saber mais, consulte o guia de preços.

Limitações de compatibilidade com versões anteriores

Não use a API REST de conversão de fala em texto v3.0 ou v3.1 para recuperar uma transcrição criada por meio da API REST de conversão de fala em texto v3.2. Talvez você veja uma mensagem de erro como:"A versão da API não pode ser usada para acessar esta transcrição. Use a versão v3.2 ou superior da API".

Modo de identificação de idioma

O LanguageIdentificationMode é adicionado a LanguageIdentificationProperties como irmão de candidateLocales e speechModelMapping. Os modos disponíveis para identificação de idioma são Continuous ou Single. A identificação contínua de idioma é o padrão. Para obter mais informações, confira Identificação de idioma.

Modelos de sussurro

A Fala de IA do Azure agora dá suporte ao modelo Whisper do OpenAI por meio da API REST de conversão de fala em texto v3.2. Para saber mais, marcar o guia Criar uma transcrição em lote.

Observação

O Serviço OpenAI do Azure também dá suporte ao modelo Whisper do OpenAI para conversão de fala em texto com uma API REST síncrona. Para saber mais, confira este início rápido. ConsulteO que é o modelo Whisper? para saber mais sobre quando usar a Fala de IA do Azure versus o Serviço OpenAI do Azure.

Fala Personalizada

Importante

Você será cobrado pelo treinamento de modelo de fala personalizado se o modelo base tiver sido criado em 1º de outubro de 2023 e posterior. Você não será cobrado pelo treinamento se o modelo base tiver sido criado antes de outubro de 2023. Para obter mais informações, consulte Preços do Azure AI Speech.

Para determinar programaticamente se um modelo foi criado antes ou depois de 1º de outubro de 2023, use a chargedForAdaptation propriedade que é nova na versão 3.2.

Formatação personalizada do texto de exibição

Para dar suporte à adaptação do modelo com dados formatação de texto da exibição personalizada, a operação Datasets_Create dá suporte ao tipo de dados OutputFormatting. Para saber mais, confira Carregar conjunto de dados.

Foi adicionada uma definição para OutputFormatType com Lexical e Display valores de enumeração.

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

O valor da enumeração OutputFormattingData é adicionado a FileKind (tipo de dados de entrada).

A propriedade supportedOutputFormat foi adicionada à BaseModelFeatures. Essa propriedade está dentro da definição 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
        }
    }
},

Cobrança pela adaptação

A propriedade chargeForAdaptation foi adicionada à BaseModelProperties. Essa propriedade está dentro da definição BaseModel.

Importante

Você será cobrado pelo treinamento de modelo de fala personalizado se o modelo base tiver sido criado em 1º de outubro de 2023 e posterior. Você não será cobrado pelo treinamento se o modelo base tiver sido criado antes de outubro de 2023. Para obter mais informações, consulte Preços do Azure AI Speech.

Se o valor de chargeForAdaptation for true, você será cobrado pelo treinamento do modelo. Se o valor for false, você será cobrado pelo treinamento do modelo. Use a propriedade chargeForAdaptation em vez da data de criação para determinar programaticamente se você é cobrado pelo treinamento de um 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
        }
    }
},

Normalização de texto

A propriedade textNormalizationKind é adicionada ao DatasetProperties.

Definição de entidade para TextNormalizationKind: o tipo de normalização de texto.

  • Padrão: a normalização de texto padrão (por exemplo, 'dois a três' substitui '2 a 3' em en-US).
  • Nenhum: nenhuma normalização de texto é aplicada ao texto de entrada. Esse valor é uma opção de substituição que só deve ser usada quando o texto é normalizado antes do upload.

Propriedades de avaliação

Adicionadas as propriedades de erro de token e contagem de tokens às EvaluationProperties propriedades:

  • correctTokenCount1: o número de tokens reconhecidos corretamente por model1.
  • tokenCount1: o número de tokens processados por model1.
  • tokenDeletionCount1: o número de tokens reconhecidos por model1 que são exclusões.
  • tokenErrorRate1: a taxa de erro de token de reconhecimento com model1.
  • tokenInsertionCount1: o número de tokens reconhecidos por model1 que são inserções.
  • tokenSubstitutionCount1: o número de palavras reconhecidas por model1 que são substituições.
  • correctTokenCount2: o número de tokens reconhecidos corretamente por model2.
  • tokenCount2: o número de tokens processados por model2.
  • tokenDeletionCount2: o número de tokens reconhecidos por model2 que são exclusões.
  • tokenErrorRate2: a taxa de erro de token de reconhecimento com model2.
  • tokenInsertionCount2: o número de tokens reconhecidos por model2 que são inserções.
  • tokenSubstitutionCount2: o número de palavras reconhecidas por model2 que são substituições.

Cópia do modelo

As alterações a seguir são para o cenário em que você copia um modelo.

  • Adicionada a nova operação de Models_Copy. Aqui está o esquema na nova operação de cópia: "$ref": "#/definitions/ModelCopyAuthorization"
  • Operação Models_CopyTo preterida. Aqui está o esquema na operação de cópia preterida: "$ref": "#/definitions/ModelCopy"
  • Adicionada a nova operação de Models_AuthorizeCopy que retorna "$ref": "#/definitions/ModelCopyAuthorization". Essa entidade retornada poderá ser utilizada na nova operação Models_Copy.

Adicionada uma nova definição de entidade 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"
        }
    }
},

Adicionada uma nova definição de entidade 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"
        }
    }
},

Adicionada uma nova propriedade copy.

  • copyTo URI: o local da ação de cópia do modelo obsoleto. Consulte a operação Models_CopyTo para obter mais detalhes.
  • copy URI: o local da ação de cópia do modelo. Consulte a operação Models_Copy para obter mais detalhes.
"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
},

IDs de operação

Você deve atualizar o caminho base no código de /speechtotext/v3.1 para /speechtotext/v3.2. Por exemplo, para obter modelos base na região eastus, use https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base em vez de https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base.

Próximas etapas