Hy-MT生产部署实战:vLLM一键搭建OpenAI兼容翻译API完整教程
Hy-MT生产部署实战:vLLM一键搭建OpenAI兼容翻译API完整教程
如果你想在生产环境中部署一个33语种互译的机器翻译API,腾讯混元开源的 Hy-MT 1.5(HY-MT1.5-1.8B / HY-MT1.5-7B)是最省心的选择之一:只需一条 vLLM 命令,就能把它变成一个OpenAI 兼容的翻译 API 服务,现有 OpenAI SDK 代码几乎零改动即可接入。本文带你从零完成整套部署流程,10分钟跑通。
一、Hy-MT 翻译模型是什么?
Hy-MT 1.5 包含两个规格:
| 模型 | 特点 |
|---|---|
| HY-MT1.5-1.8B | 小参数量、速度快,量化后可部署到边缘设备,适合实时翻译 |
| HY-MT1.5-7B | WMT25 冠军模型升级版,质量更强,适合高要求场景 |
两者均支持 33种语言互译 + 5种民族语言/方言,并且都支持术语干预、上下文翻译、带格式翻译三大高级能力。官方数据显示,1.8B 版在同尺寸模型中效果领先,甚至超过大部分商用翻译 API。
更多实验细节可查阅仓库中的技术报告:HY_MT1_5_Technical_Report.pdf。
二、环境准备:vLLM 版本与依赖安装
部署前只需要做两件事:
- 安装 vLLM(v0.10.0 及以上版本),低版本无法正确加载 Hy-MT 模型:
pip install "vllm>=0.10.0" - 安装 transformers,项目推荐的版本见 requirements.txt(transformers 4.56.0、accelerate 0.33.0 等):
pip install transformers==4.56.0
💡 如果环境中有 CUDA 12 以上驱动和一块 8GB+ 显存的 GPU,1.8B 模型即可流畅运行;7B 模型建议 24GB 显存或量化版本。
三、获取模型:选择 BF16 / FP8 / Int8 / Int4 版本
模型有 4 种精度可选,按显存情况对号入座:
| 模型版本 | 适用场景 | 对应启动脚本 |
|---|---|---|
| HY-MT1.5-1.8B(BF16 原版) | 显存充足、追求最高质量 | inference/run_server.sh |
| HY-MT1.5-1.8B-FP8 | 显存减半、推理加速(推荐) | inference/run_server_fp8.sh |
| HY-MT1.5-1.8B-GPTQ-Int4 | 显存紧张、端侧部署 | inference/run_server_int4.sh |
| Int8 量化版 | 介于两者之间 | inference/run_server_int8.sh |
获取模型有两种方式:
- vLLM 自动下载:在启动命令中直接填模型仓库名(如
tencent/HY-MT1.5-1.8B),首次启动会自动拉取; - ModelScope 手动下载:
modelscope download --model Tencent-Hunyuan/HY-MT1.5-1.8B,然后把本地路径填入。
四、一键启动:四步搭建 OpenAI 兼容翻译 API
第 1 步:设置模型路径
export MODEL_PATH=tencent/HY-MT1.5-1.8B
# 或本地路径
# export MODEL_PATH=/path/to/HY-MT1.5-1.8B
第 2 步:选择脚本启动服务
以 BF16 原版为例,执行 inference/run_server.sh:
bash inference/run_server.sh
脚本内部核心命令如下,端口固定为 8021,GPU 显存利用率 0.92,单卡张量并行:
python3 -m vllm.entrypoints.openai.api_server \
--host 0.0.0.0 \
--port 8021 \
--trust-remote-code \
--model ${MODEL_PATH} \
--gpu_memory_utilization 0.92 \
--tensor-parallel-size 1 \
--dtype bfloat16
不同精度版本的差异仅在末尾多一个参数:
- FP8 版:加
--kv-cache-dtype fp8 - Int8 版:加
--quantization experts_int8 - Int4 版:加
--quantization gptq_marlin
多卡部署时,把 --tensor-parallel-size 1 改为卡数即可。
⚠️ 安全提示:
--trust-remote-code会允许执行模型仓库中的代码,生产环境请确保模型来源可信(详见 README_CN.md 中的说明)。
第 3 步:发送翻译请求
服务启动成功后,仓库自带的 inference/openapi.sh 就是一条可直接运行的 curl 请求:
curl http://localhost:8021/v1/chat/completions -H 'Content-Type: application/json' -d '{
"model": "tencent/HY-MT1.5-1.8B",
"messages": [
{"role": "user", "content": [{"type": "text", "text": "将以下文本翻译为英语,注意只需要输出翻译后的结果,不要额外解释:\n今天天气真好。"}]}
],
"max_tokens": 2048,
"temperature": 0.7,
"top_p": 0.6,
"top_k": 20,
"repetition_penalty": 1.05
}'
如果你用 Python,直接用 OpenAI 官方 SDK 就能接入,参考 inference/run_openapi.py:
from openai import OpenAI
client = OpenAI(api_key="EMPTY", base_url="http://localhost:8021/v1")
resp = client.chat.completions.create(
model="tencent/HY-MT1.5-1.8B",
messages=[{"role": "user", "content": "Translate into Chinese: Hello, world!"}],
temperature=0.7, top_p=0.6,
extra_body={"top_k": 20, "repetition_penalty": 1.05},
)
print(resp.choices[0].message.content)
推荐采样参数(官方实测效果最佳):temperature=0.7、top_p=0.6、top_k=20、repetition_penalty=1.05。
第 4 步:使用正确的 Prompt 模板
翻译效果好不好,一半看模板。Hy-MT 官方提供了 5 类模板(完整版本见 README_CN.md):
- 中外互译:
将以下文本翻译为{目标语言},注意只需要输出翻译后的结果,不要额外解释:{原文} - 外外互译:
Translate the following segment into {target_language}, without additional explanation. {source_text} - 术语干预:在指令前加
参考下面的翻译:{源词} 翻译成 {目标词},可强制统一专有名词译法 - 上下文翻译:把上文放进 Prompt 开头,让译文与上下文保持一致
- 带格式翻译:用
<source></source>包裹原文,要求保留<sn></sn>等格式标签
💡 注意:语言名必须写全称(如"英语"、"English",而不是 "en")。
五、生产部署避坑清单
| 问题 | 解决方案 |
|---|---|
| 启动报错、模型加载失败 | 检查 vLLM 版本,必须 ≥ 0.10.0 |
| FP8 模型显存没降下来 | 确认使用了 FP8 量化模型,并带 --kv-cache-dtype fp8 参数 |
| 端口 8021 被占用 | 修改脚本中 --port 为其他端口,同步更新请求地址 |
| 多卡部署速度未提升 | 将 --tensor-parallel-size 设为 GPU 数量 |
| 译文出现重复 | 保持 repetition_penalty=1.05,不要擅自调高 temperature |
六、写在最后
到这里,你已经拥有了一个标准 OpenAI 协议、33 语种互译、支持术语干预的生产级翻译服务——上游业务代码只需替换 base_url 和 model 两个字段就能接入,后续想升级模型、扩缩容也只需重跑一条启动命令。
📌 仓库核心文件速查:
- 部署脚本:inference/
- 中文文档:README_CN.md
- 微调教程:finetune/README_CN.md
- LLaMA-Factory 训练配置:train/llama_factory_support/example_configs/hunyuan_full.yaml
