Natural Language API 기초

이 문서는 Cloud Natural Language API 사용에 관한 기본사항을 설명하는 가이드입니다. 이 개념 가이드는 Natural Language API에 대해 실행할 수 있는 요청 유형, 해당 요청 작성 방법, 응답 처리 방법을 설명합니다. 모든 Natural Language API 사용자가 API를 사용하기 전에 이 가이드 및 관련 가이드 중 하나를 읽어보는 것이 좋습니다.

Natural Language 기능

Natural Language API에는 텍스트를 분석하고 주석을 달기 위한 여러 가지 메소드가 있습니다. 각 분석 수준은 언어 이해에 중요한 정보를 제공합니다. 메소드는 아래에 나와 있습니다.

  • 감정 분석은 주어진 텍스트를 조사하고 텍스트 내의 주도적인 감정적 의견을 식별하여 작성자의 태도가 긍정적인지, 부정적인지 또는 중립적인지를 판단합니다. 감정 분석은 analyzeSentiment 메서드를 통해 수행됩니다.

  • 항목 분석은 주어진 텍스트에서 알려진 항목(유명 인사, 명소 등의 고유 명사와 식당, 경기장 등의 보통 명사)을 조사하고 해당 항목의 정보를 반환합니다. 항목 분석은 analyzeEntities 메서드를 통해 수행됩니다.

  • 항목 감정 분석은 주어진 텍스트에서 알려진 항목(고유 명사와 보통 명사)를 조사하고, 항목에 대한 정보를 반환하고, 텍스트 내의 주도적인 감정적 의견을 식별하여 작성자의 태도가 긍정적인지, 부정적인지 또는 중립적인지를 판단합니다. 항목 분석은 analyzeEntitySentiment 메서드를 통해 수행됩니다.

  • 구문 분석은 언어 정보를 추출하여 주어진 텍스트를 일련의 구문과 토큰(일반적으로 단어 경계)을 분해하고 해당 토큰을 심층 분석합니다. 구문 분석은 analyzeSyntax 메서드를 통해 수행됩니다.

  • 콘텐츠 분류는 텍스트 콘텐츠를 분석하고 콘텐츠에 대한 콘텐츠 카테고리를 반환합니다. 콘텐츠 분류는 classifyText 메서드를 통해 수행됩니다.

각 API 호출은 초기 요청에서 호출자가 언어를 지정하지 않은 경우 언어도 감지하고 반환합니다.

또한 주어진 텍스트에서 한 번의 API 호출로 여러 개의 자연어 작업을 수행하려면 annotateText 요청을 사용하여 감정 분석 및 항목 분석을 수행할 수도 있습니다.

기본 Natural Language 요청

Natural Language API는 REST API이며, JSON 요청 및 응답으로 구성됩니다. 간단한 Natural Language JSON 항목 분석 요청이 아래에 나와 있습니다.

{
  "document":{
    "type":"PLAIN_TEXT",
    "language": "EN",
    "content":"'Lawrence of Arabia' is a highly rated film biography about
                British Lieutenant T. E. Lawrence. Peter O'Toole plays
                Lawrence in the film."
  },
  "encodingType":"UTF8"
}

다음은 필드에 대한 설명입니다.

  • document에는 이 요청의 데이터가 포함되어 있으며, 다음과 같은 하위 필드로 구성됩니다.
    • type - 문서 유형(HTML 또는 PLAIN_TEXT)
    • language - (선택사항) 요청 내 텍스트의 언어입니다. 지정하지 않으면 언어가 자동으로 감지됩니다. Natural Language가 지원하는 언어에 대한 정보는 언어 지원을 참조하십시오. 지원되지 않는 언어는 JSON 응답에서 오류를 반환합니다.
    • 평가할 텍스트를 포함하는 content 또는 gcsContentUri입니다. content를 전달하는 경우 이 텍스트는 위와 같이 JSON 요청에 직접 포함됩니다. gcsContentUri를 전달하는 경우 이 필드에는 Google Cloud Storage 내 텍스트 콘텐츠를 가리키는 URI가 포함되어야 합니다.
  • encodingType - (필수) 텍스트에 대한 반환된 문자 오프셋을 계산하는 인코딩 스키마로, 전달된 텍스트의 인코딩과 일치해야 합니다. 이 매개변수가 설정되지 않은 경우 요청이 오류를 반환하는 대신 모든 오프셋이 -1-1로 설정됩니다.

텍스트 콘텐츠 지정

Natural Language API 요청을 전달할 때, 처리할 텍스트를 다음의 두 가지 방법 중 하나로 지정합니다.

  • content 필드 내에서 텍스트를 직접 전달합니다.
  • gcsContentUri 필드 내에 Google Cloud Storage URI를 전달합니다.

어떤 경우이건 콘텐츠 한도에서 허용하는 것보다 더 전달해서는 안 됩니다. 이 콘텐츠 한도는 문자 단위가 아닌 바이트 단위입니다. 따라서 문자 길이는 텍스트의 인코딩에 따라 다릅니다.

아래의 요청은 게티즈버그 연설을 포함하는 Google Cloud Storage 파일을 나타냅니다.

{
  "document":{
    "type":"PLAIN_TEXT",
    "language": "EN",
    "gcsContentUri":"gs://cloud-samples-tests/natural-language/gettysburg.txt"
  },
}

감정 분석

감정 분석은 텍스트 내에서 표현되는 전체적인 태도(긍정적 또는 부정적)를 판단하려고 시도합니다. 이는 숫자 scoremagnitude 값으로 표현됩니다.

감정 분석 응답 필드

아래에는 게티즈버그 연설에 대한 샘플 analyzeSentiment 응답이 나와 있습니다.

{
  "documentSentiment": {
    "score": 0.2,
    "magnitude": 3.6
  },
  "language": "en",
   "sentences": [
    {
      "text": {
        "content": "Four score and seven years ago our fathers brought forth
        on this continent a new nation, conceived in liberty and dedicated to
        the proposition that all men are created equal.",
        "beginOffset": 0
      },
      "sentiment": {
        "magnitude": 0.8,
        "score": 0.8
      }
    },
   ...
}

다음은 각 필드에 대한 설명입니다.

  • documentSentiment는 문서의 전체적인 감정을 포함하며, 다음과 같은 필드로 구성됩니다.
    • 감정 score의 범위는 -1.0(부정적)에서 1.0(긍정적)까지이며 텍스트의 전반적인 정서 성향을 나타냅니다.
    • magnitude의 범위는 0.0에서 +inf까지이며 주어진 텍스트 내에서 전반적인 감정 강도(긍정적 및 부정적 모두)를 나타냅니다. score와 달리 magnitude는 정규화되지 않습니다. 텍스트 내의 각 감정 표현(긍정적 및 부정적 모두)이 텍스트 magnitude에 반영되며, 따라서 긴 텍스트 블록일수록 값이 더 커집니다.
  • language에는 문서의 언어가 포함됩니다. 언어는 초기 요청 시 전달되거나, 없는 경우 자동으로 감지됩니다.
  • sentences에는 다음을 포함하여 원본 문서에서 추출된 문장의 목록이 포함됩니다.
    • sentiment에는 위에서 설명한 scoremagnitude 값을 포함하여 각 문장에 연결된 문장 수준의 감정 값이 포함됩니다.

게티즈버그 연설에 대한 응답 값 점수 0.2는 문서가 약간 긍정적임을 나타내고, 값 3.6은 문서 크기는 작지만(한 단락 정도) 상대적으로 감정적이라는 점을 나타냅니다. 게티즈버그 연설 첫 번째 문장의 score0.8로 매우 긍정적입니다.

감정 분석 값 해석

문서의 감정 score는 문서의 전반적인 정서를 나타냅니다. 문서의 감정 magnitude는 문서에 얼마나 많은 감정이 담겨 있는지를 나타내며 이 값은 종종 문서 길이와 정비례합니다.

Natural Language는 문서에서 긍정적 감정과 부정적인 감정의 차이를 나타내지 만 특정 긍정적 감정과 부정적인 감정을 식별하지는 않습니다. 예를 들어 '화가 난다'와 '슬프다'는 모두 부정적 감정으로 간주됩니다. 하지만 Natural Language는 '화가 났거나' '슬퍼' 보이는 텍스트를 분석할 때 응답으로 텍스트의 감정의 부정적이라는 것만 표시할 뿐 '슬프다'거나 '화가 났다'라고 표시하지 않습니다.

중립적 점수(0.0 근처)의 문서는 감정적 콘텐츠가 많거나 복합적 감정이 포함되어 긍정적 값과 부정적 값이 서로를 상쇄시키는 문서일 수 있습니다. 일반적으로 magnitude 값을 사용하여 이 두 가지 경우를 구분할 수 있습니다. 문서가 실제로 감정 중립적이라면 magnitude 값이 낮지만 복합적 감정이 포함되어 있는 문서는 이 값은 높게 측정됩니다.

문서(특히 서로 다른 길이의 문서)를 서로 비교할 때는 magnitude 값을 사용하여 점수를 보정하세요. 그러면 관련된 감정적 콘텐츠의 양을 측정하는 데 도움이 됩니다.

아래의 차트는 몇 가지 샘플 값과 이를 해석하는 방법을 보여줍니다.

감정 샘플 값
확실히 긍정적* "score": 0.8, "magnitude": 3.0
확실히 부정적* "score": -0.6, "magnitude": 4.0
중립적 "score": 0.1, "magnitude": 0.0
혼합 "score": 0.0, "magnitude": 4.0

* '확실히 긍정적' 및 '확실히 부정적' 감정은 사용 사례와 고객마다 다릅니다. 특정 시나리오에서는 결과가 다르게 나타날 수 있습니다. 적당한 임계값을 정의한 후에 테스트하고 결과를 확인하면서 임계값을 조정하는 것이 좋습니다. 예를 들어 0.25가 넘는 점수 임계값을 확실히 긍정적인 것으로 정의했는데, 데이터 및 결과를 검토한 후에 점수 임계값을 0.15로 수정했더니 0.15~0.25 사이의 점수도 긍정적인 것으로 간주될 수 있다는 것을 확인할 수 있습니다.

항목 분석

항목 분석은 텍스트에 있는 항목에 대한 정보를 제공합니다. 항목이란 일반적으로 유명 인사, 명소, 일반 물체 등 이름이 붙은 '사물'을 의미합니다.

항목은 크게 두 가지 카테고리로 나누어집니다. 하나는 고유 항목(특정인, 특정 장소 등)에 연결되는 고유 명사이고, 다른 하나는 보통 명사(자연어 처리에서 '노미널'이라고도 함)입니다. 일반적으로 명사는 '항목'에 해당한다고 보는 것이 좋습니다. 항목은 원래 텍스트에 색인이 생성된 오프셋으로 반환됩니다.

항목 분석 요청은 반환된 오프셋이 올바르게 해석되도록 encodingType 인수를 전달해야 합니다.

항목 분석 응답 필드

항목 분석은 감지된 항목 모음과 해당 항목과 연관된 매개변수(예: 항목 유형, 항목과 전체 텍스트의 관련성, 같은 항목을 참조하는 텍스트 내 위치)를 반환합니다. 항목은 전체 텍스트와의 관련성을 나타내는 salience 점수 순서대로(내림차순) 반환됩니다.

아래에는 항목 요청에 대한 analyzeEntities 응답이 나와 있습니다.

{
  "entities": [
    {
      "name": "Lawrence of Arabia",
      "type": "WORK_OF_ART",
      "metadata": {
        "mid": "/m/0bx0l",
        "wikipedia_url": "http://en.wikipedia.org/wiki/Lawrence_ofArabia(film)"
      },
      "salience": 0.75222147,
      "mentions": [
        {
          "text": {
            "content": "Lawrence of Arabia",
            "beginOffset": 1
          },
          "type": "PROPER"
        },
        {
          "text": {
            "content": "film biography",
            "beginOffset": 39
          },
          "type": "COMMON"
        }
      ]
    },
    {
      "name": "T.E. Lawrence",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/0bx5v",
        "wikipedia_url": "http://en.wikipedia.org/wiki/T._E._Lawrence"
      },
      "salience": 0.12430617,
      "mentions": [
        {
          "text": {
            "content": "T. E. Lawrence",
            "beginOffset": 94
          },
          "type": "PROPER"
        },
        {
          "text": {
            "content": "Lieutenant",
            "beginOffset": 83
          },
          "type": "COMMON"
        },
        {
          "text": {
            "content": "Lawrence",
            "beginOffset": 145
          },
          "type": "PROPER"
        }
      ]
    },
    {
      "name": "British",
      "type": "LOCATION",
      "metadata": {
        "mid": "/m/07ssc",
        "wikipedia_url": "http://en.wikipedia.org/wiki/United_Kingdom"
      },
      "salience": 0.078094982,
      "mentions": [
        {
          "text": {
            "content": "British",
            "beginOffset": 75
          },
          "type": "PROPER"
        }
      ]
    },
    {
      "name": "film",
      "type": "WORK_OF_ART",
      "metadata": {},
      "salience": 0.033808723,
      "mentions": [
        {
          "text": {
            "content": "film",
            "beginOffset": 161
          },
          "type": "COMMON"
        }
      ]
    },
    {
      "name": "Peter O'Toole",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/0h0jz",
        "wikipedia_url": "http://en.wikipedia.org/wiki/Peter_O'Toole"
      },
      "salience": 0.011568651,
      "mentions": [
        {
          "text": {
            "content": "Peter O'Toole",
            "beginOffset": 110
          },
          "type": "PROPER"
        }
      ]
    }
  ],
  "language": "en"
}

여기에서 Natural Language API는 'Lawrence of Arabia'(영화) 및 'T.E. Lawrence'(사람)의 항목을 반환합니다. 항목 분석은 이 경우의 'Lawrence'처럼 모호하게 비슷한 항목에 유용합니다.

항목의 매개변수를 저장하는 데 사용되는 필드가 아래에 나와 있습니다.

  • type은 항목 유형을 나타냅니다(예: 항목이 사람인지, 위치인지, 소비재인지 등). 이 정보는 항목을 구분하거나 구별 짓는 데 도움이 되며, 패턴을 쓰거나 정보를 추출하는 데 사용될 수 있습니다. 예를 들어 type 값은 WORK_OF_ART(영화)로 태그된 'Lawrence of Arabia'를 PERSON로 태그된 'T.E. Lawrence'와 구분하는 등 비슷한 이름의 항목을 구분하는 데 도움이 될 수 있습니다. 자세한 내용은 항목 유형을 참조하세요.

  • metadata는 항목의 지식 저장소에 대한 소스 정보를 포함합니다. 추후에 저장소가 추가 공개될 수 있습니다. 이 필드에는 다음 하위 필드가 포함될 수 있습니다.

    • wikipedia_url이 존재하는 경우 이 필드에는 이 항목과 관련된 위키백과 URL이 포함됩니다.
    • mid가 존재하는 경우 이 필드에는 항목의 Google 지식 정보 항목에 해당하는 머신 생성 식별자(MID)가 포함됩니다. mid 값은 여러 언어에서 고유하게 유지되므로 이러한 값을 사용하여 각기 다른 언어의 항목을 묶을 수 있습니다. 이러한 MID 값을 알아보려면 Google 지식 정보 검색 API 문서를 참조하세요.

      Google Knowledge Graph API로 반환된 모든 mid 값을 확인할 수는 없습니다. mid를 항목 고유 식별자로 사용할 수는 있지만 항목에 대한 추가 정보를 검색할 때 이 값에 의존해서는 안 됩니다.

  • salience는 전체 문서 텍스트에서 이 항목의 중요성이나 관련성을 나타냅니다. 이 점수는 두드러진 항목에 우선순위를 지정함으로써 정보 검색 및 요약에 도움을 줄 수 있습니다. 0.0에 가까운 점수일수록 덜 중요하고, 1.0에 가까운 점수일수록 더 중요합니다.

  • mentions는 텍스트 내에서 항목이 언급된 오프셋 위치를 나타냅니다. 이 정보는 텍스트에서 영화 제목은 빼고 사람 이름인 'Lawrence'가 언급된 모든 경우를 찾고자 할 때 유용할 수 있습니다. mentions를 사용하여 같은 항목인 'T.E. Lawrence'를 의미하는 'Lawrence' 등의 항목 별칭 목록을 수집할 수도 있습니다. 항목 멘션은 PROPER 또는 COMMON의 두 가지 유형 중 하나일 수 있습니다. 예를 들어 고유 명사 항목인 'Lawrence of Arabia'가 영화 제목으로 직접 언급되거나 보통 명사(T.E. Lawrence의 '전기 영화')로 언급될 수 있습니다.

항목 감정 분석

항목 감정 분석은 항목 분석과 감정 분석을 결합하며, 텍스트 내에서 항목에 대해 표현되는 감정(긍정적 또는 부정적)을 판단하려고 시도합니다. 항목 감정은 score 및 magnitude의 숫자 값으로 표현되며, 항목의 각 멘션에 대해 결정됩니다. 해당 점수가 집계되어 항목의 전체 감정 score 및 magnitude가 결정됩니다.

항목 감정 분석 요청

항목 감정 분석 요청은 다음 형식으로 analyzeEntitySentiment 메소드를 사용하여 Natural Language로 전송됩니다.

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"I love R&B music. Marvin Gaye is the best.
               'What's Going On' is one of my favorite songs.
               It was so sad when Marvin Gaye died."
  },
  "encodingType":"UTF8"
}

content 매개변수에서 텍스트의 언어 코드를 식별하는 선택적인 language 매개변수를 요청과 함께 지정할 수 있습니다. language 매개 변수를 지정하지 않으면 Natural Lnaguage가 요청 컨텐츠의 언어를 자동 감지합니다. Natural Language가 지원하는 언어에 대한 정보는 언어 지원을 참조하십시오.

항목 감정 분석 응답

Natural Language API는 주어진 텍스트를 처리하여 항목을 추출하고 감정을 판단합니다. 항목 감정 분석 요청은 감정 분석 값 해석에 설명된 대로 문서 콘텐츠에서 발견된 entities, 항목이 언급된 모든 mentions, 각 멘션의 scoremagnitude 숫자 값을 포함하는 응답을 반환합니다. 항목의 전체 scoremagnitude 값은 각 항목 멘션의 scoremagnitude 값을 집계한 것입니다. 항목의 scoremagnitude 값이 0일 수도 있습니다. 텍스트에 포함된 감정적 콘텐츠 양이 적으면 magnitude가 0이 될 수 있고, 복합적 감정이 포함되어 있으면 score가 0이 될 수 있습니다.

{
  "entities": [
    {
      "name": "R&B music",
      "type": "WORK_OF_ART",
      "metadata": {},
      "salience": 0.5306305,
      "mentions": [
        {
          "text": {
            "content": "R&B music",
            "beginOffset": 7
          },
          "type": "COMMON",
          "sentiment": {
            "magnitude": 0.9,
            "score": 0.9
          }
        }
      ],
      "sentiment": {
        "magnitude": 0.9,
        "score": 0.9
      }
    },
    {
      "name": "Marvin Gaye",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/012z8_",
        "wikipedia_url": "http://en.wikipedia.org/wiki/Marvin_Gaye"
      },
      "salience": 0.21584158,
      "mentions": [
        {
          "text": {
            "content": "Marvin Gaye",
            "beginOffset": 18
          },
          "type": "PROPER",
          "sentiment": {
            "magnitude": 0.4,
            "score": 0.4
          }
        },
        {
          "text": {
            "content": "Marvin Gaye",
            "beginOffset": 138
          },
          "type": "PROPER",
          "sentiment": {
            "magnitude": 0.2,
            "score": -0.2
          }
        }
      ],
      "sentiment": {
        "magnitude": 0.6,
        "score": 0.1
      }
    },
    ...
  ],
  "language": "en"
}

항목 감정 분석에서 예를 참조하세요.

구문 분석

Natural Language API는 구문 분석을 통해 텍스트를 분석하고 파싱하기 위한 강력한 도구 모음을 제공합니다. 구문 분석을 수행하려면 analyzeSyntax 메서드를 사용하세요.

구문 분석은 다음과 같은 작업으로 구성됩니다.

  • 구문 추출은 텍스트 스트림을 일련의 문장으로 나눕니다.
  • 토큰화는 텍스트 스트림을 일련의 토큰으로 나눕니다. 각 토큰은 단어 하나에 해당합니다.
  • 그런 다음에 Natural Language API가 토큰을 처리하고, 문장 내 위치를 사용하여 구문 정보를 토큰에 추가합니다.

구문 토큰 모음에 대한 모든 문서는 형태론 및 종속성 트리 가이드 안에 있습니다.

구문 분석 요청

구문 분석 요청은 analyzeSyntax 메서드를 다음 형식으로 사용하여 Natural Language API에 전송됩니다.

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Ask not what your country can do for you,
               ask what you can do for your country."
  },
  "encodingType":"UTF8"
}

구문 분석 응답

Natural Language API는 주어진 텍스트를 처리하여 문장과 토큰을 추출합니다. 구문 분석 요청은 이러한 sentencestokens를 포함하는 응답을 다음과 같은 형식으로 반환합니다.

{
  "sentences": [
    ... Array of sentences with sentence information
  ],
  "tokens": [
    ... Array of tokens with token information
  ]
}

문장 추출

구문 분석을 수행할 때 Natural Language API는 제공된 텍스트에서 추출된 다수의 문장을 반환합니다. 각 문장에는 text 상위 항목 안에 다음 필드가 포함되어 있습니다.

  • beginOffset은 주어진 텍스트 내에서 문장이 시작되는 문자 오프셋(0부터 시작)을 나타냅니다. 이 오프셋은 전달된 encodingType을 사용하여 계산됩니다.
  • content는 추출된 문장의 전체 텍스트를 포함합니다.

예를 들어 게티즈버그 연설의 구문 분석 요청에 대해서는 다음 sentences 요소가 반환됩니다.

{
  "sentences": [
    {
      "text": {
        "content": "Four score and seven years ago our fathers brought forth on
                    this continent a new nation, conceived in liberty and
                    dedicated to the proposition that all men are created
                    equal.",
        "beginOffset": 0
      }
    },
    {
      "text": {
        "content": "Now we are engaged in a great civil war, testing whether
                    that nation or any nation so conceived and so dedicated can
                    long endure.",
        "beginOffset": 175
      }
    },
...
...
    {
      "text": {
        "content": "It is rather for us to be here dedicated to the great task
                    remaining before us--that from these honored dead we take
                    increased devotion to that cause for which they gave the
                    last full measure of devotion--that we here highly resolve
                    that these dead shall not have died in vain, that this
                    nation under God shall have a new birth of freedom, and that
                    government of the people, by the people, for the people
                    shall not perish from the earth.",
        "beginOffset": 1002
      }
    }
  ],
  "language": "en"
}

Natural Language API에 보내는 구문 분석 요청에는 토큰 모음도 포함됩니다. 각 토큰과 연관된 정보를 사용하여 반환된 문서에 대한 추가적인 분석을 수행할 수 있습니다. 이 토큰에 대한 자세한 내용은 형태론 및 종속성 트리 가이드에서 찾아볼 수 있습니다.

토큰화

analyzeSyntax 메서드는 텍스트를 일련의 토큰으로 바꾸기도 합니다. 토큰은 전달된 콘텐츠의 서로 다른 텍스트 요소(단어 구분)에 해당합니다. Natural Language API가 이 토큰 모음을 전개하는 과정을 토큰화라고 합니다.

Natural Language API는 추출된 토큰을 처리하여 연관된 연설 부분(형태 정보 포함) 및 단어 기본형을 파악합니다. 또한 토큰은 평가를 받은 후에 종속성 트리 안에 배치됩니다. 종속성 트리는 토큰의 구문적 의미를 파악하고 토큰 간의 관계 및 포함하는 문장을 표시할 수 있게 해줍니다. 이 토큰과 연관된 구문 및 형태 정보는 Natural Language API 내에서 문장의 구문 구조를 이해하는 데 유용합니다.

구문 분석 JSON 응답에서 반환되는 토큰 필드 모음이 아래에 나와 있습니다.

  • text는 이 토큰과 연관된 텍스트 데이터를 다음의 하위 필드와 함께 포함하고 있습니다.

    • beginOffset은 제공된 텍스트 내의 문장 오프셋(0부터 시작)을 포함합니다. 종속성(아래에 설명됨)은 문장 내에서만 존재하지만 토큰 오프셋은 텍스트에 통째로 배치될 수 있습니다. 이 오프셋은 전달된 encodingType을 사용하여 계산됩니다.
    • content는 원래 텍스트의 실제 텍스트 콘텐츠를 포함합니다.
  • partOfSpeech는 토큰의 시제, 인칭, 단수/복수, 성별 등 토큰에 대한 형태론적 정보를 비롯한 문법 정보를 제공합니다. 이 필드에 대한 자세한 내용은 형태론 및 종속성 트리 가이드를 참조하세요.

  • lemma는 텍스트 내에서 단어 용법을 변형하여 사용할 수 있도록 단어의 뿌리가 되는 '기본형' 단어를 포함합니다. 예를 들어 'write', 'writing', 'wrote', 'written'은 모두 'write'라는 기본형을 바탕으로 합니다. 그리고 단수형 및 복수형도 기본형을 바탕으로 합니다. 'house'와 'houses'는 같은 기본형을 참조합니다. (기본형(형태론)을 참조하세요.)

  • dependencyEdge 필드는 방향 트리의 가장자리를 통해 토큰의 포함 문장에서 단어 간 관계를 식별합니다. 번역, 정보 추출, 요약 시 이 정보는 매우 유용할 수 있습니다. 종속성 구문 분석에 대한 자세한 내용은 형태론 및 종속성 트리 가이드에 나와 있습니다. 각 dependencyEdge 필드에는 다음의 하위 필드가 포함됩니다.

    • headTokenIndex는 토큰의 요약 문장 내에서 이 토큰의 '상위 토큰'에 대한 색인 값(0부터 시작)을 제공합니다. 이것은 상위 색인이 없는 토큰입니다.
    • label은 헤드 토큰에 대한 이 토큰의 종속성 유형을 제공합니다.

프랭클린 D. 루스벨트의 취임 연설에서 발췌한 인용문은 다음과 같은 토큰을 생성합니다.

참고: 명료성을 위해 *_UNKNOWN 값이 포함된 partOfSpeech 태그는 모두 삭제되었습니다.

 "tokens": [
    {
      "text": {
        "content": "The",
        "beginOffset": 4
      },
      "partOfSpeech": {
        "tag": "DET",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "DET"
      },
      "lemma": "The"
    },
    {
      "text": {
        "content": "only",
        "beginOffset": 8
      },
      "partOfSpeech": {
        "tag": "ADJ",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "AMOD"
      },
      "lemma": "only"
    },
    {
      "text": {
        "content": "thing",
        "beginOffset": 13
      },
      "partOfSpeech": {
        "tag": "NOUN",
        "number": "SINGULAR",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "NSUBJ"
      },
      "lemma": "thing"
    },
    {
      "text": {
        "content": "we",
        "beginOffset": 19
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "NOMINATIVE",
        "number": "PLURAL",
        "person": "FIRST",
      },
      "dependencyEdge": {
        "headTokenIndex": 4,
        "label": "NSUBJ"
      },
      "lemma": "we"
    },
    {
      "text": {
        "content": "have",
        "beginOffset": 22
      },
      "partOfSpeech": {
        "tag": "VERB",
        "mood": "INDICATIVE",
        "tense": "PRESENT",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "RCMOD"
      },
      "lemma": "have"
    },
    {
      "text": {
        "content": "to",
        "beginOffset": 27
      },
      "partOfSpeech": {
        "tag": "PRT",
      },
      "dependencyEdge": {
        "headTokenIndex": 6,
        "label": "AUX"
      },
      "lemma": "to"
    },
    {
      "text": {
        "content": "fear",
        "beginOffset": 30
      },
      "partOfSpeech": {
        "tag": "VERB",
      },
      "dependencyEdge": {
        "headTokenIndex": 4,
        "label": "XCOMP"
      },
      "lemma": "fear"
    },
    {
      "text": {
        "content": "is",
        "beginOffset": 35
      },
      "partOfSpeech": {
        "tag": "VERB",
        "mood": "INDICATIVE",
        "number": "SINGULAR",
        "person": "THIRD",
        "tense": "PRESENT",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "ROOT"
      },
      "lemma": "be"
    },
    {
      "text": {
        "content": "fear",
        "beginOffset": 38
      },
      "partOfSpeech": {
        "tag": "NOUN",
        "number": "SINGULAR",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "ATTR"
      },
      "lemma": "fear"
    },
    {
      "text": {
        "content": "itself",
        "beginOffset": 43
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "ACCUSATIVE",
        "gender": "NEUTER",
        "number": "SINGULAR",
        "person": "THIRD",
      },
      "dependencyEdge": {
        "headTokenIndex": 8,
        "label": "NN"
      },
      "lemma": "itself"
    },
    {
      "text": {
        "content": ".",
        "beginOffset": 49
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "ACCUSATIVE",
        "gender": "NEUTER",
        "number": "SINGULAR",
        "person": "THIRD",
      },
      "dependencyEdge": {
        "headTokenIndex": 8,
        "label": "NN"
      },
      "lemma": "itself"
    },
    {
      "text": {
        "content": ".",
        "beginOffset": 49
      },
      "partOfSpeech": {
        "tag": "PUNCT",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "P"
      },
      "lemma": "."
    }
  ],

콘텐츠 분류

Natural Language가 문서를 분석하고 문서에서 찾은 텍스트에 적용되는 컨텐츠 카테고리 목록을 리턴하도록 할 수 있습니다. 문서에서 콘텐츠를 분류하려면 classifyText 메서드를 호출하세요.

classifyText 메서드에 대해 반환되는 콘텐츠 카테고리의 전체 목록은 여기에서 찾아볼 수 있습니다.

Natural Language는 요청에 가장 관련성이 높은 카테고리만 포함하도록 classifyText 메소드가 리턴한 카테고리를 필터링합니다. 예를 들어 /Science/Science/Astronomy가 문서에 모두 적용되는 경우에는 더 구체적인 결과인 /Science/Astronomy 카테고리만 반환됩니다.

Natural Language를 사용한 콘텐츠 분류의 예시는 콘텐츠 분류를 참조하세요.

단일 요청에서 여러 작업 수행

단일 메소드 호출 내에서 Natural Language 조작 세트를 수행하려는 경우 annotateText을 범용Natural Language API 요청으로 사용할 수 있습니다. 텍스트 주석 JSON 요청은 표준 항목 분석 요청과 비슷하지만, 텍스트에 수행할 수 있는 작업을 표시하기 위해 전달된 기능 모음이 추가로 필요할 수 있습니다. 기능은 아래에 나와 있습니다.

  • extractDocumentSentiment감정 분석 섹션에 설명된 대로 감정 분석을 수행합니다.
  • extractEntities항목 분석 섹션에 설명된 대로 항목 분석을 수행합니다.
  • extractSyntax구문 분석 섹션에 설명된 대로 주어진 텍스트를 처리하여 구문 분석을 수행해야 한다는 것을 나타냅니다.

다음 요청은 API를 호출하여 짧은 문장에 features 주석을 답니다.

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"The windy, cold weather was unbearable this winter."
  },
  "features":{
    "extractSyntax":true,
    "extractEntities":true,
    "extractDocumentSentiment":true
  },
  "encodingType":"UTF8"
}