TranslateGemma MLX 4-bit 在 Mac 上運行教程

README.md

TranslateGemma MLX 4-bit 在 Mac 上運行教程

在 Apple Silicon Mac 上使用 MLX 框架運行 Google TranslateGemma 翻譯模型。

環境需求

• Apple Silicon Mac（M1/M2/M3/M4）
• macOS 14.0+
• Python 3.10+
• 約 4GB 可用記憶體

安裝步驟

1. 建立 Conda 環境

conda create -n translategemma python=3.12 -y
source activate translategemma

2. 安裝依賴

pip install mlx-lm gradio

3. 登入 Hugging Face（首次使用需要）

TranslateGemma 是 gated model，需要先申請存取權限：

1. 前往 https://huggingface.co/google/translategemma-4b-it
2. 點擊 "Request access" 並同意條款
3. 登入 CLI：

huggingface-cli login

輸入你的 HF Token（從 https://huggingface.co/settings/tokens 取得）

使用方式

方式一：Gradio 網頁介面

執行：

python app.py

開啟瀏覽器前往 http://127.0.0.1:7860

方式二：Python 腳本

from mlx_lm import load, generate

# 載入 4-bit 量化模型（約 2GB）
model, tokenizer = load("mlx-community/translategemma-4b-it-4bit")

def translate(text, source_lang="en", target_lang="zh-TW"):
    messages = [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "source_lang_code": source_lang,
                    "target_lang_code": target_lang,
                    "text": text,
                }
            ],
        }
    ]

    prompt = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True
    )

    result = generate(model, tokenizer, prompt=prompt, max_tokens=256)
    return result.replace("<end_of_turn>", "").strip()

# 使用範例
print(translate("Hello, how are you?", "en", "zh-TW"))
# 輸出: 你好，你好嗎？

方式三：命令列互動

python -m mlx_lm.generate \
  --model mlx-community/translategemma-4b-it-4bit \
  --prompt "Translate English to Chinese: Hello world"

支援的語言代碼

語言	代碼
English	en
繁體中文	zh-TW
简体中文	zh
日本語	ja
한국어	ko
Français	fr
Deutsch	de
Español	es
Italiano	it
Português	pt

完整支援 55 種語言，詳見 官方文檔

可用模型版本

模型	大小	記憶體需求
mlx-community/translategemma-4b-it-4bit	~2GB	~4GB
mlx-community/translategemma-4b-it-8bit	~4GB	~6GB
mlx-community/translategemma-12b-it-4bit	~6GB	~10GB
mlx-community/translategemma-27b-it-4bit	~14GB	~20GB

效能參考

在 Apple Silicon Mac 上的大致效能：

機型	4B-4bit 翻譯速度
M1	~2-3 秒/句
M2	~1.5-2 秒/句
M3	~1-1.5 秒/句
M4	~0.5-1 秒/句

常見問題

Q: 出現 "Model type gemma3 not supported"

升級 mlx-lm：

pip install -U mlx-lm

Q: 出現 "Access to model is restricted"

需要先在 Hugging Face 申請存取權限並登入 CLI。

Q: 輸出一堆 <end_of_turn>

檢查 prompt 格式是否正確，使用 tokenizer.apply_chat_template() 生成 prompt。

參考資源

• TranslateGemma 官方模型
• MLX 4-bit 量化版
• MLX 框架文檔
• TranslateGemma 技術報告

app.py

import warnings
warnings.filterwarnings("ignore")

import time
import gradio as gr
from mlx_lm import load, generate

model_id = "mlx-community/translategemma-4b-it-4bit"

print("載入 MLX 4-bit 量化模型中...")
model, tokenizer = load(model_id)
print("模型載入完成！")


def translate(text, source_lang, target_lang):
    if not text.strip():
        return "", ""

    # 使用 tokenizer 的 chat template
    messages = [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "source_lang_code": source_lang,
                    "target_lang_code": target_lang,
                    "text": text,
                }
            ],
        }
    ]

    start = time.time()

    prompt = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True
    )

    result = generate(
        model,
        tokenizer,
        prompt=prompt,
        max_tokens=256,
        verbose=False
    )

    # 清理輸出
    result = result.replace("<end_of_turn>", "").strip()

    elapsed = time.time() - start

    return result, f"{elapsed:.2f} 秒"


# 語言選項
languages = [
    ("English", "en"),
    ("繁體中文", "zh-TW"),
    ("简体中文", "zh"),
    ("日本語", "ja"),
    ("한국어", "ko"),
    ("Français", "fr"),
    ("Deutsch", "de"),
    ("Español", "es"),
    ("Italiano", "it"),
    ("Português", "pt"),
]

with gr.Blocks(title="TranslateGemma 翻譯測試") as demo:
    gr.Markdown("# TranslateGemma 翻譯測試 (MLX 4-bit)")

    with gr.Row():
        source_lang = gr.Dropdown(
            choices=languages,
            value="en",
            label="來源語言"
        )
        target_lang = gr.Dropdown(
            choices=languages,
            value="zh-TW",
            label="目標語言"
        )

    with gr.Row():
        input_text = gr.Textbox(
            label="輸入文字",
            placeholder="輸入要翻譯的文字...",
            lines=4
        )
        output_text = gr.Textbox(
            label="翻譯結果",
            lines=4
        )

    elapsed_time = gr.Textbox(label="翻譯耗時")

    translate_btn = gr.Button("翻譯", variant="primary")

    translate_btn.click(
        fn=translate,
        inputs=[input_text, source_lang, target_lang],
        outputs=[output_text, elapsed_time]
    )

demo.launch()