ComfyUI-HyMT2

Translation nodes for ComfyUI, powered by Tencent's Hy-MT2 model family.
38 languages · 7 prompt templates · streaming-friendly · no fine-tuning needed.

---

$ python cli/hymt2_cli.py "今天天气真好,我们去散步吧。" \
      --target English --ip 10.8.0.12 --port 8189
The weather is really nice today — let's go for a walk.

Why this pack? Hy-MT2 is a small "fast-thinking" translation model (1.8B / 7B / 30B-A3B) that runs well on a single 24 GB GPU and produces production-quality translations across 38 languages. This pack wraps it as a clean pair of ComfyUI nodes (HyMT2Loader + HyMT2Translate) and ships two CLI helpers for headless / batch use, so the same setup powers both UI workflows and back-end pipelines.

Contents

• Features
• Installation
• Quick start
• Nodes
• CLI tools
• Prompt templates
• Model variants
• Languages
• Troubleshooting
• Development
• License

Features

• 2 nodes, 1 model cache. A HYMT2_MODEL socket flows from HyMT2Loader into HyMT2Translate, with process-global caching keyed on (model_path, dtype, device) so loading a model once costs ~3 seconds on warm cache.
• All 7 prompt templates from the model card: default, terminology-guided, style-controlled, background-aware — in both English and Chinese prompt forms.
• Race-free CLI client. Opens the WebSocket before submit, polls /history on cache hits, handles modern execution_success semantics. Battle-tested against a real deployment (CHANGELOG tells the story).
• Resumable batch processing. Drop a JSON of source strings, get one JSON output per item, re-run anytime — finished items are skipped.
• No nonsense. Banner-on-import for fast debugging, cuda_alloc / free printed before and after model load, single-file CLI you can scp to anywhere.

Installation

Prerequisites

Component	Minimum	Notes
ComfyUI	recent	Tested against the May 2026 build
Python	3.10+	Tested on 3.12 and 3.13
transformers	≥ 5.6.0	Required by Hy-MT2's hunyuan_v1_dense architecture
accelerate	≥ 0.30	Required by device_map
torch	any ComfyUI build	Don't pin torch — ComfyUI's venv already ships the right build

Install

cd ComfyUI/custom_nodes
git clone https://github.com/aadebuger/ComfyUI-HyMT2.git
cd ComfyUI-HyMT2
./scripts/install_deps.sh

The install script ends with a smoke test that fails loudly if any of transformers / accelerate / tokenizers / torch didn't install — no silent failures.

Important

transformers >= 5.6.0 conflicts with some other custom nodes that pin transformers==4.57.3 (Qwen3TTS, Sonic, certain VibeVoice forks). If you're running these, read INSTALL_NOTES.md for the recommended isolation strategy (run Hy-MT2 in a second ComfyUI instance on a different port).

Restart ComfyUI. Confirm the load banner is present:

grep "ComfyUI-HyMT2" /path/to/comfy.log
# expected:  [ComfyUI-HyMT2] v0.1.2 loaded from ...

And confirm both nodes are registered:

curl -s http://localhost:8188/object_info | python3 -c "
import json, sys
d = json.load(sys.stdin)
for n in ['HyMT2Loader', 'HyMT2Translate']:
    print(f'  {n}: {chr(0x2713) if n in d else chr(0x2717)}')"

Quick start

In the ComfyUI UI

Load example_workflows/01_simple_translate.json via the Load menu. The default workflow translates 今天天气真好,我们去公园散步吧。 into English. Hit Queue Prompt.

From the command line

# Single shot
python cli/hymt2_cli.py "今天天气真好,我们去散步吧。" \
    --target English --ip 10.8.0.12 --port 8188

# Read from file, write to file
python cli/hymt2_cli.py article.zh.md \
    --target English --ip 10.8.0.12 \
    --out article.en.md

# Read from stdin
cat article.zh.md | python cli/hymt2_cli.py - \
    --target Japanese --ip 10.8.0.12

# Batch
python cli/hymt2_batch.py news_terms.json \
    --out-dir out/hymt2_news \
    --target Japanese --ip 10.8.0.12 \
    --limit 16

See cli/README.md for the full CLI reference.

Nodes

HyMT2Loader

Loads (or returns the cached instance of) a Hy-MT2 model. Outputs a HYMT2_MODEL.

Input	Type	Default	Notes
model_path	STRING	tencent/Hy-MT2-1.8B	HF repo id or absolute local path
device	choice	cuda:0	cuda:0, cuda:1, or cpu
dtype	choice	bf16	bf16 / fp16 / fp32
force_reload (optional)	BOOLEAN	false	Bypass cache
evict_others (optional)	BOOLEAN	true	Drop other cached entries before loading

HyMT2Translate

Single-shot translation. Consumes the loader's HYMT2_MODEL and outputs a STRING.

Input	Type	Default	Notes
model	HYMT2_MODEL	—	From HyMT2Loader
source_text	STRING (multiline)	—	Text to translate
target_lang	choice (38)	English	Full language name in EN or ZH
prompt_lang	choice	en	Selects EN or ZH prompt template
temperature	FLOAT	0.7	Model card recommendation for 1.8B/7B
top_p	FLOAT	0.6
top_k	INT	20	Use -1 to disable (recommended for 30B-A3B)
repetition_penalty	FLOAT	1.05
max_new_tokens	INT	4096
seed	INT	-1	-1 = no fixed seed
terminology (optional)	STRING (multiline)	""	Glossary, one pair per line
target_style (optional)	STRING	""	Style descriptor
background_text (optional)	STRING (multiline)	""	Background paragraph

Template precedence: background_text > target_style > terminology

default.

CLI tools

Two helpers under cli/:

Script	Purpose
hymt2_cli.py	Single-shot translation. Inline text, file path, or stdin.
hymt2_batch.py	JSON batch with resumable runs and CJK-safe filenames.

Both default to 127.0.0.1:8188; point at a remote server with --ip / --port. Add -v to see every WebSocket message and the final /history status — great for debugging.

For a permanent alias on your client:

# ~/.zshrc or ~/.bashrc
alias hymt2-cli='uv run --no-project --with websocket-client \
    python /path/to/ComfyUI-HyMT2/cli/hymt2_cli.py'

hymt2-cli "早上好" --target English --ip 10.8.0.12 --port 8188 -v

--no-project is the key flag — it stops uv from reading the package's pyproject.toml and pulling hundreds of MB of model dependencies for a tiny client script.

Prompt templates

Hy-MT2 supports four template families, in both English and Chinese forms:

Template	When to use
Default	Plain translation, no extras.
Terminology	Pin specific words (e.g. "API → 接口"). Useful for technical docs.
Style	Free-text style descriptor (正式书面语, casual colloquial, legal register).
Background	Pass a context paragraph so the model disambiguates references and tone.

Glossary format (one pair per line; # lines ignored; separators =>, ->, |, or tab):

# tech terms
API       => API
endpoint  => endpoint
webhook   => webhook
token     => token

# domain terms
plaintiff => 原告
defendant => 被告

Model variants

The same HyMT2Loader works for every Hy-MT2 size — just change model_path:

Variant	model_path	VRAM (bf16)	Recommended sampling
1.8B	tencent/Hy-MT2-1.8B	~3.6 GB	T=0.7, top_p=0.6, top_k=20, rep=1.05
7B	tencent/Hy-MT2-7B	~14 GB	T=0.7, top_p=0.6, top_k=20, rep=1.05
30B-A3B	tencent/Hy-MT2-30B-A3B	~60 GB	T=0.7, top_p=1.0, top_k=-1, rep=1.0

For 30B-A3B on a 24 GB card, use the Hy-MT2-30B-A3B-FP8 checkpoint or a GGUF build via a llama.cpp-backed node pack.

Languages

38 supported, per the model card. The node dropdown lists both English and Chinese names; use English names with prompt_lang=en and Chinese names with prompt_lang=zh.

Full list (English / Chinese)

English	中文
Chinese	中文
English	英语
French	法语
Portuguese	葡萄牙语
Spanish	西班牙语
Japanese	日语
Turkish	土耳其语
Russian	俄语
Arabic	阿拉伯语
Korean	韩语
Thai	泰语
Italian	意大利语
German	德语
Vietnamese	越南语
Malay	马来语
Indonesian	印尼语
Filipino	菲律宾语
Hindi	印地语
Traditional Chinese	繁体中文
Polish	波兰语
Czech	捷克语
Dutch	荷兰语
Khmer	高棉语
Burmese	缅甸语
Persian	波斯语
Gujarati	古吉拉特语
Urdu	乌尔都语
Telugu	泰卢固语
Marathi	马拉地语
Hebrew	希伯来语
Bengali	孟加拉语
Tamil	泰米尔语
Ukrainian	乌克兰语
Tibetan	藏语
Kazakh	哈萨克语
Mongolian	蒙古语
Uyghur	维吾尔语
Cantonese	粤语

Troubleshooting

"Requires accelerate"

ValueError: Using a `device_map`, ... requires `accelerate`.

scripts/install_deps.sh ships accelerate, but if you skipped it:

uv pip install --python /path/to/.venv/bin/python "accelerate>=0.30"

"Unrecognized keys in rope_parameters"

Harmless warning. Hy-MT2's config carries YaRN-style RoPE extension params (mscale, beta_fast, beta_slow) that the current dynamic-rope code doesn't consume. Translation still works.

CLI hangs forever

Almost always the cached-prompt race (fixed in v0.1.2) or uv run syncing model deps.

# 1. Verify your CLI is v0.1.2
md5sum cli/hymt2_cli.py
# expected: 3e2948df3b7064f65bd53df7e0dbf70c

# 2. Don't use `uv run` without `--no-project`
uv run --no-project --with websocket-client \
    python cli/hymt2_cli.py "..." --ip ... --port ... -v

# 3. Or skip uv entirely
/path/to/.venv/bin/python cli/hymt2_cli.py "..." --ip ... --port ... -v

Nodes don't appear in ComfyUI

# Make sure no stale .bak directories are shadowing the pack
find ComfyUI/custom_nodes -maxdepth 1 -name "ComfyUI-HyMT2*"

# Clear pycache for this pack
find ComfyUI/custom_nodes/ComfyUI-HyMT2 -name __pycache__ \
    -exec rm -rf {} + 2>/dev/null

More patterns in INSTALL_NOTES.md.

Development

git clone https://github.com/aadebuger/ComfyUI-HyMT2.git
cd ComfyUI-HyMT2

# Offline tests — prompt builder & terminology parser, no model needed
python -m pytest tests/ -v

# Import smoke test (also no model)
python -c "
import sys; sys.path.insert(0, '.')
from nodes.runtime import build_prompt, parse_terminology
print(build_prompt('hello world', 'Chinese'))"

See CONTRIBUTING.md for PR guidelines, log-prefix conventions, and the "don't pin torch" rule.

License

Apache 2.0. The model itself is governed by Tencent's Hy-MT2 license.

Acknowledgments

• Tencent Hunyuan team for the Hy-MT2 model family.
• ComfyUI for the host runtime.