#Lina とローカル HY-MT1.5-1.8B でローカライズ項目を翻訳する

このガイドでは、ローカライズ翻訳の実践例として、翻訳専用の小型モデルをローカルにデプロイし、OpenAI 互換サービスとして公開し、Lina が NocoBase のローカライズ項目を一括翻訳できるように設定する方法を説明します。

この方法は、システム項目、プラグイン文言、メニュー、コレクション名、フィールドラベルなど大量の翻訳に適しています。オンラインモデルと比べて、ローカルモデルは外部 API の RPM、TPM、同時実行制限の影響を受けず、マシンとモデルの能力に合わせて同時実行数を調整できます。

#概要

このガイドで使用するもの:

• モデル: tencent/HY-MT1.5-1.8B-GGUF
• 推論サービス: llama-server
• 連携方式: OpenAI-compatible API
• AI 従業員: Lina
• 入口: Localization Management ページ

#前提条件

• Localization Management プラグインが有効になっている。
• 対象言語が有効になっている。
• ローカライズ項目が同期済みである。
• ローカルマシンまたはサーバーで llama-server を実行できる。
• NocoBase サービスから llama-server の HTTP アドレスにアクセスできる。

#HY-MT GGUF をデプロイする

#llama.cpp をインストールする

macOS では Homebrew でインストールできます:

brew install llama.cpp

事前ビルド済みの llama.cpp バイナリを使うか、ソースからビルドすることもできます。最終的に llama-server が利用できれば問題ありません。

#OpenAI 互換サービスを起動する

Hugging Face の GGUF モデルでサービスを起動します:

llama-server \
  -hf tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M \
  --host 0.0.0.0 \
  --port 8000 \
  -c 2048 \
  -np 4

#モデルサービスをテストする

llama-server 起動後、サービスの状態を確認します:

curl http://127.0.0.1:8000/health

次に OpenAI 互換 API で翻訳をテストします:

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tencent/HY-MT1.5-1.8B-GGUF:Q4_K_M",
    "messages": [
      {
        "role": "user",
        "content": "Translate the following text into Chinese. Output only the translated result without any additional explanation:\n\nSave"
      }
    ]
  }'

ローカルモデルファイルから起動する場合は、model をサービスが返す、または設定した実際のモデル名に変更してください。

#NocoBase で LLM サービスを設定する

System Settings -> AI Employees -> LLM service に移動し、LLM サービスを追加します。

設定後、Test flight でモデルを検証します。

#Lina の専用モデルを設定する

System Settings -> AI Employees -> AI employees に移動して Lina を開き、Model settings に切り替えます。

1. Enable dedicated model configuration を有効にします。
2. Models でローカル HY-MT モデルを選択します。
3. 設定を保存します。

以後、Lina はローカライズ翻訳タスクにこのモデルを使用し、汎用チャットモデルへの切り替えを避けます。

詳細は AI 従業員モデルの設定 を参照してください。

#翻訳同時実行数を設定する

ローカライズ翻訳タスクの同時実行数は AI_LOCALIZATION_CONCURRENCY で制御します:

AI_LOCALIZATION_CONCURRENCY=10

ルール:

• デフォルト: 10
• 最小: 1
• 最大: 20
• 範囲外の値はデフォルトを使用

最適な同時実行数は CPU、GPU、メモリ、モデル量子化、llama-server -np に依存します。デフォルト値で問題が出る場合:

1. AI_LOCALIZATION_CONCURRENCY=1 から始め、単一項目の翻訳を確認します。
2. llama-server -np と AI_LOCALIZATION_CONCURRENCY を 2 または 4 に設定します。
3. 応答時間、CPU/GPU 使用率、タスク進行状況を確認します。
4. 安定している場合のみ段階的に増やします。

#ローカライズ翻訳を実行する

System Management -> Localization Management に移動します。

1. 対象言語に切り替えます。
2. Synchronize をクリックして項目が同期されていることを確認します。
3. Lina のアバターをクリックします。
4. タスク範囲を選択します:
   • Incremental translation: 翻訳がない項目を翻訳します。
   • Selected translation: テーブルで選択した項目を翻訳します。
   • Full translation: 現在の言語のすべての項目を翻訳します。
5. 確認ダイアログで項目数、プロバイダー、モデルを確認します。
6. 確認して非同期タスクを作成します。
7. 完了を待ち、翻訳を確認して公開します。

増分または全量翻訳の前に、まず数件を Selected translation で実行し、出力スタイルと速度を確認してください。

#Lina が翻訳リクエストを構築する方法

Lina は項目と参照翻訳からリクエストを構築します。短い項目では、既存の参照を使って一貫性を高めます:

• 組み込み項目は中国語翻訳を参照として優先します。
• 非組み込み項目はシステムのデフォルト言語を参照として優先します。
• 英語の参照がある場合、英語をソーステキストとして使用します。
• 翻訳結果は対象言語に書き込まれますが、自動公開はされません。

prompt の意味はおおよそ次のとおりです:

Refer to the following translation:
{source_term} is translated as {target_term}

Translate the following text into {target_language}. Output only the translated result without any additional explanation:

{source_text}

#トラブルシューティング

#タスク作成後に進捗がない

llama-server がリクエストを受け取っているか確認してください。サービスログを確認するか、curl で /v1/chat/completions を呼び出します。

モデルがリクエストを受け取っても返さない場合は、次を下げます:

• AI_LOCALIZATION_CONCURRENCY
• llama-server -np
• llama-server -c

#モデルが翻訳ではなく説明を返す

ローカル翻訳モデルは通常、汎用チャットモデルより安定しています。それでも説明が出る場合は、同じ prompt を curl でテストしてモデルの出力傾向を確認してください。短い項目から翻訳する、temperature などのサンプリングパラメーターを下げる方法もあります。

#NocoBase がモデルサービスに接続できない

確認項目:

• Base URL に /v1 が含まれているか。
• NocoBase の実行環境からそのアドレスにアクセスできるか。
• ファイアウォールやコンテナネットワークがポートをブロックしていないか。
• llama-server がまだ実行中か。

#公開前の確認

AI 翻訳完了後、公開前に確認してください:

• モジュールでフィルタし、メニュー、ボタン、フィールド名、ステータスなど短い項目を確認します。
• 変数、プレースホルダー、HTML タグ、書式記号を確認します。
• 重要な業務用語の一貫性を確認します。
• 組み込み項目の翻訳が上書きされた場合は、Localization Management で再同期し、Reset system built-in entry translations を選択してデフォルトを復元します。システムおよび公式プラグインのデフォルト翻訳に貢献するには、Translation Contribution を参照してください。
• まずテスト環境で公開し、その後本番に同期します。

#参考

• tencent/HY-MT1.5-1.8B-GGUF
• llama-server ドキュメント
• Lina: ローカライズエンジニア