lywsvip/MTranServer
1
0
Fork 0
mirror of https://github.com/xxnuo/MTranServer.git synced 2026-09-03 06:35:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: clean

Browse Source
This commit is contained in:
xxnuo
2025-11-09 16:02:45 +08:00
parent e4296dd600
commit 3259d4cacb
2 changed files with 10 additions and 287 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
README.md
View File

@@ -6,7 +6,7 @@
[English](README_en.md) | 中文
<img src="./images/icon.png" width="64px" height="64px" align="right" alt="MTran">
<!-- <img src="./images/icon.png" width="64px" height="64px" align="right" alt="MTran"> -->
一个超低资源消耗超快的离线翻译服务器，无需显卡。单个请求平均响应时间 50 毫秒。支持全世界主要语言的翻译。
@@ -14,10 +14,6 @@
> 注意本模型专注于速度和多种设备私有部署，所以翻译质量肯定是不如大模型翻译的效果。需要高质量的翻译建议使用在线大模型 API。
## Demo
> 即将上线
<img src="./images/preview.png" width="auto" height="460">
## 同类项目效果(CPU,英译中)
@@ -32,117 +28,11 @@
> 表中数据仅供参考，非严格测试，非量化版本对比。
## 更新日志
[更新日志](./CHANGELOG.md)
## 桌面端
即将发布桌面端软件，敬请期待。
## 服务器部署
> 对普通用户来说有难度，建议使用桌面端。
### 1.1 环境要求
- Docker
- Docker Compose（可选）
### 1.2 镜像版本
- 默认无内置模型翻译时自动下载：`xxnuo/mtranserver:latest`
- 内置中英互译模型：`xxnuo/mtranserver:latest-zh`
- 内置日英互译模型：`xxnuo/mtranserver:latest-ja`
### 1.3 Docker 部署
复制下面的命令，在终端执行。
```bash
docker run -d --name mtranserver -p 8989:8989 -e API_TOKEN=your_token xxnuo/mtranserver:latest
```
### 1.4 Docker Compose 部署
服务器准备一个存放配置的文件夹，打开终端执行以下命令
```bash
mkdir mtranserver
cd mtranserver
touch compose.yml
```
用编辑器打开 `compose.yml` 文件，写入以下内容。
> 1. 修改下面的 `your_token` 为你自己设置的一个密码，使用英文大小写和数字。自己内网可以不设置，如果是`云服务器`强烈建议设置一个密码，保护服务以免被`扫到、攻击、滥用`。
>
> 2. 如果需要更改端口，修改 `ports` 的值，比如修改为 `9999:8989` 表示将服务端口映射到本机 9999 端口。
>
> 3. 建议使用 `API_TOKEN` 设置密码，旧版本的 `CORE_API_TOKEN` 也还可以生效。
```yaml
services:
mtranserver:
image: xxnuo/mtranserver:latest
container_name: mtranserver
restart: unless-stopped
ports:
- "8989:8989"
environment:
- API_TOKEN=your_token
```
先启动测试，确保 8989 端口没被占用。
```bash
docker compose up
```
正常输出示例：
```bash
HTTP Service URL: http://0.0.0.0:8989
Swagger UI: http://0.0.0.0:8989/docs
```
然后按 `Ctrl+C` 停止服务运行，然后正式启动服务器
```bash
docker compose up -d
```
这时候服务器就在后台运行了。
## 准备模型
⚠️ 注意：第一次请求翻译 API 时会在后台自动下载模型，无需手动下载。
模型自动下载功能需要连接网络（中国大陆不需要代理），**后续翻译及其他功能均无需联网完全离线**。
**所以第一次翻译不是秒回，要等待一会儿！**
可在 Docker 日志处观察进度。下载速度取决于网络速度，一般在 10s 内能完成一个语言模型的下载。如果下载超时/失败，请检查容器是否能正常联网。
如果属于内网机器无法访问互联网可按照下文指导手动下载模型。
### API 使用
下面表格内的 `localhost` 可以替换为你的服务器地址或 Docker 容器名。
下面表格内的 `8989` 端口可以替换为你在 `compose.yml` 文件中设置的端口值。
如果未设置环境变量 `API_TOKEN`、`CORE_API_TOKEN` 或者设置为空，翻译插件使用`无密码`的 API。
如果设置了 `API_TOKEN`、`CORE_API_TOKEN`，翻译插件使用`有密码`的 API。
下面表格中的 `your_token` 替换为你在环境变量中设置的 `API_TOKEN` 值。
#### 翻译插件接口
> 注：
>
> - [沉浸式翻译](https://immersivetranslate.com/zh-Hans/docs/services/custom/) 在`设置`页面，开发者模式中启用`Beta`特性，即可在`翻译服务`中看到`自定义 API 设置`([官方图文教程](https://immersivetranslate.com/zh-Hans/docs/services/custom/))。然后将`自定义 API 设置`的`每秒最大请求数`拉高以充分发挥服务器性能准备体验飞一般的感觉。我设置的是`每秒最大请求数`为`5000`，`每次请求最大段落数`为`10`。你可以根据自己服务器配置设置。
> - [沉浸式翻译](https://immersivetranslate.com/zh-Hans/docs/services/custom/) 在`设置`页面，开发者模式中启用`Beta`特性，即可在`翻译服务`中看到`自定义 API 设置`([官方图文教程](https://immersivetranslate.com/zh-Hans/docs/services/custom/))。然后将`自定义 API 设置`的`每秒最大请求数`拉高以充分发挥服务器性能准备体验飞一般的感觉。我设置的是`每秒最大请求数`为`5000`，`每次请求最大段落数`为`1`。你可以根据自己服务器配置设置。
>
> - [简约翻译](https://github.com/fishjar/kiss-translator) 在`设置`页面，接口设置中滚动到下面，即可看到自定义接口 `Custom`。同理，设置`最大请求并发数量`、`每次请求间隔时间`以充分发挥服务器性能。我设置的是`最大请求并发数量`为`100`，`每次请求间隔时间`为`1`。你可以根据自己服务器配置设置。
>
@@ -157,49 +47,10 @@ docker compose up -d
**普通用户参照表格内容设置好插件使用的接口地址就可以使用了。**
### 保持更新
```bash
cd mtranserver
docker pull xxnuo/mtranserver:latest
docker compose up -d
```
### 开发者接口
> Base URL: `http://localhost:8989`
>
> 在 v3.0.0 及以上版本中，API 文档可通过访问 `http://localhost:8989/docs` 查看完整 Swagger 文档
| 名称 | URL | 请求格式 | 返回格式 | 认证头 |
| ------------------ | ------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
| 服务版本 | `/version` | 无 | `{"version": "v3.0.0"}` | 无 |
| 支持的语言列表 | `/languages` | 无 | `{"languages":["en","zh","ja","ko"...]}` | Authorization: your_token |
| 普通翻译接口 | `/translate` | `{"from": "en", "to": "zh", "text": "Hello, world!"}` | `{"result": "你好，世界！"}` | Authorization: your_token |
| 批量翻译接口 | `/translate/batch` | `{"from": "en", "to": "zh", "texts": ["Hello, world!", "Hello, world!"]}` | `{"results": ["你好，世界！", "你好，世界！"]}` | Authorization: your_token |
| 健康检查 | `/health` | 无 | `{"status": "ok"}` | 无 |
| 心跳检查 | `/__heartbeat__` | 无 | `Ready` | 无 |
| 负载均衡心跳检查 | `/__lbheartbeat__` | 无 | `Ready` | 无 |
| 谷歌翻译兼容接口 1 | `/language/translate/v2` | `{"q": "The Great Pyramid of Giza", "source": "en", "target": "zh", "format": "text"}` | `{"data": {"translations": [{"translatedText": "吉萨大金字塔"}]}}` | Authorization: your_token |
> 开发者高级设置请参考 [CONFIG.md](./CONFIG.md)
## 贡献者
<table>
<tbody>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/Devillmy"><img src="https://avatars.githubusercontent.com/u/36851750?v=3?s=100" width="100px;" alt="Lv Meiyang"/><br /><sub><b>Lv Meiyang</b></sub></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/xxnuo"><img src="https://avatars.githubusercontent.com/u/54252779?v=3?s=100" width="100px;" alt="Leo"/><br /><sub><b>Leo</b></sub></td>
</tr>
</tbody>
</table>
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=xxnuo/MTranServer&type=Timeline)](https://www.star-history.com/#xxnuo/MTranServer&Timeline)
## Thanks
[Bergamot Project](https://browser.mt/) for awesome idea of local translation.

144
README_en.md
View File

@@ -1,6 +1,6 @@
# MTranServer
<img src="./images/icon.png" width="64px" height="64px" align="right" alt="MTran">
<!-- <img src="./images/icon.png" width="64px" height="64px" align="right" alt="MTran"> -->
[中文](README.md) | English
@@ -12,10 +12,6 @@ Note: This model focuses on speed and private deployment on various devices, so
For high-quality translation, consider using online large language model APIs.
## Demo
> Coming soon
<img src="./images/preview.png" width="auto" height="460">
## Comparison with Similar Projects (CPU, English to Chinese)
@@ -32,98 +28,6 @@ For high-quality translation, consider using online large language model APIs.
>
> Table data is for reference only, not strict testing, non-quantized version comparison.
## Update Log
[Update Log](./CHANGELOG.md)
## Desktop Client
Desktop client software coming soon, stay tuned.
## Server Deployment
> This may be challenging for regular users, consider using the desktop client when available.
### 1.1 Requirements
- Docker
- Docker Compose (optional)
### 1.2 Image Versions
- Default version (download models automatically when no built-in models are available): `xxnuo/mtranserver:latest`
- Built-in Chinese <-> English translation models: `xxnuo/mtranserver:latest-zh`
- Built-in Japanese <-> English translation models: `xxnuo/mtranserver:latest-ja`
### 1.3 Docker Deployment
Copy the command below and execute it in your terminal.
```bash
docker run -d --name mtranserver -p 8989:8989 -e API_TOKEN=your_token xxnuo/mtranserver:latest
```
### 1.4 Docker Compose Deployment
Prepare a folder for configuration files on your server and run the following commands in terminal:
```bash
mkdir mtranserver
cd mtranserver
touch compose.yml
```
Open `compose.yml` with an editor and add the following content:
> 1. Change `your_token` below to your own password using English letters and numbers. For internal network use, setting a password is optional, but for `cloud servers`, it is strongly recommended to set a password to protect against `scanning, attacks, and abuse`.
>
> 2. To change the port, modify the `ports` value. For example, change to `9999:8989` to map the service port to local port 9999.
```yaml
services:
mtranserver:
image: xxnuo/mtranserver:latest
container_name: mtranserver
restart: unless-stopped
ports:
- "8989:8989"
environment:
- CORE_API_TOKEN=your_token
```
First, test the service to ensure the port isn't occupied:
```bash
docker compose up
```
Example normal output:
```bash
HTTP Service URL: http://0.0.0.0:8989
Swagger UI: http://0.0.0.0:8989/docs
```
Then press `Ctrl+C` to stop the service, and start it officially:
```bash
docker compose up -d
```
The server will now run in the background.
## Preparing Models
⚠️ Note: Models will be automatically downloaded in the background when you first request the translation API, no manual download needed.
The automatic model download feature requires internet connection (no proxy needed in mainland China), **all subsequent translations and other functions work completely offline without internet**.
**So the first translation won't be instant, you'll need to wait a moment!**
You can monitor the progress in the Docker logs. Download speed depends on your network speed, typically completing a language model download within 10 seconds. If the download times out or fails, check if your container has normal internet access.
If your machine is on an internal network without internet access, you can follow the instructions below to manually download models.
### API Usage
In the following tables, `localhost` can be replaced with your server address or Docker container name.
@@ -140,7 +44,7 @@ Replace `your_token` in the following tables with your `API_TOKEN` or `CORE_API_
> Note:
>
> - [Immersive Translation](https://immersivetranslate.com/docs/services/custom/) - Enable `Beta` features in developer mode in `Settings` to see `Custom API Settings` under `Translation Services` ([official tutorial with images](https://immersivetranslate.com/docs/services/custom/)). Then increase the `Maximum Requests per Second` in `Custom API Settings` to fully utilize server performance. I set `Maximum Requests per Second` to `5000` and `Maximum Paragraphs per Request` to `10`. You can adjust based on your server hardware.
> - [Immersive Translation](https://immersivetranslate.com/docs/services/custom/) - Enable `Beta` features in developer mode in `Settings` to see `Custom API Settings` under `Translation Services` ([official tutorial with images](https://immersivetranslate.com/docs/services/custom/)). Then increase the `Maximum Requests per Second` in `Custom API Settings` to fully utilize server performance. I set `Maximum Requests per Second` to `5000` and `Maximum Paragraphs per Request` to `1`. You can adjust based on your server hardware.
>
> - [Kiss Translator](https://github.com/fishjar/kiss-translator) - Scroll down in `Settings` page to find the custom interface `Custom`. Similarly, set `Maximum Concurrent Requests` and `Request Interval Time` to fully utilize server performance. I set `Maximum Concurrent Requests` to `100` and `Request Interval Time` to `1`. You can adjust based on your server configuration.
>
@@ -155,50 +59,18 @@ Replace `your_token` in the following tables with your `API_TOKEN` or `CORE_API_
**Regular users can start using the service after setting up the plugin interface address according to the table above.**
### Keep Updating
```bash
cd mtranserver
docker pull xxnuo/mtranserver:latest
docker compose up -d
```
### Developer APIs
> Base URL: `http://localhost:8989`
>
> In v3.0.0, complete API documentation can be viewed at `http://localhost:8989/docs` using Swagger UI
| Name | URL | Request Format | Response Format | Auth Header |
| --------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------- |
| Service Version | `/version` | None | `{"version": "v3.0.0"}` | None |
| Supported Languages | `/languages` | None | `{"languages":["en","zh","ja","ko"...]}` | Authorization: your_token |
| Standard Translation | `/translate` | `{"from": "en", "to": "zh", "text": "Hello, world!"}` | `{"result": "你好，世界！"}` | Authorization: your_token |
| Batch Translation | `/translate/batch` | `{"from": "en", "to": "zh", "texts": ["Hello, world!", "Hello, world!"]}` | `{"results": ["你好，世界！", "你好，世界！"]}` | Authorization: your_token |
| Health Check | `/health` | None | `{"status": "ok"}` | None |
| Heartbeat Check | `/__heartbeat__` | None | `Ready` | None |
| Load Balancer Heartbeat | `/__lbheartbeat__` | None | `Ready` | None |
| Google Translate Compatible Interface 1 | `/language/translate/v2` | `{"q": "The Great Pyramid of Giza", "source": "en", "target": "zh", "format": "text"}` | `{"data": {"translations": [{"translatedText": "吉萨大金字塔"}]}}` | Authorization: your_token |
> Developer advanced settings please refer to [CONFIG.md](./CONFIG.md)
## Support Me
[Buy me a coffee ☕️](https://www.creem.io/payment/prod_3QOnrHlGyrtTaKHsOw9Vs1)
[Mainland China 💗 Like](./DONATE.md)
## Contributors
<table>
<tbody>
<tr>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/Devillmy"><img src="https://avatars.githubusercontent.com/u/36851750?v=3?s=100" width="100px;" alt="Lv Meiyang"/><br /><sub><b>Lv Meiyang</b></sub></td>
<td align="center" valign="top" width="14.28%"><a href="https://github.com/xxnuo"><img src="https://avatars.githubusercontent.com/u/54252779?v=3?s=100" width="100px;" alt="Leo"/><br /><sub><b>Leo</b></sub></td>
</tr>
</tbody>
</table>
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=xxnuo/MTranServer&type=Timeline)](https://star-history.com/#xxnuo/MTranServer&Timeline)
## Thanks
[Bergamot Project](https://browser.mt/) for awesome idea of local translation.
[Mozilla](https://github.com/mozilla) for the [models](https://github.com/mozilla/firefox-translations-models).