Extensions/comfyui-hymt2

ComfyUI Extension

comfyui-hymt2

ComfyUI custom nodes for Tencent's Hy-MT2 translation model family (1.8B / 7B / 30B-A3B).

By aadebuger·Created 3 months ago·Updated 3 months ago· 0

aadebuger/ComfyUI-HyMT2

Nodes—

On cloudLocal install

Stars0

Updated3 months ago

Readme

<h1 align="center">ComfyUI-HyMT2</h1> <p align="center"> <strong>Translation nodes for ComfyUI, powered by Tencent's Hy-MT2 model family.</strong><br> <em>38 languages · 7 prompt templates · streaming-friendly · no fine-tuning needed.</em> </p> <p align="center"> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green.svg" alt="Apache 2.0"></a> <a href="https://huggingface.co/tencent/Hy-MT2-1.8B"><img src="https://img.shields.io/badge/🤗-Hy--MT2-yellow.svg" alt="HF model"></a> <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.1.2-orange.svg" alt="Version"></a> </p>

$ 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.

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.

<details> <summary>Full list (English / Chinese)</summary>

| 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 | 粤语 |

</details>

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.