feat: add mtran ROS2 translation service
This commit is contained in:
324
src/mtran/README.md
Normal file
324
src/mtran/README.md
Normal file
@@ -0,0 +1,324 @@
|
||||
# mtran ROS2 英译中服务
|
||||
|
||||
`mtran` 是一个 ROS2 Humble C++ 功能包。它提供同步服务
|
||||
`/translate_en_to_zh`，请求中放入一句英语，响应中返回简体中文译文。
|
||||
|
||||
```text
|
||||
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 工作区
|
||||
|
||||
目标目录必须是：
|
||||
|
||||
```text
|
||||
smart-healthcare-2026/src/mtran
|
||||
```
|
||||
|
||||
在当前项目中，功能包已经位于以下目录：
|
||||
|
||||
```bash
|
||||
cd ~/smart-healthcare-2026/src/mtran
|
||||
```
|
||||
|
||||
复制完成后，当前目录中应直接存在 `package.xml` 和 `CMakeLists.txt`，不能再套一层
|
||||
`src/mtran`。
|
||||
|
||||
## 3. 准备依赖、sidecar 和模型
|
||||
|
||||
从 `smart-healthcare-2026/src/mtran` 执行：
|
||||
|
||||
```bash
|
||||
./dependencies/auto_install.sh
|
||||
```
|
||||
|
||||
脚本会请求 `sudo` 安装非 ROS apt 包，在 `dependencies/tools` 安装固定版本 Bun，
|
||||
从 `vendor/mtranserver` 构建当前 CPU 可运行的 sidecar，并只准备
|
||||
`en -> zh-Hans` 模型。成功结尾类似：
|
||||
|
||||
```text
|
||||
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` 执行：
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
应存在以下生成物：
|
||||
|
||||
```text
|
||||
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` 执行，而不是从包目录执行：
|
||||
|
||||
```bash
|
||||
source /opt/ros/humble/setup.bash
|
||||
PYTHONNOUSERSITE=1 colcon build --packages-select mtran
|
||||
```
|
||||
|
||||
成功时应看到：
|
||||
|
||||
```text
|
||||
Finished <<< mtran
|
||||
Summary: 1 package finished
|
||||
```
|
||||
|
||||
CMake 不会联网、安装依赖或调用 Bun。它只检查第 4 节的准备产物，然后把 sidecar、
|
||||
模型和 `records.json` 复制到 ROS2 install space。
|
||||
|
||||
## 6. 启动
|
||||
|
||||
从 `smart-healthcare-2026` 执行：
|
||||
|
||||
```bash
|
||||
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`。日志中应出现：
|
||||
|
||||
```text
|
||||
MTranServer is healthy and the en-to-zh-Hans model is warm
|
||||
```
|
||||
|
||||
## 7. 调用服务
|
||||
|
||||
保留启动终端，在第二个终端中从 `smart-healthcare-2026` 执行：
|
||||
|
||||
```bash
|
||||
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.'}"
|
||||
```
|
||||
|
||||
成功响应类似：
|
||||
|
||||
```text
|
||||
mtran.srv.TranslateEnglishToChinese_Response(
|
||||
success=True,
|
||||
translation='机器人已完成检查。',
|
||||
error=''
|
||||
)
|
||||
```
|
||||
|
||||
## 8. Service 字段和错误码
|
||||
|
||||
接口定义：
|
||||
|
||||
```srv
|
||||
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 设置：
|
||||
|
||||
```text
|
||||
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` 执行：
|
||||
|
||||
```bash
|
||||
rm -f runtime/bin/mtranserver
|
||||
rm -rf .build/mtranserver
|
||||
./dependencies/auto_install.sh
|
||||
```
|
||||
|
||||
完全重新准备，从同一目录执行：
|
||||
|
||||
```bash
|
||||
rm -rf dependencies/tools .build runtime/config models/en_zh-Hans
|
||||
rm -f runtime/bin/mtranserver
|
||||
./dependencies/auto_install.sh
|
||||
```
|
||||
|
||||
清理 ROS2 构建结果，从 `smart-healthcare-2026` 执行：
|
||||
|
||||
```bash
|
||||
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 被占用
|
||||
|
||||
检查占用者：
|
||||
|
||||
```bash
|
||||
ss -ltnp | grep ':8989'
|
||||
```
|
||||
|
||||
停止冲突进程，或为 launch 同时覆盖 `port`，并确保没有其他节点仍使用旧端口：
|
||||
|
||||
```bash
|
||||
ros2 launch mtran translator.launch.py port:=8990
|
||||
```
|
||||
|
||||
### sidecar 重启后暂时返回 `NOT_READY`
|
||||
|
||||
这是恢复阶段的预期行为。等待日志再次出现模型已预热信息后重试；不要为每次请求
|
||||
手工启动新的 sidecar。
|
||||
|
||||
### 找不到 `/translate_en_to_zh`
|
||||
|
||||
服务只在健康检查和首次预热成功后创建。先查看 launch 终端日志，再执行：
|
||||
|
||||
```bash
|
||||
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. 维护者目录参考
|
||||
|
||||
```text
|
||||
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` 为准。
|
||||
Reference in New Issue
Block a user