借助 Cloud Vision API，您可以在简单的 REST API 中封装强大的机器学习模型，从而了解图片的内容。
在本实验中，我们将向 Vision API 发送图片，检测其是否检测到了对象、人脸和地标。
学习内容
- 创建 Vision API 请求并使用 curl 调用 API
- 使用 Vision API 的标签、网络、人脸和地标检测方法
所需
您将如何使用本教程？
您如何评价自己在使用 Google Cloud Platform 方面的经验水平？
自定进度的环境设置
如果您还没有 Google 帐号（Gmail 或 Google Apps），则必须创建一个。登录 Google Cloud Platform Console (console.cloud.google.com) 并创建一个新项目：
请记住项目 ID，它在所有 Google Cloud 项目中都是唯一名称（很抱歉，上述名称已被占用，您无法使用！）。它稍后将在此 Codelab 中被称为 PROJECT_ID。
接下来，您需要在 Cloud Console 中启用结算功能，才能使用 Google Cloud 资源。
在此 Codelab 中运行仅花费几美元，但是如果您决定使用更多资源或继续让它们运行，费用可能更高（请参阅本文档末尾的“清理”部分）。
Google Cloud Platform 的新用户有资格获享 $300 免费试用。
点击屏幕左上角的菜单图标。
从下拉菜单中选择 API 和服务，然后点击“信息中心”
点击启用 API 和服务。
然后，在搜索框中搜索“vision”。点击 Google Cloud Vision API。
点击启用以启用 Cloud Vision API：
请稍等片刻，以将其启用。启用之后，您将看到以下内容：
Google Cloud Shell 是在云端运行的命令行环境。这是一款基于 Debian 的虚拟机，其中预装了您需要的所有开发工具（gcloud、bq、git 等），并提供 5GB 的永久性主目录。我们将使用 Cloud Shell 创建对 Speech API 的请求。
如需开始使用 Cloud Shell，请点击标题栏右上角的“激活 Google Cloud Shell”图标 
一个 Cloud Shell 会话随即会在控制台底部的新框内打开，并显示命令行提示符。等待 user@project:~$ 提示出现
由于我们要使用 curl 向 Vision API 发送请求，因此需要生成 API 密钥来传入请求网址。如需创建 API 密钥，请转到 Cloud Console 中“API 和服务”的“凭据”部分：
在下拉菜单中选择 API 密钥：
接下来，复制您刚刚生成的密钥。
现在您已经有了 API 密钥，请将其保存到环境变量，这样就不必在每个请求中插入 API 密钥的值了。您可以在 Cloud Shell 中执行此操作。请务必将 <your_api_key> 替换为您刚刚复制的密钥。
export API_KEY=<YOUR_API_KEY>创建 Cloud Storage 存储分区
您可以通过以下两种方式向 Vision API 发送图片以进行图片检测：向 API 发送 base64 编码的图片字符串，或将图片传递给 Google Cloud Storage 中存储的文件的网址。我们将使用 Cloud Storage 网址。我们将创建一个 Google Cloud Storage 存储分区来存储我们的图片。
在 Cloud Console 中转到项目的 Storage 浏览器：
然后点击创建存储分区。为您的存储分区指定一个唯一名称（例如您的项目 ID），然后点击创建。
将图片上传到存储分区
右键点击以下甜甜圈图片，然后点击图片另存为，并将其作为“donuts.png”保存到“下载”文件夹中。
转到您刚刚在存储浏览器中创建的存储分区，然后点击上传文件。然后选择 donuts.png。
您应该会在存储分区中看到该文件：
接下来，修改映像的权限。
点击添加一项。
添加 Group 和 allUsers 的新实体：
点击保存。
现在，您的存储分区中已有该文件，接下来就可以创建 Vision API 请求并向其传递此甜甜圈图片的网址了。
在 Cloud Shell 环境中，使用以下代码创建一个 request.json 文件，请务必将 my-bucket-name 替换为您创建的 Cloud Storage 存储分区的名称。您可以使用以下任一首选命令行编辑器（nano、vim、emacs）创建该文件，也可以使用 Cloud Shell 中的内置 Orion 编辑器：
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/donuts.png"
}
},
"features": [
{
"type": "LABEL_DETECTION",
"maxResults": 10
}
]
}
]
}我们要探索的第一个 Cloud Vision API 功能是标签检测。此方法会返回图片中标签（字词）的列表。
现在，我们可以通过 curl 调用 Vision API：
curl -s -X POST -H "Content-Type: application/json" --data-binary @request.json https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}您的响应应如下所示：
{
"responses": [
{
"labelAnnotations": [
{
"mid": "/m/01dk8s",
"description": "powdered sugar",
"score": 0.9436922
},
{
"mid": "/m/01wydv",
"description": "beignet",
"score": 0.7160288
},
{
"mid": "/m/06_dn",
"description": "snow",
"score": 0.71219236
},
{
"mid": "/m/02wvn_6",
"mid": "/m/0bp3f6m",
"description": "fried food",
"score": 0.7075312
},
{
"mid": "/m/02wvn_6",
"description": "ricciarelli",
"score": 0.5625
},
{
"mid": "/m/052lwg6",
"description": "baked goods",
"score": 0.53270763
}
]
}
]
}该 API 能够识别这些甜甜圈的具体类型（甜甜圈），太酷了！对于找到的 Vision API 的每个标签，它都会返回一个包含相应商品名称的 description。它还会返回 score（一个介于 0 到 100 之间的数字），表示该说明与图片内容匹配的可信程度。mid 值映射到 Google 知识图谱中的项。您可以在调用 Knowledge Graph API 时使用 mid，获取有关该项的更多信息。
除了为图片中的内容添加标签之外，Vision API 还可以通过互联网搜索有关图片的其他详细信息。通过该 API 的 webDetection 方法，我们可以获得很多有趣的数据：
- 我们的图片（基于包含类似图片的网页中的内容）中的实体的列表
- 网上找到的完全匹配和部分匹配图片的网址，以及对应的网页的网址
- 类似图片的网址，例如执行逆向图片搜索
为了尝试网络检测功能，我们将使用上面相同的贝尼特图片，因此，我们只需要更改 request.json 文件中的一行内容（您也可以探索未知内容，并使用完全不同的图片）。在功能列表下方，只需将类型从 LABEL_DETECTION 更改为 WEB_DETECTION 即可。request.json 现在应如下所示：
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/donuts.png"
}
},
"features": [
{
"type": "WEB_DETECTION",
"maxResults": 10
}
]
}
]
}如需将其发送到 Vision API，您可以使用与之前相同的 curl 命令（只需按 Cloud Shell 中的向上箭头即可）：
curl -s -X POST -H "Content-Type: application/json" --data-binary @request.json https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}让我们从 webEntities 开始进行响应。以下是此图片返回的部分实体：
"webEntities": [
{
"entityId": "/m/01hyh_",
"score": 0.7155,
"description": "Machine learning"
},
{
"entityId": "/m/01wydv",
"score": 0.48758492,
"description": "Beignet"
},
{
"entityId": "/m/0105pbj4",
"score": 0.3976,
"description": "Google Cloud Platform"
},
{
"entityId": "/m/02y_9m3",
"score": 0.3782,
"description": "Cloud computing"
},
...
]
此图片已在关于 Cloud ML API 的许多演示文稿中重复使用，因此，该 API 发现了“机器学习”实体“Google Cloud Platform”和“云计算”实体。
如果我们检查 fullMatchingImages、partialMatchingImages 和 pagesWithMatchingImages 下的网址，就会发现很多网址都指向此 Codelab 网站（超级元网址！）。
假设我们要寻找其他贝尼特图片，但不是精确的图片。这正是 API 响应的 visuallySimilarImages 部分的用武之地。下面是一些在视觉上相似的图片：
"visuallySimilarImages": [
{
"url": "https://igx.4sqi.net/img/general/558x200/21646809_fe8K-bZGnLLqWQeWruymGEhDGfyl-6HSouI2BFPGh8o.jpg"
},
{
"url": "https://spoilednyc.com//2016/02/16/beignetszzzzzz-852.jpg"
},
{
"url": "https://img-global.cpcdn.com/001_recipes/a66a9a6fc2696648/1200x630cq70/photo.jpg"
},
...
]我们可以转到这些网址来查看类似图片：
棒极了！现在我们可能需要一个米黄色（抱歉）这类似于在 Google 图片上按图片搜索：
但借助 Cloud Vision，我们可以通过一个易于使用的 REST API 访问该功能，并将其集成到我们的应用中。
接下来，我们将探索 Vision API 的人脸检测和地标检测方法。人脸检测方法会返回在图片中找到的人脸的相关数据，包括人脸的情绪及其在图片中的位置。地标检测可以识别常见（和模糊）的地标 - 它会返回地标的名称、其经纬度坐标以及图片中地标的位置。
上传新图片
要使用这两种新方法，请将包含人脸和地标的新图片上传到 Cloud Storage 存储分区。右键点击下面的图片，然后点击图片另存为，并将其作为“selfie.png”保存到“下载”文件夹中。
然后，按照与上一步相同的方式将该文件上传到您的 Cloud Storage 存储分区。为此，请务必选中“公开共享”复选框。
更新请求
接下来，我们将更新 request.json 文件以包含新图片的网址，并使用人脸和地标检测，而不是标签检测。请务必将 my-bucket-name 替换为 Cloud Storage 存储分区的名称：
request.json
{
"requests": [
{
"image": {
"source": {
"gcsImageUri": "gs://my-bucket-name/selfie.png"
}
},
"features": [
{
"type": "FACE_DETECTION"
},
{
"type": "LANDMARK_DETECTION"
}
]
}
]
}调用 Vision API 并解析响应
现在，您可以使用上面所用的同一 curl 命令调用 Vision API：
curl -s -X POST -H "Content-Type: application/json" --data-binary @request.json https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}我们先来看看响应中的 faceAnnotations 对象。您会发现 API 会为图片中的每张人脸返回一个对象，在本例中为 3 个。以下是回复的剪辑版本：
{
"faceAnnotations": [
{
"boundingPoly": {
"vertices": [
{
"x": 669,
"y": 324
},
...
]
},
"fdBoundingPoly": {
...
},
"landmarks": [
{
"type": "LEFT_EYE",
"position": {
"x": 692.05646,
"y": 372.95868,
"z": -0.00025268539
}
},
...
],
"rollAngle": 0.21619819,
"panAngle": -23.027969,
"tiltAngle": -1.5531756,
"detectionConfidence": 0.72354823,
"landmarkingConfidence": 0.20047489,
"joyLikelihood": "POSSIBLE",
"sorrowLikelihood": "VERY_UNLIKELY",
"angerLikelihood": "VERY_UNLIKELY",
"surpriseLikelihood": "VERY_UNLIKELY",
"underExposedLikelihood": "VERY_UNLIKELY",
"blurredLikelihood": "VERY_UNLIKELY",
"headwearLikelihood": "VERY_LIKELY"
}
...
}
}boundingPoly 为我们围绕图片中的人脸提供 x,y 坐标。fdBoundingPoly 比 boundingPoly 小，会封装在面部的皮肤部位。landmarks 是每个面部特征的对象（有些您可能甚至不知道！）。这会告诉我们地标的类型，以及该地图项的 3D 位置（x、y、z 坐标），其中 z 坐标为深度。剩下的值可让我们了解面孔的详细信息，包括欢乐、悲伤、愤怒和惊讶的可能性。上面的对象是图片中距离最远的那个人。您可以看到他有点怪诞，解释了 POSSIBLE 的 joyLikelihood。
接下来，我们看看响应的 landmarkAnnotations 部分：
"landmarkAnnotations": [
{
"mid": "/m/0c7zy",
"description": "Petra",
"score": 0.5403372,
"boundingPoly": {
"vertices": [
{
"x": 153,
"y": 64
},
...
]
},
"locations": [
{
"latLng": {
"latitude": 30.323975,
"longitude": 35.449361
}
}
]在这里，Vision API 能够识别出这张照片是在 Petra 中拍摄的，鉴于此图像中的线索极小，这一点令人印象深刻。此响应中的值应类似于上述 labelAnnotations 响应。
我们会获得地标的mid、其名称 (description) 以及置信度 score。boundingPoly 表示图片中地标的识别区域。locations 键用于告诉我们此地标的纬度经度坐标。
我们了解了 Vision API 的标签、人脸和地标检测方法，但还存在另外三种未探索的方法。请浏览文档，了解其他三项内容：
- 徽标检测：识别图片中常见的徽标及其位置。
- 安全搜索检测：确定图片是否包含露骨内容。这对包含用户生成的内容的任何应用都很有用。您可以根据以下四个因素过滤图片：成人内容、医疗内容、暴力内容和仿冒内容。
- 文本检测：运行 OCR 以从图片中提取文本。此方法甚至可以识别图片中的文本使用的语言。
您已了解如何使用 Vision API 分析图片。在此示例中，您向 API 传递了图片的 Google Cloud Storage 网址。或者，您也可以传递图片的 base64 编码字符串。
所学内容
- 通过将 Cloud Storage 存储分区中的图片网址传递给 Vision API，使用 curl 调用 Vision API
- 使用 Vision API 的标签、网页、人脸和地标检测方法
后续步骤
- 查看文档中的 Vision API 教程
- 以您偏好的语言查找 Vision API 示例
- 试用 Speech API 和 Natural Language API Codelab！