# ComfyUI-HyMT2 — CLI tools

Two helpers for running Hy-MT2 through a remote ComfyUI server without
opening the UI.

| Script | Style | Purpose |
|---|---|---|
| `hymt2_cli.py`   | v2.0 套路 A/B | One-shot translation. |
| `hymt2_batch.py` | v2.0 套路 C   | JSON batch with resumable runs. |

Both default to `127.0.0.1:8188`; point them at your GPU server with
`--ip 10.8.0.12` (or `--server 10.8.0.12:8188`).

For best startup time we recommend calling the venv's python directly
(per v2.0 §2.4):

```bash
PY=/mnt/modelall/ComfyUI/.venv/bin/python
```

## 1. `hymt2_cli.py` — single shot

### Inline text

```bash
$PY hymt2_cli.py "今天天气真好,我们去散步吧。" \
    --target English --prompt-lang en --ip 10.8.0.12
```

### Read from a file

```bash
$PY hymt2_cli.py /path/to/article.zh.md \
    --target English --prompt-lang en --ip 10.8.0.12 \
    --out /path/to/article.en.md
```

### Read from stdin

```bash
cat article.zh.md | $PY hymt2_cli.py - \
    --target Japanese --prompt-lang en --ip 10.8.0.12
```

### With a glossary

```bash
cat > /tmp/glossary.txt <<'EOF'
# tech glossary
endpoint => endpoint
webhook => webhook
token    => token
EOF

$PY hymt2_cli.py "调用 API 时,请在 endpoint 后附 token" \
    --target English --prompt-lang en --ip 10.8.0.12 \
    --terminology /tmp/glossary.txt
```

### With background context

```bash
$PY hymt2_cli.py "本判决系终审判决。" \
    --target English --prompt-lang en --ip 10.8.0.12 \
    --background "Closing paragraph of a Chinese administrative-litigation judgment."
```

### With a style descriptor

```bash
$PY hymt2_cli.py "Hi guys, this is a great product!" \
    --target Chinese --prompt-lang zh --ip 10.8.0.12 \
    --style "正式书面语"
```

### Useful flags

| Flag | Default | Notes |
|---|---|---|
| `--target` | `English` | Full language name. EN names with `--prompt-lang en`, ZH names with `--prompt-lang zh`. |
| `--prompt-lang` | `en` | Selects the EN or ZH prompt template. |
| `--model-path` | `tencent/Hy-MT2-1.8B` | Use `tencent/Hy-MT2-7B` for the 7B model. |
| `--gpu` | `0` | Maps to `cuda:N`. |
| `--temperature / --top-p / --top-k / --repetition-penalty / --max-new-tokens` | model-card defaults | Override the sampling params. |
| `--seed` | `-1` | Set a value for reproducible runs. |
| `--dump-workflow PATH` | — | Write the API workflow JSON for UI loading. |
| `--ws-recv-timeout` | `600` s | Cold-load tolerance for the WebSocket idle timeout (v2.0 §10). |
| `--force-reload` | off | Bypass the loader cache. |

## 2. `hymt2_batch.py` — batch translation

Input formats accepted (autodetected):

```jsonc
// (a) list of strings
[
  "今天天气真好",
  "明天去散步吧"
]

// (b) list of {id, text}
[
  { "id": "weather_1", "text": "今天天气真好" },
  { "id": "weather_2", "text": "明天去散步吧" }
]

// (c) dict of id → text
{
  "weather_1": "今天天气真好",
  "weather_2": "明天去散步吧"
}
```

Each item produces one output file `<out-dir>/<sanitized-id>.json` containing:

```json
{
  "id": "weather_1",
  "source": "今天天气真好",
  "translation": "The weather is really nice today.",
  "target_lang": "English",
  "prompt_lang": "en",
  "model_path": "tencent/Hy-MT2-1.8B"
}
```

### Resumable batch run

```bash
$PY hymt2_batch.py /mnt/modelall/in/ai_news_vocab.json \
    --out-dir /mnt/modelall/out/hymt2_ai_news \
    --target Japanese --prompt-lang en \
    --ip 10.8.0.12 \
    --limit 100 \
    --dump-workflow /mnt/modelall/tmp/hymt2_first.json
```

Re-run the same command — already-finished files are skipped. Pass `--force`
to retranslate everything.

### Apply a glossary to every item

```bash
$PY hymt2_batch.py words.json \
    --out-dir /mnt/modelall/out/hymt2_words \
    --target English --prompt-lang en --ip 10.8.0.12 \
    --terminology /mnt/modelall/in/glossary.txt
```

## Debugging tips

1. `--dump-workflow /tmp/wf.json` and load that into the ComfyUI UI — easiest
   way to confirm the prompt was built the way you expected.
2. On the server: `tail -f /mnt/modelall/tmp/comfy.log` while the CLI runs
   to see `[hymt2/translate]`, `[hymt2/gen]`, and VRAM diagnostic lines.
3. If the WebSocket disconnects on a cold first-load, bump `--ws-recv-timeout`
   to `1200` or higher.