Computer Vision API 호출하기

등록일시: 2017-11-02 08:00,  수정일시: 2017-11-02 02:44
조회수: 3,368
이 문서는 Cognitive Services 기술을 널리 알리고자 하는 개인적인 취지로 제공되는 번역문서입니다. 이 문서에 대한 모든 저작권은 마이크로소프트에 있으며 요청이 있을 경우 언제라도 게시가 중단될 수 있습니다. 번역 내용에 오역이 존재할 수 있고 주석은 번역자 개인의 의견일 뿐이며 마이크로소프트는 이에 관한 어떠한 보장도 하지 않습니다. 번역이 완료된 이후에도 대상 제품 및 기술이 개선되거나 변경됨에 따라 원문의 내용도 변경되거나 보완되었을 수 있으므로 주의하시기 바랍니다.
본문에서는 REST 방식으로 Computer Vision API를 호출하는 방법을 간단히 살펴봅니다.

본문에서는 REST 방식으로 Computer Vision API를 호출하는 방법을 살펴봅니다. 제시되는 예제들은 Computer Vision API 클라이언트 라이브러리를 사용하는 C# 코드와 HTTP POST/GET 호출의 두 가지 방식으로 작성됩니다. 본문에서 집중적으로 살펴볼 내용은 다음과 같습니다:

  • 태그, 설명 및 범주를 가져오는 방법
  • 특정 도메인 관련 정보를 가져오는 방법 (유명인사 정보)

요구 사항

이미지 URL, 또는 로컬에 저장된 이미지의 경로가 필요합니다.

  • 지원되는 입력 방식: application/octet-stream 형식의 원시 이미지 이진 콘텐츠 또는 이미지 URL
  • 지원되는 이미지 형식: JPEG, PNG, GIF, BMP
  • 이미지 파일 크기: 4 MB 미만
  • 이미지 크기: 50 x 50 픽셀 이상

본문의 예제에서는 다음과 같은 기능들을 살펴봅니다:

  1. 이미지를 분석하고 반환된 태그 배열 및 설명 가져오기
  2. 도메인 특정 모델("celebrities" 모델)을 사용해서 이미지를 분석하고, 반환된 JSON 형식의 데이터에서 결과 가져오기

기능은 다음과 같이 세분화됩니다:

  • 첫 번째 옵션: 범위 분석 - 지정한 모델만 분석합니다.
  • 두 번째 옵션: 고급 분석 - 분석을 통해서 86 가지 범주 분류와 함께 추가적인 세부 정보를 제공합니다.
역주

본문의 예제 코드들 중 일부는 문제가 있다고 판단되어 역자가 이해를 돕기 위해 코드를 변경하거나 임의로 순서를 바꾸는 등 첨삭하였으므로 참고하시기 바랍니다. 또한 Cognitive Services를 처음 접하시는 분들의 경우, 본문의 내용만으로는 구체적인 동작 방식을 이해하기에 다소 무리가 있을 것이라는게 개인적인 판단입니다. 본문은 계속해서 제공되는 퀵 스타트 문서 및 자습서 문서들을 살펴보기 위한 준비 단계 정도로 생각하시면 될 것 같습니다.

단계 1: API 호출 인증하기

매번 Computer Vision API를 호출할 때마다 쿼리 문자열 매개 변수나 요청 헤더를 통해서 구독 키를 전달해야 합니다.

구독 키를 발급받는 방법은 Computer Vision API 구독 키 발급받기 문서를 참고하시기 바랍니다.

1. 쿼리 문자열을 통해서 구독 키를 전달하는 방법은 아래의 Computer Vision API 예제를 참고하시기 바랍니다:

https://westus.api.cognitive.microsoft.com/vision/v1.0/analyze?visualFeatures=Description,Tags&subscription-key=<Your subscription key>

2. 또는 HTTP 요청 헤더에 구독 키를 지정해서 전달할 수도 있습니다:

ocp-apim-subscription-key: <Your subscription key>

3. 클라이언트 라이브러리를 사용할 경우, VisionServiceClient 클래스의 생성자에 지정한 구독 키가 전달됩니다:

var visionClient = new VisionServiceClient("Your subscription key");

단계 2: Computer Vision API 서비스에 이미지를 업로드하고 태그, 설명 및 유명인사 정보 가져오기

Computer Vision API를 호출하는 가장 기본적인 방식은 직접 이미지를 업로드하는 것으로, 이 작업은 이미지에서 읽어온 데이터가 담긴 application/octet-stream 콘텐츠 유형의 "POST" 요청을 전송함으로써 수행됩니다. 태그 및 설명의 경우, 업로드 방식은 모든 Computer Vision API 호출에서 동일하며, 유일한 차이점은 사용자가 지정하는 쿼리 매개 변수뿐입니다.

역주

본문에서는 분석할 이미지를 대부분 직접 업로드하는 방식을 사용한다고 가정하고 있습니다. 그러나 요구 사항 절에서 설명한 것처럼 이미지의 URL을 전달하는 방식도 지원되며, 그 구체적인 사용 방법은 이후의 문서들에서 살펴보게 될 것입니다.

지정한 이미지에 대한 태그와 설명을 가져오는 방법:

첫 번째 옵션: 태그 목록 및 단일 설명 가져오기

역주

다음 예제 코드의 의미는 REST 방식으로 API를 호출할 경우, HTTP POST 방식을 사용해서 application/octet-stream 콘텐츠 유형의 이미지 데이터를 담은 요청을 예제의 URL로 전송한다는 뜻입니다. 이처럼 간단한 URL만 제시되는 이유는, POST 요청을 전송하는 프로그래밍 언어 또는 도구가 그 무엇이라도 상관 없기 때문입니다. 실제로 다음 문서부터 살펴보게 될 퀵 스타트 문서 및 자습서 문서들은 cURL 도구, C#, Java, JavaScript, PHP, Python 등을 사용하여 Computer Vision API를 호출하는 방법을 설명합니다.

POST https://westus.api.cognitive.microsoft.com/vision/v1.0/analyze?visualFeatures=Description,Tags&subscription-key=<Your subscription key>
역주

다음 예제는 방금 살펴본 위의 예제를 클라이언트 라이브러리를 이용하여 C#으로 다시 구현한 스니핏입니다. Computer Vision API 자체는 REST 형태로 제공되지만, 실제 작업에서 매번 HTTP 요청과 응답을 효율적으로 처리하는 코드를 반복해서 만들 필요는 없을 것입니다. 그렇기 때문에 상당 수의 Cognitive Services들은 자신의 API들을 래핑한 클라이언트 라이브러리를 제공합니다. 다만, 모든 Cognitive Services들이 클라이언트 라이브러리를 제공하는 것도 아니고, 해당 서비스의 모든 API가 클라이언트 라이브러리로 구현되는 것도 아니라는 점을 염두에 두시기 바랍니다. 특정 API는 HTTP 통신 방식으로만 사용할 수 있는 경우도 있습니다. Computer Vision API의 클라이언트 라이브러리는 Microsoft.ProjectOxford.Vision NuGet 패키지로 제공되며 (GitHub 코드), 그 외에도 AndroidSwift 용 클라이언트 라이브러리들도 별도로 제공됩니다.

using Microsoft.ProjectOxford.Vision;
using Microsoft.ProjectOxford.Vision.Contract;
using System.IO;

AnalysisResult analysisResult;
var features = new VisualFeature[] { VisualFeature.Tags, VisualFeature.Description };

using (var fs = new FileStream(@"C:\Vision\Sample.jpg", FileMode.Open))
{
    analysisResult = await visionClient.AnalyzeImageAsync(fs, features);
}

두 번째 옵션: 태그 목록만, 또는 설명 목록만 가져오기

태그만 가져오기:
POST https://westus.api.cognitive.microsoft.com/vision/v1.0/tag?subscription-key=<Your subscription key>
                        
var analysisResult = await visionClient.GetTagsAsync("http://contoso.com/example.jpg");
설명만 가져오기:
POST https://westus.api.cognitive.microsoft.com/vision/v1.0/describe?subscription-key=<Your subscription key>

using (var fs = new FileStream(@"C:\Vision\Sample.jpg", FileMode.Open))
{
    analysisResult = await visionClient.DescribeAsync(fs);
}

특정 도메인(유명인사)에 대한 분석 결과를 가져오는 방법:

첫 번째 옵션: 범위 분석 - 지정한 특정 모델만을 대상으로 하는 분석

POST https://westus.api.cognitive.microsoft.com/vision/v1.0/models/celebrities/analyze?subscription-key=<Your subscription key>

var celebritiesResult = await visionClient.AnalyzeImageInDomainAsync(url, "celebrities");

이 옵션의 경우, 다른 모든 쿼리 매개 변수는 (즉, visualFeatures 및 details 매개 변수는) 유효하지 않습니다. 지원되는 도메인 특정 모델의 전체 목록을 살펴보려면 다음 메서드를 이용합니다:

역주

현재 지원되는 도메인 특정 (Domain-Specific) 모델은 유명인사 (celebrities) 모델과 랜드마크 (landmarks) 모델이 전부입니다.

GET https://westus.api.cognitive.microsoft.com/vision/v1.0/models?subscription-key=<Your subscription key>

var models = await visionClient.ListModelsAsync();

두 번째 옵션: 고급 분석 - 86 가지 범주 분류에 더해 추가적인 세부 정보 제공를 위한 분석

일반적인 이미지 분석 결과와 한 가지 이상의 도메인 특정 모델의 세부 결과를 함께 얻고자 하는 응용 프로그램의 경우, 모델 쿼리 매개 변수를 이용해서 v1 API를 확장합니다.

POST https://westus.api.cognitive.microsoft.com/vision/v1.0/analyze?details=celebrities&subscription-key=<Your subscription key>

이 메서드가 호출되면 먼저 86 가지 범주 분류자(Classifier)가 호출됩니다. 그런 다음, 범주 중 하나가 알려진/일치하는 모델과 일치할 경우, 뒤이어 분류자 호출의 두 번째 과정이 수행됩니다. 가령, 'details=all'이거나 'details'에 'celebrities'가 포함된 경우, 86 가지 범주 분류자가 호출된 뒤에 유명인사 모델이 호출되고 그 결과에 사람(person) 범주가 포함됩니다. 따라서 이 방식을 사용할 경우, 유명인사에 관심 있는 사용자의 대기 시간이 첫 번째 옵션에 비해 길어집니다.

이 경우 모든 v1 쿼리 매개 변수는 동일하게 동작합니다. 만약 visualFeatures=categories 매개 변수가 지정되지 않았다면 암시적으로 활성화됩니다.

단계 3: analyze&visualFeatures=Description,Tags에 대한 JSON 출력 조회 및 이해하기

다음은 출력 예제입니다:

{
  "tags": [
    {
      "name": "outdoor",
      "score": 0.976
    },
    {
      "name": "bird",
      "score": 0.95
    }
  ],
  "description": 
  {
    "tags": [
      "outdoor",
      "bird"
    ],
    "captions": [
      {
        "text": "partridge in a pear tree",
        "confidence": 0.96
      }
    ]
  }
}
필드 형식 내용
Tags 개체 태그 배열의 최상위 개체
tags[].Name 문자열 태그 분류자 키워드
tags[].Score 숫자 신뢰 점수, 0 부터 1 까지
description 개체 설명에 대한 최상위 개체
description.tags[] 문자열 태그들의 목록. 생성된 캡션의 신뢰도가 불충분한 경우, 태그가 호출자에게 제공할 수 있는 유일한 정보가 될 수도 있습니다.
description.captions[].text 문자열 이미지를 설명하는 문구
description.captions[].confidence 숫자 문구에 대한 신뢰도

단계 4: 도메인 특정 모델의 JSON 출력 조회 및 이해하기

첫 번째 옵션: 범위 분석 - 지정한 특정 모델만을 대상으로 하는 분석

{
  "requestId": "87e44580-925a-49c8-b661-d1c54d1b83b5",
  "metadata":     {
    "width": 640,
    "height": 430,
    "format": "Jpeg"
  },
  "result": {
    "celebrities": [
      {
        "name": "Richard Nixon",
        "faceRectangle": {
          "left": 107,
          "top": 98,
          "width": 165,
          "height": 165
        },
        "confidence": 0.9999827
      }
    ]
  }
}

두 번째 옵션: 고급 분석 - 86 가지 범주 분류에 더해 추가적인 세부 정보 제공를 위한 분석

두 번째 옵션(고급 분석)을 사용한 도메인 특정 모델 분석의 경우, 다음과 같이 범주 반환 형식이 확장됩니다:

{
  "requestId": "5211ba3c-2819-436f-bc78-0c79b146dbab",
  "metadata": {
    "width": 1200,
    "height": 701,
    "format": "Jpeg"
  },
  "categories": [
    {
      "name": "people_portrait",
      "score": 0.72265625,
      "detail": {
        "celebrities": [
          {
            "name": "Barack Hussein Obama",
            "faceRectangle": {
              "left": 261,
              "top": 163,
              "width": 318,
              "height": 318
            },
            "confidence": 0.9993975
          }
        ]
      }
    }
  ]    
}

여기서 categories 필드는 원본 분류의 86 가지 범주 중 한 가지 이상의 목록입니다. 또한 밑줄로 끝나는 범주는 해당 범주 자신 및 그 하위 항목과 일치한다는 점을 기억하시기 바랍니다 (가령 유명인사 모델의 경우, people_ 뿐만 아니라 people_group도).

필드 형식 내용
categories 개체 최상위 개체
categories[].name 문자열 86 가지 범주 분류의 이름
categories[].score 숫자 신뢰 점수, 0 부터 1 까지
categories[].detail 개체 선택적 세부정보 개체

여러 개의 범주가 일치할 경우 (예를 들어서, model=celebrities일 경우, 86 가지 범주 분류자는 people_ 및 people_young에 대한 점수를 반환합니다), 세부 정보는 가장 포괄적인 수준의 범주에 (이 경우 people_ 범주에) 추가됩니다.

오류 응답

오류 응답은 vision.analyze와 동일하고, 추가로 NotSupportedModel 오류(HTTP 400)가 발생할 수 있으며, 첫 번째 옵션 및 두 번째 옵션 시나리오 모두에서 반환될 수 있습니다. 두 번째 옵션의 경우 (고급 분석), details에 지정된 모델 중 하나라도 인식되지 않으면, 한 가지 이상의 모델이 유효하더라도 API에서 NotSupportedModel을 반환합니다. 사용자는 listModels을 호출해서 지원되는 모델들을 찾을 수 있습니다.

역주

여기에서 말하는 listModels는 클라이언트 라이브러리에서 제공되는 VisionServiceClient 클래스의 ListModelsAsync() 메서드를 뜻하는 것으로 보입니다. 이에 대응하는 HTTP API는 GET 방식의 List Domain Specific Models입니다. 예제 코드는 본문의 특정 도메인(유명인사)에 대한 분석 결과를 얻는 방법 절의 첫 번째 옵션에 관한 예제에서 확인하실 수 있습니다.

요약

지금까지 Computer Vision API의 기본 기능, 즉, 이미지를 업로드하고 반환된 중요한 메타데이터를 검색하는 방법을 살펴봤습니다.

REST API를 실제로 테스트해보려면 Computer Vision API 참조 페이지를 방문해보시기 바랍니다.