Share via

REST API v3.1에서 v3.2로 코드 마이그레이션

  • 아티클

음성 텍스트 변환 REST API는 일괄 처리 기록 및 사용자 지정 음성에 사용됩니다. 이 문서에서는 버전 3.1에서 3.2로의 변경에 대해 설명합니다.

Important

음성 텍스트 변환 REST API v3.2는 미리 보기로 사용 가능합니다. 음성 텍스트 변환 REST API v3.1이 일반적으로 사용 가능합니다. 음성 텍스트 변환 REST API 버전 3.0은 2026년 4월 1일부터 사용 중지됩니다. 자세한 내용은 음성 텍스트 변환 REST API v3.0에서 v3.1 마이그레이션 가이드와 v3.1에서 v3.2 마이그레이션 가이드를 참조하세요.

기본 경로

코드의 기본 경로를 /speechtotext/v3.1에서 /speechtotext/v3.2-preview.2로 업데이트해야 합니다. 예를 들어, eastus 지역에서 기본 모델을 얻으려면 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base 대신 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base를 사용합니다.

자세한 내용은 이 가이드 뒷부분에 있는 작업 ID를 참조하세요.

전사 일괄 처리

Important

음성 텍스트 변환 REST API v3.2를 통한 일괄 처리 대화 기록에 새로운 가격 책정이 적용됩니다. 자세한 내용은 가격 책정 가이드를 참조하세요.

이전 버전과의 호환성 제한 사항

음성 텍스트 변환 REST API v3.2를 통해 만들어진 대화 내용 기록을 검색하는 데 음성 텍스트 변환 REST API v3.0 또는 v3.1을 사용하지 마세요. "API 버전은 이 대화 내용 기록에 액세스하는 데 사용할 수 없습니다. API 버전 v3.2 이상을 사용하세요." 같은 오류 메시지가 표시될 수 있습니다.

언어 식별 모드

LanguageIdentificationMode는 candidateLocales 및 speechModelMapping의 형제로 LanguageIdentificationProperties에 추가됩니다. 언어 식별에 사용할 수 있는 모드는 Continuous 또는 Single입니다. 연속 언어 식별이 기본값입니다. 자세한 내용은 언어 식별을 참조하세요.

Whisper 모델

이제 Azure AI 음성은 음성 텍스트 변환 REST API를 통해 OpenAI의 Whisper 모델을 지원합니다. 자세한 내용은 일괄 처리 대화 내용 기록 만들기 가이드를 확인해 보세요.

참고 항목

Azure OpenAI 서비스는 동기 REST API를 사용하여 음성을 텍스트로 변환하기 위한 OpenAI의 Whisper 모델도 지원합니다. 자세히 알아보려면 빠른 시작을 확인하세요. Azure AI 음성과 Azure OpenAI Service를 언제 사용해야 하는지 자세히 알아보려면 Whisper 모델이란?을 확인하세요.

사용자 지정 음성

Important

기본 모델이 2023년 10월 1일 이후에 만들어진 경우, 사용자 지정 음성 모델 학습에 대한 요금이 청구됩니다. 기본 모델이 2023년 10월 이전에 만들어진 경우에는 학습에 대한 요금이 청구되지 않습니다. 자세한 내용은 Azure AI 음성 가격 책정을 참조하세요.

2023년 10월 1일 이전 또는 이후에 모델을 만들었는지 여부를 프로그래밍 방식으로 확인하려면 버전 3.2에 새로 도입된chargedForAdaptation 속성을 사용합니다.

사용자 지정 표시 텍스트 서식

사용자 지정 표시 텍스트 서식 데이터로 모델 적응을 지원하기 위해 Datasets_Create 작업은 OutputFormatting 데이터 종류를 지원합니다. 자세한 내용은 데이터 세트 업로드를 참조하세요.

Lexical 및 Display 열거형 값이 있는 OutputFormatType에 대한 정의가 추가되었습니다.

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

OutputFormattingData 열거형 값은 FileKind(입력 데이터 형식)에 추가됩니다.

supportedOutputFormat 속성은 BaseModelFeatures에 추가됩니다. 이 속성은 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
        }
    }
},

적응에 대한 요금

chargeForAdaptation 속성은 BaseModelProperties에 추가됩니다. 이 속성은 BaseModel 정의 내에 있습니다.

Important

기본 모델이 2023년 10월 1일 이후에 만들어진 경우, 사용자 지정 음성 모델 학습에 대한 요금이 청구됩니다. 기본 모델이 2023년 10월 이전에 만들어진 경우에는 학습에 대한 요금이 청구되지 않습니다. 자세한 내용은 Azure AI 음성 가격 책정을 참조하세요.

chargeForAdaptation 값이 true인 경우 모델 학습에 대한 요금이 청구됩니다. 값이 false인 경우 모델 학습에 대한 요금이 청구됩니다. 만든 날짜 대신 chargeForAdaptation 속성을 사용하여 모델 학습에 대한 요금이 청구되는지 여부를 프로그래밍 방식으로 확인합니다.

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

텍스트 정규화

textNormalizationKind 속성은 DatasetProperties에 추가됩니다.

TextNormalizationKind에 대한 엔터티 정의: 텍스트 정규화의 종류입니다.

  • 기본값: 기본 텍스트 정규화입니다(예: en-US에서는 '2에서 3까지'가 '2~3'으로 대체됨).
  • 없음: 입력 텍스트에 텍스트 정규화가 적용되지 않습니다. 이 값은 업로드 전에 텍스트를 정규화할 때만 사용해야 하는 재정의 옵션입니다.

평가 속성

EvaluationProperties 속성에 토큰 수 및 토큰 오류 속성이 추가되었습니다.

  • correctTokenCount1: model1에서 올바르게 인식된 토큰의 수입니다.
  • tokenCount1: model1에서 처리된 토큰 수입니다.
  • tokenDeletionCount1: 삭제되는 model1에서 인식된 토큰의 수입니다.
  • tokenErrorRate1: model1을 사용한 인식의 토큰 오류율입니다.
  • tokenInsertionCount1: 삽입되는 model1에서 인식된 토큰의 수입니다.
  • tokenSubstitutionCount1: 대체되는 model1에서 인식된 토큰의 수입니다.
  • correctTokenCount2: model2에서 올바르게 인식된 토큰의 수입니다.
  • tokenCount2: model2에서 처리된 토큰 수입니다.
  • tokenDeletionCount2: 삭제되는 model2에서 인식된 토큰의 수입니다.
  • tokenErrorRate2: model2를 사용한 인식의 토큰 오류율입니다.
  • tokenInsertionCount2: 삽입되는 model2에서 인식된 토큰의 수입니다.
  • tokenSubstitutionCount2: 대체되는 model2에서 인식된 토큰의 수입니다.

모델 복사

모델을 복사하는 시나리오에는 다음과 같은 변경 내용이 있습니다.

  • 새 Models_Copy 작업이 추가되었습니다. 새 복사 작업의 스키마는 다음과 같습니다. "$ref": "#/definitions/ModelCopyAuthorization"
  • Models_CopyTo 작업이 더 이상 사용되지 않습니다. 사용되지 않는 복사 작업의 스키마는 다음과 같습니다. "$ref": "#/definitions/ModelCopy"
  • "$ref": "#/definitions/ModelCopyAuthorization"(을)를 반환하는 새 Models_AuthorizeCopy 작업이 추가되었습니다. 반환된 이 엔터티는 새 Models_Copy 작업에서 사용할 수 있습니다.

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

ModelCopyAuthorizationDefinition에 대한 새 엔터티 정의가 추가되었습니다.

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

새 copy 속성이 추가되었습니다.

  • copyTo URI: 사용되지 않는 모델 복사 작업의 위치입니다. 자세한 내용은 Models_CopyTo 작업을 참조하세요.
  • copy URI: 모델 복사 작업의 위치입니다. 자세한 내용은 Models_Copy 작업을 참조하세요.
"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
},

작업 ID

코드의 기본 경로를 /speechtotext/v3.1에서 /speechtotext/v3.2-preview.2로 업데이트해야 합니다. 예를 들어, eastus 지역에서 기본 모델을 얻으려면 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base 대신 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/models/base를 사용합니다.

다음 단계