Partilhar via

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

  • Artigo

A API REST Speech to text é usada para transcrição rápida, transcrição em lote e fala personalizada. Este artigo descreve as alterações da versão 3.1 para 3.2.

Importante

A versão 2024-11-15 da API REST de fala para texto é a versão mais recente disponível ao público.

  • A versão 2024-05-15-preview da API REST de fala para texto será desativada em uma data a ser anunciada.
  • Speech to text REST API v3.0, v3.1, v3.2, 3.2-preview.1, e 3.2-preview.2 será desativada em 1º de abril de 2026.

Para obter mais informações sobre atualização, consulte os guias de migração Speech to text REST API v3.0 para v3.1, v3.1 para v3.2 e v3.2 para 2024-11-15 .

Caminho base

Você deve atualizar o caminho base em seu código de /speechtotext/v3.1 para /speechtotext/v3.2. Por exemplo, para obter modelos base na eastus região, 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 em lotes

Importante

Novos preços estão em vigor para transcrição em lote via Speech to text REST API v3.2. Para obter mais informações, consulte o guia de preços.

Limitações de compatibilidade com versões anteriores

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

Modo de identificação linguística

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

Modelos de sussurro

O Azure AI Speech agora suporta o modelo Whisper da OpenAI por meio da API REST de fala para texto v3.2. Para saber mais, consulte o guia Criar uma transcrição em lote.

Nota

O Serviço OpenAI do Azure também suporta o modelo Whisper da OpenAI para conversão de voz em texto com uma API REST síncrona. Para saber mais, confira o guia de início rápido. Confira O que é o modelo Whisper?, para saber mais sobre quando usar o Azure AI Speech versus o Azure OpenAI Service.

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 posteriormente. 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 de texto de exibição personalizada

Para dar suporte à adaptação do modelo com dados de formatação de texto de exibição personalizados, a operação Datasets_Create suporta o tipo de dados OutputFormating. Para obter mais informações, consulte carregar conjuntos de dados.

Adicionada uma definição para OutputFormatType valores com Lexical e Display enum.

"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 OutputFormattingData valor do enum é adicionado a FileKind (tipo de dados de entrada).

A supportedOutputFormat propriedade é adicionada ao BaseModelFeatures. Esta propriedade está dentro da BaseModel definição.

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

Taxa de adaptação

A chargeForAdaptation propriedade é adicionada ao BaseModelProperties. Esta propriedade está dentro da BaseModel definição.

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 posteriormente. 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 chargeForAdaptation propriedade em vez da data criada para determinar programaticamente se você será 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 textNormalizationKind propriedade é adicionada ao DatasetProperties.

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

  • Padrão: 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 propriedades de contagem de token e erro de token às EvaluationProperties propriedades:

  • correctTokenCount1: O número de tokens reconhecidos corretamente por model1.
  • tokenCount1: O número de tokens processados por modelo1.
  • 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 pelo modelo1 que são substituições.
  • correctTokenCount2: O número de tokens reconhecidos corretamente por model2.
  • tokenCount2: O número de tokens processados por modelo2.
  • 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 pelo modelo2 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 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 copy propriedade.

  • copyTo URI: O local da ação de cópia de modelo obsoleta. 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 em seu código de /speechtotext/v3.1 para /speechtotext/v3.2. Por exemplo, para obter modelos base na eastus região, 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óximos passos