本文档介绍了使用 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 API 基本请求
Natural Language API 是一个 REST API，由 JSON 请求和响应组成。下面显示一个简单的 Natural Language 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 中的文本内容。
- 编码类型 -（必填）计算返回的字符在文本中的偏移所采用的编码方案，必须与传递的文本的编码匹配。
如果未设置此参数，请求将不会出错，但所有这些偏移都将设置为
-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" }, }
情感分析
情感分析尝试确定文本中传达的整体态度（积极或消极）。情感由数值 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包含附加到每个句子的“句子级情感”值，其包含介于-1.0（消极）和1.0（积极）之间的score，以及介于0.0和1.0之间的magnitude值。请注意，sentences的magnitude会归一化。
葛底斯堡演说的情感值为 0.2，表示情绪略偏积极，而 magnitude 值为 3.6，表示该文档尽管篇幅较短（大约一段），但相对情绪饱满。请注意，葛底斯堡演说的第一句包含非常积极的 score，其值为 0.8。
解读情感分析值
文档的情感 score 表示文档的总体情绪。文档情感的 magnitude 表明文档中存在多少情绪化内容，这个值通常与文档的长度成正比。
需要指出的是：Natural Language API 可以指出文档中积极与消极情绪的差异，但不会标识出具体的积极和消极情绪。例如，“愤怒”和“悲伤”都被认为是消极情绪。然而，当 Natural Language API 分析被认为是“愤怒”的文本或者被认为是“悲伤”的文本时，其响应只能指出文本中的情感是消极的，而不能指出是“悲伤”或“愤怒”。
具有中性得分（大约为 0.0）的文档可能表示缺乏情绪表达，或者可能表示混合型情绪，同时具有高正值和高负值，彼此抵消。一般来说，您可以使用 magnitude 值来区别开上述两种情况，因为真正的中立文档 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.25 的分数也应视为积极，于是将分数阈值修改为 0.15。
实体分析
实体分析提供文本中实体的信息，这些实体通常指有名称的“事物”，例如著名人物、地标、常见对象等。
实体大致可分为两大类：与独一无二的实体（具体的人物、地点等）对应的 专有名词或普通名词（在自然语言处理中也称为“名词性词”）。您可以遵循的一个常规良好做法是：如果某物是名词，它就可以作为“实体”。实体以索引偏移的形式返回到原始文本中。
实体分析请求应该传递 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”（人名）返回实体。这种情况下，实体分析对于区别“Lawrence”等类似实体很有用。
下面列出了用于存储实体参数的字段：
type表示此实体的类型（例如实体是人、地点、消费品等）。这些信息有助于区分实体和/或消除实体的歧义，并可用于编写模式或提取信息。举例来说，type值可以帮助区分名称类似的实体，例如区别标记为WORK_OF_ART（电影名）的“Lawrence of Arabia”与标记为PERSON的“T.E. Lawrence”。（如需了解详情，请参阅实体类型。）metadata包含有关实体知识库的来源信息。未来可能会提供其他库。mentions表示文本内提到实体的偏移位置。如果您想在文本中找到所有提及人物“Lawrence”的地方，而不是电影名，那么此信息会很有用。您也可以使用提及来收集实体别名（例如“Lawrence”）的列表，这些别名指的是同一实体“ TE Lawrence”。实体提及可能是以下两种类型之一：PROPER或COMMON。举例来说，专有名词实体“Lawrence of Arabia”可以直接作为电影名提及，也可作为普通名词（T.E. Lawrence 的“传记电影”）提及。
实体情感分析
实体情感分析将实体分析和情感分析结合起来，并力图确定文本中传达的关于实体的情感（积极还是消极）。 实体情感用数字分数和量值来表示，并且由实体的每次提及确定。 然后将这些分数汇总为实体的总体情感分数和量级。
实体情感分析请求
实体情感分析请求通过使用 analyzeEntitySentiment 方法按以下形式发送到 Natural Language API：
{ "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 然后处理词法单元，并使用它们在句子中的位置将语法信息添加到词法单元中。
词态学与依存关系树指南提供了关于语法词法单元的完整文档。
语法分析请求
语法分析请求通过使用 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 处理给定文本以提取句子和词法单元。语法分析请求按以下形式返回包含这些 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”等词都基于相同的词元（“write”）。同样，复数和单数形式也基于词元：“house”和“houses”均指相同的形式。（请参阅词元（词法）。）dependencyEdge字段通过有向树中的边缘来确定包含词法单元的句子中单词之间的关系。此信息对翻译、信息提取和总结而言都很有价值。（词法与依存关系树指南包含有关依存关系解析的更多详细信息。）各dependencyEdge字段包含以下子字段：headTokenIndex提供此词法单元的“父级词法单元”在包含此词法单元的语句中的索引值（从零开始）。没有父级的词法单元由自身索引。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 API 分析文档并返回文档中找到的文本的内容类别列表。如需对文档中的内容进行分类，请调用 classifyText 方法。
如需查看 classifyText 方法返回的内容分类的完整列表，请点击此处。
Natural Language API 过滤由 classifyText 方法返回的类别，以仅包含与请求最相关的类别。例如，如果 和 都适用于文档，则它将只返回 类别，因为它是更具体的结果。例如，如果 /Science 和 /Science/Astronomy 都适用于文档，则它将只返回 /Science/Astronomy 类别，因为它是更具体的结果。
如需查看使用 Natural Language API 进行内容分类的示例，请参阅对内容进行分类。
在单个请求中执行多项操作
如果您希望在单个方法调用中执行一组 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" }