企业官网建设流程全解析

LibreTranslate 离线部署完整指南：在断网机器上跑通本地翻译 API

【免费下载链接】LibreTranslateFree and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.项目地址: https://gitcode.com/GitHub_Trending/li/LibreTranslate

先给结论：LibreTranslate 可以完全离线部署，运行时零外网请求；磁盘占用随语言对数量线性增长，只装一对语言就是最小占用。本文写给需要在一台没有网络的机器上交付翻译服务的开发与运维人员。

LibreTranslate 是什么：模型装好后就不再碰外网的自托管翻译

LibreTranslate 是开源自托管翻译引擎：把 Argos Translate 的离线语言模型装进本地，对外提供 REST API 和 Web 页面。核心原理一句话——模型文件落到本机磁盘后，翻译推理全程在本机完成，一条请求都不发往外网。Web 层是 Flask（锁定 2.2.5），翻译引擎是 argos-translate-lt（锁定 1.12.1），要求 Python 3.8+，见 pyproject.toml。

部署形态对比：先决定走哪条路，再动手

本地直跑是后两者的基础：便携版是它的打包形态，容器化是它的镜像形态。docker/Dockerfile 用with_models、models两个构建参数在 build 期装好模型，镜像本身即是离线包；不传models则装全量语言模型，离线场景务必只传需要的短码。

离线部署最短路径：环境、模型、启动三步

第一步，建环境装依赖。这步按 pyproject.toml 拉齐全部运行时依赖：

git clone https://gitcode.com/GitHub_Trending/li/LibreTranslate cd LibreTranslate python -m venv venv && source venv/bin/activate pip install .

pip 以Successfully installed收尾即成功。

第二步，只装需要的语言对。--load_only_lang_codes用 ISO 639-1 短码、逗号分隔；zh会被 libretranslate/language.py 自动映射为zh-Hans（zt映射zh-Hant）：

python scripts/install_models.py --load_only_lang_codes "en,zh"

日志出现Loaded support for 2 languages (2 models total)!即成功。模型文件落在用户主目录的~/.local下（Docker 镜像里是/home/libretranslate/.local），这是唯一需要随机器离线搬运的部分。

第三步，起服务。默认监听 127.0.0.1 的 5000 端口：

python main.py --host 127.0.0.1 --port 5000

日志出现Running on http://127.0.0.1:5000即成功。启动时程序会先尝试刷新模型索引，断网时 libretranslate/init.py 输出Cannot update models (normal if you're offline)，属预期行为，不是错误。

把体积压到最小：只装用得到的

• 按语言对裁剪：占用与装的对数成正比，只装实际用到的对是最有效的瘦身手段；全装则体积最大。
• 依赖做成离线包：有网机器下载 wheel，目标机装本地目录：

pip freeze > requirements.txt pip download -r requirements.txt -d dependencies/ --only-binary=:all: pip install --no-index --find-links=./dependencies/ -r requirements.txt

• 三个离线开关核对：libretranslate/default_values.py 全部走LT_前缀环境变量——UPDATE_MODELS保持默认False（不自动更新模型）、SHARED_STORAGE保持默认memory://（内存计数，不用部署 Redis）、API_KEYS_REMOTE留空。
• 模型更新：联网机执行python scripts/install_models.py --update，把~/.local模型目录压缩带走即更新包。

部署后自检与高频坑排障

验证按三步走：

1. 健康检查：curl http://127.0.0.1:5000/health，返回{"status": "ok"}为通过 ✅
2. 真实调一次翻译：

curl -X POST http://127.0.0.1:5000/translate \ -d "q=Hello world&source=en&target=zh"

返回translatedText与detectedLanguage即接口可用。

3. 断开网络重测一遍，响应与在线时一致，离线闭环成立。

⚠️ 高频坑（现象 → 原因 → 解法）：

• 报Model not found或语言不受支持：--load-only（起服务时）或--load_only_lang_codes（装模型时）的短码与已装模型对不上 → 核对两边短码一致，并确认模型目录可读。
• 翻译慢：--threads默认 4，按 CPU 核数调整；生产环境关--debug。
• 启动日志刷Cannot update models：init.py的boot()吞掉联网异常，离线重启不受影响 → 忽略即可。
• 依赖冲突：离线缓存加--no-index坚持用，别与在线装包混着来。

总结与后续方向

本地、容器、便携三条路任选其一，模型只装用得到的语言对，断网内网机上就有自己的翻译服务。可跟进的两个方向：模型量化进一步压缩体积，纯前端 WebAssembly 离线部署。

【免费下载链接】LibreTranslateFree and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.项目地址: https://gitcode.com/GitHub_Trending/li/LibreTranslate