自托管离线翻译部署手记：让 LibreTranslate 在断网服务器上跑起来

自托管离线翻译部署手记让 LibreTranslate 在断网服务器上跑起来【免费下载链接】LibreTranslateFree and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.项目地址: https://gitcode.com/GitHub_Trending/li/LibreTranslate把 LibreTranslate 部署到一台完全断网的服务器上全程 40 分钟零报错。这篇文章是围绕自托管离线翻译的一份完整部署手记我会用实际踩过的坑讲清如何给这个免费开源、可完全离线运行的机器翻译 API 准备语言模型、离线化依赖包并完成配置与验证。全程只有两段关键命令新手照着敲也能落地。起因一次计划内的断网公司把一批业务系统迁进新的隔离机房要求所有对外数据请求一律禁止。别的服务都好说唯独翻译功能卡住了——旧方案是调用云厂商的翻译接口断网等于断翻译。排查之后我们把目光落在 LibreTranslate 上它自带语言模型翻译在本地完成唯一需要网络的是下载模型和安装依赖这两个一次性动作。换句话说只要在联网环境把东西备齐断网环境就能用。这篇手记就是那次落地的全过程。一、离线翻译解决的问题比想象的多有人觉得离线部署只是断网可用实际收益远不止这一点数据主权原文、译文全程不出内网敏感文本不需要交给任何第三方零网络延迟请求在本地推理省去网络往返慢不下来成本可控没有按字符计费、没有配额焦虑跑多少都是自己的算力完全自主可控模型版本、依赖版本、启动参数都由你决定别人升级不影响你。对绝大多数人来说最后一条才是真正的长期价值——翻译能力变成一种可维护的基础设施而不是一个不可控的黑盒。二、先认清它的离线拼图LibreTranslate 的离线能力建立在模块化设计上。看pyproject.toml就能摸清骨架组件作用关键配置位置argos-translate-lt核心翻译引擎负责加载本地模型libretranslate/language.pyFlaskWeb 服务框架暴露 HTTP APIlibretranslate/app.pylangdetect语言自动检测libretranslate/detect.pyexpiringdict翻译结果缓存libretranslate/cache.py值得注意的一点libretranslate/default_values.py里LT_UPDATE_MODELS的默认值本来就是False——也就是说默认情况下它不会主动联网更新模型离线运行不需要改任何代码这是设计好的行为。语言模型放在固定目录一个语言对对应一个.argosmodel文件Linux / macOS~/.local/share/argos-translate/packages/WindowsC:\Users\用户名\AppData\Roaming\argos-translate\packages\记住这两个路径后面排查模型找不到全靠它。三、有网时把种子备齐离线部署的本质是把联网环境里能下载的东西提前变成可以搬运的文件。需要搬运的有两样语言模型、Python 依赖包。第一步获取模型只挑你需要的模型不用全下载一个中英互译也就几百 MB。scripts/install_models.py提供了按语言筛选的入口git clone https://gitcode.com/GitHub_Trending/li/LibreTranslate cd LibreTranslate # 只下载中英互译所需的模型 python scripts/install_models.py --load_only_lang_codes en,zh白话解释--load_only_lang_codes后面跟逗号分隔的语言代码脚本会只下载代码集合内互相翻译的模型。比如只想做中英互译就传en,zh想覆盖欧洲主要语种就传en,fr,es,de,it。下载完成后模型文件就在上面说的packages/目录里把这个目录整个拷走即可。第二步把依赖打包成离线可安装的形式依赖不打包到了断网机器上pip install会直接失败。用pip wheel把所有依赖连同项目本身打成 wheel 包# 在联网机器上执行 pip wheel . -w offline_deps/白话解释pip wheel会把pyproject.toml里声明的所有依赖Flask、argos-translate-lt、langdetect 等下载并编译成.whl文件放进offline_deps/目录。这个目录就是你的离线安装包拷到断网机器上即可。四、无网时安装、配置、启动到了目标机器先离线安装依赖再本地安装项目本体pip install --no-index --find-links./offline_deps/ .--no-index表示禁止访问 PyPI--find-links指定从本地目录找包。装完依赖后把之前备好的packages/模型目录放到对应位置就可以启动了。配置检查清单对照libretranslate/default_values.py确认这几项处于离线友好状态LT_UPDATE_MODELS保持默认False避免启动时尝试联网更新模型LT_SHARED_STORAGE使用默认的memory://不依赖 Redis 等外部存储通过LT_LOAD_ONLY或启动参数--load-only限定只加载你下载的语言减少内存占用启动参数用--host 0.0.0.0 --port 5000对外提供服务--threads按机器核数调整。启动命令python main.py --host 0.0.0.0 --port 5000 --load-only en,zh日志里看到Loaded support for 2 languages之类输出说明模型加载成功服务已经在线。五、验证从能跑到跑得对服务起来了不代表一切正常我按下面清单逐项验证启动日志无网络连接错误离线环境最常见的问题日志显示的已加载语言数量与下载的模型一致翻译接口返回正确结果语言检测接口可用首次翻译响应时间在 1 秒内后续翻译明显更快有缓存。用两个 curl 就能完成核心功能验证# 翻译Hello world - 你好世界 curl -X POST http://127.0.0.1:5000/translate \ -H Content-Type: application/x-www-form-urlencoded \ -d qHello worldsourceentargetzh # 语言检测识别输入文本是什么语言 curl -X POST http://127.0.0.1:5000/detect \ -H Content-Type: application/x-www-form-urlencoded \ -d qBonjour le monde返回的 JSON 里能拿到译文和置信度到这一步离线翻译链路就算真正打通了。六、踩坑记录三件小事整个过程中真正卡住我的只有三个问题提前说清楚能省不少时间模型路径不对症状是启动即报模型缺失。多半是packages/目录没放在正确位置或者目录权限不足。检查上面说的两个默认路径把模型目录放进去即可。依赖版本打架症状是pip install时版本冲突报错。离线机器上的 Python 版本最好与打包环境保持一致差异越大越容易翻车。内存不够症状是启动缓慢甚至被杀进程。--load-only只加载必要语言对比一次全量加载省得多机器内存紧张时宁可少加载几种语言。七、收尾前两条值得做的调整第一如果目标环境有 Docker可以把模型 代码 依赖整体打进镜像部署就变成一条docker run命令后续迁移也省事。项目里docker/Dockerfile已给出基础模板在此基础上把模型目录 COPY 进去即可。第二离线不代表可以裸奔。libretranslate/security.py里提供了 API 密钥、访问来源限制等能力内网部署同样建议开启--api-keys做访问控制并定期清理翻译缓存避免敏感内容长期滞留。写在最后LibreTranslate 的离线部署说到底是三个动作的排列组合有网时备模型、备依赖无网时安装、配置、验证。做完一次之后你会发现它没有想象中复杂——所有的联网依赖都集中在准备阶段运行阶段它就是一个安静待在本地、随叫随到的翻译服务。下一次再遇到必须在隔离网络里做翻译的需求不用慌按这份手记从头走一遍就行。从今天起把翻译能力放在自己手里比什么都踏实。【免费下载链接】LibreTranslateFree and Open Source Machine Translation API. Self-hosted, offline capable and easy to setup.项目地址: https://gitcode.com/GitHub_Trending/li/LibreTranslate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考