היסודות של Natural Language API

במסמך הזה מוסבר איך משתמשים ב-Cloud Natural Language API. במדריך הזה מוסבר על סוגי הבקשות שאפשר לשלוח אל Natural Language API, איך ליצור את הבקשות האלה ואיך לטפל בתשובות שמתקבלות. מומלץ שכל המשתמשים ב-Natural Language API יקראו את המדריך הזה ואחד מהמדריכים שקשורים אליו לפני שמתחילים להשתמש ב-API עצמו.

תכונות של שפה טבעית

ל-Natural Language API יש כמה שיטות לביצוע ניתוח והוספת הערות לטקסט. כל רמת ניתוח מספקת מידע חשוב להבנת השפה. השיטות האלה מפורטות בהמשך:

ניתוח סנטימנטים בודק את הטקסט שצוין ומזהה את הדעה הרגשית הרווחת בטקסט, במיוחד כדי לקבוע את הגישה של הכותב כחיובית, שלילית או ניטרלית. ניתוח הסנטימנטים מתבצע באמצעות שיטת analyzeSentiment.
ניתוח ישויות בודק את הטקסט שצוין כדי למצוא ישויות מוכרות (שמות עצם כמו דמויות ציבוריות, ציוני דרך וכו'). שמות עצם כלליים כמו מסעדה, אצטדיון וכו') ומחזירה מידע על הישויות האלה. ניתוח הישויות מתבצע באמצעות השיטה analyzeEntities.
ניתוח סנטימנטים של ישויות בודק את הטקסט הנתון כדי למצוא ישויות מוכרות (שמות עצם פרטיים ושמות עצם כלליים), מחזיר מידע על הישויות האלה ומזהה את הדעה הרגשית הרווחת לגבי הישות בטקסט, במיוחד כדי לקבוע אם היחס של הכותב לישות הוא חיובי, שלילי או ניטרלי. ניתוח הישויות מתבצע באמצעות השיטה analyzeEntitySentiment.
ניתוח תחבירי מחלץ מידע לשוני, מפרק את הטקסט הנתון לסדרה של משפטים וטוקנים (בדרך כלל, גבולות מילים), ומספק ניתוח נוסף של הטוקנים האלה. ניתוח תחבירי מתבצע באמצעות השיטה analyzeSyntax.
סיווג תוכן מנתח תוכן טקסט ומחזיר קטגוריית תוכן עבור התוכן. סיווג התוכן מתבצע באמצעות השיטה classifyText.

כל קריאה ל-API גם מזהה ומחזירה את השפה, אם המשתמש לא ציין שפה בבקשה הראשונית.

בנוסף, אם רוצים לבצע כמה פעולות של שפה טבעית על טקסט מסוים באמצעות קריאה אחת בלבד ל-API, אפשר להשתמש בבקשת annotateText גם כדי לבצע ניתוח סנטימנטים וניתוח ישויות.

נסו בעצמכם

אנחנו ממליצים למשתמשים חדשים ב-Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של Natural Language בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300 $להרצה, לבדיקה ולפריסה של עומסי העבודה.

לניסיון חינם של Natural Language

בקשות בסיסיות בשפה טבעית

‫Natural Language API הוא API בארכיטקטורת REST, והוא מורכב מבקשות ותגובות בפורמט JSON. בקשה פשוטה לניתוח ישויות ב-JSON בשפה טבעית מוצגת בהמשך:

{
  "document":{
    "type":"PLAIN_TEXT",
    "language_code": "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 API זמין במאמר שפות נתמכות. שפות לא נתמכות יחזירו שגיאה בתגובת ה-JSON.
- הטקסט שצריך להעריך, או content או gcsContentUri שמכילים את הטקסט. אם מעבירים את הערך content, הטקסט הזה נכלל ישירות בבקשת ה-JSON (כפי שמוצג למעלה). אם הערך הוא gcsContentUri, השדה חייב להכיל URI שמפנה לתוכן טקסט ב-Google Cloud Storage.
‫encodingType – (חובה) סכמת הקידוד שבה צריך לחשב את ההיסטים של התווים שמוחזרים בטקסט, שצריכה להיות זהה לקידוד של הטקסט שמועבר. אם לא מגדירים את הפרמטר הזה, לא תהיה שגיאה בבקשה, אבל כל ההיסטים האלה יוגדרו ל--1.

ציון תוכן טקסטואלי

כשמעבירים בקשת API ל-Natural Language API, מציינים את הטקסט לעיבוד באחת משתי דרכים:

העברת הטקסט ישירות בשדה content.
העברת URI של Cloud Storage בשדה gcsContentUri.

בכל מקרה, חשוב לוודא שלא חורגים מהמגבלות שמפורטות במגבלות התוכן. שימו לב שמגבלות התוכן האלה הן לפי בייט ולא לפי תו. לכן, אורך התווים תלוי בקידוד הטקסט.

הבקשה שמופיעה בהמשך מתייחסת לקובץ ב-Google Cloud Storage שמכיל את הנאום בגטיסברג:

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

ניתוח סנטימנטים

ניתוח סנטימנט מנסה לקבוע את הגישה הכללית (חיובית או שלילית) שמופיעה בטקסט. הסנטימנט מיוצג על ידי ערכים מספריים score ו-magnitude.

שדות התשובה של ניתוח הסנטימנטים

בדוגמה הבאה מוצגת תגובה ל'נאום גטיסברג':analyzeSentiment

{
  "documentSentiment": {
    "score": 0.2,
    "magnitude": 3.6
  },
  "language_code": "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 לא עובר נרמול עבור documentSentiment. כל ביטוי של רגש בטקסט (חיובי ושלילי) תורם ל-magnitude של הטקסט (לכן, לבלוקים ארוכים יותר של טקסט עשויים להיות ערכים גדולים יותר).
‫language_code מכיל את שפת המסמך, שהועברה בבקשה הראשונית או זוהתה באופן אוטומטי אם היא לא צוינה.
language_supported מכיל ערך בוליאני שמציין אם השפה נתמכת באופן רשמי
‫sentences מכיל רשימה של המשפטים שחולצו מהמסמך המקורי, שכולל:
- המאפיין sentiment מכיל את הערכים של הסנטימנט ברמת המשפט שמצורפים לכל משפט, שמכילים את הערך score בין -1.0 (שלילי) לבין 1.0 (חיובי) ואת הערכים magnitude בין 0.0 לבין 1.0. הערה: הערך של magnitude עבור sentences הוא מנורמל.

ערך הסנטימנט 0.2 של נאום גטיסברג מציין שהרגש שבו הוא מעט חיובי, ואילו ערך העוצמה 3.6 מציין שמדובר במסמך רגשי יחסית, בהתחשב בגודל הקטן שלו (בערך פסקה אחת). שימו לב שהמשפט הראשון של הנאום בגטיסבורג מכיל score חיובי מאוד של 0.8.

פירוש הערכים של ניתוח הסנטימנטים

הציון של סנטימנט במסמך מציין את הרגש הכללי במסמך. העוצמה של הסנטימנט במסמך מציינת את כמות התוכן הרגשי במסמך, והערך הזה לרוב פרופורציונלי לאורך המסמך.

חשוב לציין ש-Natural Language API מציין הבדלים בין רגשות חיוביים ושליליים במסמך, אבל לא מזהה רגשות חיוביים ושליליים ספציפיים. לדוגמה, 'כועס' ו'עצוב' נחשבים שניהם לרגשות שליליים. עם זאת, כש-Natural Language API מנתח טקסט שנחשב ל "כועס" או ל "עצוב", התגובה מציינת רק שהסנטימנט בטקסט הוא שלילי, ולא "עצוב" או "כועס".

מסמך עם ציון ניטרלי (סביב 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, כדי שאפשר יהיה לפרש את ההיסטים שמוחזרים בצורה נכונה.

שדות בתשובה של ניתוח ישויות

ניתוח הישויות מחזיר קבוצה של ישויות שזוהו ופרמטרים שמשויכים לישויות האלה, כמו סוג הישות, הרלוונטיות של הישות לטקסט הכולל והמיקומים בטקסט שמתייחסים לאותה ישות.

בהמשך מוצגת analyzeEntities תשובה לבקשת הישות:

{
  "entities": [
    {
      "name": "British",
      "type": "LOCATION",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "British",
            "beginOffset": 58
          },
          "type": "PROPER",
          "probability": 0.941
        }
      ]
    },
    {
      "name": "Lawrence",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lawrence",
            "beginOffset": 113
          },
          "type": "PROPER",
          "probability": 0.914
        }
      ]
    },
    {
      "name": "Lawrence of Arabia",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lawrence of Arabia",
            "beginOffset": 0
          },
          "type": "PROPER",
          "probability": 0.761
        }
      ]
    },
    {
      "name": "Lieutenant",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lieutenant",
            "beginOffset": 66
          },
          "type": "COMMON",
          "probability": 0.927
        }
      ]
    },
    {
      "name": "Peter O Toole",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Peter O Toole",
            "beginOffset": 93
          },
          "type": "PROPER",
          "probability": 0.907
        }
      ]
    },
    {
      "name": "T. E. Lawrence",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "T. E. Lawrence",
            "beginOffset": 77
          },
          "type": "PROPER",
          "probability": 0.853
        }
      ]
    },
    {
      "name": "film",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "film",
            "beginOffset": 129
          },
          "type": "COMMON",
          "probability": 0.805
        }
      ]
    },
    {
      "name": "film biography",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "film biography",
            "beginOffset": 37
          },
          "type": "COMMON",
          "probability": 0.876
        }
      ]
    }
  ],
  "languageCode": "en",
  "languageSupported": true
}

שימו לב: Natural Language API מחזירה ישויות עבור 'Lawrence of Arabia' (הסרט) ו-'T.E. Lawrence' (האדם). ניתוח ישויות שימושי כדי להבחין בין ישויות דומות, כמו 'לורנס' במקרה הזה.

השדות שמשמשים לאחסון הפרמטרים של הישות מפורטים בהמשך:

‫type מציין את סוג הישות (לדוגמה, אם הישות היא אדם, מיקום, מוצר צריכה וכו') המידע הזה עוזר להבחין בין ישויות ו/או להסיר דו-משמעות, ואפשר להשתמש בו כדי לכתוב תבניות או לחלץ מידע. לדוגמה, ערך type יכול לעזור להבחין בין ישויות עם שמות דומים, כמו 'לורנס איש ערב', שתויג כWORK_OF_ART (סרט), לבין 'תומאס אדוארד לורנס', שתויג כPERSON. (מידע נוסף זמין במאמר סוגי ישויות).
‫metadata מכיל מידע על המקורות של מאגר הידע של הישות. יכול להיות שבעתיד ייחשפו מאגרים נוספים.
‫mentions מציינים את מיקומי ההיסט בטקסט שבהם מוזכרת ישות. המידע הזה יכול להיות שימושי אם רוצים למצוא את כל האזכורים של האדם 'לורנס' בטקסט, אבל לא את שם הסרט. אפשר גם להשתמש בתיוגים כדי לאסוף את רשימת הכינויים של ישות, כמו 'לורנס', שמתייחסים לאותה ישות 'ט.א. לורנס'. תיוג של ישות יכול להיות אחד משני סוגים: PROPER או COMMON. ישות של שם עצם כמו 'לורנס איש ערב' יכולה להיות מוזכרת ישירות כשם הסרט, או כשם עצם כללי ('ביוגרפיה קולנועית' של ת.א. לורנס).

ניתוח סנטימנטים של ישויות

ניתוח סנטימנטים של ישויות משלב בין ניתוח ישויות לניתוח סנטימנטים, ומנסה לקבוע את הסנטימנט (חיובי או שלילי) שמופיע לגבי ישויות בטקסט. הסנטימנט של ישות מיוצג על ידי ערכים מספריים של ציון ועוצמה, והוא נקבע לכל אזכור של ישות. הציונים האלה מצטברים לציון כולל של הסנטימנט ולגודל של ישות.

בקשות לניתוח סנטימנטים של ישויות

בקשות לניתוח סנטימנט של ישויות נשלחות אל Natural Language API באמצעות השיטה analyzeEntitySentiment בפורמט הבא:

{
  "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"
}

אפשר לציין פרמטר אופציונלי language בבקשה כדי לזהות את קוד השפה של הטקסט בפרמטר content. אם לא מציינים פרמטר language, Natural Language API מזהה אוטומטית את השפה של תוכן הבקשה. מידע על השפות שנתמכות ב-Natural Language API זמין במאמר תמיכה בשפות.

תשובות לניתוח סנטימנטים של ישויות

‫Natural Language API מעבד את הטקסט שצוין כדי לחלץ את הישויות ולקבוע את הסנטימנט. בקשה לניתוח סנטימנט של ישות מחזירה תגובה שמכילה את entities שנמצאו בתוכן המסמך, רשומה של mentions בכל פעם שהישות מוזכרת, וערכים מספריים של score ו-magnitude לכל אזכור, כפי שמתואר במאמר הסבר על ערכי ניתוח סנטימנט. הערכים הכוללים של score ושל magnitude עבור ישות הם סכום הערכים הספציפיים של score ושל magnitude לכל אזכור של הישות. הערכים score ו-magnitude של ישות יכולים להיות 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 מעבד את הטוקנים ומוסיף להם מידע תחבירי על סמך המיקום שלהם במשפטים.

תיעוד מלא של קבוצת האסימונים התחביריים מופיע במדריך Morphology & Dependency Trees.

בקשות לניתוח תחבירי

בקשות לניתוח תחבירי נשלחות אל Natural Language API באמצעות שיטת analyzeSyntax בפורמט הבא:

{
  "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 מעבד את הטקסט שצוין כדי לחלץ משפטים וטוקנים. בקשה לניתוח תחבירי מחזירה תגובה שמכילה את sentences וtokens בפורמט הבא:

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

חילוץ משפטים

כשמבצעים ניתוח תחבירי, Natural Language API מחזיר מערך של משפטים שחולצו מהטקסט שסופק, כאשר כל משפט מכיל את השדות הבאים בתוך רכיב text:

beginOffset שמציין את ההיסט (מבוסס-אפס) של התו בטקסט הנתון שבו מתחיל המשפט. הערה: ההיסט הזה מחושב לפי 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 מכיל את ההיסט (מבוסס-אפס) של התו בטקסט שסופק. שימו לב שלמרות שהתלויות (שמתוארות בהמשך) קיימות רק בתוך משפטים, ההיסטים של הטוקנים ממוקמים בטקסט כשלם. שימו לב שההיסט הזה מחושב באמצעות הערך שהועבר encodingType.
- ‫content מכיל את תוכן הטקסט בפועל מהטקסט המקורי.
‫partOfSpeech מספק מידע דקדוקי, כולל מידע מורפולוגי, על הטוקן, כמו הזמן, הגוף, המספר, המין וכו' של הטוקן. (מידע מלא יותר על השדות האלה זמין במדריך עצי תלות ומורפולוגיה).
‫lemma מכיל את מילת הבסיס שעליה מבוססת המילה הזו, וכך אפשר להשתמש במילה באופן קנוני בטקסט. לדוגמה, המילים "write",‏ "writing",‏ "wrote" ו-"written" מבוססות על אותה למה (lemma) –‏ "write". בנוסף, צורות יחיד ורבים מבוססות על לֶמות (lemmas): גם house וגם houses מתייחסות לאותה צורה. (ראו למה (מורפולוגיה)).
שדות dependencyEdge מזהים את הקשר בין מילים במשפט שמכיל טוקן באמצעות קשתות בעץ מכוון. המידע הזה יכול להיות שימושי לתרגום, לחילוץ מידע ולסיכום. (במדריך Morphology & Dependency Trees יש מידע מפורט יותר על ניתוח תלות). כל שדה dependencyEdge מכיל את שדות הצאצא הבאים:
- ‫headTokenIndex מספק את ערך האינדקס (החל מ-0) של 'אסימון האב' של האסימון הזה בתוך המשפט שמכיל את האסימון. טוקן ללא הורה מאנדקס את עצמו.
- ‫label מציין את סוג התלות של האסימון הזה באסימון הראשי שלו.

הציטוט הבא הוא מתוך Franklin D. הטקסט Roosevelt's Inaugural speech ייצור את האסימונים הבאים:

הערה: כל התגים partOfSpeech שמכילים ערכים של *_UNKNOWN הוסרו לשם הבהרה.

 "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 API כדי לנתח מסמך ולקבל רשימה של קטגוריות תוכן שרלוונטיות לטקסט שנמצא במסמך. כדי לסווג את התוכן במסמך, קוראים לשיטה classifyText.

כאן אפשר למצוא רשימה מלאה של קטגוריות התוכן שמוחזרות עבור השיטה classifyText.

ה-Natural Language API מסנן את הקטגוריות שמוחזרות על ידי השיטה classifyText כדי לכלול רק את הקטגוריות הרלוונטיות ביותר לבקשה. לדוגמה, אם גם /Science וגם /Science/Astronomy חלים על מסמך, רק הקטגוריה /Science/Astronomy מוחזרת, כי היא התוצאה הספציפית יותר.

דוגמה לסיווג תוכן באמצעות Natural Language API מופיעה במאמר בנושא סיווג תוכן.

ביצוע כמה פעולות בבקשה אחת

אם רוצים לבצע קבוצה של פעולות בשפה טבעית בתוך הפעלת method אחת, אפשר להשתמש ב-annotateText כבקשת 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"
}