GSP075 - 使用 Cloud ML API 進行影像文字擷取、分析與翻譯

GSP075 實驗室說明

• EN Name：Extract, Analyze, and Translate Text from Images with the Cloud ML APIs
• ZH Name：無
• 時長：01:30:00
• 使用Credit：5
• 等級：Intermediate （中級）
• 完成日期：20251031
• Youtube Ref：https://www.youtube.com/watch?v=zuYuo54SWWg
• 備註：由於GSP075只有英語版本，我會把英文翻成易懂好理解的版本

目的

用 Vision API OCR 擷取文字 → 用 Translation API 翻譯 → 用 Natural Language API 做語意分析與實體抽取

1. Vision API (OCR)：從圖片文字擷取字串、語言代碼、位置資訊
2. Cloud Storage 基礎操作：上傳圖片檔、設定公開讀取連結
3. Translation API：自動偵測來源語言 ➜ 翻譯至指定語言
4. Natural Language API：找出文字中的實體 (人名、地標、物品)、語義重要性等等
5. 使用 cURL 呼叫 API：建立 JSON 請求、送出 API Request 與儲存回應

在開始之前必須收集的「必要資訊」

有一些資訊如Username、Password、Project_ID，會在實驗室開始之前就會取得，其他如API Key、Bucket name，會在實驗室啟動之後才會取得，每個實驗室都不一樣，不管如何請記得複製以下格式，依序所需資訊複製貼上，方便查詢

• Username：
• Password：
• Project_ID：
• API key：
• Bucket name：

實驗室開始

由於GSP075只有英文，並未提供繁體中文，所以我把重要的說明列在下方

Task 1. 建立一組專屬的API Key

因為你將使用 curl 向 Vision API 發送請求，所以需要先產生一組 API 金鑰，並把它放進你的請求網址中。

1. 要建立 API 金鑰，請前往：Navigation Menu > APIs & services > Credentials
2. 點選 ＋Create Credentials
3. 從下拉選單中選擇 API key
4. 接著，複製你剛產生的金鑰，複製進必要資訊內然後按 Close
5. 最後，把這組 API 金鑰儲存在環境變數中，避免你每次發送請求時都要重新輸入金鑰的值

Task 2. 建立一組專屬的API Key

• 建立 Cloud Storage Bucket

要把圖片送到 Vision API 進行影像辨識，有兩種方式：傳送 base64 編碼後的圖片字串或提供儲存在 Cloud Storage 裡的圖片 URL。在這個 Lab 中，你會先建立一個 Cloud Storage bucket 來存放圖片。

1. 在 Console 中，前往 Navigation menu > Cloud Storage，然後點 Create bucket。
2. 幫你的 bucket 取一個全域唯一的名稱：<lab 開始時提供>bucket。這個會在實驗室開始會提供
3. 命名完成後，點選 Choose how to control access to objects。
4. 取消 Enforce public access prevention on this bucket 的勾勾。
5. 在 Access Control 中選擇 Fine-grained，然後點 Create。

• 將圖片上傳到你的 bucket

1. 下載圖片並命名為 sign.jpg
2. 前往你剛剛建立的 Cloud Storage bucket，點 Upload > Upload files，然後選擇 sign.jpg 上傳。 👉（就是把 sign.jpg 上傳到你的 bucket） 接下來，你會讓單一圖片檔案公開瀏覽，但 bucket 本身仍維持私有。

3. 在下方圖片檔右側找到 三個點的選單，點下去。

4. 點選 Edit access（編輯存取權限）。

5. 點 Add Entry（新增條目），並設定如下（Entity：選 Public，Name：確認是 allUsers，Access：選 Reader），然後選擇儲存，簡單來說，就是新增一個「Public / allUsers / Reader」的存取條目，讓這張圖片可以被公開讀取。

Task３.建立你的 Cloud Vision API 請求

1. 在你的 Cloud Shell 環境中，建立一個名為 ocr-request.json 的檔案，再把下面的程式碼貼進去，並將其中的 my-bucket-name 替換成你自己建立的 bucket 名稱。你可以用你喜歡的指令列編輯器（如 nano、vim、emacs）來建立這個檔案，或直接點 Cloud Shell 上的 鉛筆圖示（Code Editor） 開啟編輯器來建立檔案。請直接複製下方其中一個（二選一）就可以

nano ocr-request.json

vim ocr-request.json

2. 然後把下幫內容複製進ocr-request.json

{
  "requests": [
      {
        "image": {
          "source": {
              "gcsImageUri": "gs://換成你的bucket name/sign.jpg"
          }
        },
        "features": [
          {
            "type": "TEXT_DETECTION",
            "maxResults": 10
          }
        ]
      }
  ]
}

Task 4.使用 Cloud Storage JSON/REST API 建立一個 Bucket

1. 在 Cloud Shell 中，使用 curl 呼叫 Cloud Vision API：OCR 方法可以從圖片中擷取大量的文字。在 textAnnotations 回傳的資料裡，第一筆資料是 API 在圖片中偵測到的「整段文字」，其中包含：

• 語言代碼（這裡是法文，所以是 fr）
• 完整的文字內容字串
• bounding box（邊界框）：表示這段文字在圖片中的位置

接著，你會看到針對 每一個單字，API 都會再提供一個獨立的物件，其中也包含該字專屬的 bounding box。

curl -s -X POST -H "Content-Type: application/json" --data-binary @ocr-request.json  https://vision.googleapis.com/v1/images:annotate?key=${API_KEY}

2. 執行以下這段 curl 指令，並把 API 回傳的結果儲存成 ocr-response.json 檔案，之後你就可以在後續的步驟中引用它。

Task 5.使用 Cloud Storage JSON/REST API 建立一個 Bucket

Translation API（翻譯 API）可以把文字翻譯成超過 100 種語言，也能自動偵測輸入文字的語言。要把這段法文翻成英文，只需要把 要翻譯的文字 和 目標語言代碼（en-US） 傳給 Translation API。

1. 首先，建立一個名為 translation-request.json 的檔案，然後把下列內容加入其中： 其中 q 欄位就是你要放「要翻譯的文字字串」的地方。

{
"q": "your_text_here",
"target": "en"
}

2. 點許SAVE儲存檔案
3. 在 Cloud Shell 中執行下面這個 Bash 指令， 它會從你上一個步驟的 OCR 回應中，把圖片的文字擷取出來， 並一次完成建立新的 translation-request.json，且自動把文字填進去（全部用同一條指令完成）。

STR=$(jq .responses[0].textAnnotations[0].description ocr-response.json) && STR="${STR//\"}" && sed -i "s|your_text_here|$STR|g" translation-request.json

4. 準備好呼叫 Translation API 了。執行下面這條指令，它也會把 API 的回應儲存成 translation-response.json 檔案，方便你後續引用。

curl -s -X POST -H "Content-Type: application/json" --data-binary @translation-request.json https://translation.googleapis.com/language/translate/v2?key=${API_KEY} -o translation-response.json

5. 執行下面這條指令來查看 Translation API 回傳的內容，順便檢查 translation-response.json 這個檔案。

cat translation-response.json

於是現在你可以更了解這部分到底寫了什麼！

• translatedText：包含翻譯後的文字內容
• detectedSourceLanguage：顯示來源語言是 fr（法文的 ISO 語言代碼）

{
  "data": {
    "translations": [
      {
        "translatedText": "TO THE PUBLIC GOOD the dispatches For Obama, the mustard is from Dijon",
        "detectedSourceLanguage": "fr"
      }
    ]
  }
}

Translation API 支援超過 100 種語言，你可以在 Language support reference（語言支援列表） 查詢支援的語言：https://cloud.google.com/translate/docs/languages

Task 6. 使用 Natural Language API 分析圖片中的文字

Natural Language API 的功能是可以幫助你了解文字內容，例如：

• 抽取其中提到的實體（entities）
• 分析情緒（sentiment analysis）
• 分析句法（syntax）
• 把文字分類到不同的主題類別（text classification）

在這裡，你會使用 analyzeEntities 方法，來看看 Natural Language API 能從圖片文字中找出哪些「實體」。

1. 首先，建立一個名為 nl-request.json 的檔案，並加入以下內容：

{
"document":{
"type":"PLAIN_TEXT",
"content":"your_text_here"
},
"encodingType":"UTF8"
}

解釋一下這邊的意思

• type：說明支援的文字型態是 PLAIN_TEXT 或 HTML。
• content：這裡放的是你要給 Natural Language API 做分析的文字內容。 Natural Language API 也支援從 Cloud Storage 讀取文字檔。如果你要傳 Cloud Storage 裡的檔案，就把 content 換成 gcsContentUri，並把 Cloud Storage 文字檔的 URI 當作值。
• encodingType：告訴 API 在處理文字時要使用哪一種文字編碼。API 會用這個資訊來計算「實體（entities）在文字中的位置」。

2. 在 Cloud Shell 中執行Bash 指令，它會把你剛剛（使用 Translation API）得到的翻譯文字，自動填入 Natural Language API request 的 content 欄位中。也就是說：這條指令會幫你更新 nl-request.json，無需手動複製貼上，非常方便。

STR=$(jq .data.translations[0].translatedText translation-response.json) && STR="${STR//\"}" && sed -i "s|your_text_here|$STR|g" nl-request.json

3. 使用下面這條 curl 指令，呼叫 Natural Language API 的 analyzeEntities 端點（endpoint），分析文字中的實體。

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \ -s -X POST -H "Content-Type: application/json" --data-binary @nl-request.json

對於那些擁有 Wikipedia 頁面的實體（entity），API 會在回傳結果中提供該實體的相關資訊，包括：

• 該 Wikipedia 頁面的 URL
• 以及 mid（Google Knowledge Graph 裡面這個實體的唯一 ID）

如果你想取得更多關於這個實體的資訊，可以把這個 mid 送給 Knowledge Graph API 進一步查詢。對於所有類型的實體，Natural Language API 都會告訴你：

• mentions：這個實體在文字中出現的位置與形式
• type：實體的類型（例如人名、地點、組織…）
• salience：重要性指標，介於 0 到 1 之間，代表「這個實體對整段文字有多重要」

此外，Natural Language API 不只支援英文，也支援許多其他語言，完整語言支援列表可在 Language Support 參考文件中查詢。

實驗室結束

請記得按下Check，來確認是否完成100％，沒有100%，重新再來一次也沒關係，因為我們的目的是學會，而不是征服，加油喔

結語目的

走完這個 GSP075，你不是只按了幾條指令、完成幾個 Task 而已，你其實剛剛完成了一條真正的 AI 影像 → 文字 → 語意分析 完整資料管線（Pipeline）。你學會了——

• 用 Vision API OCR 從圖片中擷取文字
• 用 Translation API 自動偵測語言並轉換成你需要的語言
• 用 Natural Language API 深入理解文字背後的語意與實體
• 使用 Cloud Storage、公開權限、Bucket 建立等核心雲端技能
• 用 cURL 與 API 溝通，知道如何建立 Request 與解析 Response

這些看似小小的步驟，累積起來，就是你未來在 AI、資料分析、雲端領域能自由發揮的基礎能力。這不是「跟著做就結束」，記得把資料整合進你的Notion，建立自己的雲端第二大腦，加油！