多國語言翻譯系統（Multi-language Translation）

本專案是以 Django ASGI + Transformers 為核心的翻譯服務，支援本機模型載入與 GPU 加速。

系統架構圖

類別圖

本文件涵蓋：

CPU 模式啟動
GPU mode 啟用（Docker / Podman 各一套）
GPU mode 自動檢查條件與排錯

英文版請見：README_en.md

GPU mode 自動檢查（必要條件）

判定：torch.cuda.is_available() = True 且未設定 force_cpu → GPU；否則 CPU
必要：GPU 暴露到容器（Docker：--gpus all／compose gpus: all；Podman：CDI nvidia.com/gpu=all）
必要：容器內安裝 CUDA 版 PyTorch（例如 cu118/cu121）

安裝 PowerShell 7.x（Windows）

用 winget 安裝：

winget install --id Microsoft.PowerShell --source winget

重新開一個終端機，確認版本：

pwsh --version

檢查：PowerShell Major 版本需為 7。

安裝 Docker（Windows：建議 WSL2 + Docker Engine）

備註：Docker Desktop 可能涉及商業授權/訂閱限制；請先依官方授權條款評估。若要避免 Desktop 授權風險，建議改用 WSL2 內安裝 Docker Engine。

啟用 WSL2（如果你尚未啟用）：

wsl --install
wsl --set-default-version 2

安裝一個 Linux 發行版（例如 Ubuntu），並進入 WSL：

wsl --install -d Ubuntu
wsl -d Ubuntu

在 WSL（Ubuntu）內安裝 Docker Engine + Compose plugin（以下指令在 WSL 內執行）：

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo service docker start

（可選）免 sudo 使用 docker（在 WSL 內）：

sudo usermod -aG docker $USER
newgrp docker

在 WSL 內確認 docker/compose 可用：

docker version
docker compose version

（可選）如果你仍要用 Docker Desktop：

winget install --id Docker.DockerDesktop --source winget

安裝 Podman（Windows：Podman Desktop / podman machine）

安裝 Podman：

winget install --id RedHat.Podman --source winget

建立並啟動 podman machine：

podman machine init --now
podman machine list
podman info

專案設定（共通：Docker / Podman / 本機）

1) 複製與配置檔

git clone <repository-url>
cd MutilLangTranslate

Copy-Item config/app_config.yaml.example config/app_config.yaml
Copy-Item config/model_config.yaml.example config/model_config.yaml

2) 模型資料

模型路徑：models/（需包含 config.json 與權重檔）。

GPU Mode（Docker）

0) 先做一次「引擎層」GPU Smoke Test

docker run --rm --gpus all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi

1) 用 GPU compose 啟動（會安裝 cu118 版 torch）

docker compose -f docker-compose.docker.gpu.yaml up -d --build

2) 驗證「容器內 torch 能看到 CUDA」

docker exec translation-service python -c "import torch; print('torch', torch.__version__, 'cuda_available', torch.cuda.is_available(), 'torch_cuda', torch.version.cuda)"

檢查：cuda_available True 且 torch_cuda 有值（例如 11.8）

GPU Mode（Podman / CDI）

0) 進入 podman machine

podman machine ssh

1) 檢查 GPU 裝置

ls -l /dev/nvidia* 2>/dev/null || true
ls -l /dev/dxg 2>/dev/null || true

2) 在 machine 內安裝 NVIDIA Container Toolkit 並生成 CDI

在 machine 內執行：

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

3) CDI Smoke Test

podman run --rm --device nvidia.com/gpu=all nvidia/cuda:12.3.2-base-ubuntu22.04 nvidia-smi

4) 回到 Windows，用 GPU compose 啟動（會安裝 cu118 版 torch）

# 註：專案啟動時會自動判斷 GPU 是否可用；若硬體/驅動不支援，會改走 CPU 路徑。
# 但無論 GPU/CPU mode，要用 podman compose 啟動都需要先確保 Podman VM（machine）與連線正常。
# 先確認 Podman VM（machine）與連線正常，避免出現 "Cannot connect to Podman socket" / SSH 連線錯誤
podman machine list
podman machine start  # 第一次使用可先跑：podman machine init --now
podman system connection list

# 若仍遇到連線問題，可先快速重啟 machine
podman machine stop
podman machine start

podman compose -f docker-compose.podman.gpu.yaml up -d --build

5) 驗證「容器內 torch 能看到 CUDA」

podman exec translation-service python -c "import torch; print('torch', torch.__version__, 'cuda_available', torch.cuda.is_available(), 'torch_cuda', torch.version.cuda)"

檢查：cuda_available True 且 torch_cuda 有值（例如 11.8）

CPU Mode（Docker / Podman）

CPU 模式：

docker compose -f docker-compose.yaml up -d --build

# 註：專案啟動時會自動判斷 GPU 是否可用；若硬體/驅動不支援，會改走 CPU 路徑。
# 但要用 podman compose 啟動仍需先確保 Podman VM（machine）與連線正常。
podman machine list
podman machine start  # 第一次使用可先跑：podman machine init --now
podman system connection list

# 若遇到連線問題，可先快速重啟 machine
podman machine stop
podman machine start

podman compose -f docker-compose.yaml up -d --build

啟動後驗證

1) 健康檢查

curl -f http://localhost:8000/api/health/

2) quick test（印出 torch/cuda 狀態）

python tests/quick_model_test.py

一鍵檢查（PowerShell）

本專案提供檢查腳本：scripts/Check-Gpu.ps1

Set-ExecutionPolicy -Scope Process Bypass
pwsh -NoProfile -File scripts/Check-Gpu.ps1 -RunCudaSmokeTest -RunProjectTorchProbe

參考文件（官方）

NVIDIA Container Toolkit 安裝指南：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
NVIDIA Container Toolkit CDI 指南：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/cdi-support.html
Docker Desktop（Windows）文件：https://docs.docker.com/desktop/
Docker Engine（Ubuntu）安裝文件：https://docs.docker.com/engine/install/ubuntu/
Docker Desktop 授權/訂閱：https://www.docker.com/pricing/
WSL（Windows Subsystem for Linux）文件：https://learn.microsoft.com/windows/wsl/
Podman 文件：https://podman.io/docs

常見問題（GPU mode）

1) 容器內 `torch.cuda.is_available()` = False

Docker：重跑 docker run --rm --gpus all ... nvidia-smi
Docker：重跑 docker compose -f docker-compose.docker.gpu.yaml up -d --build
Docker：重跑 docker exec translation-service python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"

2) Podman machine 看不到 GPU

在 machine 內重跑：ls -l /dev/nvidia* /dev/dxg
若不存在：改用 WSL2 + Docker Engine（或 Docker Desktop）

目錄結構

MutilLanguageTranslate/
├── config/                          # 配置檔目錄
│   ├── app_config.yaml              # 應用程式配置
│   ├── model_config.yaml            # 模型配置
│   └── languages.yaml               # 語言定義
├── logs/                            # 日誌目錄
├── models/                          # 模型目錄
│   ├── TAIDE-LX-7B-Chat/            # 模型名稱一（建議使用，請自行下載）
│   └── Llama-3.1-TAIDE-LX-8B-Chat/  # 模型名稱二（建議使用，請自行下載）
├── translation_project/             # Django 專案
│   ├── translation_project/         # 專案設定
│   │   ├── settings.py
│   │   ├── urls.py
│   │   └── asgi.py
│   └── translator/                  # 翻譯應用程式
│       ├── api/                     # REST API
│       ├── services/                # 服務層
│       ├── templates/               # 前端模板
│       ├── static/                  # 靜態資源
│       └── utils/                   # 工具函數
├── specs/                           # 規格文件
├── tests/                           # 測試
├── Containerfile                    # 容器建置檔
├── docker-compose.yaml              # Docker Compose
├── requirements.txt                 # Python 相依套件
└── README.md                        # 本文件

API 文件

翻譯 API

POST /api/v1/translate/

執行文字翻譯。

請求

{
  "text": "要翻譯的文字",
  "source_language": "auto",
  "target_language": "en",
  "quality": "standard"
}

回應

{
  "request_id": "uuid",
  "status": "completed",
  "translated_text": "Translated text",
  "processing_time_ms": 1234.56,
  "detected_language": "zh-TW"
}

健康檢查 API

GET /api/health/

回傳系統健康狀態。

GET /api/ready/

就緒探針，檢查服務是否準備好接收流量。

GET /api/live/

存活探針，檢查服務是否存活。

語言 API

GET /api/v1/languages/

取得支援的語言清單。

管理 API

POST /api/v1/admin/model/test/

測試載入小型模型（用於驗證環境與量化設定）。

請求

{
  "model_name": "gpt2"
}

回應

{
  "success": true,
  "message": "小模型載入與推論成功 (gpt2)",
  "model_info": {
    "model_name": "gpt2",
    "generated": "Hello world, I'm not sure what to say",
    "cuda_available": true,
    "cuda_device_count": 1
  }
}

配置說明

app_config.yaml

server:
  host: "0.0.0.0"
  port: 8000
  workers: 1

translation:
  default_source_language: "auto"
  default_target_language: "en"
  max_text_length: 5000
  timeout_seconds: 120

security:
  admin_ip_whitelist:
    - "127.0.0.1"
    - "::1"

model_config.yaml

model:
  name: "taide/TAIDE-LX-7B"
  cache_dir: "./models"
  device: "auto"  # auto, cuda, cpu
  torch_dtype: "auto"

inference:
  max_new_tokens: 2048
  temperature: 0.7
  top_p: 0.9

界面範例

授權

MIT License

貢獻

歡迎提交 Issue 和 Pull Request！

聯絡

如有問題，請透過 GitHub Issues 聯絡我們。

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.github		.github
.specify		.specify
.vscode		.vscode
Docs		Docs
Out		Out
Prompt		Prompt
config		config
logs		logs
scripts		scripts
specs		specs
tests		tests
translation_project		translation_project
.containerignore		.containerignore
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Containerfile		Containerfile
LICENSE		LICENSE
README.md		README.md
README_en.md		README_en.md
docker-compose.docker.gpu.yaml		docker-compose.docker.gpu.yaml
docker-compose.podman.gpu.yaml		docker-compose.podman.gpu.yaml
docker-compose.yaml		docker-compose.yaml
pytest.ini		pytest.ini
requirements.txt		requirements.txt

License

fankachang/MutilLanguageTranslate

Folders and files

Latest commit

History

Repository files navigation