LibreTranslate 自托管翻译服务完整上手：7 个勾选项跑通离线部署

LibreTranslate 自托管翻译服务完整上手：7 个勾选项跑通离线部署

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

LibreTranslate 是一个免费开源、可完全自托管的机器翻译 API，翻译引擎由开源的 Argos Translate 驱动，不依赖 Google、Azure 等任何商业服务，断网也能用。如果你受够了云端翻译的限额、账单和数据外流，这篇文章会带你用"打勾通关"的方式，从零跑通一套属于你自己的离线翻译服务——每完成一步都有可验证的结果，全程约 15 分钟。

它到底是什么，凭什么值得自己搭？

简单说，LibreTranslate 就是一套"翻译的 Web 服务"：装上之后，它在本机开一个 HTTP 端口，网页界面和 REST API 同时可用。你把文字发过去，它把译文返回来，仅此而已。但"仅此而已"的背后藏着三个实打实的价值：

• 数据主权：所有翻译都在你的机器上完成，敏感内容不出内网。
• 零费用：没有按字符计费，没有免费额度用尽后的涨价。
• 完全可控：装哪些语言、给谁用、限不限制频次，都是你说了算。

它和普通云端 API 的本质区别，可以看这张表：

对比维度	LibreTranslate（自托管）	商业云端翻译 API
数据流向	全程本地，不出内网	必须上传到厂商服务器
费用	一次性投入（硬件+模型），无按量计费	按字符/请求持续付费
网络依赖	部署后可完全离线	每次调用都依赖外网
语言模型	按需下载，可离线拷贝	厂商锁定，不可移植
定制能力	开源可改，可量化、可裁剪	仅限厂商提供的选项

一句话：如果你是个人开发者、内网团队，或者对数据敏感的业务场景，自托管是比云端更省心、更省钱的选择。

第 1 关：装好运行环境 ✅

LibreTranslate 是纯 Python 项目（要求 Python 3.8+），最省事的安装方式是直接通过 pip 装发布版：

pip install libretranslate

想尝鲜最新代码，也可以拉取仓库再以可编辑模式安装：

git clone https://gitcode.com/GitHub_Trending/li/LibreTranslate cd LibreTranslate pip install -e .

验证结果：终端执行libretranslate --help（或python main.py --help），能看到一长串启动参数说明，说明安装成功。

第 2 关：第一次启动，见证模型自动下载 ✅

翻译能力的"大脑"是语言模型。首次启动时，LibreTranslate 会检查本地模型，缺失就自动从网络下载：

libretranslate --host 127.0.0.1 --port 5000

验证结果：日志中出现Loaded support for X languages (Y models total)!，然后浏览器打开http://127.0.0.1:5000，你会看到一个干净的翻译网页界面，直接在文本框里输入文字就能翻译。

第 3 关：按需选择语言模型，拒绝硬盘臃肿 ✅

全部模型下载完要占用好几个 GB，多数人根本用不上。仓库里提供了按语言裁剪的脚本scripts/install_models.py，只需要中英互译就这么干：

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

只要英、法、西、德等欧洲主流语言，就把代码用逗号拼起来：

python scripts/install_models.py --load_only_lang_codes "en,fr,es,de,it"

验证结果：脚本结束时会打印下载和加载的模型数量，随后启动服务时带上同样的语言列表，服务就会"只认"这些语言：

libretranslate --load-only en,zh

第 4 关：用 curl 验证 API 三大核心能力 ✅

网页界面只是开胃菜，REST API 才是自托管的价值所在。翻译接口长这样：

curl -X POST "http://127.0.0.1:5000/translate" \ -H "Content-Type: application/json" \ -d '{"q":"Good morning","source":"en","target":"zh"}'

验证结果：返回 JSON 里出现"translatedText": "早上好"之类的译文。

再试试语言检测和批量翻译：

# 语言检测：自动判断输入是哪国语言 curl -X POST "http://127.0.0.1:5000/detect" \ -H "Content-Type: application/json" \ -d '{"q":"Bonjour tout le monde"}' # 批量翻译：q 传数组，一次请求处理多条文本 curl -X POST "http://127.0.0.1:5000/translate" \ -H "Content-Type: application/json" \ -d '{"q":["Good morning","Have a nice day"],"source":"en","target":"zh"}'

验证结果：/detect返回语言代码（如fr）；批量接口的translatedText是一个数组，长度与输入一致。

第 5 关：把部署切成"真离线"模式 ✅

离线部署的关键是：模型提前备好，启动时不联网。LibreTranslate 默认不会在启动时联网更新模型（UPDATE_MODELS默认为 False），这正是离线友好的设计。

在有网的机器上预下载模型后，把模型目录整个拷贝到离线机器即可，模型默认存放在：

• Linux / macOS：~/.local/share/argos-translate/packages/
• Windows：%APPDATA%\argos-translate\packages\

离线机上直接用环境变量启动，全程零网络访问：

export LT_LOAD_ONLY=en,zh export LT_UPDATE_MODELS=False libretranslate --host 0.0.0.0 --port 5000

验证结果：启动日志干净利落，没有 "Updating language models" 之类的联网动作；拔掉网线翻译依然秒回。

第 6 关：看一眼配置速查表，按需拧开关 ✅

所有配置都有"环境变量"和"命令行参数"两种写法（环境变量统一加LT_前缀），常用开关如下：

配置项	环境变量	命令行参数	默认值	作用
限制可用语言	LT_LOAD_ONLY	--load-only	全部	只加载指定语言，省内存
启动时更新模型	LT_UPDATE_MODELS	--update-models	False	离线环境务必保持 False
开启 API 密钥	LT_API_KEYS	--api-keys	False	为每个调用者做配额管理
每分钟请求上限	LT_REQ_LIMIT	--req-limit	-1（不限）	防滥用，可对单 IP 限流
工作线程数	LT_THREADS	--threads	4	高并发时调大
共享存储	LT_SHARED_STORAGE	--shared-storage	memory://	多进程/多节点共享限流状态
翻译结果缓存	LT_TRANSLATION_CACHE	--translation-cache	关闭	缓存重复翻译，提速明显

第 7 关：按部署场景对号入座 ✅

最后对照这张"选址图"，确认你的配置属于哪种档位：

部署场景	推荐配置	预计模型占用
个人本地使用	中英互译 + 默认参数	约 300MB
内网团队协作	5~8 种常用语言 + API 密钥 + 限流	1GB 左右
对外生产服务	全语言 + 缓存 + 多线程 + Docker	3GB 以上

验证结果：服务在目标场景下稳定运行 24 小时，无崩溃、无异常日志。到这里，你已经拥有了一套属于自己的离线翻译服务。

踩坑合集：症状、原因与解法

坑 1：日志反复出现 "Cannot update models (normal if you're offline)"

• 症状：启动时打印Cannot update models (normal if you're offline)，且之后没有任何语言被加载。
• 原因：离线环境下程序尝试同步模型索引失败；本质是本地压根没有模型文件。
• 解决：这行字本身只是提示、不必惊慌。正确做法是：在有网的机器上用scripts/install_models.py下载好模型，把packages目录拷贝到离线机，再正常启动即可。

坑 2：接口返回 400，提示 "xx is not supported"

• 症状：调用/translate时，指定某个语言组合直接被拒。
• 原因：目标语言对没有安装模型，或者不在--load-only白名单里。
• 解决：确认模型确实已下载，且--load-only的参数里包含了这对语言代码；中英互译要保证en和zh都在列表里。

坑 3：内存不够，启动即崩或奇慢

• 症状：加载几十种语言后内存吃满，服务响应极慢。
• 原因：默认加载全部已安装模型，语言越多内存占用越高。
• 解决：用--load-only裁剪语言；同时把--threads调小，别让线程数叠加内存峰值。

进阶玩法：让自托管翻译物超所值

玩法一：直接翻译整份文件

仓库内置了文件翻译能力（基于 argostranslate-files），支持 HTML、PDF、Word、PPT 等常见格式。向/translate_files上传文档，服务端解析并翻译后返回新文件，适合批量处理多语言手册。不需要该功能时可用--disable-files-translation关闭。

玩法二：API 密钥 + 限流，把服务安全地开放给团队

开启--api-keys后，用项目自带的ltmanage命令行工具创建和管理密钥，再配合--req-limit、--req-flood-threshold做单用户配额与防刷。这样团队里每个人用自己的密钥，谁超量一目了然。

玩法三：一次配置，多节点扩展

生产环境想扛住高并发？--threads调高、--translation-cache all开启结果缓存，重复文本直接命中缓存；多台机器部署时用--shared-storage把限流状态共享到 Redis，配合仓库里的docker-compose.yml和Dockerfile一键起容器，扩展不过是改几个参数的事。

现在，你的翻译能力完全由你掌控

回想开头的问题：数据出内网、按量计费、模型被厂商锁死——这三个痛点，LibreTranslate 全部给了你替代方案。它不追求炫技，只做一件事：把"翻译"这个能力，完完整整地交还到你手里。

从第 1 关到第 7 关，你已经走完了从安装到离线的全部路程。剩下的就交给实践：先跑起中英互译感受一下速度，再按团队需求逐个打开开关。最棒的是，这一切免费、开源，而且完全属于你——现在就去搭一套吧。

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