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.
---
```bash
$ 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](#features)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Nodes](#nodes)
- [CLI tools](#cli-tools)
- [Prompt templates](#prompt-templates)
- [Model variants](#model-variants)
- [Languages](#languages)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [License](#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](https://huggingface.co/tencent/Hy-MT2-1.8B): 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](CHANGELOG.md) 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
```bash
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](INSTALL_NOTES.md#1-transformers-version-pin--likely-blocker)
> 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:
```bash
grep "ComfyUI-HyMT2" /path/to/comfy.log
# expected: [ComfyUI-HyMT2] v0.1.2 loaded from ...
```
And confirm both nodes are registered:
```bash
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
```bash
# 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](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`](cli/hymt2_cli.py) | Single-shot translation. Inline text, file path, or stdin. |
| [`hymt2_batch.py`](cli/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:
```bash
# ~/.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):
```text
# 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:
```bash
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**.
```bash
# 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
```bash
# 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](INSTALL_NOTES.md).
## Development
```bash
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](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](https://huggingface.co/tencent/Hy-MT2-1.8B).
## Acknowledgments
- [Tencent Hunyuan team](https://huggingface.co/tencent) for the Hy-MT2 model family.
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) for the host runtime.