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

아티클
04/13/2024

음성 텍스트 변환 REST API는 일괄 처리 기록 및 사용자 지정 음성에 사용됩니다. 버전 3.0에서 3.1로의 변경 내용은 아래 섹션에 설명되어 있습니다.

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.0에서 /speechtotext/v3.1로 업데이트해야 합니다. 예를 들어, eastus 지역에서 기본 모델을 얻으려면 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.0/models/base 대신 https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base를 사용합니다.

다음과 같은 다른 변경 사항에 유의합니다.

버전 3.0의 /models/{id}/copyto 작업('/'포함)은 버전 3.1의 /models/{id}:copyto 작업(':'포함)으로 대체됩니다.
버전 3.0의 /webhooks/{id}/ping 작업('/'포함)은 버전 3.1의 /webhooks/{id}:ping 작업(':'포함)으로 대체됩니다.
버전 3.0의 /webhooks/{id}/test 작업('/'포함)은 버전 3.1의 /webhooks/{id}:test 작업(':'포함)으로 대체됩니다.

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

전사 일괄 처리

참고 항목

Speech to text REST API v3.0을 사용하여 Speech to text REST API v3.1을 통해 생성된 전사를 사용하지 마세요. "API 버전은 이 대화 내용 기록에 액세스하는 데 사용할 수 없습니다. API 버전 v3.1 이상을 사용하세요." 같은 오류 메시지가 표시됩니다.

Transcriptions_Create 작업에는 다음의 세 가지 속성이 추가됩니다.

displayFormWordLevelTimestampsEnabled 속성은 대화 내용 기록 결과의 표시 형식에서 단어 수준의 타임스탬프를 보고하도록 하는 데 사용할 수 있습니다. 결과는 대화 내용 기록 파일의 displayWords 속성에 반환됩니다.
diarization 속성은 선택적 분리(화자 분리)를 수행할 때 생성할 화자 레이블의 최소/최대 수에 대한 힌트를 지정하는 데 사용할 수 있습니다. 이 기능을 사용하면 이제 서비스에서 두 명을 초과하는 화자에 대한 화자 레이블을 생성할 수 있습니다. 이 속성을 사용하려면 diarizationEnabled 속성 또한 true로 설정해야 합니다. v3.0 API에서는 화자 분리를 통해 식별할 수 있는 화자 수가 2명이었지만 v3.1 API에서는 이러한 화자 수가 증가했습니다. 성능 향상을 위해 화자 수를 30명 미만으로 유지하는 것이 좋습니다.
languageIdentification 속성은 대화 내용 기록 전 입력에서 언어 식별 설정을 지정하는 데 사용될 수 있습니다. 언어 식별에는 최대 10개의 후보 로캘이 지원됩니다. 반환된 대화 내용 기록에는 인식된 언어 또는 제공한 로캘에 대한 새 locale 속성이 포함됩니다.

filter 속성은 Transcriptions_List, Transcriptions_ListFiles, Projects_ListTranscriptions 작업에 추가됩니다. filter 식을 이용해 사용 가능한 리소스의 하위 집합을 선택할 수 있습니다. displayName, description, createdDateTime, lastActionDateTime, status, locale별로 필터링할 수 있습니다. 예: filter=createdDateTime gt 2022-02-01T11:00:00Z

웹후크를 사용하여 대화 내용 기록 상태에 대한 알림을 받는 경우, V3.0 API를 통해 만든 웹후크에서는 V3.1 대화 내용 기록 요청에 대한 알림을 받을 수 없습니다. V3.1 대화 내용 기록 요청에 대한 알림을 받으려면 V3.1 API를 통해 새로운 웹후크 엔드포인트를 만들어야 합니다.

사용자 지정 음성

데이터 집합

데이터 세트에 여러 데이터 블록을 업로드하고 관리하기 위해 다음 작업이 추가됩니다.

Datasets_UploadBlock - 데이터 세트에 대한 데이터 블록을 업로드합니다. 블록의 최대 크기는 8MiB입니다.
Datasets_GetDatasetBlocks - 이 데이터 세트에 업로드된 블록의 목록을 가져옵니다.
Datasets_CommitBlocks - 차단 목록을 커밋하여 데이터 세트 업로드를 완료합니다.

markdown 데이터에서 정형 텍스트로 모델 적응을 지원하기 위해 이제 Datasets_Create 작업에서는 LanguageMarkdown 데이터 종류를 지원합니다. 자세한 내용은 데이터 세트 업로드를 참조하세요.

모델

Models_ListBaseModels 및 Models_ListBaseModel 작업은 각 기본 모델에서 지원하는 적응 유형에 대한 정보를 반환합니다.

"features": {
    "supportsAdaptationsWith": [
        "Acoustic",
        "Language",
        "LanguageMarkdown",
        "Pronunciation"
    ]
}

Models_Create 작업에는 사용자 지정 언어 모델(일반 또는 정형 텍스트 테이터에서 학습됨)을 기본 언어 모델과 결합할 때 사용되는 가중치를 지정할 수 있는 새로운 customModelWeightPercent 속성이 있습니다. 유효한 값은 1~100의 정수입니다. 기본값은 현재 30입니다.

filter 속성은 다음 작업에 추가됩니다.

filter 식을 이용해 사용 가능한 리소스의 하위 집합을 선택할 수 있습니다. displayName, description, createdDateTime, lastActionDateTime, status, locale, kind별로 필터링할 수 있습니다. 예: filter=locale eq 'en-US'

지정된 ID별로 식별되는 모델의 파일을 가져오는 Models_ListFiles 작업을 추가했습니다.

모델(ID로 식별됨)에서 한 가지 특정 파일(fileId로 식별됨)을 가져오는 Models_GetFile 작업을 추가했습니다. 이렇게 하면 학습 중에 처리된 데이터에 대한 정보를 제공하는 ModelReport 파일을 검색할 수 있습니다.

작업 ID

버전 3.1의 각 operationId 이름에는 개체 이름이 접두사로 붙습니다. 예를 들면, ‘모델 만들기’의 operationId가 버전 3.0의 CreateModel에서 버전 3.1의 Models_Create로 변경되었습니다.

버전 3.0의 /models/{id}/copyto 작업('/'포함)은 버전 3.1의 /models/{id}:copyto 작업(':'포함)으로 대체됩니다.

버전 3.0의 /webhooks/{id}/ping 작업('/'포함)은 버전 3.1의 /webhooks/{id}:ping 작업(':'포함)으로 대체됩니다.

버전 3.0의 /webhooks/{id}/test 작업('/'포함)은 버전 3.1의 /webhooks/{id}:test 작업(':'포함)으로 대체됩니다.