mtran ROS2 英译中服务
mtran 是一个 ROS2 Humble C++ 功能包。它提供同步服务
/translate_en_to_zh，请求中放入一句英语，响应中返回简体中文译文。
ROS2 Service 请求
|
v
mtran_bridge_node (C++ / libcurl)
|
v
常驻 MTranServer sidecar (Bergamot WASM / en_zh-Hans 模型)
MTranServer 随 ros2 launch 启动并保持常驻。模型只在启动阶段预热，不会在每次
Service 调用时临时启动或重新加载。本包不提供话题接口、批量翻译、多语言选择、
HTML 翻译或自动语言检测。
1. 环境前提
- Ubuntu 22.04
- ROS2 Humble，且由使用者提前安装
- CPU 架构为
x86_64或aarch64 - 首次准备阶段可访问 apt、npm registry 和 Mozilla 模型站点
- 建议预留约 1.5 GB 临时构建空间
dependencies/auto_install.sh 只安装非 ROS 依赖、构建 MTranServer、下载并校验
英译中模型。脚本不会安装 ROS2，也不会运行 colcon build。 ROS2 和 colcon
构建由工作区使用者负责。
2. 放入 ROS2 工作区
目标目录必须是：
smart-healthcare-2026/src/mtran
在当前项目中，功能包已经位于以下目录：
cd ~/smart-healthcare-2026/src/mtran
复制完成后，当前目录中应直接存在 package.xml 和 CMakeLists.txt，不能再套一层
src/mtran。
3. 准备依赖、sidecar 和模型
从 smart-healthcare-2026/src/mtran 执行：
./dependencies/auto_install.sh
脚本会请求 sudo 安装非 ROS apt 包，在 dependencies/tools 安装固定版本 Bun，
从 vendor/mtranserver 构建当前 CPU 可运行的 sidecar，并只准备
en -> zh-Hans 模型。成功结尾类似：
Preparation complete.
Next: cd .../smart-healthcare-2026 && colcon build --packages-select mtran
Then: source install/setup.bash && ros2 launch mtran translator.launch.py
4. 检查准备结果
仍从 smart-healthcare-2026/src/mtran 执行：
file runtime/bin/mtranserver
test -s runtime/config/records.json
ls -lh models/en_zh-Hans
python3 dependencies/verify_runtime_data.py \
--records runtime/config/records.json \
--model-dir models/en_zh-Hans
应存在以下生成物：
runtime/bin/mtranserver
runtime/config/records.json
models/en_zh-Hans/model.enzh.intgemm.alphas.bin
models/en_zh-Hans/lex.50.50.enzh.s2t.bin
models/en_zh-Hans/srcvocab.enzh.spm
models/en_zh-Hans/trgvocab.enzh.spm
校验器会根据 records.json 中的 decompressedHash 和 decompressedSize 验证四个
模型文件。校验失败时不要继续构建，重新运行准备脚本。
5. 构建 ROS2 包
从工作区根目录 smart-healthcare-2026 执行，而不是从包目录执行：
source /opt/ros/humble/setup.bash
PYTHONNOUSERSITE=1 colcon build --packages-select mtran
成功时应看到：
Finished <<< mtran
Summary: 1 package finished
CMake 不会联网、安装依赖或调用 Bun。它只检查第 4 节的准备产物，然后把 sidecar、
模型和 records.json 复制到 ROS2 install space。
6. 启动
从 smart-healthcare-2026 执行：
source /opt/ros/humble/setup.bash
source install/setup.bash
PYTHONNOUSERSITE=1 ros2 launch mtran translator.launch.py
launch 同时启动 MTranServer 和 mtran_bridge_node。节点会等待 sidecar 健康检查成功，
再执行一次内部英译中预热；只有预热完成后才发布 /translate_en_to_zh。日志中应出现：
MTranServer is healthy and the en-to-zh-Hans model is warm
7. 调用服务
保留启动终端，在第二个终端中从 smart-healthcare-2026 执行：
source /opt/ros/humble/setup.bash
source install/setup.bash
ros2 service call /translate_en_to_zh \
mtran/srv/TranslateEnglishToChinese \
"{text: 'The robot has completed the inspection.'}"
成功响应类似：
mtran.srv.TranslateEnglishToChinese_Response(
success=True,
translation='机器人已完成检查。',
error=''
)
8. Service 字段和错误码
接口定义：
string text
---
bool success
string translation
string error
text：非空英语普通文本，最多 512 个 UTF-8 字符。success：翻译成功时为true。translation：成功时为简体中文；失败时始终为空。error：成功时为空，失败时为下列稳定错误码之一。
| 错误码 | 含义 |
|---|---|
INVALID_INPUT |
输入为空或仅含空白。 |
INPUT_TOO_LONG |
输入超过 512 个字符。 |
NOT_READY |
sidecar 未就绪、连接中断或模型正在重新预热。 |
TIMEOUT |
单次翻译超过 30 秒。 |
UPSTREAM_ERROR |
HTTP 传输或 MTranServer 状态异常。 |
INVALID_RESPONSE |
sidecar 返回的 JSON 缺少字符串 result。 |
节点使用单线程 executor，同一时刻串行处理请求，不考虑多句批处理。
9. 常驻预热和离线运行
launch 固定向 sidecar 设置：
MT_HOST=127.0.0.1
MT_PORT=8989
MT_ENABLE_UI=false
MT_OFFLINE=true
MT_CHECK_UPDATE=false
MT_WORKER_IDLE_TIMEOUT=86400
MT_CACHE_SIZE=100
准备和 colcon build 完成后，运行阶段不需要网络。模型 worker 的空闲时间为 24 小时，
桥接节点每 12 小时发送一次内部保温翻译。sidecar 异常退出时 launch 会在 2 秒后重启；
恢复期间服务返回 NOT_READY，健康检查和重新预热成功后自动恢复。
10. x86_64 和 ARM64
C++ 源码和模型数据不区分 CPU 架构。auto_install.sh 在运行机器上本机构建 sidecar：
uname -m为x86_64时生成 x86-64 ELF。uname -m为aarch64时生成 ARM64 ELF。
推荐把同一个包目录复制到 ARM64 Ubuntu 22.04 目标机后，在目标机执行准备脚本和
colcon build。本包不提供 x86_64 主机到 aarch64 的交叉构建流程。已经下载的
records.json 和模型可以跨架构复制，但 runtime/bin/mtranserver 必须与目标机架构
匹配；脚本检测到不匹配时会重新构建。
11. 重复安装和清理
准备脚本可重复执行。它会复用以下有效产物：
- 版本正确的工作区 Bun
- 架构正确的 sidecar
- 哈希和大小正确的四个模型文件
只重新构建 sidecar，从 smart-healthcare-2026/src/mtran 执行：
rm -f runtime/bin/mtranserver
rm -rf .build/mtranserver
./dependencies/auto_install.sh
完全重新准备，从同一目录执行：
rm -rf dependencies/tools .build runtime/config models/en_zh-Hans
rm -f runtime/bin/mtranserver
./dependencies/auto_install.sh
清理 ROS2 构建结果，从 smart-healthcare-2026 执行：
rm -rf build/mtran install/mtran log
colcon build --packages-select mtran
12. 故障排查
提示缺少 ROS2 Humble
脚本不会安装 ROS2。确认 /opt/ros/humble 存在，并安装错误信息列出的
ros-humble-* 包。然后重新执行准备脚本。
apt 安装失败
检查 Ubuntu 软件源、代理、DNS 和 sudo 权限。apt 成功后可直接重复运行脚本，
已完成的本地步骤会被复用。
Bun 或 npm registry 失败
检查到 https://registry.npmjs.org/ 的网络连接。工具安装位置是
dependencies/tools；删除该目录后重跑脚本可强制重装 Bun 1.3.14。
模型缺失或哈希不匹配
从包根运行第 4 节的 verify_runtime_data.py。确认 Mozilla records 与附件 CDN 可访问，
然后删除 runtime/config 和 models/en_zh-Hans 并重跑准备脚本。脚本只会把完整校验
后的临时下载移动到最终位置。
端口 8989 被占用
检查占用者：
ss -ltnp | grep ':8989'
停止冲突进程，或为 launch 同时覆盖 port，并确保没有其他节点仍使用旧端口：
ros2 launch mtran translator.launch.py port:=8990
sidecar 重启后暂时返回 NOT_READY
这是恢复阶段的预期行为。等待日志再次出现模型已预热信息后重试；不要为每次请求 手工启动新的 sidecar。
找不到 /translate_en_to_zh
服务只在健康检查和首次预热成功后创建。先查看 launch 终端日志，再执行：
ros2 service list | grep translate_en_to_zh
ros2 service type /translate_en_to_zh
还要确认调用终端已经 source /opt/ros/humble/setup.bash 和当前工作区
install/setup.bash。
Python 用户目录包冲突
若 colcon 或 launch 报告用户目录中的 setuptools、packaging 版本冲突，在命令前
保留 PYTHONNOUSERSITE=1，使 ROS2 Humble 使用 Ubuntu 系统 Python 包。
13. 维护者目录参考
mtran/
├── CMakeLists.txt ROS2 构建、准备检查和安装映射
├── package.xml 包元数据和 ROS 依赖
├── dependencies/
│ ├── auto_install.sh 唯一联网准备入口
│ ├── dependencies.txt 完整依赖和下载来源清单
│ ├── verify_runtime_data.py records/模型完整性校验
│ └── tools/ 工作区 Bun 和缓存（生成）
├── vendor/mtranserver/ 固定提交 f5672a9 的上游源码
├── .build/mtranserver/ sidecar 构建目录（生成）
├── runtime/bin/mtranserver 本机 sidecar（生成）
├── runtime/config/records.json Mozilla 模型索引（生成）
├── models/en_zh-Hans/ 四个英译中模型文件（生成）
├── include/mtran/ C++ 头文件
├── src/ C++ 实现
├── srv/ ROS2 Service 定义
├── launch/ sidecar 与桥接节点启动文件
├── config/ ROS2 参数
└── test/ C++、shell 和 Python 测试
依赖版本、来源和生成/提交边界以 dependencies/dependencies.txt 为准。