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 가지 범주 분류와 함께 추가적인 세부 정보를 제공합니다.

단계 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 호출에서 동일하며, 유일한 차이점은 사용자가 지정하는 쿼리 매개 변수뿐입니다.

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

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

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

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 매개 변수는) 유효하지 않습니다. 지원되는 도메인 특정 모델의 전체 목록을 살펴보려면 다음 메서드를 이용합니다:

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
      }
    ]
  }
}

단계 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도).

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

오류 응답

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

요약

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

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