모델을 이해했다면 이제 실제로 구동해 볼 차례입니다. 사용 목적에 따라 네 가지 경로를 선택할 수 있습니다. 간단한 테스트에는 transformers, 상시 서비스나 API 제공이 목적이라면 vLLM 또는 SGLang을 추천합니다. 만약 리소스가 제한된 로컬 환경이라면 GGUF 변종이 제공되는 1.8B·7B 모델과 llama.cpp 조합이 가장 현실적인 선택지입니다.

시작 전 확인: 컨텍스트와 추천 샘플링 설정

원활한 추론을 위해 공식 제원과 권장 파라미터를 먼저 확인하세요.

• 최대 컨텍스트(max_context): 8192 토큰
• 시스템 프롬프트: Hy-MT2는 별도의 기본 system prompt를 사용하지 않습니다. 모든 번역 지시는 user 메시지에 직접 포함시켜야 합니다.
• 30B-A3B 추천 파라미터:

{
  "temperature": 0.7,
  "top_p": 1.0,
  "top_k": -1,
  "repetition_penalty": 1.0,
  "max_tokens": 4096
}

참고로 1.8B와 7B 모델은 top_p: 0.6, top_k: 20, repetition_penalty: 1.05를 권장합니다. 30B-A3B는 이보다 조금 더 유연한(기본값에 가까운) 샘플링 설정을 사용한다는 점이 특징입니다.

transformers로 빠르게 시작하기

transformers>=5.6.0 환경에서 아래 코드를 통해 즉시 실행할 수 있습니다. 공식 예제를 바탕으로 영문장을 한국어로 번역하는 시나리오로 재구성했습니다.

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

model_path = "tencent/Hy-MT2-30B-A3B"

# 토크나이저 로드
tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)

# 모델 로드
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)
model.eval()

# 추론 예제
prompt = "Translate the following text into Korean. Note that you should only output the translated result without any additional explanation:\n\nThe weather is really nice today."
messages = [{"role": "user", "content": prompt}]
inputs = tokenizer.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=4096,
    )
response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True)
print(response)

trust_remote_code=True 옵션이 토크나이저와 모델 로드 양쪽에 모두 적용되어야 한다는 점에 유의하세요. 또한 프롬프트 내 언어 명칭은 프롬프트와 동일한 언어로 작성해야 합니다. 예를 들어 영어 프롬프트를 쓴다면 대상 언어는 Korean으로 표기합니다.

vLLM으로 고성능 서빙 구축하기

vLLM을 통해 모델을 서빙하려면 효율적인 파싱을 위해 소스 빌드 과정이 필요합니다.

uv venv --python 3.12 --seed --managed-python
source .venv/bin/activate
git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install --editable . --torch-backend=auto

빌드 완료 후 다음과 같이 서버를 기동합니다.

vllm serve tencent/Hy-MT2-30B-A3B --tensor-parallel-size 1

서버가 정상적으로 실행되면 http://localhost:8000/v1/chat/completions 엔드포인트를 통해 OpenAI 호환 요청을 보낼 수 있습니다. 자세한 요청 예제는 실전 예제 글을 참고하세요.

SGLang으로 추론 최적화하기

SGLang 역시 동일한 이유로 소스 설치를 권장합니다.

git clone https://github.com/sgl-project/sglang
cd sglang
pip3 install pip --upgrade
pip3 install "transformers>=5.6.0"
pip3 install -e "python"

서버 기동 명령은 다음과 같습니다.

python3 -m sglang.launch_server --model tencent/Hy-MT2-30B-A3B --tp 1

llama.cpp와 GGUF로 로컬 실행하기

앞서 언급했듯 30B-A3B는 GGUF 변종이 없으므로, llama.cpp를 통한 실행은 1.8B 또는 7B 모델을 대상으로 합니다. 특히 1.8B의 2bit/1.25bit GGUF 모델은 텐센트의 STQ 커널에 의존하므로, llama.cpp PR #22836이 반영된 최신 빌드를 사용해야 정상적으로 동작합니다.

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build --config Release

준비가 되었다면 아래 명령어로 번역을 실행합니다.

./build/bin/llama-completion \
  --model model.gguf \
  -p \"Translate the following segment into Chinese, without additional explanation：Hello\" \
  --jinja \
  -ngl 0 \
  -n 64 -st

--jinja는 챗 템플릿 적용을 위해, -ngl은 GPU 오프로드 레이어 수를 지정하는 옵션입니다. CPU 전용으로 실행하려면 -ngl 0을, GPU 가속을 사용하려면 값을 높여 설정하세요. 성능 측정을 위한 벤치마크는 다음 명령어로 수행합니다.

./build/bin/llama-bench -m model_zoo/model.gguf -ngl 0

모델 경량화를 위한 양자화와 AngelSlim

Hy-MT2는 다양한 환경에 대응하기 위해 FP8, GGUF, 극한 양자화 등 여러 변종을 제공합니다.

환경 및 목적	추천 선택지
VRAM이 제한적인 GPU 서버 서빙	Hy-MT2-30B-A3B-FP8, Hy-MT2-7B-FP8, Hy-MT2-1.8B-FP8
CPU 기반 또는 가벼운 로컬 실행	Hy-MT2-7B-GGUF, Hy-MT2-1.8B-GGUF
온디바이스 또는 초저용량 환경	Hy-MT2-1.8B-2bit-GGUF, Hy-MT2-1.8B-1.25bit-GGUF(용량 440MB, 속도 1.5배)

만약 제공되는 모델 외에 직접 양자화를 수행해야 한다면, 텐센트가 공개한 압축 툴킷인 AngelSlim(저장소 바로가기)을 활용해 보세요. 범용 양자화부터 저비트 양자화, 추측 샘플링까지 통합적으로 관리할 수 있는 강력한 도구입니다.

실행 환경이 준비되었다면, 이제 어떤 프롬프트로 번역 품질을 극대화할 수 있는지 다음 글에서 살펴보겠습니다.