TranslateGemma 實驗專案

使用 Google Colab + VS Code 開發 TranslateGemma 翻譯模型，並部署到 Cloud Run

📋 專案簡介

本專案實驗 Google 最新開源的 TranslateGemma 翻譯模型（4B 參數版本），採用 Colab-First 開發策略：

• ✅ 在 Google Colab 免費 T4 GPU 上驗證模型
• ✅ 使用 VS Code + Colab 整合進行雲端開發
• ✅ 設計可直接部署到 Cloud Run 的流程
• ✅ 支援 55 種語言的高品質翻譯

為什麼選擇 Colab-First？

• 💡 零本地資源消耗：不需要高階 GPU 或大量磁碟空間
• 🚀 快速驗證：免費 T4 GPU 足以運行 4B 模型
• 🔄 無縫部署：notebook 可直接轉換為生產環境
• 💰 成本優化：開發免費，部署按需計費

🚀 快速開始

⚠️ 前置需求：Hugging Face 模型存取

TranslateGemma 是 gated repository，使用前需要：

1. 前往 Hugging Face TranslateGemma 頁面
2. 點擊「Request access」申請存取（通常立即批准）
3. 建立 Hugging Face Access Token

詳細步驟請參考：Hugging Face 存取設定指南

選項 1: Google Colab（推薦）

我們提供兩個 Colab notebooks，依據使用場景選擇：

📖 arXiv 雙語閱讀版（研究者/學生專用）

專注於學術論文雙語閱讀：

• ✅ 雙語對照預設啟用（學習英文學術寫作）
• ✅ 智慧混合模式（自動處理圖表頁面）
• ✅ 分章節翻譯（Abstract、Method、Experiments）
• ✅ 自動生成術語對照表

適合：深入研讀論文、學習專業術語、準備寫作/審稿

🔧 通用文件翻譯版

支援多種檔案類型：

• 📄 PDF 翻譯（arXiv、上傳、圖片模式）
• 🖼️ 圖片翻譯（菜單、海報、截圖）
• 🌐 網頁翻譯（文章抓取、截圖）

適合：一般翻譯需求、多種檔案格式

---

使用步驟（兩個 notebook 都適用）：

1. 完成上方的 Hugging Face 存取申請
2. 點擊按鈕在 Colab 中開啟 notebook
3. 確認 GPU 已啟用（Runtime > Change runtime type > T4 GPU）
4. 在 Colab Secrets 中設定 HF_TOKEN（或手動輸入）
5. 執行所有 cells，體驗 TranslateGemma 翻譯功能

選項 2: VS Code + Colab 整合

1. 安裝 VS Code Colab Extension
2. 在 VS Code 中開啟 document-translator-colab.ipynb
3. 連接到 Colab runtime 並執行

選項 3: 本地運行（使用 uv）⚡

最簡單的方式（推薦）：

# 1. 安裝 uv（如果尚未安裝）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 建立 .env 檔案
cp .env.example .env
# 編輯 .env 並填入你的 HF_TOKEN

# 3. 運行範例（一行指令搞定！）
./run-examples.sh verify-hf-token    # 驗證 HF Token（不需要 GPU）
./run-examples.sh local-test         # 完整測試（需要 GPU，可選）

# 4. 清理快取（可選）
./run-examples.sh cleanup            # 清理 HF/uv 快取，釋放空間

優點：

• ⚡ 10-100x 比 pip 快
• 🎯 自動管理虛擬環境（不需要手動 activate）
• 📦 零配置，一行指令即可運行
• 🔄 自動載入 .env 檔案
• 🧹 內建清理功能（自動檢測並清理快取）

詳細說明請參考：QUICKSTART.md

📦 專案結構

trans-gemma/
├── document-translator-colab.ipynb  # 文件翻譯 Colab notebook（核心檔案）
├── README.md                         # 本檔案
├── .gitignore                        # Git 忽略規則
│
├── cloudrun/                      # Cloud Run 部署配置
│   ├── Dockerfile                # 容器定義
│   ├── requirements.txt          # Python 依賴
│   ├── main.py                   # FastAPI 應用
│   └── deploy.sh                 # 部署腳本
│
├── docs/                          # 文檔
│   ├── colab-vscode-setup.md    # VS Code Colab 整合教學
│   └── deployment-guide.md      # 部署指南
│
├── examples/                      # 使用範例
│   └── simple-translation.py    # 簡單翻譯範例
│
└── tests/                         # 測試檔案
    └── test_translation.py      # 單元測試

🎯 功能特色

• ✅ 多語言翻譯：支援 55 種語言（英↔中、英↔日等）
• ✅ Colab 免費 GPU：在 T4 GPU 上運行 4B 模型
• ✅ FastAPI 服務：RESTful API 設計
• ✅ Cloud Run 部署：一鍵部署到 GCP
• ✅ 效能基準測試：完整的效能評估數據

📚 文檔

• VS Code Colab 整合教學
• Cloud Run 部署指南
• API 參考文件
• 效能基準測試

🔗 相關資源

TranslateGemma 官方資源

• Google Blog: TranslateGemma
• Kaggle Models
• Hugging Face: translategemma-4b-it
• Technical Report (arXiv)

開發工具

• Google Colab
• VS Code Colab Extension
• Cloud Run GPU Documentation

📊 效能數據

詳細效能測試結果請參考 performance-benchmarks.md

🚀 部署到 Cloud Run

使用 GitHub Actions（推薦）

1. Fork 本專案
2. 設定 GCP 認證（Workload Identity）
3. Push 到 main 分支，自動觸發部署

手動部署

cd cloudrun
./deploy.sh

詳細步驟請參考 deployment-guide.md

🤝 貢獻

歡迎提交 Issue 或 Pull Request！

📝 授權

本專案採用 MIT 授權條款 - 詳見 LICENSE 檔案

👤 作者

Jimmy Liao (@jimmyliao)

---

⭐ 如果這個專案對你有幫助，請給個 Star！