다음을 통해 공유

Docker로 Speech 컨테이너 설치 및 실행하기

  • 아티클

컨테이너를 사용하면 자체 환경에서 음성 서비스 기능의 하위 집합을 사용할 수 있습니다. 이 문서에서는 음성 컨테이너를 다운로드, 설치 및 실행하는 방법에 대해 알아봅니다.

참고 항목

연결이 끊긴 컨테이너 가격 책정 및 약정 계층은 표준 컨테이너마다 다릅니다. 자세한 내용은 Speech Service 가격 책정을 참조하세요.

필수 조건

Speech Service 컨테이너를 사용하려면 먼저 다음 필수 구성 요소를 충족해야 합니다. Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다. 필요 항목:

  • 호스트 컴퓨터에 설치된 Docker. Docker는 컨테이너에서 Azure에 연결하여 청구 데이터를 보낼 수 있도록 구성해야 합니다.
    • Windows에서 Docker는 Linux 컨테이너를 지원하도록 구성해야 합니다.
    • Docker 개념에 대한 기본적으로 이해하고 있어야 합니다.
  • 무료(F0) 또는 표준(S) 가격 책정 계층이 있는 Speech Services 리소스입니다.

청구 인수

음성 컨테이너는 라이선스상 측정을 위해 Azure에 연결하지 않고 실행할 수 없습니다. 항상 측정 서비스와 청구 정보를 통신하도록 컨테이너를 구성해야 합니다.

모든 Azure AI 컨테이너에는 세 가지 기본 매개 변수가 필요합니다. Microsoft Software 사용 조건에는 동의 값이 있어야 합니다. 엔드포인트 URI 및 API 키도 필요합니다.

컨테이너에 대한 쿼리는 ApiKey 매개 변수에 사용되는 Azure 리소스의 가격 책정 계층으로 청구됩니다.

다음 세 가지 옵션이 모두 유효한 값으로 제공되면 docker run 명령은 컨테이너를 시작합니다.

옵션 설명
ApiKey 청구 정보를 추적하는 데 사용되는 Speech 리소스의 API 키입니다.
ApiKey 값은 컨테이너를 시작하는 데 사용되며 해당 Speech 리소스에 대한 Azure portal의 키 페이지에서 사용할 수 있습니다. 키 페이지로 이동하여 클립보드에 복사 아이콘을 선택합니다.
Billing 청구 정보를 추적하는 데 사용되는 Speech 리소스의 엔드포인트입니다.
엔드포인트는 해당 Speech 리소스의 Azure Portal 개요 페이지에서 확인할 수 있습니다. 개요 페이지로 이동하여 엔드포인트를 마우스로 가리키고 클립보드에 복사 아이콘이 나타납니다. 필요한 경우 엔드포인트를 복사하여 사용합니다.
Eula 컨테이너에 대한 라이선스에 동의했음을 나타냅니다.
이 옵션의 값은 동의로 설정해야 합니다.

Important

이러한 구독 키는 Azure AI 서비스 API에 액세스하는 데 사용됩니다. 키를 공유하지 마세요. 안전하게 저장하세요. 예를 들어 Azure Key Vault를 사용합니다. 또한 이러한 키를 정기적으로 다시 생성하는 것이 좋습니다. API 호출을 수행하는 데는 키가 하나만 필요합니다. 첫 번째 키를 다시 생성하는 경우 두 번째 키를 사용하여 서비스에 계속 액세스할 수 있습니다.

컨테이너에는 실행할 청구 인수 값이 필요합니다. 이러한 값을 통해 컨테이너는 청구 엔드포인트에 연결할 수 있습니다. 컨테이너는 약 10 ~ 15분마다 사용량을 보고합니다. 컨테이너가 허용되는 시간 내에서 Azure에 연결되지 않으면 컨테이너는 계속 실행되지만 청구 엔드포인트가 복원될 때까지 쿼리를 처리하지 않습니다. 10 ~ 15분 간격으로 동시에 10회 동안 연결이 시도됩니다. 10회 시도 안에 청구 엔드포인트에 연결할 수 없는 경우 컨테이너는 요청 처리를 중지합니다. 청구를 위해 Microsoft로 전송되는 정보의 예는 Azure AI 서비스 설명서에서 Azure AI 컨테이너 FAQ를 참조하세요.

이러한 옵션에 대한 자세한 내용은 컨테이너 구성을 참조하세요.

컨테이너 요구 사항 및 추천

다음 표에서는 각 음성 컨테이너의 최소 및 권장 리소스 할당에 대해 설명합니다.

컨테이너 최소 권장 음성 모델
음성 텍스트 변환 4코어, 4GB 메모리 8개 코어, 8GB 메모리 +4~8GB 메모리
사용자 지정 음성 텍스트 변환 4코어, 4GB 메모리 8개 코어, 8GB 메모리 +4~8GB 메모리
음성 언어 식별 1개 코어, 1GB 메모리 1개 코어, 1GB 메모리 해당 없음
인공신경망 텍스트 음성 변환 6개 코어, 12GB 메모리 8개 코어, 16GB 메모리 해당 없음

각 코어는 속도가 2.6GHz 이상이어야 합니다.

docker run 명령의 일부로 사용되는 --cpus 및 --memory 설정에 해당하는 코어 및 메모리.

참고 항목

최소 및 권장 할당은 호스트 시스템 리소스가 아닌 Docker 제한을 기반으로 합니다. 예를 들어, 음성 텍스트 변환 컨테이너는 큰 언어 모델의 일부를 메모리 매핑합니다. 전체 파일이 메모리에 맞는 것이 좋습니다. 음성 모델을 로드하려면 4~8GB를 추가해야 합니다(이전 표 참조). 또한 모델이 메모리로 페이징되므로 두 컨테이너의 첫 번째 실행은 더 오래 걸릴 수 있습니다.

호스트 컴퓨터 요구 사항 및 권장 사항

호스트는 Docker 컨테이너를 실행하는 x64 기반 컴퓨터입니다. 다음과 같이 Azure에서 컴퓨터 온-프레미스 또는 Docker 호스팅 서비스일 수 있습니다.

참고 항목

컨테이너는 GStreamer를 사용하여 Speech SDK에 대한 압축 오디오 입력을 지원합니다. 컨테이너에 GStreamer를 설치하려면 음성 SDK를 통해 코덱 압축 오디오 입력 사용에서 GStreamer에 대한 Linux 지침을 따릅니다.

고급 벡터 확장 지원

호스트는 Docker 컨테이너를 실행하는 컴퓨터입니다. 호스트는 Advanced Vector Extensions(AVX2)를 지원해야 합니다. 다음 명령을 사용하여 Linux 호스트에서의 AVX2 지원을 확인할 수 있습니다.

grep -q avx2 /proc/cpuinfo && echo AVX2 supported || echo No AVX2 support detected

Warning

호스트 컴퓨터는 AVX2를 지원하는 데 필요합니다. AVX2가 제대로 지원되지 않으면 컨테이너가 제대로 작동하지 않습니다.

컨테이너 실행

docker run 명령을 사용하여 컨테이너를 실행합니다. 한번 실행되면 컨테이너는 컨테이너를 중지할 때까지 계속 실행됩니다.

docker run 명령을 사용하여 다음 모범 사례를 기록해 둡니다.

  • 줄 연속 문자: 다음 섹션에서 Docker 명령은 줄 연속 문자로 백슬래시(\)를 사용합니다. 호스트 운영 체제의 요구 사항에 따라 이 문자를 바꾸거나 제거합니다.
  • 인수 순서: Docker 컨테이너에 익숙하지 않으면 인수 순서를 변경하지 않습니다.

docker images 명령을 사용하여 다운로드한 컨테이너 이미지를 나열할 수 있습니다. 다음 명령은 다운로드한 각 컨테이너 이미지의 ID, 리포지토리 및 태그를 테이블 형식으로 나열합니다.

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

다음은 결과의 예입니다.

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

컨테이너가 실행 중인지 확인

컨테이너가 실행되고 있는지 확인하는 방법은 여러 가지가 있습니다. 확인 대상인 컨테이너의 외부 IP 주소 및 노출된 포트를 찾고 즐겨 찾는 웹 브라우저를 엽니다. 아래의 다양한 요청 URL을 사용하여 컨테이너가 실행되는지 확인합니다.

여기에 나열된 예제 요청 URL은 http://localhost:5000이지만, 특정 컨테이너는 다를 수 있습니다. 컨테이너의 외부 IP 주소 및 공개된 포트를 사용해야 합니다.

요청 URL 용도
http://localhost:5000/ 컨테이너는 홈페이지를 제공합니다.
http://localhost:5000/ready GET을 사용하여 요청된 이 URL에서 컨테이너가 모델에 대한 쿼리를 수락할 준비가 되었음을 확인합니다. 이 요청은 Kubernetes 활동성 및 준비 상태 프로브에 사용될 수 있습니다.
http://localhost:5000/status 또한 GET을 사용하여 요청된 이 URL은 컨테이너를 시작하는 데 사용된 API 키가 엔드포인트 쿼리를 수행하지 않고 유효한지 확인합니다. 이 요청은 Kubernetes 활동성 및 준비 상태 프로브에 사용될 수 있습니다.
http://localhost:5000/swagger 컨테이너는 엔드포인트에 대한 전체 설명서 세트와 사용해 보기 기능을 제공합니다. 이 기능을 사용하면 웹 기반 HTML 양식으로 설정을 입력할 수 있고 코드 작성 없이 쿼리를 만들 수 있습니다. 쿼리가 반환되면 필요한 HTTP 헤더 및 본문 형식을 보여주기 위해 예제 CURL 명령이 제공됩니다.

컨테이너 중지

컨테이너를 종료하려면 컨테이너를 실행하는 명령줄 환경에서 Ctrl+C를 선택합니다.

동일한 호스트에서 여러 컨테이너 실행

노출된 포트로 여러 컨테이너를 실행하려는 경우, 각 컨테이너를 다른 노출된 포트로 실행해야 합니다. 예를 들어 첫 번째 컨테이너는 포트 5000에서 실행하고 두 번째 컨테이너는 포트 5001에서 실행합니다.

이 컨테이너와 다른 Azure AI 컨테이너를 HOST에서 함께 실행할 수 있습니다. 동일한 Azure AI 컨테이너의 여러 컨테이너를 실행할 수도 있습니다.

호스트 URL

참고 항목

여러 컨테이너를 실행하는 경우 고유한 포트 번호를 사용합니다.

프로토콜 호스트 URL 컨테이너
WS ws://localhost:5000 음성 텍스트 변환

사용자 지정 음성 텍스트 변환
HTTP http://localhost:5000 인공신경망 텍스트 음성 변환

음성 언어 식별

WSS 및 HTTPS 프로토콜을 사용하는 방법에 대한 자세한 내용은 Azure AI 서비스 설명서의 컨테이너 보안을 참조하세요.

문제 해결

컨테이너를 시작하거나 실행할 때 문제가 발생할 수 있습니다. 출력 탑재를 사용하고 로깅을 사용하도록 설정합니다. 이렇게 하면 문제를 해결할 때 컨테이너에서 유용한 로그 파일을 생성할 수 있습니다.

팁

자세한 문제 해결 정보 및 지침은 Azure AI 서비스 설명서의 Azure AI 컨테이너 FAQ를 참조하세요.

로깅 설정

음성 컨테이너에는 ASP.NET Core 로깅 지원이 제공됩니다. 다음은 콘솔에서 기본 로깅으로 시작된 neural-text-to-speech container의 예입니다.

docker run --rm -it -p 5000:5000 --memory 12g --cpus 6 \
mcr.microsoft.com/azure-cognitive-services/speechservices/neural-text-to-speech \
Eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY} \
Logging:Console:LogLevel:Default=Information

로깅에 대한 자세한 내용은 Azure AI 서비스 설명서에서 Speech 컨테이너 구성 및 사용량 레코드를 참조하세요.

Microsoft 진단 컨테이너

Azure AI 컨테이너를 실행하는 데 문제가 있는 경우 Microsoft 진단 컨테이너를 사용해 볼 수 있습니다. 이 컨테이너를 사용하여 Azure AI 컨테이너가 예상대로 작동하지 못하게 할 수 있는 배포 환경의 일반적인 오류를 진단합니다.

컨테이너를 가져오려면 다음 docker pull 명령을 사용합니다.

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

그런 다음, 컨테이너를 실행합니다. {ENDPOINT_URI}를 엔드포인트로 바꾸고, {API_KEY}를 리소스에 대한 키로 바꿉니다.

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

컨테이너는 청구 엔드포인트에 대한 네트워크 연결을 테스트합니다.

연결이 끊긴 컨테이너 실행

인터넷에 연결되지 않은 연결 해제된 컨테이너를 실행하려면 이 요청 양식을 제출하고 승인을 기다려야 합니다. 연결이 끊긴 환경에서 컨테이너를 사용하기 위한 약정 플랜 적용 및 구매에 대한 자세한 내용은 Azure AI 서비스 문서의 연결이 끊긴 환경에서 컨테이너 사용을 참조하세요.

다음 단계