
示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载Google Cloud Natural Language API 为开发者提供了一整套自然语言理解能力包括情感分析Sentiment Analysis、实体识别Entity Recognition与句法分析Syntax Analysis并隶属于更大的 Cloud Machine Learning API 体系。本文以 python-docs-samples 仓库中的 language/snippets/api 示例为核心从环境准备、认证配置、命令行使用到源码级实现剖析带你完整掌握如何用 Python 通过 REST Discovery 客户端调用 Natural Language API并理解编码类型与偏移量等关键细节。读完本文你将能够独立搭建环境、运行三个核心分析命令并看懂仓库内测试用例对返回结果的验证逻辑。示例目录与文档定位language/snippets/api目录是整个仓库中展示 Natural Language API 最基础用法的示例。它包含以下文件文件作用README.rst示例说明文档含环境搭建与运行指引由模板自动生成README.rst.in用于生成 README.rst 的元数据模板产品描述、Setup 步骤、示例声明、folder: language/apianalyze.py核心命令行工具一次实现实体、情感、句法三种分析analyze_test.py针对三种分析功能及编码偏移量的完整测试requirements.txt运行依赖清单requirements-test.txt测试依赖清单从 README.rst.in 可以看出该 README 并非手写而是由 readme-gen 之类的工具根据模板渲染而成模板中声明了产品名称、简介、认证与依赖安装的 Setup 步骤以及唯一一个示例Analyze syntax对应文件analyze.py并开启show_help: true即 README 中展示的 usage 帮助文本来源。因此理解这个示例本质上就是理解该目录的全部核心内容。环境准备认证与依赖安装配置应用默认凭证调用任何 Google Cloud API 前都需要完成身份认证。本示例遵循 Google Cloud 的标准认证模型——应用默认凭证Application Default Credentials, ADC即从环境变量、gcloud 登录态或服务账号 JSON 文件中自动发现凭证。你只需按官方 Authentication 入门指南完成一次配置googleapiclient与google-auth会在运行时自动完成凭证加载与请求签名。克隆仓库并安装依赖原文档给出的标准操作流程如下克隆仓库并进入示例目录$ git clone https://gitcode.com/GitHub_Trending/py/python-docs-samples.git $ cd language/snippets/api创建并激活虚拟环境virtualenv与pip均需预先安装$ virtualenv env $ source env/bin/activate原文档注明示例兼容 Python 2.7 与 3.4这是写作时的历史声明。需要说明的是当前仓库锁定的依赖版本已要求现代 Python 3 环境——见下文 requirements.txt 的固定版本。安装依赖$ pip install -r requirements.txt依赖清单解读requirements.txt 当前固定为三个包google-api-python-client2.131.0 google-auth2.38.0 google-auth-httplib20.2.0google-api-python-client本示例的核心——通过 REST Discovery 文档动态构建 API 客户端即googleapiclient.discovery.build无需手写 HTTP 请求google-auth/google-auth-httplib2负责应用默认凭证的加载、刷新与传输层鉴权是客户端请求能够免配置鉴权的基础。测试依赖见 requirements-test.txtpytest9.0.3; python_version 3.10可见当前示例的测试体系需要 Python 3.10 环境运行pytest。核心实现剖析analyze.py 的三重分析analyze.py 是整个示例的灵魂仅有约 90 行代码却完整展示了三种 Natural Language API 能力。它的设计非常清晰三个同构的分析函数 一个 CLI 入口。构建服务客户端三个函数都以同一行代码创建服务对象service googleapiclient.discovery.build(language, v1)这表示通过 Discovery API 机制构建language服务的v1版本客户端。之后即可像调用本地方法一样调用 REST 端点request service.documents().analyzeEntities(bodybody) response request.execute()即documents资源上的analyzeEntities、analyzeSentiment、analyzeSyntax三个方法分别对应三种分析能力。请求体结构三个函数构造的body结构完全一致仅端点不同body { document: {type: PLAIN_TEXT, content: text}, encoding_type: encoding, }这里有两个关键字段document.type文档类型本示例使用PLAIN_TEXT纯文本。仓库中 language/v1/language_syntax_text.py 的注释明确指出可选值为PLAIN_TEXT、HTML两种且language字段可选——不指定时 API 会自动检测语言encoding_type编码类型决定 API 返回的beginOffset偏移量的计量单位可选值为NONE、UTF8、UTF16、UTF32。这是本示例最值得深挖的技术细节详见后文。编码类型的自动选择analyze.py 中有一个容易被忽略但非常重要的辅助函数def get_native_encoding_type(): Returns the encoding type that matches Pythons native strings. if sys.maxunicode 65535: return UTF16 else: return UTF32它根据 Python 解释器内部的 Unicode 字符串宽度选择编码若sys.maxunicode 65535说明解释器使用 UCS-2 窄字符构建历史上对应 Python 2 及部分 Windows 构建此时选用UTF16否则宽字符构建现代 Python 3 的主流形态选用UTF32。为什么要这么做因为 API 返回的 token 偏移量beginOffset是按所选编码的字符单元计数的。当编码与 Python 原生字符串的索引语义一致时你可以直接用偏移量索引 Python 字符串见测试test_annotate_text_utf32_directly_index_into_unicode的论证避免换算错误。这也是三个分析函数在 CLI 入口处统一调用get_native_encoding_type()传入的原因。CLI 入口命令行解析使用标准库argparseparser argparse.ArgumentParser( description__doc__, formatter_classargparse.RawDescriptionHelpFormatter ) parser.add_argument(command, choices[entities, sentiment, syntax]) parser.add_argument(text)即两个位置参数第一个是子命令entities/sentiment/syntax第二个是要分析的文本。根据子命令分发到对应函数后结果以格式化 JSON 输出print(json.dumps(result, indent2))命令行使用与输出解读原文档给出了运行该示例的帮助信息$ python analyze.py usage: analyze.py [-h] {entities,sentiment,syntax} text Analyzes text using the Google Cloud Natural Language API. positional arguments: {entities,sentiment,syntax} text optional arguments: -h, --help show this help message and exit三个命令的实际运行方式如下实体识别entities$ python analyze.py entities Tom Sawyer is a book written by a guy known as Mark Twain.返回的entities数组中每个实体包含name代表名称、type实体类型、salience显著度等信息。仓库测试 analyze_test.py 验证了该输入会返回language en、首个实体类型为PERSON且名称以Tom开头。若使用客户端库版示例 language/v1/language_entities_text.py可以看到更丰富的输出维度实体类型如PERSON、LOCATION、ADDRESS、NUMBER等、salience显著度分数取值区间 [0, 1.0]、元数据如已知实体的wikipedia_url与知识图谱mid以及 mentions 提及信息当前 API 支持专有名词提及。情感分析sentiment$ python analyze.py sentiment your face is really ugly and i hate it.返回的documentSentiment包含两个核心指标score情感极性分数取值范围 [-1.0, 1.0]正数表示正面情绪、负数表示负面情绪magnitude情感强度绝对量与文本中表达情感的内容多少相关不随正负方向变化。测试 analyze_test.py 分别用一句负面文本断言score 0和一句高度修辞化的正面文本断言score 0验证了判向能力。此外language/snippets/sentiment/sentiment_analysis.py 展示了更贴近教程场景的用法——读取电影评论文件并逐句打印情感分数最终给出整体score与magnitude。句法分析syntax$ python analyze.py syntax Keep away from people who try to belittle your ambitions.返回的tokens数组包含分词token级的语言学信息。结合 language/v1/language_syntax_text.py 的客户端库示例每个 token 包含text.content与text.begin_offset词形文本及其在文档中的偏移位置partOfSpeech.tag词性标签如NOUN、ADJ、VERB、PUNCT等partOfSpeech.voice/tense语态如ACTIVE、PASSIVE与时态如PAST、FUTURE、PRESENTlemma词元词典原型形式dependencyEdge.head_token_index与dependencyEdge.label依存句法树的头节点索引与依存标签如NSUBJ表示名词性主语。测试 analyze_test.py 断言了分词结果首个 token 为Keep、词性标签为VERB且返回多个句子、语言为en。language/v1/test/analyzing_syntax.test.yaml 中的样例测试还验证了is→VERBTense: PRESENTLemma: be、short→ADJ、Alice→NOUNLabel: NSUBJ等具体词例可作为理解返回结构的对照基准。编码类型与 beginOffset 偏移量最容易踩坑的细节句法分析的 token 偏移量beginOffset的语义完全取决于请求中的encoding_type。仓库用三个测试用例系统验证了这一行为是理解该细节的最佳教材编码语义测试用例UTF8偏移量是 token 首字符的首字节索引UTF-8 变长字符占 1~4 字节不等test_analyze_syntax_utf8UTF16偏移量是16 位字符单元数低码点字符占 1 个单元2 字节高码点如 emoji占 2 个单元4 字节test_analyze_syntax_utf16UTF32偏移量是32 位字符单元数所有字符固定占 1 个单元4 字节test_annotate_text_utf32测试使用的字符串a \u00e3 \u0201 \U0001f636 b刻意混合了 ASCII、双字节字符和 emoji 高码点字符用于验证偏移量在变长编码下的累计效果。其中test_annotate_text_utf32_directly_index_into_unicode给出了一个极具实用价值的结论见 analyze_test.pyPython 的 Unicode 字符串按解释后的字符索引每个字符恰好占一个槽位等价于按 UTF32 索引。因此当encoding_typeUTF32时API 返回的beginOffset可以直接用来索引 Python 字符串对象无需任何换算。这正是get_native_encoding_type()在现代 Python 3 下返回UTF32的底层原因——让偏移量语义与 Python 原生字符串索引天然对齐。理解这一点能避免在提取子串、高亮 token 等下游处理时出现错位。测试体系如何验证三种分析能力analyze_test.py 用 6 个测试函数覆盖了示例的全部功能面功能正确性test_analyze_entities实体类型与语言检测、test_analyze_sentiment正负情感判向、test_analyze_syntax分词、词性、句子切分编码偏移量正确性test_analyze_syntax_utf8、test_analyze_syntax_utf16、test_annotate_text_utf32、test_annotate_text_utf32_directly_index_into_unicode四个用例分别验证三种编码下偏移量到字节数组/Unicode 索引的换算关系。运行测试只需在示例目录执行$ pip install -r requirements-test.txt $ pytest注意这些测试会真实调用云端 API因此需要有效的应用默认凭证与配额。仓库同时提供了基于客户端库的样例测试编排 language/v1/test/analyzing_syntax.test.yaml其call/assert_contains结构展示了按测试套件断言输出文本如Part of Speech tag: VERB、Lemma: be的规范化做法可作为扩展测试的参考。REST 客户端与客户端库仓库内的两条实现路线在language目录下同一批 API 能力存在两套实现风格理解其差异有助于按需选择REST Discovery 客户端本示例googleapiclient.discovery.build(language, v1)通过动态发现机制调用documents().analyzeEntities/analyzeSentiment/analyzeSyntax依赖 requirements.txt 中的google-api-python-client。优点是代码通用、零代码生成适合快速原型官方客户端库language/v1 与 language/v2 目录使用google.cloud.language_v1/language_v2包需pip install google-cloud-language如 language/v1/language_syntax_text.py 调用client.analyze_syntax()。优点是强类型、IDE 友好返回对象可直接访问token.part_of_speech.tag等属性适合生产项目。此外 language/snippets/sentiment/sentiment_analysis.py 对应官方 Sentiment Analysis 教程展示了读取电影评论文件进行逐句情感打分的完整流程可作为本示例在真实业务场景评论分析中的自然延伸。小结本示例以约 90 行代码浓缩了 Google Cloud Natural Language API 的三大核心能力实体识别、情感分析与句法分析。通过 analyze.py 你可以立即上手体验通过 analyze_test.py 可以深入理解编码类型与偏移量的换算原理再对照 language/v1 的客户端库实现即可平滑迁移到生产代码。对于任何需要处理非结构化文本、做舆情监控、实体抽取或文本结构解析的 Python 开发者这都是一个理想的起点。赞分享示例工程【免费下载链接】python-docs-samplesCode samples used on cloud.google.com项目地址https://gitcode.com/GitHub_Trending/py/python-docs-samples点击查看免费下载相关推荐CANN ops-math Sinc 算子详解从 aclnn 两段式调用到 AiCore 内核实现CANN ops math Sinc 算子详解从 aclnn 两段式调用到 AiCore 内核实现 导读 本文以 math/sinc/README.md ht示例工程claude-seo 集成 Google Cloud Natural Language API 实战指南用实体、情感与分类信号驱动 E-E-A-T 内容优化claude seo 集成 Google Cloud Natural Language API 实战指南用实体、情感与分类信号驱动 E E A T 内容优化如何使用Google Cloud Natural Language API进行情感分析PHP开发者的终极指南如何使用Google Cloud Natural Language API进行情感分析PHP开发者的终极指南 Google Cloud Natural Lan后端上一篇为什么你需要bclm科学证据支持40-80电池保护规则下一篇FM11RF08S芯片恢复工具从Linux到多平台的跨平台兼容性突破创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考