LibreTranslate 自托管指南：三步跑通自己的免费翻译API

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 是一个基于 AGPLv3 协议的开源机器翻译 API，你可以把它部署在自己的服务器上，全程离线工作，不经过任何第三方的翻译服务。它把翻译引擎（Argos Translate 的开源模型）直接跑在你机器上，通过 RESTful 接口提供文本翻译、文件翻译和语言自动检测，还自带一个浏览器里的操作界面。如果你的数据不能出内网、不想按调用量给商业 API 付费、或者需要一个随时可改可审计的自建翻译 API，它就是目前最省事的选择之一。

先说清楚它适合谁，不适合谁

把自托管翻译服务想象成"在家里自己装一台打印机"：墨盒（语言模型）是你自己的，印多少张不跟谁交钱，纸（数据）也不经过任何外人。代价是：打印机的质量取决于你买的墨盒，而不是印厂中央的顶级设备。

所以我的判断很直接——它适合内网系统、个人项目、隐私敏感业务、中小流量场景，以及"必须完全可控"的合规需求。它不适合指望它替代顶级商业引擎的场景：Argos 的开源模型翻译日常对话、文档、工单绰绰有余，但和头部商用模型比，长难句和文学性文本的质量是有差距的。预期摆正，它就不会让你失望。

三步跑起来，Docker 最省心

整个项目用 Python 写的 Flask 应用（核心路由和校验逻辑都在 libretranslate/app.py），依赖和模型打包都挺干净。生产上我推荐直接用官方镜像，一条命令的事：

docker run -d -p 5000:5000 -v lt-local:/home/libretranslate/.local --name libretranslate libretranslate/libretranslate

这里有个容易忽略的细节：第一次启动时它会自动下载语言模型（每个语言对几十到几百 MB），所以首次启动必须能联网，之后就可以完全离线跑了。模型统一放在/home/libretranslate/.local，所以上面那条命令挂了个卷，避免重启容器后重新下载。仓库里还有个更简单的入口 run.sh，会帮你检查 Docker 环境再启动，嫌输命令麻烦可以直接用它；docker-compose.yml 则适合需要长期运维的场景。

想从源码跑也行，流程就四步：克隆仓库后pip install -e .，再执行python scripts/install_models.py（模型安装脚本，支持--load_only_lang_codes只装指定语言），最后python main.py --host 0.0.0.0 --port 5000。克隆地址用git clone https://gitcode.com/GitHub_Trending/li/LibreTranslate。

翻译 API 怎么调：一个 curl 就够

服务起来后，浏览器打开http://服务器IP:5000就能看到内置的 Web 界面，输入文本选语言对即可翻译，文件（txt、docx、pdf 等）也能直接传。接口党不用看图，翻译的核心就一个/translate端点：

curl -X POST http://localhost:5000/translate \ -d "q=Hello, world!" -d "source=auto" -d "target=zh"

返回 JSON，translatedText字段就是结果；source传auto时会顺带返回detectedLanguage，相当于翻译和语言检测一次搞定。这个端点还有不少实用参数：q可以传数组做批量翻译，format支持text和html两种输入，alternatives能要多个候选译文（完整参数定义在 app.py 的 swagger 注释里）。配合起来看这几个辅助端点就够了：/languages返回已装的语言和可译目标，/health给容器健康检查用，/docs是自动生成的 Swagger 界面——接口文档不用查外部资料，开着它点就行。

调通了接口，下一步通常是把它交给团队或上线，这就到了加固环节。

🔑 API 密钥和请求限制怎么开

默认状态下任何人都能无限调用你的服务，内网无所谓，暴露公网就是事故。项目内置了一套很完整的防滥用机制（限流与封禁逻辑在 libretranslate/flood.py），常用开关有这么几个：

启动时加--api-keys，然后用自带管理工具签发密钥：python manage.py keys add 60000，它会生成一个 UUID 并打印出来，60000 是这把钥匙每分钟允许的请求数。密钥存在 SQLite 里（默认路径db/api_keys.db，实现见 libretranslate/api_keys.py），还支持按密钥单独设置--char-limit字符上限。如果嫌管本地库麻烦，--api-keys-remote可以把密钥校验转发给你自己的远端服务。

几个高频开关建议记一下：--req-limit按分钟限流、--char-limit按字符限流、--batch-limit限制单批文本条数，超限的请求会触发封禁计数，屡教不改的 IP 会被 ban。真被爬虫盯上了，直接开--under-attack，所有请求强制带密钥，裸调一律 403。

资源层面，--load-only en,zh,fr只加载需要的语言，能省下大几 GB 内存；--threads默认 4 个线程，机器核多可以调高；--metrics加个--metrics-auth-token就暴露出 Prometheus 指标端点/metrics，接入监控台一劳永逸。部署在反代后面时，--url-prefix让它挂在子路径下，--trust-forwarded-for则让限流能读到真实客户端 IP。

🕳️ 避坑指南：上线前必看

• 默认只监听 127.0.0.1：源码方式启动不写--host 0.0.0.0的话，别的机器根本访问不到，这是被问得最多的"为什么连不上"。
• 默认全无限流：req-limit、char-limit默认都是 -1（不限制），内网自嗨没问题，公网部署前一定要把限额加上，这是自托管翻译服务被刷爆的第一原因。
• auto 检测不是万能的：短句、夹杂专有名词或两种语言的混合文本容易误判。稳定场景里，source能明确传就明确传，别依赖自动检测。
• 离线环境装模型要提前备货：--update-models只会在启动时尝试更新，内网机器建议在有网环境先跑一遍模型下载，把整个.local目录拷过去。
• 别全量加载语言：每个语言对都是一个实体模型，全装下来内存和磁盘都不友好。按业务需要--load-only，这是性能优化的第一杠杆。

顺带一提，libretranslate/tests/test_api/ 下的测试文件（test_api_translate.py、test_api_detect_language.py等）基本覆盖了所有接口的行为边界，改配置前翻一翻，比猜参数行为要快得多。

自托管翻译 API 这事，技术门槛其实不高，真正的成本在于想清楚：你的流量有多大、数据要守住哪道门、模型质量够不够你的场景。把这三件事答完，上面这些开关怎么组合，基本就水到渠成了。

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