다음을 통해 공유


일괄 처리 기록 만들기

일괄 처리 전사를 사용하면 오디오 데이터를 일괄 처리로 제출합니다. 이 서비스는 오디오 데이터를 전사하고 결과를 스토리지 컨테이너에 저장합니다. 그런 다음, 스토리지 컨테이너에서 결과를 검색할 수 있습니다.

Important

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

필수 조건

  • Speech SDK가 설치되었습니다.
  • 표준(S0) 음성 리소스입니다. 무료 리소스(F0)는 지원되지 않습니다.

대화 내용 기록 작업 만들기

대화 내용 기록을 만들려면 음성 텍스트 변환 REST APITranscriptions_Create 작업을 사용합니다. 다음 지침에 따라 요청 본문을 생성합니다.

  • contentContainerUrl 또는 contentUrls 속성을 설정해야 합니다. 일괄 처리 대화 내용 기록을 위한 Azure Blob Storage에 대한 자세한 내용은 일괄 처리 대화 내용 기록을 위한 오디오 파일 찾기를 참조하세요.
  • 필수 locale 속성을 설정합니다. 이 값은 내용을 기록할 오디오 데이터의 예상 로캘과 일치해야 합니다. 나중에 로캘을 변경할 수 없습니다.
  • 필수 displayName 속성을 설정합니다. 나중에 참조할 수 있는 대화 내용 기록 이름을 선택합니다. 대화 내용 기록 이름은 고유할 필요가 없으며 나중에 변경할 수 있습니다.
  • 필요에 따라 기본 모델 이외의 모델을 사용하려면 model 속성을 모델 ID로 설정합니다. 자세한 내용은 사용자 지정 모델 사용Whisper 모델 사용을 참조하세요.
  • 필요에 따라 wordLevelTimestampsEnabled 속성을 true로 설정하여 대화 내용 기록 결과에서 단어 수준 타임스탬프를 사용하도록 설정합니다. 기본값은 false입니다. Whisper 모델의 경우 대신 displayFormWordLevelTimestampsEnabled 속성을 설정합니다. Whisper는 표시 전용 모델이므로 녹취록에 어휘 필드가 채워지지 않습니다.
  • 필요에 따라 languageIdentification 속성을 설정합니다. 언어 식별은 지원되는 언어 목록과 비교할 때 오디오에서 말하는 언어를 식별하는 데 사용됩니다. languageIdentification 속성을 설정하는 경우 후보 로캘을 사용하여 languageIdentification.candidateLocales도 설정해야 합니다.

자세한 내용은 요청 구성 옵션을 참조하세요.

다음 Transcriptions_Create 예제와 같이 URI를 사용하는 HTTP POST 요청을 수행합니다.

  • YourSubscriptionKey를 Speech 리소스 키로 바꿉니다.
  • YourServiceRegion을 음성 리소스 지역으로 바꿉니다.
  • 이전에 설명한 대로 요청 본문 속성을 설정합니다.
curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": null,
  "properties": {
    "wordLevelTimestampsEnabled": true,
    "languageIdentification": {
      "candidateLocales": [
        "en-US", "de-DE", "es-ES"
      ],
    }
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions"

응답 본문은 다음 형식으로 표시되어야 합니다.

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/db474955-ab85-4c6c-ba6e-3bfe63d041ba/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": true,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked",
    "languageIdentification": {
      "candidateLocales": [
        "en-US",
        "de-DE",
        "es-ES"
      ]
    }
  },
  "lastActionDateTime": "2022-10-21T14:18:06Z",
  "status": "NotStarted",
  "createdDateTime": "2022-10-21T14:18:06Z",
  "locale": "en-US",
  "displayName": "My Transcription"
}

응답 본문의 최상위 self 속성은 대화 내용 기록의 URI입니다. 이 URI를 사용하여 대화 내용 기록 및 대화 내용 기록 보고서 파일의 URI 같은 세부 정보를 가져옵니다. 또한 이 URI를 사용하여 대화 내용 기록을 업데이트하거나삭제합니다.

Transcriptions_Get 작업을 사용하여 대화 내용 기록 상태를 쿼리할 수 있습니다.

결과를 검색한 후 서비스에서 정기적으로 Transcriptions_Delete를 호출합니다. 또는 결과가 최종적으로 삭제되도록 timeToLive 속성을 설정합니다.

대화 내용 기록을 만들려면 spx batch transcription create 명령을 사용합니다. 다음 지침에 따라 요청 매개 변수를 생성합니다.

  • 필수 content 매개 변수를 설정합니다. 개별 파일의 세미콜론으로 구분된 목록 또는 전체 컨테이너의 URL을 지정할 수 있습니다. 일괄 처리 대화 내용 기록을 위한 Azure Blob Storage에 대한 자세한 내용은 일괄 처리 대화 내용 기록을 위한 오디오 파일 찾기를 참조하세요.
  • 필수 language 속성을 설정합니다. 이 값은 내용을 기록할 오디오 데이터의 예상 로캘과 일치해야 합니다. 나중에 로캘을 변경할 수 없습니다. Speech CLI language 매개 변수는 JSON 요청 및 응답의 locale 속성에 해당합니다.
  • 필수 name 속성을 설정합니다. 나중에 참조할 수 있는 대화 내용 기록 이름을 선택합니다. 대화 내용 기록 이름은 고유할 필요가 없으며 나중에 변경할 수 있습니다. Speech CLI name 매개 변수는 JSON 요청 및 응답의 displayName 속성에 해당합니다.

다음은 대화 내용 기록 작업을 만드는 음성 CLI 명령의 예입니다.

spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav

응답 본문은 다음 형식으로 표시되어야 합니다.

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/13fb305e-09ad-4bce-b3a1-938c9124dda3"
  },
  "links": {
    "files": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions/7f4232d5-9873-47a7-a6f7-4a3f00d00dc0/files"
  },
  "properties": {
    "diarizationEnabled": false,
    "wordLevelTimestampsEnabled": false,
    "channels": [
      0,
      1
    ],
    "punctuationMode": "DictatedAndAutomatic",
    "profanityFilterMode": "Masked"
  },
  "lastActionDateTime": "2022-10-21T14:21:59Z",
  "status": "NotStarted",
  "createdDateTime": "2022-10-21T14:21:59Z",
  "locale": "en-US",
  "displayName": "My Transcription",
  "description": ""
}

응답 본문의 최상위 self 속성은 대화 내용 기록의 URI입니다. 이 URI를 사용하여 대화 내용 기록 및 대화 내용 기록 보고서 파일의 URI 같은 세부 정보를 가져옵니다. 또한 이 URI를 사용하여 대화 내용 기록을 업데이트하거나 삭제합니다.

대화 내용 기록에 대한 음성 CLI 도움말을 보려면 다음 명령을 실행합니다.

spx help batch transcription

요청 구성 옵션

다음은 Transcriptions_Create 작업을 호출할 때 대화 내용 기록을 구성하는 데 사용할 수 있는 몇 가지 속성 옵션입니다.

속성 설명
channels 처리할 채널 번호의 배열입니다. 채널 01는 기본적으로 전사됩니다.
contentContainerUrl 개별 오디오 파일 또는 전체 스토리지 컨테이너를 제출할 수 있습니다.

contentContainerUrl 또는 contentUrls 속성을 사용하여 오디오 데이터 위치를 지정해야 합니다. 일괄 처리 대화 내용 기록을 위한 Azure Blob Storage에 대한 자세한 내용은 일괄 처리 대화 내용 기록을 위한 오디오 파일 찾기를 참조하세요.

이 속성은 응답에서 반환되지 않습니다.
contentUrls 개별 오디오 파일 또는 전체 스토리지 컨테이너를 제출할 수 있습니다.

contentContainerUrl 또는 contentUrls 속성을 사용하여 오디오 데이터 위치를 지정해야 합니다. 자세한 내용은 일괄 처리 대화 내용 기록용 오디오 파일 찾기를 참조하세요.

이 속성은 응답에서 반환되지 않습니다.
destinationContainerUrl 결과를 Azure 컨테이너에 저장할 수 있습니다. 컨테이너를 지정하지 않으면 음성 서비스에 의해 Microsoft에서 관리하는 컨테이너에 결과가 저장됩니다. 대화 기록 작업이 삭제되면 대화 기록 결과 데이터도 삭제됩니다. 지원되는 보안 시나리오와 같은 자세한 내용은 대상 컨테이너 URL 지정을 참조하세요.
diarization Speech Service에서 입력에 대한 분할 분석을 시도해야 하며, 이는 여러 음성이 포함된 모노 채널이어야 합니다. 스테레오 녹음에서는 이 기능을 사용할 수 없습니다.

분할은 발화자를 오디오 데이터로 분리하는 프로세스입니다. 일괄 처리 파이프라인은 모노 채널 녹음에서 여러 발화자를 인식하고 구분할 수 있습니다.

말할 수 있는 최소 및 최대 사용자 수를 지정합니다. 또한 diarizationEnabled 속성을 true로 설정해야 합니다. 전사 파일에는 기록된 각 구에 대한 speaker 항목이 포함되어 있습니다.

3개 이상의 스피커가 필요한 경우 이 속성을 사용해야 합니다. 두 스피커의 경우 diarizationEnabled 속성을 true로 설정하는 것만으로도 충분합니다. 속성 사용의 예는 Transcriptions_Create를 참조하세요.

분할을 위한 최대 스피커 수는 36개 미만이어야 하며 minSpeakers 속성과 같거나 이상이어야 합니다. 예제는 Transcriptions_Create를 참조하세요.

이 속성을 선택하면 원본 오디오 길이가 파일당 240분을 초과할 수 없습니다.

참고: 이 속성은 음성 텍스트 변환 REST API 버전 3.1 이상에서만 사용할 수 있습니다. 이전 버전(예: 버전 3.0)으로 이 속성을 설정하면 무시되고 두 명의 스피커만 식별됩니다.
diarizationEnabled Speech Service에서 입력에 대한 분할 분석을 시도하도록 지정합니다. 이는 두 개의 음성이 포함된 모노 채널이어야 합니다. 기본값은 false입니다.

세 개 이상의 음성의 경우 diarization 속성을 사용해야 합니다. 음성 텍스트 변환 REST API 버전 3.1 이상에서만 사용합니다.

이 속성을 선택하면 원본 오디오 길이가 파일당 240분을 초과할 수 없습니다.
displayName 일괄 처리 대화 내용 기록의 이름입니다. 나중에 참조할 수 있는 이름을 선택합니다. 표시 이름은 고유하지 않아도 됩니다.

이 속성은 필수입니다.
displayFormWordLevelTimestampsEnabled 대화 기록 결과의 표시 형식에 단어 수준 타임스탬프를 포함할지 여부를 지정합니다. 결과는 대화 내용 기록 파일의 displayWords 속성에 반환됩니다. 기본값은 false입니다.

참고: 이 속성은 음성 텍스트 변환 REST API 버전 3.1 이상에서만 사용할 수 있습니다.
languageIdentification 언어 식별은 지원되는 언어 목록과 비교할 때 오디오에서 말하는 언어를 식별하는 데 사용됩니다.

languageIdentification 속성을 설정하는 경우 묶은 candidateLocales 속성도 설정해야 합니다.
languageIdentification.candidateLocales "properties": { "languageIdentification": { "candidateLocales": ["en-US", "de-DE", "es-ES"]}}와 같은 언어 식별에 대한 후보 로캘입니다. 대화 내용 기록에 대한 기본 로캘을 포함하여 최소 2개 및 최대 10개의 후보 로캘이 지원됩니다.
locale 일괄 처리 대화 내용 기록의 로캘입니다. 이 값은 내용을 기록할 오디오 데이터의 예상 로캘과 일치해야 합니다. 로캘은 나중에 변경할 수 없습니다.

이 속성은 필수입니다.
model 특정 베이스 모델 또는 사용자 지정 음성 모델을 사용하도록 model 속성을 설정할 수 있습니다. model을 지정하지 않으면 로캘의 기본 모델이 사용됩니다. 자세한 내용은 사용자 지정 모델 사용Whisper 모델 사용을 참조하세요.
profanityFilterMode 인식 결과에서 욕설의 처리 방법을 지정합니다. 허용되는 값은 욕설 필터링을 사용하지 않으려면 None, 욕설을 별표로 바꾸려면 Masked, 결과에서 모든 욕설을 제거하려면 Removed, 욕설 태그를 추가하려면 Tags입니다. 기본값은 Masked입니다.
punctuationMode 인식 결과에서 문장 부호의 처리 방법을 지정합니다. 허용되는 값은 문장 부호를 사용하지 않으려면 None, 명시적(음성) 문장 부호를 암시하려면 Dictated, 디코더가 문장 부호를 처리하도록 허용하려면 Automatic, 받아쓰기 및 자동 구두점을 사용하려면 DictatedAndAutomatic입니다. 기본값은 DictatedAndAutomatic입니다.

이 속성은 Whisper 모델에는 적용되지 않습니다.
timeToLive 대화 내용 기록 작업이 생성된 후 대화 내용 기록 결과가 자동으로 삭제되는 기간입니다. 값은 ISO 8601로 인코딩된 기간입니다. 예를 들어, 12시간에 대해 PT12H를 지정합니다. 또는 대화 기록 결과를 검색한 후 정기적으로 Transcriptions_Delete를 호출할 수 있습니다.
wordLevelTimestampsEnabled 단어 수준 타임스탬프를 출력에 포함할지 여부를 지정합니다. 기본값은 false입니다.

이 속성은 Whisper 모델에는 적용되지 않습니다. Whisper는 표시 전용 모델이므로 녹취록에 어휘 필드가 채워지지 않습니다.

대화 내용 기록 구성 옵션이 있는 음성 CLI 도움말을 보려면 다음 명령을 실행합니다.

spx help batch transcription create advanced

사용자 지정 모델 사용

일괄 처리 대화 내용 기록은 지정한 로캘에 기본 베이스 모델을 사용합니다. 기본 베이스 모델을 사용하도록 속성을 설정할 필요가 없습니다.

필요에 따라 특정 베이스 모델 또는 사용자 지정 음성 모델을 사용하도록 model 속성을 설정하여 이전의 대화 내용 기록 만들기 예제를 수정할 수 있습니다.

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/1aae1070-7972-47e9-a977-87e3b05c457d"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://YourServiceRegion.api.cognitive.microsoft.com/speechtotext/v3.1/transcriptions"
spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.1/models/base/1aae1070-7972-47e9-a977-87e3b05c457d"

일괄 처리 대화 내용 기록에 사용자 지정 음성 모델을 사용하려면 모델의 URI가 필요합니다. 응답 본문의 최상위 self 속성은 모델의 URI입니다. 모델을 만들거나 가져올 때 모델 위치를 검색할 수 있습니다. 자세한 내용은 모델 만들기의 JSON 응답 예제를 참조하세요.

호스트된 배포 엔드포인트는 일괄처리 대화 내용 기록 서비스와 함께 사용자 지정 음성을 사용하는데 필요하지 않습니다. 일괄 대화 내용 기록에만 사용자 지정 음성 모델을 사용하는 경우 리소스를 보존할 수 있습니다.

만료된 모델에 대한 일괄 처리 대화 기록 요청이 4xx 오류로 인해 실패합니다. 만료되지 않은 기본 모델 또는 사용자 지정 모델로 model 속성을 설정합니다. 그렇지 않으면 항상 최신 기본 모델을 사용하는 model 속성을 포함하지 않습니다. 자세한 내용은 모델 선택사용자 지정 음성 모델 수명 주기를 참조하세요.

Whisper 모델 사용

Azure AI 음성은 일괄 처리 대화 기록 API를 사용하여 OpenAI의 Whisper 모델을 지원합니다. 일괄 처리 대화 내용 기록에 Whisper 모델을 사용할 수 있습니다.

참고 항목

Azure OpenAI 서비스는 동기 REST API를 사용하여 음성을 텍스트로 변환하기 위한 OpenAI의 Whisper 모델도 지원합니다. 자세한 내용은 Azure OpenAI Whisper 모델을 사용하여 음성 텍스트 변환을 참조하세요. Azure AI 음성을 사용하는 경우와 Azure OpenAI Service를 사용하는 경우에 대한 자세한 내용은 Whisper 모델이란?을 참조하세요.

일괄 처리 대화 내용 기록에 Whisper 모델을 사용하려면 model 속성을 설정해야 합니다. Whisper는 표시 전용 모델이므로 응답에 어휘 필드가 채워지지 않습니다.

Important

위스퍼 모델의 경우 항상 음성 텍스트 변환 API의 버전 3.2를 사용해야 합니다.

일괄 처리 대화 내용 기록의 위스퍼 모델은 오스트레일리아 동부, 미국 중부, 미국 동부, 미국 중북부, 미국 중남부, 동남 아시아 및 서유럽 지역에서 지원됩니다.

Models_ListBaseModels 요청을 수행하여 모든 로캘에 사용 가능한 기본 모델을 가져올 수 있습니다.

eastus 지역에 대해 다음 예와 같이 HTTP GET 요청을 수행합니다. YourSubscriptionKey를 Speech 리소스 키로 바꿉니다. 다른 지역을 사용하는 경우 eastus를 바꿉니다.

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

기본적으로 가장 오래된 기본 모델 100개만 반환됩니다. skiptop 쿼리 매개 변수를 사용하여 결과를 페이징합니다. 예를 들어 다음 요청은 첫 100개 이후의 다음 기본 모델 100개를 반환합니다.

curl -v -X GET "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base?skip=100&top=100" -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey"

지원되는 지역 중 하나에서 음성 리소스에 대한 구성 변수를 설정했는지 확인합니다. spx csr list --base 명령을 실행하여 모든 로캘에 사용 가능한 기본 모델을 가져올 수 있습니다.

spx csr list --base --api-version v3.2

위스퍼 모델의 displayName 속성에는 이 예제와 같이 "Whisper"가 포함됩니다. Whisper는 표시 전용 모델이므로 녹취록에 어휘 필드가 채워지지 않습니다.

{
  "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950",
  "links": {
    "manifest": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/e418c4a9-9937-4db7-b2c9-8afbff72d950/manifest"
  },
  "properties": {
    "deprecationDates": {
      "adaptationDateTime": "2025-04-15T00:00:00Z",
      "transcriptionDateTime": "2026-04-15T00:00:00Z"
    },
    "features": {
      "supportsTranscriptions": true,
      "supportsEndpoints": false,
      "supportsTranscriptionsOnSpeechContainers": false,
      "supportsAdaptationsWith": [
        "Acoustic"
      ],
      "supportedOutputFormats": [
        "Display"
      ]
    },
    "chargeForAdaptation": true
  },
  "lastActionDateTime": "2024-02-29T15:53:28Z",
  "status": "Succeeded",
  "createdDateTime": "2024-02-29T15:46:07Z",
  "locale": "en-US",
  "displayName": "20240228 Whisper Large V2",
  "description": "OpenAI Whisper Model in Azure AI Speech (Whisper v2-large)"
},

eastus 지역에 대해 이 예에 표시된 대로 전체 모델 URI를 설정합니다. YourSubscriptionKey를 Speech 리소스 키로 바꿉니다. 다른 지역을 사용하는 경우 eastus를 바꿉니다.

curl -v -X POST -H "Ocp-Apim-Subscription-Key: YourSubscriptionKey" -H "Content-Type: application/json" -d '{
  "contentUrls": [
    "https://crbn.us/hello.wav",
    "https://crbn.us/whatstheweatherlike.wav"
  ],
  "locale": "en-US",
  "displayName": "My Transcription",
  "model": {
    "self": "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6"
  },
  "properties": {
    "wordLevelTimestampsEnabled": true,
  },
}'  "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/transcriptions"
spx batch transcription create --name "My Transcription" --language "en-US" --content https://crbn.us/hello.wav;https://crbn.us/whatstheweatherlike.wav --model "https://eastus.api.cognitive.microsoft.com/speechtotext/v3.2/models/base/d9cbeee6-582b-47ad-b5c1-6226583c92b6" --api-version v3.2

대상 컨테이너 URL 지정

대화 내용 기록 결과를 Azure 컨테이너에 저장할 수 있습니다. 컨테이너를 지정하지 않으면 음성 서비스에 의해 Microsoft에서 관리하는 컨테이너에 결과가 저장됩니다. 이 경우 대화 내용 기록 작업이 삭제되면 대화 내용 기록 결과 데이터도 삭제됩니다.

일괄 처리 대화 내용 기록 만들기 요청에서 옵션 destinationContainerUrl을 사용하여 일괄 처리 대화 내용 기록의 결과를 쓰기 가능한 Azure Blob Storage 컨테이너에 저장할 수 있습니다. 이 옵션은 임시 SAS URI만 사용하며 신뢰할 수 있는 Azure 서비스 보안 메커니즘은 지원하지 않습니다. 이 옵션은 액세스 정책 기반 SAS도 지원하지 않습니다. 대상 컨테이너의 Storage 계정 리소스는 모든 외부 트래픽을 허용해야 합니다.

신뢰할 수 있는 Azure 서비스 보안 메커니즘을 사용하여 대화 내용 기록 결과를 Azure Blob Storage 컨테이너에 저장하려면 BYOS(Bring-Your-Own-Storage)를 사용하는 것이 좋습니다. 자세한 내용은 음성 텍스트 변환을 위한 BYOS(Bring Your Own Storage) 음성 리소스 사용을 참조하세요.