Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

היסודות של 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.
העברת Google Cloud Storage URI בשדה 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 כדי לכייל את הציונים, כי הם יכולים לעזור לכם להעריך את הכמות הרלוונטית של תוכן רגשי.

בתרשים הבא מוצגים כמה ערכים לדוגמה והסבר על המשמעות שלהם:

סנטימנט	ערכים לדוגמה
Clearly Positive*	`"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 מחזירה ישויות עבור 'לורנס איש ערב' (הסרט) ו'T.E. Lawrence' (האדם). ניתוח ישויות שימושי כדי להבחין בין ישויות דומות, כמו 'לורנס' במקרה הזה.

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

‫type מציין את סוג הישות הזו (לדוגמה, אם הישות היא אדם, מיקום, מוצר צריכה וכו'). המידע הזה עוזר להבחין בין ישויות ו/או להסיר דו-משמעות, ואפשר להשתמש בו כדי לכתוב תבניות או לחלץ מידע. לדוגמה, ערך type יכול לעזור להבחין בין ישויות עם שמות דומים, כמו 'לורנס איש ערב', שתויגה כWORK_OF_ART (סרט), לבין 'ת.א. לורנס', שתויגה כPERSON. (מידע נוסף זמין במאמר סוגי ישויות).
‫metadata מכיל מידע על מקורות הידע של הישות יכול להיות שבעתיד ייחשפו מאגרי מידע נוספים.
‫mentions מציינים את מיקומי ההיסט בטקסט שבהם מוזכרת ישות. המידע הזה יכול להיות שימושי אם רוצים למצוא את כל האזכורים של האדם 'לורנס' בטקסט, אבל לא את שם הסרט. אפשר גם להשתמש בתיוגים כדי לאסוף את רשימת הכינויים של ישויות, כמו 'לורנס', שמתייחסים לאותה ישות 'T.E. Lawrence'. תיוג של ישות יכול להיות אחד משני סוגים: 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 מעבד את הטוקנים ומוסיף להם מידע תחבירי על סמך המיקום שלהם במשפטים.

תיעוד מלא של קבוצת הטוקנים התחביריים מופיע במדריך עצי תלות ומורפולוגיה.

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

בקשות לניתוח תחבירי נשלחות אל 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 תכלול גם קבוצה של טוקנים. אפשר להשתמש במידע שמשויך לכל טוקן כדי לבצע ניתוח נוסף של המשפטים שמוחזרים. מידע נוסף על הטוקנים האלה זמין במדריך Morphology & Dependency Trees.

יצירת טוקנים

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

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

קבוצת שדות האסימון שמוחזרת בתגובת JSON של ניתוח תחבירי מופיעה בהמשך:

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

הציטוט הבא הוא של פרנקלין ד' הנאום של רוזוולט בהשבעה ייצור את האסימונים הבאים:

הערה: כל התגים 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"
}