Google Cloud Vision API Python 快速入门：基于 ImageAnnotatorClient 实现图片标签识别（Label Detection）-开发者社区

示例工程

【免费下载链接】python-docs-samples

Code samples used on cloud.google.com

项目地址：https://gitcode.com/GitHub_Trending/py/python-docs-samples

导读

本文围绕 python-docs-samples 仓库中 vision/snippets/quickstart 目录下的快速入门示例展开，系统讲解如何用 Python 调用 Google Cloud Vision API 完成图片标签识别（Label Detection）：从环境认证、依赖安装、运行命令，到核心代码ImageAnnotatorClient的调用链逐行拆解，并结合同目录的测试与detect模块源码补充本地文件识别、错误处理与扩展用法，帮助读者快速上手并真正理解该 API 的底层调用方式。

一、快速入门示例是什么

vision/snippets/quickstart目录是 Cloud Vision API 的官方 Python 快速入门样例，其入口文档 README.rst 对 Cloud Vision API 的能力做了如下概括：允许开发者将视觉检测功能轻松集成到应用程序中，包括：

图像标签识别（image labeling）
人脸检测与地标检测（face and landmark detection）
光学字符识别（OCR）
敏感内容标注（tagging of explicit content）

该目录内的示例专注于其中最简单、最能体现 API 用法的"图片标签识别"：对一张给定的图片，返回一组描述图片内容的标签（如 "cat"、"pet"、"animal" 等），并打印到终端。这也是进入 Cloud Vision API 生态最直接的起点。

目录结构如下：

文件	作用
quickstart.py	快速入门核心示例代码，执行标签识别
README.rst	官方自动生成的文档（由 README.rst.in 模板生成）
quickstart_test.py	对该示例的集成测试
requirements.txt	运行示例所需的依赖（`google-cloud-vision==3.8.1`）
requirements-test.txt	运行测试所需的依赖（`pytest`）

说明：README 模板中声明的文件夹路径为vision/cloud-client/quickstart（历史路径），在当前仓库中该示例的实际位置是vision/snippets/quickstart。

二、环境准备与认证

2.1 认证是前提

Cloud Vision API 是云端托管服务，调用前必须先完成应用认证（Authentication）。官方要求参照 Google Cloud 的"认证入门指南"配置凭据，即通过设置环境变量GOOGLE_APPLICATION_CREDENTIALS指向服务账号 JSON 密钥文件，或使用gcloud auth application-default login生成应用默认凭据。客户端库（google-cloud-vision）在实例化时会自动读取应用默认凭据（ADC），因此示例代码中看不到任何显式的密钥传入逻辑。

2.2 安装依赖

按照 README 给出的标准流程，运行示例前需要完成四步：

# 1. 克隆 python-docs-samples 仓库并进入示例目录 $ git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git # 2. 创建虚拟环境并激活（示例兼容 Python 2.7 与 3.4+，但当前依赖版本实际要求更高版本 Python，见下文） $ virtualenv env $ source env/bin/activate # 3. 安装示例依赖 $ pip install -r requirements.txt

当前仓库的 requirements.txt 内容为：

google-cloud-vision==3.8.1

这是被锁定的客户端库版本，保证示例在固定版本下行为一致。需要说明的是：虽然历史 README 声称兼容 Python 2.7/3.4+，但从测试依赖 requirements-test.txt 中pytest==9.0.3; python_version >= "3.10"的标记可以推断，当前示例与测试实际面向Python 3.10+运行，建议读者使用较新的 Python 版本。

三、运行快速入门示例

认证与依赖就绪后，在示例目录下直接执行：

$ python quickstart.py

程序会对一张位于 Google Cloud Storage 上的公开样例图片（gs://cloud-samples-data/vision/label/wakeupcat.jpg，一张醒来的猫的图片）执行标签检测，并在终端输出识别结果，形如：

Labels: cat pet animal ...

如需在 Cloud Shell 中一键打开并运行，README 也提供了对应的 Cloud Shell 快捷入口（按钮指向quickstart.py与README.rst的编辑器视图）。

四、核心代码逐行拆解

quickstart.py 全文仅 50 行左右，却完整展示了 Cloud Vision API 的全部关键调用链，逐段拆解如下。

4.1 导入客户端库

from google.cloud import vision

这是google-cloud-vision客户端库的统一入口模块，其中vision.ImageAnnotatorClient是调用标注（annotation）类 API 的客户端类，代码中用# [START vision_python_migration_import]/# [END vision_python_migration_import]标注片段，供官方文档站点做代码片段嵌入。

4.2 实例化客户端

def run_quickstart() -> vision.EntityAnnotation: """Provides a quick start example for Cloud Vision.""" client = vision.ImageAnnotatorClient()

ImageAnnotatorClient()构造函数不传任何参数，完全依赖应用默认凭据（ADC）完成鉴权。函数返回类型标注为vision.EntityAnnotation，即单个标签实体的类型。

4.3 构造图片对象

# The URI of the image file to annotate file_uri = "gs://cloud-samples-data/vision/label/wakeupcat.jpg" image = vision.Image() image.source.image_uri = file_uri

这里展示了 Cloud Vision 的图片引用方式：vision.Image对象通过source.image_uri指定图片位置，支持gs://开头的 GCS 对象 URI 或https://公网图片地址。图片本身不随请求上传，API 服务端直接读取该 URI，因此调用方无需下载图片字节流。

对比：若要识别本地文件，则使用vision.Image(content=image_bytes)将图片二进制内容直接放入请求体（详见下文detect.py的detect_labels函数）。

4.4 执行标签检测

# Performs label detection on the image file response = client.label_detection(image=image) labels = response.label_annotations

这是整个示例的核心调用：

client.label_detection(image=image)发起同步 RPC 请求，返回AnnotateImageResponse响应对象；
response.label_annotations是EntityAnnotation的列表，按置信度从高到低排列，每项含description（标签文本）、score（置信度）、mid（实体 ID）等字段。

4.5 输出结果

print("Labels:") for label in labels: print(label.description) return labels

遍历标签列表并打印每个标签的description字段，最后将labels返回给调用方——这也是测试代码复用的关键（见第六章）。

五、源码级纵深：错误处理与本地文件识别

快速入门只覆盖了"通过 GCS URI 识别"这一条路径。同目录仓库中的 detect.py（位于vision/snippets/detect/）提供了标签检测的更完整实现，可作为生产化扩展参考。

5.1 本地图片文件识别

detect.py中的detect_labels(path)展示了本地文件的识别方式：

with open(path, "rb") as image_file: content = image_file.read() image = vision.Image(content=content) response = client.label_detection(image=image) labels = response.label_annotations

其命令行用法为python detect.py labels ./resources/landmark.jpg。与快速入门相比，差异仅在Image对象的构造方式：本地文件用Image(content=...)携带二进制内容，远程文件用Image(source.image_uri=...)携带 URI。

5.2 响应错误检查

快速入门示例省略了错误处理，而detect.py中的生产级写法会在每次调用后检查响应中的错误信息：

if response.error.message: raise Exception( "{}\nFor more info on error messages, check: " "https://cloud.google.com/apis/design/errors".format(response.error.message) )

即：即使 HTTP 层调用成功，API 也可能在响应体内返回error字段（如图片损坏、URI 不可访问等），应显式检查并抛出异常，这是可移植到快速入门代码中的重要实践。

5.3 迁移背景

README 中特别提及了"迁移指南"：官方文档说明该示例已迁移到 Python 客户端库 v0.25.1+ 的新 API 风格。从代码可见，当前示例使用的是现代化写法（ImageAnnotatorClient+label_detection方法），# [START vision_python_migration_*]系列标注正是迁移前后代码对照的片段标记，新老版本在客户端类名与方法命名上存在差异。

六、测试如何验证示例

quickstart_test.py 展示了该示例的自动化验证方式：

import quickstart def test_quickstart() -> None: labels = quickstart.run_quickstart() for label in labels: assert len(label.description) > 0

测试逻辑非常简洁：

直接导入quickstart模块并调用run_quickstart()；
断言返回的每个标签description字段非空。

这属于真实调用云服务的集成测试，运行前提是环境已配置好有效凭据且可访问公网/GCS。requirements-test.txt指定pytest==9.0.3; python_version >= "3.10"，因此测试应在 Python 3.10+ 环境下通过pytest运行。

七、依赖版本与运行环境小结

文件	内容	说明
requirements.txt	`google-cloud-vision==3.8.1`	客户端库版本锁定
requirements-test.txt	`pytest==9.0.3; python_version >= "3.10"`	测试框架，要求 Python ≥ 3.10
运行命令	`python quickstart.py`	需先完成认证与依赖安装
测试命令	`pytest`	需真实凭据，属于集成测试

八、继续深入：仓库内的相邻示例

vision/snippets目录下还提供了多个同主题的扩展样例，可作为标签识别之外的学习路径：

vision/snippets/detect：人脸检测、OCR、Web 检测、物体定位等完整能力集合（detect.py入口）；
vision/snippets/face_detection：人脸检测专项示例；
vision/snippets/document_text：文档文字识别（OCR）专项；
vision/snippets/web：Web 实体与相似图片检索；
vision/snippets/product_search：商品搜索；
vision/snippets/crop_hints：构图裁剪提示。

九、总结

从vision/snippets/quickstart这份快速入门可以提炼出使用 Cloud Vision API 的最小可行套路：配置应用默认凭据 → 实例化ImageAnnotatorClient→ 构造Image（本地字节或远程 URI）→ 调用label_detection→ 遍历label_annotations输出结果。基于 quickstart.py 及其测试、detect.py扩展实现，读者既能立刻跑通首个示例，也能在此基础上按需补充错误检查、切换本地图片输入、或扩展到人脸、OCR 等其他标注能力，是进入视觉识别应用开发的可靠起点。