ניתוח ישויות

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

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

ניתוח ישויות במחרוזת

הנה דוגמה לניתוח ישויות במחרוזת טקסט שנשלחה ישירות אל Natural Language API:

פרוטוקול

כדי לנתח ישויות במסמך, שולחים בקשת POST אל ה-method‏ documents:analyzeEntities של REST ומספקים את תוכן הבקשה המתאים, כפי שמוצג בדוגמה הבאה.

בדוגמה נעשה שימוש בפקודה gcloud auth application-default print-access-token כדי לקבל אסימון גישה לחשבון שירות שהוגדר לפרויקט באמצעות CLI של gcloud ב-Google Cloud Platform. הוראות להתקנת ה-CLI של gcloud ולהגדרת פרויקט עם חשבון שירות מופיעות במדריך למתחילים.

curl -X POST \
     -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
  'encodingType': 'UTF8',
  'document': {
    'type': 'PLAIN_TEXT',
    'content': 'President Trump will speak from the White House, located
  at 1600 Pennsylvania Ave NW, Washington, DC, on October 7.'
  }
}" "https://language.googleapis.com/v2/documents:analyzeEntities"

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

אם הבקשה מצליחה, השרת מחזיר קוד סטטוס 200 OK של HTTP ואת התשובה בפורמט JSON:

{
  "entities": [
    {
      "name": "October 7",
      "type": "DATE",
      "metadata": {
        "month": "10",
        "day": "7"
      },
      "mentions": [
        {
          "text": {
            "content": "October 7",
            "beginOffset": -1
          },
          "type": "TYPE_UNKNOWN",
          "probability": 1
        }
      ]
    },
    {
      "name": "1600",
      "type": "NUMBER",
      "metadata": {
        "value": "1600"
      },
      "mentions": [
        {
          "text": {
            "content": "1600",
            "beginOffset": -1
          },
          "type": "TYPE_UNKNOWN",
          "probability": 1
        }
      ]
    },
    {
      "name": "7",
      "type": "NUMBER",
      "metadata": {
        "value": "7"
      },
      "mentions": [
        {
          "text": {
            "content": "7",
            "beginOffset": -1
          },
          "type": "TYPE_UNKNOWN",
          "probability": 1
        }
      ]
    },
    {
      "name": "1600 Pennsylvania Ave NW, Washington, DC",
      "type": "ADDRESS",
      "metadata": {
        "locality": "Washington",
        "narrow_region": "District of Columbia",
        "street_name": "Pennsylvania Avenue Northwest",
        "street_number": "1600",
        "broad_region": "District of Columbia",
        "country": "US"
      },
      "mentions": [
        {
          "text": {
            "content": "1600 Pennsylvania Ave NW, Washington, DC",
            "beginOffset": -1
          },
          "type": "TYPE_UNKNOWN",
          "probability": 1
        }
      ]
    },
    {
      "name": "1600 Pennsylvania Ave NW",
      "type": "LOCATION",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "1600 Pennsylvania Ave NW",
            "beginOffset": -1
          },
          "type": "PROPER",
          "probability": 0.901
        }
      ]
    },
    {
      "name": "President",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "President",
            "beginOffset": -1
          },
          "type": "COMMON",
          "probability": 0.941
        }
      ]
    },
    {
      "name": "Trump",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Trump",
            "beginOffset": -1
          },
          "type": "PROPER",
          "probability": 0.948
        }
      ]
    },
    {
      "name": "Washington, DC",
      "type": "LOCATION",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Washington, DC",
            "beginOffset": -1
          },
          "type": "PROPER",
          "probability": 0.92
        }
      ]
    },
    {
      "name": "White House",
      "type": "LOCATION",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "White House",
            "beginOffset": -1
          },
          "type": "PROPER",
          "probability": 0.785
        }
      ]
    }
  ],
  "languageCode": "en",
  "languageSupported": true
}

מערך entities מכיל אובייקטים של Entity שמייצגים את הישויות שזוהו, כולל מידע כמו שם הישות והסוג שלה.

gcloud

פרטים נוספים זמינים בפקודה analyze-entities.

כדי לבצע ניתוח של ישויות, משתמשים ב-CLI של gcloud ובדגל --content כדי לציין את התוכן לניתוח:

gcloud ml language analyze-entities --content="President Trump will speak from the White House, located
  at 1600 Pennsylvania Ave NW, Washington, DC, on October 7."

אם הבקשה מצליחה, השרת מחזיר תגובה בפורמט JSON:

{
  "entities": [
    {
      "name": "Trump",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/0cqt90",
        "wikipedia_url": "https://en.wikipedia.org/wiki/Donald_Trump"
      },
      "salience": 0.7936003,
      "mentions": [
        {
          "text": {
            "content": "Trump",
            "beginOffset": 10
          },
          "type": "PROPER"
        },
        {
          "text": {
            "content": "President",
            "beginOffset": 0
          },
          "type": "COMMON"
        }
      ]
    },
    {
      "name": "White House",
      "type": "LOCATION",
      "metadata": {
        "mid": "/m/081sq",
        "wikipedia_url": "https://en.wikipedia.org/wiki/White_House"
      },
      "salience": 0.09172433,
      "mentions": [
        {
          "text": {
            "content": "White House",
            "beginOffset": 36
          },
          "type": "PROPER"
        }
      ]
    },
    {
      "name": "Pennsylvania Ave NW",
      "type": "LOCATION",
      "metadata": {
        "mid": "/g/1tgb87cq"
      },
      "salience": 0.085507184,
      "mentions": [
        {
          "text": {
            "content": "Pennsylvania Ave NW",
            "beginOffset": 65
          },
          "type": "PROPER"
        }
      ]
    },
    {
      "name": "Washington, DC",
      "type": "LOCATION",
      "metadata": {
        "mid": "/m/0rh6k",
        "wikipedia_url": "https://en.wikipedia.org/wiki/Washington,_D.C."
      },
      "salience": 0.029168168,
      "mentions": [
        {
          "text": {
            "content": "Washington, DC",
            "beginOffset": 86
          },
          "type": "PROPER"
        }
      ]
    }
    {
      "name": "1600 Pennsylvania Ave NW, Washington, DC",
      "type": "ADDRESS",
      "metadata": {
        "country": "US",
        "sublocality": "Fort Lesley J. McNair",
        "locality": "Washington",
        "street_name": "Pennsylvania Avenue Northwest",
        "broad_region": "District of Columbia",
        "narrow_region": "District of Columbia",
        "street_number": "1600"
      },
      "salience": 0,
      "mentions": [
        {
          "text": {
            "content": "1600 Pennsylvania Ave NW, Washington, DC",
            "beginOffset": 60
          },
          "type": "TYPE_UNKNOWN"
        }
      ]
      }
    }
    {
      "name": "1600",
       "type": "NUMBER",
       "metadata": {
           "value": "1600"
       },
       "salience": 0,
       "mentions": [
         {
          "text": {
              "content": "1600",
              "beginOffset": 60
           },
           "type": "TYPE_UNKNOWN"
        }
     ]
     },
     {
       "name": "October 7",
       "type": "DATE",
       "metadata": {
         "day": "7",
         "month": "10"
       },
       "salience": 0,
       "mentions": [
         {
           "text": {
             "content": "October 7",
             "beginOffset": 105
            },
           "type": "TYPE_UNKNOWN"
         }
       ]
     }
     {
       "name": "7",
       "type": "NUMBER",
       "metadata": {
         "value": "7"
       },
       "salience": 0,
       "mentions": [
         {
           "text": {
             "content": "7",
             "beginOffset": 113
           },
         "type": "TYPE_UNKNOWN"
         }
        ]
     }
  ],
  "language": "en"
}

מערך entities מכיל אובייקטים של Entity שמייצגים את הישויות שזוהו, כולל מידע כמו שם הישות והסוג שלה.

Go

מידע על התקנת ספריית הלקוח של Natural Language ושימוש בה מופיע במאמר ספריות הלקוח של Natural Language. מידע נוסף מופיע במאמרי העזרה של Natural Language Go API.

כדי לבצע אימות ב-Natural Language, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

import (
	"context"
	"fmt"
	"io"

	language "cloud.google.com/go/language/apiv2"
	"cloud.google.com/go/language/apiv2/languagepb"
)

// analyzeEntities sends a string of text to the Cloud Natural Language API to
// detect the entities of the text.
func analyzeEntities(w io.Writer, text string) error {
	ctx := context.Background()

	// Initialize client.
	client, err := language.NewClient(ctx)
	if err != nil {
		return err
	}
	defer client.Close()

	resp, err := client.AnalyzeEntities(ctx, &languagepb.AnalyzeEntitiesRequest{
		Document: &languagepb.Document{
			Source: &languagepb.Document_Content{
				Content: text,
			},
			Type: languagepb.Document_PLAIN_TEXT,
		},
		EncodingType: languagepb.EncodingType_UTF8,
	})

	if err != nil {
		return fmt.Errorf("AnalyzeEntities: %w", err)
	}
	fmt.Fprintf(w, "Response: %q\n", resp)

	return nil
}

Java

מידע על התקנת ספריית הלקוח של Natural Language ושימוש בה מופיע במאמר ספריות הלקוח של Natural Language. מידע נוסף מופיע במאמרי העזרה של Natural Language Java API.

// Instantiate the Language client com.google.cloud.language.v2.LanguageServiceClient
try (LanguageServiceClient language = LanguageServiceClient.create()) {
  Document doc = Document.newBuilder().setContent(text).setType(Type.PLAIN_TEXT).build();
  AnalyzeEntitiesRequest request =
      AnalyzeEntitiesRequest.newBuilder()
          .setDocument(doc)
          .setEncodingType(EncodingType.UTF16)
          .build();

  AnalyzeEntitiesResponse response = language.analyzeEntities(request);

  // Print the response
  for (Entity entity : response.getEntitiesList()) {
    System.out.printf("Entity: %s", entity.getName());
    System.out.println("Metadata: ");
    for (Map.Entry<String, String> entry : entity.getMetadataMap().entrySet()) {
      System.out.printf("%s : %s", entry.getKey(), entry.getValue());
    }
    for (EntityMention mention : entity.getMentionsList()) {
      System.out.printf("Begin offset: %d\n", mention.getText().getBeginOffset());
      System.out.printf("Content: %s\n", mention.getText().getContent());
      System.out.printf("Type: %s\n\n", mention.getType());
      System.out.printf("Probability: %s\n\n", mention.getProbability());
    }
  }
}

Node.js

מידע על התקנת ספריית הלקוח של Natural Language ושימוש בה מופיע במאמר ספריות הלקוח של Natural Language. מידע נוסף מופיע במאמרי העזרה של Natural Language Node.js API.

// Imports the Google Cloud client library
const language = require('@google-cloud/language').v2;

// Creates a client
const client = new language.LanguageServiceClient();

/**
 * TODO(developer): Uncomment the following line to run this code.
 */
// const text = 'Your text to analyze, e.g. Hello, world!';

// Prepares a document, representing the provided text
const document = {
  content: text,
  type: 'PLAIN_TEXT',
};

// Detects entities in the document
const [result] = await client.analyzeEntities({document});

const entities = result.entities;

console.log('Entities:');
entities.forEach(entity => {
  console.log(entity.name);
  console.log(` - Type: ${entity.type}`);
  if (entity.metadata) {
    console.log(` - Metadata: ${entity.metadata}`);
  }
});

Python

מידע על התקנת ספריית הלקוח של Natural Language ושימוש בה מופיע במאמר ספריות הלקוח של Natural Language. מידע נוסף מופיע במאמרי העזרה של Natural Language Python API.

from google.cloud import language_v2


def sample_analyze_entities(text_content: str = "California is a state.") -> None:
    """
    Analyzes Entities in a string.

    Args:
      text_content: The text content to analyze
    """

    client = language_v2.LanguageServiceClient()

    # Available types: PLAIN_TEXT, HTML
    document_type_in_plain_text = language_v2.Document.Type.PLAIN_TEXT

    # Optional. If not specified, the language is automatically detected.
    # For list of supported languages:
    # https://cloud.google.com/natural-language/docs/languages
    language_code = "en"
    document = {
        "content": text_content,
        "type_": document_type_in_plain_text,
        "language_code": language_code,
    }

    # Available values: NONE, UTF8, UTF16, UTF32.
    # See https://cloud.google.com/natural-language/docs/reference/rest/v2/EncodingType.
    encoding_type = language_v2.EncodingType.UTF8

    response = client.analyze_entities(
        request={"document": document, "encoding_type": encoding_type}
    )

    for entity in response.entities:
        print(f"Representative name for the entity: {entity.name}")

        # Get entity type, e.g. PERSON, LOCATION, ADDRESS, NUMBER, et al.
        # See https://cloud.google.com/natural-language/docs/reference/rest/v2/Entity#type.
        print(f"Entity type: {language_v2.Entity.Type(entity.type_).name}")

        # Loop over the metadata associated with entity.
        # Some entity types may have additional metadata, e.g. ADDRESS entities
        # may have metadata for the address street_name, postal_code, et al.
        for metadata_name, metadata_value in entity.metadata.items():
            print(f"{metadata_name}: {metadata_value}")

        # Loop over the mentions of this entity in the input document.
        # The API currently supports proper noun mentions.
        for mention in entity.mentions:
            print(f"Mention text: {mention.text.content}")

            # Get the mention type, e.g. PROPER for proper noun
            print(f"Mention type: {language_v2.EntityMention.Type(mention.type_).name}")

            # Get the probability score associated with the first mention of the entity in the (0, 1.0] range.
            print(f"Probability score: {mention.probability}")

    # Get the language of the text, which will be the same as
    # the language specified in the request or, if not specified,
    # the automatically-detected language.
    print(f"Language of the text: {response.language_code}")

שפות נוספות

‫C#‎: פועלים לפי הוראות ההגדרה של C# ‎ בדף של ספריות הלקוח, ואז עוברים אל מאמרי העזרה בנושא Natural Language ל-‎ .NET.

‫PHP: פועלים לפי הוראות ההגדרה של PHP בדף של ספריות הלקוח ואז עוברים אל מסמכי העזר של Natural Language ל-PHP.

‫Ruby: צריך לפעול לפי הוראות ההגדרה של Ruby בדף של ספריות הלקוח ואז לעיין במאמרי העזרה בנושא שפה טבעית ל-Ruby.