Azure AI 번역기 컨테이너 설치 및 실행

Important

• 번역기 컨테이너를 사용하려면 온라인 요청을 제출하고 승인을 받아야 합니다. 자세한 내용은 컨테이너 액세스 요청을 참조하세요.
• Azure AI 번역기 컨테이너는 클라우드 제공 사항에 비해 제한된 기능을 지원합니다.

컨테이너를 사용하면 자체 인프라에서 Azure AI 번역기 API를 호스팅할 수 있습니다. 컨테이너 이미지에는 프라이빗, 공용 또는 프라이빗 컴퓨팅 환경에서 애플리케이션을 일관되게 실행하는 데 필요한 모든 라이브러리, 도구 및 종속성이 포함되어 있습니다. Azure AI 번역기 API를 원격으로 호출하여 보안 또는 데이터 거버넌스 요구 사항을 충족할 수 없는 경우 컨테이너는 좋은 옵션입니다.

이 문서에서는 Docker API를 사용하여 온라인으로 번역기 컨테이너를 설치하고 실행하는 방법을 알아봅니다. Azure AI 번역기 컨테이너는 다음 작업을 지원합니다.

• 텍스트 번역. 지원되는 source에서 지원되는 target 언어로 단어 또는 구의 컨텍스트적 의미를 실시간으로 번역합니다. 자세한 내용은 컨테이너: 텍스트 번역을 참조하세요.

• 🆕 텍스트 음역. 한 언어 스크립트 또는 쓰기 시스템의 텍스트를 실시간으로 다른 언어 스크립트 또는 쓰기 시스템으로 변환합니다. 자세한 내용은 컨테이너: 텍스트 음역을 참조하세요.

• 🆕 문서 번역(미리보기). 실시간으로 구조와 형식을 유지하면서 문서를 동기식으로 번역합니다. 자세한 내용은 컨테이너:문서 번역을 참조하세요.

필수 조건

시작하려면 다음 리소스, 액세스 승인 및 도구가 필요합니다.

Azure 리소스

• 활성화된 Azure 구독 계정이 없으면 12개월 무료 계정을 만듭니다.

• 번역기 연결된 컨테이너 또는 번역기 연결이 끊긴 컨테이너에 대한 승인된 액세스 요청입니다.

• 승인된 구독 ID로 만들어진 Azure AI 번역기 리소스(멀티 서비스 Azure AI 서비스 리소스가 아님). 리소스와 연결된 API 키와 엔드포인트 URI가 필요합니다. 두 값 모두 컨테이너를 시작하는 데 필요하며 Azure Portal의 리소스 개요 페이지에서 찾을 수 있습니다.

  • 번역기 연결된 컨테이너의 경우 S1 가격 책정 계층을 선택합니다.

  • 번역기 연결이 끊긴 컨테이너의 경우 가격 책정 계층으로 Commitment tier disconnected containers를 선택합니다. 연결이 끊긴 컨테이너 액세스 요청이 승인된 경우에만 약정 계층을 구매하는 옵션이 표시됩니다.

    

Docker 도구

레지스트리, 저장소, 컨테이너, 컨테이너 이미지와 같은 Docker 개념에 대한 기본적인 이해와 기본 docker용어 및 명령에 대한 지식이 있어야 합니다. Docker 및 컨테이너에 대한 기본 사항은 Docker 개요를 참조하세요.

팁

컴퓨팅 환경에 Docker Desktop을 추가해 보세요. Docker Desktop은 데스크톱에서 직접 컨테이너화된 애플리케이션을 빌드, 실행 및 공유할 수 있는 GUI(그래픽 사용자 인터페이스)입니다.

DockerDesktop에는 Docker 엔진, Docker CLI 클라이언트, Docker Compose가 포함되어 있으며 기본 운영 체제에 맞게 Docker를 구성하는 패키지를 제공합니다.

• macOS,
• Windows
• Linux

도구	설명	조건
Docker 엔진.	Docker 엔진은 Docker 컨테이너화 플랫폼의 핵심 구성 요소입니다. 컨테이너를 빌드, 실행 및 관리하려면 호스트 컴퓨터에 설치해야 합니다.	모든 작업에 필수입니다.
Docker Compose	Docker Compose 도구는 다중 컨테이너 애플리케이션을 정의하고 실행하는 데 사용됩니다.	컨테이너 지원을 위해 필수입니다.
Docker CLI	Docker 명령줄 인터페이스를 사용하면 Docker 엔진과 상호 작용하고 로컬 컴퓨터에서 직접 Docker 컨테이너를 관리할 수 있습니다.	권장

호스트 컴퓨터 요구 사항

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

• Azure Kubernetes Service.
• Azure Container Instances.
• Kubernetes 클러스터는 Azure Stack에 배포됩니다. 자세한 내용은 Azure Stack에 Kubernetes 배포를 참조하세요.

운영 체제	시스템 요구 사항
Windows	• Windows 10 또는 Windows 11이 설치되어 있음 • 64비트 프로세서 • 최소 4GB RAM • Windows Hyper-V 및 컨테이너 기능, BIOS 수준 하드웨어 가상화 • 자세한 내용은 Windows에 Docker Desktop 설치를 참조하세요.
Mac	• 2010년 컴퓨터 모델 이상 • OS 10.13 이상 • 최소 4GB RAM • 자세한 내용은 Mac에 Docker Desktop 설치를 참조하세요.
Linux	• 64비트 버전의 Ubuntu(최신 LTS(장기 지원) 버전 또는 현재 비 LTS 버전), Debian 12, Fedora 38 또는 Fedora 39 • 가상화를 위한 CPU 지원 • 최소 4GB RAM • 자세한 내용은 Linux에 Docker Desktop 설치를 참조하세요.

권장 CPU 코어 및 메모리

참고 항목

최소 사양과 권장 사향은 호스트 컴퓨터 리소스가 아닌 Docker 한도에 따릅니다.

다음 표에서는 각 컨테이너에 대해 최소 및 권장 사양과 허용되는 TPS(초당 트랜잭션)를 설명합니다.

함수	최소 권장	주의
텍스트 번역	4개 코어, 4GB 메모리
텍스트 음역	4개 코어, 2GB 메모리
문서 번역	4개 코어, 6GB 메모리	동시에 처리할 수 있는 문서 수는 [최소(n-2),(m-6)/4)] 수식으로 계산할 수 있습니다. • n은 CPU 코어 수입니다. • m은 메모리 GB입니다. • 예: 8Core, 32GB 메모리는 6개의 동시 문서[최소(8-2), (36-6)/4)]를 처리할 수 있습니다.

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

• 모든 언어 쌍에 대해 2GB의 메모리가 권장됩니다.

• 기본 요구 사항 외에도 모든 동시 문서 처리를 위한 4GB 메모리가 필요합니다.

  팁

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

  docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"
  
  IMAGE ID         REPOSITORY                TAG
  <image-id>       <repository-path/name>    <tag-name>
  

필수 입력

모든 Azure AI 컨테이너에는 다음 입력 값이 필요합니다.

• EULA 승인 설정. 값이 Eula=accept인 EULA(최종 사용자 사용권 계약)가 있어야 합니다.

• API 키 및 엔드포인트 URL. API 키는 컨테이너를 시작하는 데 사용됩니다. Azure AI 번역기 리소스 키 및 엔드포인트 페이지로 이동하고 Copy to clipboard 아이콘을 선택하여 API 키 및 엔드포인트 URL 값을 검색할 수 있습니다.

• 문서를 번역하는 경우 문서 번역 엔드포인트를 사용해야 합니다.

Important

• 키는 Azure AI 리소스에 액세스하는 데 사용됩니다. 키를 공유하지 마시고 예를 들어 Azure Key Vault를 사용하여 안전하게 저장합니다.

• 또한 이러한 키는 정기적으로 다시 생성하는 것이 좋습니다. API 호출을 수행하는 데는 키가 하나만 필요합니다. 첫 번째 키를 다시 생성하는 경우, 두 번째 키를 사용하여 서비스에 계속 액세스할 수 있습니다.

결제

• 컨테이너에 대한 쿼리는 API Key에 사용되는 Azure 리소스의 가격 책정 계층으로 청구됩니다.

• 문서와 이미지를 처리하는 데 사용되는 각 컨테이너 인스턴스에 대해 요금이 청구됩니다.

• docker run 명령은 Microsoft 아티팩트 레지스트리에서 이미지를 다운로드하고 다음 세 가지 옵션이 모두 유효한 값으로 제공되면 컨테이너를 시작합니다.

옵션	설명
ApiKey	청구 정보를 추적하는 데 사용되는 Azure AI 서비스 리소스의 키입니다. 이 옵션의 값은 Billing에 지정된 프로비저닝된 리소스에 대한 API 키로 설정해야 합니다.
Billing	청구 정보를 추적하는 데 사용되는 Azure AI 서비스 리소스의 엔드포인트입니다. 이 옵션의 값은 프로비저닝된 Azure 리소스의 엔드포인트 URI로 설정해야 합니다.
Eula	컨테이너에 대한 라이선스에 동의했음을 나타냅니다. 이 옵션의 값은 동의로 설정해야 합니다.

Azure에 연결

• 컨테이너 청구 인수 값을 사용하면 컨테이너가 청구 엔드포인트에 연결하여 실행할 수 있습니다.

• 컨테이너는 약 10 ~ 15분마다 사용량을 보고합니다. 컨테이너가 허용되는 시간 내에서 Azure에 연결되지 않으면 컨테이너는 계속 실행되지만 청구 엔드포인트가 복원될 때까지 쿼리를 처리하지 않습니다.

• 10 ~ 15분 간격으로 동시에 10회 동안 연결이 시도됩니다. 10회 시도 안에 청구 엔드포인트에 연결할 수 없는 경우 컨테이너는 요청 처리를 중지합니다. 청구를 위해 Microsoft로 전송되는 정보의 예는 Azure AI 컨테이너 FAQ를 참조하세요.

컨테이너 이미지 및 태그

Azure AI 서비스 컨테이너 이미지는 Microsoft 아티팩트 레지스트리 카탈로그에서 찾을 수 있습니다. Azure AI 번역기 컨테이너는 azure-cognitive-services/translator 리포지토리 내에 있으며 이름은 text-translation입니다. 정규화된 컨테이너 이미지 이름은 mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest입니다.

최신 버전의 컨테이너를 사용하려면 최신 태그를 사용합니다. MCR에서 Azure AI 서비스 텍스트 번역 버전 태그의 전체 목록을 볼 수 있습니다.

컨테이너 사용

Azure AI 번역기 컨테이너 환경을 선택하려면 탭을 선택합니다.

연결된 컨테이너

Azure AI 번역기 컨테이너를 사용하면 사용자 환경에서 Azure AI 번역기 서비스 on-premise를 실행할 수 있습니다. 연결된 컨테이너는 로컬로 실행되며 청구를 위해 사용량 정보를 클라우드로 보냅니다.

컨테이너 이미지 다운로드 및 실행

docker run 명령은 Microsoft 아티팩트 레지스트리에서 이미지를 다운로드하고 컨테이너를 시작합니다.

Important

• 다음 섹션에서 Docker 명령은 줄 연속 문자 같은 백 슬래시, \을 사용합니다. 호스트 운영 체제의 요구 사항에서 이 기준을 바꾸거나 제거합니다.
• 컨테이너를 인스턴스화하려면 EULA, Billing 및 ApiKey 옵션을 지정해야 합니다. 그렇지 않으면 컨테이너가 시작되지 않습니다.
• 문서를 번역하는 경우 문서 번역 엔드포인트를 사용해야 합니다.

docker run --rm -it -p 5000:5000 --memory 12g --cpus 4 \
-v /mnt/d/TranslatorContainer:/usr/local/models \
-e apikey={API_KEY} \
-e eula=accept \
-e billing={ENDPOINT_URI} \
-e Languages=en,fr,es,ar,ru  \
mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest

위 명령은 다음과 같습니다.

• 다운로드한 컨테이너 이미지에서 실행 중인 번역기 컨테이너를 만듭니다.
• 메모리 12GB(기가바이트)와 CPU 코어 4개를 할당합니다.
• TCP(Transmission Control Protocol) 포트 5000을 노출하고 컨테이너에 의사 TTY를 할당합니다. 이제 localhost 주소는 호스트 컴퓨터가 아닌 컨테이너 자체를 가리킵니다.
• EULA(최종 사용자 계약)에 동의합니다.
• 청구 엔드포인트를 구성합니다.
• 영어, 프랑스어, 스페인어, 아랍어 및 러시아어의 번역 모델을 다운로드합니다.
• 종료 후 자동으로 컨테이너를 제거합니다. 컨테이너 이미지는 호스트 컴퓨터에서 계속 사용할 수 있습니다.

팁

추가 Docker 명령:

• docker ps는 실행 중인 컨테이너를 나열합니다.
• docker pause {your-container name}은 실행 중인 컨테이너를 일시 중지합니다.
• docker unpause {your-container-name}은 일시 중지된 컨테이너를 일시 중지 해제합니다.
• docker restart {your-container-name}은 실행 중인 컨테이너를 다시 시작합니다.
• docker exec를 사용하면 실행 중인 컨테이너에서 분리하거나 환경 변수를 설정하는 명령을 실행할 수 있습니다.

자세한 내용은 docker CLI 참조를 참조하세요.

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

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

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

번역기 컨테이너 엔드포인트 쿼리

컨테이너는 REST 기반 Translator 엔드포인트 API를 제공합니다. 다음은 소스 언어(from=en)가 지정된 요청 예입니다.

  curl -X POST "http://localhost:5000/translate?api-version=3.0&from=en&to=zh-HANS" -H "Content-Type: application/json" -d "[{'Text':'Hello, what is your name?'}]"

참고 항목

• 소스 언어 감지에는 추가 컨테이너가 필요합니다. 자세한 내용은 컨테이너 지원을 참조하세요.

• cURL POST 요청이 Service is temporarily unavailable 응답을 반환하면 컨테이너가 준비되지 않은 것입니다. 몇 분 기다렸다가 다시 시도하세요.

연결이 끊긴(오프라인) 컨테이너

연결이 끊긴 컨테이너를 사용하면 인터넷 액세스를 통해 Docker 이미지를 컴퓨터로 내보낸 다음 오프라인으로 Docker를 사용하여 Azure AI 번역기 API를 사용할 수 있습니다. 연결이 끊긴 컨테이너는 컨테이너를 실행하는 데 클라우드와의 연결이 필요하지 않은 시나리오를 위한 것입니다.

연결이 끊긴 컨테이너 약정 플랜

• 연결 해제된 컨테이너에 대한 약정 플랜에는 1년 약정 기간이 있습니다.

• 플랜을 구매하면 즉시 전체 가격이 청구됩니다.

• 약정 기간에는 약정 플랜을 변경할 수 없지만, 해당 연도의 남은 일수에 대해 비례 배분된 가격으로 추가 단위를 구매할 수 있습니다.

• 약정 마지막 날 자정(UTC)까지 약정 플랜을 종료하거나 변경할 수 있습니다.

• 리소스 관리 섹션 아래 있는 리소스의 약정 계층 가격 책정에서 다른 약정 플랜을 선택할 수 있습니다.

새 Translator 리소스를 만들고 약정 플랜을 구매합니다.

1. Azure Portal에서 Translator 리소스를 만듭니다.

2. 리소스를 만들려면 해당 정보를 입력합니다. 가격 책정 계층으로 약정 계층 연결 해제 컨테이너를 선택해야 합니다. 승인된 경우에만 약정 계층을 구매하는 옵션이 표시됩니다.

   

3. 페이지 아래쪽에서 검토 + 만들기를 선택합니다. 정보를 검토하고 만들기를 선택합니다.

약정 플랜 종료

• 약정 플랜을 계속 구매하지 않으려는 경우 리소스의 자동 갱신을 자동 갱신 안 함으로 설정할 수 있습니다.

• 약정 플랜은 표시된 약정 종료 날짜에 만료됩니다. 이 날짜 이후에는 약정 플랜에 대한 요금이 청구되지 않습니다. 종량제 가격 책정으로 청구되는 API 호출을 위해 계속해서 Azure 리소스를 사용할 수 있습니다.

• 연결 해제된 컨테이너에 대한 약정 플랜을 종료하려면 해당 연도의 마지막 날 자정(UTC)까지 보유합니다. 그렇게 하면 다음 해에는 요금이 청구되지 않습니다.

필수 매개 변수 수집

모든 Azure AI 서비스 컨테이너에는 세 가지 필수 매개 변수가 있습니다.

• EULA(최종 사용자 사용권 계약)는 수락 값과 함께 제공되어야 합니다.

• Azure Portal의 리소스에 대한 컨테이너 엔드포인트 URL입니다.

• Azure Portal의 리소스에 대한 API 키

연결이 끊어진 사용 구성을 구현하기 위해 컨테이너를 처음 실행할 때 엔드포인트 URL과 API 키가 모두 필요합니다. Azure Portal의 리소스에 대한 키 및 엔드포인트 페이지에서 키와 엔드포인트를 찾을 수 있습니다.

Important

연결이 끊어진 상태에서 실행되도록 컨테이너를 구성하는 데에만 키와 엔드포인트를 사용합니다. 문서를 번역하는 경우 문서 번역 엔드포인트를 사용해야 합니다. 자동화합니다. 컨테이너를 구성한 후에는 API 요청을 보내는 데 키와 엔드포인트 값이 필요하지 않습니다. 예를 들어 Azure Key Vault를 사용하여 안전하게 저장합니다. 이 프로세스에는 하나의 키만 필요합니다.

번역기 컨테이너 이미지 끌어오기 및 로드

1. 로컬 환경에 Docker 도구가 설치되어 있어야 합니다.

2. docker pull을 사용하여 Azure AI 번역기 컨테이너를 다운로드합니다.

   Docker pull 명령	값	형식
   • docker pull [image] • docker pull [image]:latest	최신 컨테이너 이미지	• mcr.microsoft.com/azure-cognitive-services/translator/text-translation • mcr.microsoft.com/azure-cognitive-services/translator/text-translation: latest
   • docker pull [image]:[version]	특정 컨테이너 이미지	mcr.microsoft.com/azure-cognitive-services/translator/text-translation:1.0.019410001-amd64

   예제 Docker 풀 명령:

   docker pull mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest
   

3. 이미지를 .tar 파일에 저장합니다.

4. 로컬 Docker 인스턴스에 .tar 파일을 로드합니다. 자세한 내용은 Docker: 파일에서 이미지 로드를 참조하세요.

   $docker load --input {path-to-your-file}.tar
   
   

연결이 끊긴 환경에서 실행되도록 컨테이너 구성

이제 컨테이너를 다운로드했으므로 다음 매개 변수를 사용하여 docker run 명령을 실행할 수 있습니다.

• DownloadLicense=True. 이 매개 변수는 Docker 컨테이너가 인터넷에 연결되어 있지 않을 때 실행할 수 있도록 하는 라이선스 파일을 다운로드합니다. 또한 만료 날짜가 포함되어 있으며, 이후에는 라이선스 파일이 컨테이너를 실행하는 데 유효하지 않습니다. 해당하는 승인된 컨테이너에서만 라이선스 파일을 사용할 수 있습니다.
• Languages={language list}. 번역하려는 언어에 대해 모델 파일을 다운로드하도록 이 매개 변수를 포함해야 합니다.

Important

docker run 명령은 컨테이너를 실행하는 데 사용할 수 있는 템플릿을 생성합니다. 템플릿에는 다운로드한 모델과 구성 파일에 필요한 매개 변수가 포함됩니다. 이 템플릿을 저장했는지 확인합니다.

다음 예제는 자리 표시자 값을 사용하여 docker run 명령의 형식을 보여 줍니다. 이러한 자리 표시자 값을 고유한 값으로 바꿉니다.

자리 표시자	값	형식
[image]	사용하려는 컨테이너 이미지입니다.	mcr.microsoft.com/azure-cognitive-services/translator/text-translation
{LICENSE_MOUNT}	라이선스를 다운로드하고 탑재하는 경로입니다.	/host/license:/path/to/license/directory
{MODEL_MOUNT_PATH}	기계 번역 모델이 다운로드되어 탑재되는 경로입니다. 디렉터리 구조는 /usr/local/models로 형식이 지정되어야 합니다.	/host/translator/models:/usr/local/models
{ENDPOINT_URI}	서비스 요청을 인증하기 위한 엔드포인트입니다. Azure Portal의 리소스 키 및 엔드포인트 페이지에서 이 값을 찾을 수 있습니다.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API_KEY}	텍스트 번역 리소스의 키입니다. Azure Portal의 리소스 키 및 엔드포인트 페이지에서 이 값을 찾을 수 있습니다.	{string}
{LANGUAGES_LIST}	쉼표로 구분된 언어 코드 목록입니다. 목록의 일부로 영어(en) 언어를 반드시 포함해야 합니다.	en, fr, it, zu, uk
{CONTAINER_LICENSE_DIRECTORY}	컨테이너의 로컬 파일 시스템에 있는 라이선스 폴더의 위치입니다.	/path/to/license/directory

예제 docker run 명령

docker run --rm -it -p 5000:5000 \

-v {MODEL_MOUNT_PATH} \

-v {LICENSE_MOUNT_PATH} \

-e Mounts:License={CONTAINER_LICENSE_DIRECTORY} \

-e DownloadLicense=true \

-e eula=accept \

-e billing={ENDPOINT_URI} \

-e apikey={API_KEY} \

-e Languages={LANGUAGES_LIST} \

[image]

Translator 번역 모델 및 컨테이너 구성

컨테이너를 구성하고 나면 다운로드한 번역 모델과 컨테이너 구성에 대한 값이 생성되고 컨테이너 출력에 표시됩니다.

    -e MODELS= usr/local/models/model1/, usr/local/models/model2/
    -e TRANSLATORSYSTEMCONFIG=/usr/local/models/Config/5a72fa7c-394b-45db-8c06-ecdfc98c0832

연결이 끊긴 환경에서 컨테이너 실행

라이선스 파일이 다운로드되면 라이선스와 적절한 메모리, 적합한 CPU 할당을 사용해 연결이 끊긴 환경에서 컨테이너를 실행할 수 있습니다. 다음 예제는 자리 표시자 값을 사용하여 docker run 명령의 형식을 보여 줍니다. 이러한 자리 표시자 값을 고유한 값으로 바꿉니다.

컨테이너가 실행되는 곳마다 라이선스 파일을 컨테이너에 탑재해야 하고, 컨테이너의 로컬 파일 시스템에서 라이선스 폴더의 위치를 Mounts:License=로 지정해야 합니다. 또한 청구 사용량 기록을 작성할 수 있도록 출력 탑재를 지정해야 합니다.

자리 표시자	값	형식
[image]	사용하려는 컨테이너 이미지입니다.	mcr.microsoft.com/azure-cognitive-services/translator/text-translation
{MEMORY_SIZE}	컨테이너에 할당할 적절한 메모리 크기입니다.	16g
{NUMBER_CPUS}	컨테이너에 할당할 적절한 CPU 수입니다.	4
{LICENSE_MOUNT}	라이선스를 찾고 탑재하는 경로입니다.	/host/translator/license:/path/to/license/directory
{MODEL_MOUNT_PATH}	기계 번역 모델이 다운로드되어 탑재되는 경로입니다. 디렉터리 구조는 /usr/local/models로 형식이 지정되어야 합니다.	/host/translator/models:/usr/local/models
{MODELS_DIRECTORY_LIST}	각각 기계 번역 모델이 있는 쉼표로 구분된 디렉터리 목록입니다.	/usr/local/models/enu_esn_generalnn_2022240501,/usr/local/models/esn_enu_generalnn_2022240501
{OUTPUT_PATH}	사용량 기록 로깅을 위한 출력 경로입니다.	/host/output:/path/to/output/directory
{CONTAINER_LICENSE_DIRECTORY}	컨테이너의 로컬 파일 시스템에 있는 라이선스 폴더의 위치입니다.	/path/to/license/directory
{CONTAINER_OUTPUT_DIRECTORY}	컨테이너의 로컬 파일 시스템에 있는 출력 폴더의 위치입니다.	/path/to/output/directory
{TRANSLATOR_CONFIG_JSON}	컨테이너에서 내부적으로 사용하는 Translator 시스템 구성 파일입니다.	/usr/local/models/Config/5a72fa7c-394b-45db-8c06-ecdfc98c0832

예제 docker run 명령

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \

-v {MODEL_MOUNT_PATH} \

-v {LICENSE_MOUNT_PATH} \

-v {OUTPUT_MOUNT_PATH} \

-e Mounts:License={CONTAINER_LICENSE_DIRECTORY} \

-e Mounts:Output={CONTAINER_OUTPUT_DIRECTORY} \

-e MODELS={MODELS_DIRECTORY_LIST} \

-e TRANSLATORSYSTEMCONFIG={TRANSLATOR_CONFIG_JSON} \

-e eula=accept \

[image]

문제 해결

출력 탑재 및 로깅이 사용하도록 설정된 상태에서 컨테이너를 실행합니다. 이러한 설정을 사용하면 컨테이너를 시작하거나 실행하는 동안 발생하는 문제를 해결하는 데 유용한 로그 파일을 컨테이너에서 생성할 수 있습니다.

팁

문제 해결 정보 및 지침에 대한 자세한 내용은 연결이 끊긴 컨테이너 질문과 대답(FAQ)을 참조하세요.

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

컨테이너가 실행되고 있는지 확인하는 방법에는 여러 가지가 있습니다.

• 컨테이너는 /에서 컨테이너가 실행 중인지 시각적으로 확인할 수 있는 홈페이지를 제공합니다.

• 즐겨 찾는 웹 브라우저를 열고 확인하려는 컨테이너의 외부 IP 주소와 노출된 포트로 이동하면 됩니다. 다음 요청 URL을 사용하여 컨테이너가 실행 중인지 확인하세요. 나열된 요청 URL 예는 http://localhost:5000을 가리키지만 특정 컨테이너는 다를 수 있습니다. 컨테이너의 외부 IP 주소와 노출된 포트로 이동해야 합니다.

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

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}

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

컨테이너 중지

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

컨테이너 지원 사용 사례

일부 Translator 쿼리에는 작업을 성공적으로 완료하기 위해 지원 컨테이너가 필요합니다. Office 문서를 사용하고 소스 언어 감지가 필요하지 않은 경우 번역기 컨테이너만 필요합니다. 그러나 소스 언어 감지가 필요하거나 검사한 PDF 문서를 사용하는 경우 지원 컨테이너가 필요합니다.

다음 표에는 텍스트 및 문서 번역 작업에 필요한 지원 컨테이너가 나열되어 있습니다. 번역기 컨테이너는 Azure 계정의 Azure AI 번역기 리소스를 통해 Azure에 청구 정보를 보냅니다.

연산	쿼리 요청	Document type	지원 컨테이너
• 텍스트 번역 • 문서 번역	from 지정됨.	Office 문서	None
• 텍스트 번역 • 문서 번역	from 지정되지 않음. 소스 언어를 결정하려면 자동 언어 감지가 필요합니다.	Office 문서	✔️ Text analytics:언어 컨테이너
• 텍스트 번역 • 문서 번역	from 지정됨.	검사한 PDF 문서	✔️ Vision:읽기 컨테이너
• 텍스트 번역 • 문서 번역	from은 소스 언어를 결정하기 위해 자동 언어 감지가 필요하도록 지정되지 않았습니다.	검사한 PDF 문서	✔️ Text analytics:언어 컨테이너 ✔️ Vision:읽기 컨테이너

docker compose를 사용하여 지원 컨테이너 운영

Docker Compose는 일반적으로 compose.yaml이라는 단일 YAML 파일을 사용하여 다중 컨테이너 애플리케이션을 구성할 수 있는 도구입니다. docker compose up 명령을 사용하여 컨테이너 애플리케이션을 시작하고 docker compose down 명령을 사용하여 컨테이너를 중지하고 제거합니다.

Docker Desktop CLI를 설치한 경우 Docker Compose와 필수 구성 요소가 포함되어 있습니다. Docker Desktop이 없으면 Docker Compose 설치 개요를 참조하세요.

애플리케이션 만들기

1. 기본 편집기 또는 IDE를 사용하여 container-environment라는 앱용 새 디렉터리 또는 원하는 이름을 만듭니다.

2. compose.yaml이라는 새 YAML 파일을 만듭니다. .yml 또는 .yaml 확장명을 모두 compose 파일에 사용할 수 있습니다.

3. 다음 YAML 코드 샘플을 복사하여 compose.yaml 파일에 붙여넣습니다. {TRANSLATOR_KEY} 및 {TRANSLATOR_ENDPOINT_URI}를 Azure Portal Translator 인스턴스의 키 및 엔드포인트 값으로 바꿉니다. 문서를 번역하는 경우 document translation endpoint를 사용해야 합니다.

4. 최상위 이름(azure-ai-translator, azure-ai-language, azure-ai-read)은 사용자가 지정하는 매개 변수입니다.

5. container_name은 docker compose가 이름을 생성하도록 하는 대신 실행 시 컨테이너의 이름을 설정하는 선택적 매개 변수입니다.

   services:
     azure-ai-translator:
       container_name: azure-ai-translator
       image: mcr.microsoft.com/product/azure-cognitive-services/translator/text-translation:latest
       environment:
           - EULA=accept
           - billing={TRANSLATOR_ENDPOINT_URI}
           - apiKey={TRANSLATOR_KEY}
           - AzureAiLanguageHost=http://azure-ai-language:5000
           - AzureAiReadHost=http://azure-ai-read:5000
       ports:
             - "5000:5000"
       azure-ai-language:
         container_name: azure-ai-language
         image:  mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest
         environment:
             - EULA=accept
             - billing={TRANSLATOR_ENDPOINT_URI}
             - apiKey={TRANSLATOR_KEY}
       azure-ai-read:
         container_name: azure-ai-read
         image:  mcr.microsoft.com/azure-cognitive-services/vision/read:latest
         environment:
             - EULA=accept
             - billing={TRANSLATOR_ENDPOINT_URI}
             - apiKey={TRANSLATOR_KEY}
   

6. 터미널을 열고 container-environment 폴더로 이동하고 다음 docker-compose 명령을 사용하여 컨테이너를 시작합니다.

   docker compose up
   

7. 컨테이너를 중지하려면 다음 명령을 사용합니다.

   docker compose down
   

   팁

   유용한 Docker 명령:

   • docker compose pause는 실행 중인 컨테이너를 일시 중지합니다.
   • docker compose unpause {your-container-name}은 일시 중지된 컨테이너를 일시 중지 해제합니다.
   • docker compose restart는 모든 이전 변경 내용을 그대로 유지하면서 중지되고 실행 중인 모든 컨테이너를 다시 시작합니다. compose.yaml 구성을 변경하는 경우 이러한 변경 내용은 docker compose restart 명령으로 업데이트되지 않습니다. compose.yaml 파일의 업데이트 및 변경 내용을 반영하려면 docker compose up 명령을 사용해야 합니다.
   • docker compose ps -a는 중지된 컨테이너를 포함하여 모든 컨테이너를 나열합니다.
   • docker compose exec를 사용하면 실행 중인 컨테이너에서 분리하거나 환경 변수를 설정하는 명령을 실행할 수 있습니다.

   자세한 내용은 docker CLI 참조를 참조하세요.

번역기 및 지원 컨테이너 이미지와 태그

Azure AI 서비스 컨테이너 이미지는 Microsoft 아티팩트 레지스트리 카탈로그에서 찾을 수 있습니다. 다음 표에는 텍스트 및 문서 번역을 위한 정규화된 이미지 위치가 나열되어 있습니다.

컨테이너	이미지 위치	주의
번역기: 텍스트 및 문서 번역	mcr.microsoft.com/azure-cognitive-services/translator/text-translation:latest	MCR에서 Azure AI 서비스 텍스트 번역 버전 태그의 전체 목록을 볼 수 있습니다.
Text analytics: 언어	mcr.microsoft.com/azure-cognitive-services/textanalytics/language:latest	MCR에서 Azure AI 서비스 Text Analytics 언어 버전 태그의 전체 목록을 볼 수 있습니다.
Vision: 읽기	mcr.microsoft.com/azure-cognitive-services/vision/read:latest	MCR에서 Azure AI 서비스 Computer Vision 읽기 OCR 버전 태그의 전체 목록을 볼 수 있습니다.

기타 매개 변수 및 명령

컨테이너를 실행하는 데 사용할 수 있는 몇 가지 추가 매개 변수와 명령은 다음과 같습니다.

사용량 레코드

연결이 끊긴 환경에서 Docker 컨테이너를 작동할 때 컨테이너는 시간이 지남에 따라 수집되는 볼륨에 사용량 레코드를 씁니다. REST API 엔드포인트를 호출하여 서비스 사용량에 대한 보고서를 생성할 수도 있습니다.

로그 저장을 위한 인수

연결이 끊긴 환경에서 실행할 때 사용량 로그를 저장하려면 컨테이너에서 출력 탑재를 사용량할 수 있어야 합니다. 예를 들면, 다음 예제에서 -v /host/output:{OUTPUT_PATH} 및 Mounts:Output={OUTPUT_PATH}를 포함하고 {OUTPUT_PATH}를 로그가 저장되는 경로로 바꿉니다.

예제 docker run 명령

docker run -v /host/output:{OUTPUT_PATH} ... <image> ... Mounts:Output={OUTPUT_PATH}

Kubernetes 배포의 환경 변수 이름

• 일부 Azure AI 컨테이너(예: Translator)에서는 사용자가 컨테이너를 실행할 때 콜론(:)을 포함하는 환경 변수 이름을 전달해야 합니다.

• Kubernetes는 환경 변수 이름에 콜론을 허용하지 않습니다. 이 문제를 해결하려면 Kubernetes에 배포할 때 콜론을 두 개의 밑줄 문자(__)로 바꿀 수 있습니다. 환경 변수 이름에 허용되는 형식의 다음 예를 참조하세요.

        env:
        - name: Mounts__License
          value: "/license"
        - name: Mounts__Output
          value: "/output"

이 예에서는 docker run 명령의 Mounts:License 및 Mounts:Output 환경 변수 이름에 대한 기본 형식을 바꿉니다.

컨테이너 엔드포인트를 사용하여 사용 기록 가져오기

컨테이너는 사용량에 대한 레코드를 반환하기 위해 두 개의 엔드포인트를 제공합니다.

모든 기록 가져오기

다음 엔드포인트는 탑재된 청구 레코드 디렉터리에서 수집한 모든 사용량을 요약한 보고서를 제공합니다.

https://<service>/records/usage-logs/

모든 레코드를 검색하기 위한 HTTPS 엔드포인트 예

http://localhost:5000/records/usage-logs

특정 월의 기록 가져오기

다음 엔드포인트는 특정 월/년의 사용량을 요약한 보고서를 제공합니다.

https://<service>/records/usage-logs/{MONTH}/{YEAR}

특정 월 및 연도의 레코드를 검색하기 위한 HTTPS 엔드포인트 예

http://localhost:5000/records/usage-logs/03/2024

사용량 로그 엔드포인트는 다음 예와 유사한 JSON 응답을 반환합니다.

연결된 컨테이너

quantity는 연결된 컨테이너 사용에 대해 청구되는 금액입니다.

{
"apiType": "string",
"serviceName": "string",
"meters": [
{
    "name": "string",
    "quantity": 256345435
    }
  ]
}

연결 해제된 컨테이너

      {
    "type": "CommerceUsageResponse",
    "meters": [
      {
        "name": "CognitiveServices.TextTranslation.Container.OneDocumentTranslatedCharacters",
        "quantity": 1250000,
        "billedUnit": 1875000
      },
      {
        "name": "CognitiveServices.TextTranslation.Container.TranslatedCharacters",
        "quantity": 1250000,
        "billedUnit": 1250000
      }
    ],
    "apiType": "texttranslation",
    "serviceName": "texttranslation"
   }

다음 미터에 대해 집계된 billedUnit 값은 연결이 끊긴 컨테이너 사용에 대해 라이선스를 부여한 문자에 포함됩니다.

• CognitiveServices.TextTranslation.Container.OneDocumentTranslatedCharacters

• CognitiveServices.TextTranslation.Container.TranslatedCharacters

요약

이 문서에서는 Azure AI 번역기 컨테이너를 다운로드, 설치 및 실행하기 위한 개념과 워크플로를 알아보았습니다.

• Azure AI 번역기 컨테이너는 텍스트 번역, 동기 문서 번역 및 텍스트 음역을 지원합니다.

• 컨테이너 이미지는 컨테이너 레지스트리에서 다운로드되어 Docker에서 실행됩니다.

• 컨테이너를 인스턴스화할 때 청구 정보를 지정해야 합니다.

다음 단계

Azure AI 컨테이너 구성에 대해 자세히 알아봅니다.컨테이너 언어 지원에 대해 자세히 알아봅니다.