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

이 콘텐츠의 적용 대상: v3.0(GA) v3.1(GA)

연결이 끊긴 컨테이너란?

Azure AI 컨테이너는 일부 문서 인텔리전스 서비스를 컨테이너에서 로컬로 실행할 수 있는 유연성을 제공합니다. 연결된 컨테이너는 사용자 환경에서 로컬로 실행되며 청구를 위해 사용량 정보를 클라우드로 보냅니다. 연결이 끊긴 컨테이너는 컨테이너를 실행하는 데 클라우드와의 연결이 필요하지 않은 시나리오를 위한 것입니다.

Azure AI 문서 인텔리전스 컨테이너를 사용하면 컨테이너화의 이점과 함께 문서 인텔리전스 API를 사용할 수 있습니다. 연결이 끊긴 컨테이너는 종량제 가격 책정에 비해 할인된 요금의 약정 계층 가격 책정을 통해 제공됩니다. 약정 계층 가격을 사용하면 워크로드 요구 사항에 따라 예측 가능한 총 비용으로 고정 요금으로 문서 인텔리전스 기능을 사용하도록 약정할 수 있습니다.

시작하기

오프라인 환경에서 Docker 컨테이너를 실행하기 전에 컨테이너를 성공적으로 다운로드하고 사용하려면 다음 요구 사항을 잘 알고 있어야 합니다.

• 호스트 컴퓨터 요구 사항 및 권장 사항
• 컨테이너를 다운로드하는 Docker pull 명령입니다.
• 컨테이너가 실행 중인지 유효성 검사하는 방법입니다.
• 실행 중인 컨테이너의 엔드포인트에 쿼리를 보내는 방법입니다.

연결되지 않은 환경에서 컨테이너 사용에 대한 액세스 요청

연결되지 않은 환경에서 문서 인텔리전스 컨테이너를 사용하려면 먼저 요청 양식을 작성하여 제출하고 약정 요금제를 구매해야 합니다.

Azure portal에서 새 리소스 만들기

포털에서 새 리소스를 프로비전하여 시작하세요.

• 가격 책정 계층에 대해 Commitment tier disconnected containers DC0 옵션을 선택했는지 확인하세요.

• 사용자 지정, 읽기 또는 미리 빌드된 약정 계층 중 하나 이상에서 적절한 가격 책정 계층을 선택합니다.

  

컨테이너	최소	권장	약정 플랜
Read	8개 코어, 10GB 메모리	8개 코어, 24GB 메모리	OCR (읽기)
Layout	8개 코어, 16GB 메모리	8개 코어, 24GB 메모리	사전 제작
Business Card	8개 코어, 16GB 메모리	8개 코어, 24GB 메모리	사전 제작
General Document	8개 코어, 12GB 메모리	8개 코어, 24GB 메모리	사전 제작
ID Document	8개 코어, 8GB 메모리	8개 코어, 24GB 메모리	사전 제작
Invoice	8개 코어, 16GB 메모리	8개 코어, 24GB 메모리	사전 제작
Receipt	8개 코어, 11GB 메모리	8개 코어, 24GB 메모리	사전 제작
Custom Template	8개 코어, 16GB 메모리	8개 코어, 24GB 메모리	사용자 지정 API

필수 매개 변수 수집

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

• EULA(최종 사용자 사용권 계약)는 수락 값과 함께 제공되어야 합니다.
• Azure Portal의 리소스에 대한 엔드포인트 URL입니다.
• Azure Portal의 리소스에 대한 API 키

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

Important

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

docker pull을 사용하여 Docker 컨테이너 다운로드

연결이 끊긴 환경에서 실행하도록 승인된 Docker 컨테이너를 다운로드합니다. 예시:

Docker pull 명령	값	형식
● docker pull [image] ● docker pull [image]latest	최신 컨테이너 이미지	● mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest ● mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice-3.0:latest

Docker 끌어오기 명령 예제

docker pull mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice:latest

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

연결이 끊긴 컨테이너 이미지는 연결된 컨테이너와 동일합니다. 주요 차이점은 연결이 끊긴 컨테이너에는 라이센스 파일이 필요하다는 것입니다. 이 라이선스 파일은 downloadLicense 매개 변수가 true로 설정된 연결 모드에서 컨테이너를 시작하여 다운로드됩니다.

이제 컨테이너가 다운로드되었으므로 다음 매개 변수를 docker run 사용하여 명령을 실행해야 합니다.

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

Important

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

다음 예제에서는 자리 표시자 값과 함께 사용할 명령에 대 한 docker run 서식을 보여 있습니다. 이러한 자리 표시자 값을 고유한 값으로 바꿉니다.

자리 표시자	값	형식 또는 예
{IMAGE}	사용하려는 컨테이너 이미지입니다.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{LICENSE_MOUNT}	라이선스를 다운로드하고 탑재하는 경로입니다.	/host/license:/path/to/license/directory
{ENDPOINT_URI}	서비스 요청을 인증하기 위한 엔드포인트입니다. Azure Portal의 리소스 키 및 엔드포인트 페이지에서 이 값을 찾을 수 있습니다.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API_KEY}	문서 인텔리전스 리소스의 키입니다. Azure Portal의 리소스 키 및 엔드포인트 페이지에서 이 값을 찾을 수 있습니다.	{string}
{CONTAINER_LICENSE_DIRECTORY}	컨테이너의 로컬 파일 시스템에 있는 라이선스 폴더의 위치입니다.	/path/to/license/directory

예제 docker run 명령

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

-v {LICENSE_MOUNT} \

{IMAGE} \

eula=accept \

billing={ENDPOINT_URI} \

apikey={API_KEY} \

DownloadLicense=True \

Mounts:License={CONTAINER_LICENSE_DIRECTORY}

다음 명령에서 폴더 경로, 청구 엔드포인트 및 API 키의 자리 표시자를 바꿔 레이아웃 컨테이너에 대한 라이선스 파일을 다운로드합니다.

docker run -v {folder path}:/license --env Mounts:License=/license --env DownloadLicense=True --env Eula=accept --env Billing={billing endpoint} --env ApiKey={api key} mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest

컨테이너가 구성되면 다음 섹션을 사용하여 라이선스와 적절한 메모리 및 CPU 할당을 사용하여 사용자 환경에서 컨테이너를 실행합니다.

문서 인텔리전스 컨테이너 모델 및 구성

컨테이너를 구성한 후 다운로드한 문서 인텔리전스 모델 및 컨테이너 구성에 대한 값이 생성되어 컨테이너 출력에 표시됩니다.

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

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

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

자리 표시자	값	형식 또는 예
{IMAGE}	사용하려는 컨테이너 이미지입니다.	mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice
{MEMORY_SIZE}	컨테이너에 할당할 적절한 메모리 크기입니다.	4g
{NUMBER_CPUS}	컨테이너에 할당할 적절한 CPU 수입니다.	4
{LICENSE_MOUNT}	라이선스를 찾고 탑재하는 경로입니다.	/host/license:/path/to/license/directory
{OUTPUT_PATH}	사용량 기록 로깅을 위한 출력 경로입니다.	/host/output:/path/to/output/directory
{CONTAINER_LICENSE_DIRECTORY}	컨테이너의 로컬 파일 시스템에 있는 라이선스 폴더의 위치입니다.	/path/to/license/directory
{CONTAINER_OUTPUT_DIRECTORY}	컨테이너의 로컬 파일 시스템에 있는 출력 폴더의 위치입니다.	/path/to/output/directory

예제 docker run 명령

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

-v {LICENSE_MOUNT} \

-v {OUTPUT_PATH} \

{IMAGE} \

eula=accept \

Mounts:License={CONTAINER_LICENSE_DIRECTORY}

Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

연결이 끊긴 컨테이너를 시작하는 것은 연결된 컨테이너를 시작하는 것과 유사합니다. 연결이 끊긴 컨테이너에는 추가 라이선스 매개 변수가 필요합니다. 다음은 연결 끊김 모드에서 사용자 지정 컨테이너를 시작하기 위한 샘플 docker-compose.yml 파일입니다. 다운로드한 라이선스 파일이 포함된 폴더에 값이 설정된 CUSTOM_LICENSE_MOUNT_PATH 환경 변수와 OUTPUT_MOUNT_PATH 사용 현황 로그가 있는 폴더로 설정된 값이 있는 환경 변수를 추가합니다.

version: '3.3'
services:
 nginx:
  image: nginx:alpine
  container_name: reverseproxy
  volumes:
    - ${NGINX_CONF_FILE}:/etc/nginx/nginx.conf
  ports:
    - "5000:5050"
 layout:
  container_name: azure-cognitive-service-layout
  image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.0:latest
  environment:
    eula: accept
    apikey: ${FORM_RECOGNIZER_KEY}
    billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
    Logging:Console:LogLevel:Default: Information
    SharedRootFolder: /shared
    Mounts:Shared: /shared
    Mounts:Output: /logs
    Mounts:License: /license
  volumes:
    - type: bind
      source: ${SHARED_MOUNT_PATH}
      target: /shared
    - type: bind
      source: ${OUTPUT_MOUNT_PATH}
      target: /logs
    - type: bind
      source: ${LAYOUT_LICENSE_MOUNT_PATH}
      target: /license
  expose:
    - "5000"

 custom-template:
  container_name: azure-cognitive-service-custom-template
  image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/custom-template-3.0:latest
  restart: always
  depends_on:
    - layout
  environment:
    AzureCognitiveServiceLayoutHost: http://azure-cognitive-service-layout:5000
    eula: accept
    apikey: ${FORM_RECOGNIZER_KEY}
    billing: ${FORM_RECOGNIZER_ENDPOINT_URI}
    Logging:Console:LogLevel:Default: Information
    SharedRootFolder: /shared
    Mounts:Shared: /shared
    Mounts:Output: /logs
    Mounts:License: /license
  volumes:
    - type: bind
      source: ${SHARED_MOUNT_PATH}
      target: /shared
    - type: bind
      source: ${OUTPUT_MOUNT_PATH}
      target: /logs
    - type: bind
      source: ${CUSTOM_LICENSE_MOUNT_PATH}
      target: /license
  expose:
    - "5000"

 studio:
  container_name: form-recognizer-studio
  image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/studio:3.0
  environment:
    ONPREM_LOCALFILE_BASEPATH: /onprem_folder
    STORAGE_DATABASE_CONNECTION_STRING: /onprem_db/Application.db
  volumes:
    - type: bind
      source: ${FILE_MOUNT_PATH} # path to your local folder
      target: /onprem_folder
    - type: bind
      source: ${DB_MOUNT_PATH} # path to your local folder
      target: /onprem_db
  ports:
    - "5001:5001"
  user: "1000:1000" # echo $(id -u):$(id -g)

기타 매개 변수 및 명령

컨테이너를 실행하는 데 필요한 몇 가지 매개 변수 및 명령은 다음과 같습니다.

사용량 레코드

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

로그 저장을 위한 인수

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

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

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

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

모든 기록 가져오기

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

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

예제 HTTPS 엔드포인트

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

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

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

특정 월의 기록 가져오기

다음 엔드포인트는 특정 월 및 연도의 사용량을 요약하는 보고서를 제공합니다.

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

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

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

문제 해결

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

팁

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

다음 단계

• 샘플 레이블 지정 도구를 ACI(Azure Container Instance)에 배포
• 약정 플랜 변경 또는 종료