# RapidTransSrv

**Repository Path**: RapidAI/RapidTransSrv

## Basic Information

- **Project Name**: RapidTransSrv
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RapidTransSrv

[English](readme_en.md) | 中文

RapidTransSrv 是一个纯 Go 本地 RESTful 翻译服务，面向私有化文档翻译、法律文本翻译和 AI Agent 工具集成。服务在本机进程内加载腾讯 Hy-MT GGUF 模型，不依赖 Python、不启动外部推理服务，提供文本翻译、Markdown 风格文档翻译、Web 管理界面、并发控制、持久化缓存、Prometheus 指标、Windows NT Service 和 NSIS 安装包脚本。

## 模型来源

默认模型来自腾讯 Hy-MT GGUF 发布页：

- Hugging Face: [tencent/Hy-MT1.5-1.8B-1.25bit-GGUF](https://huggingface.co/tencent/Hy-MT1.5-1.8B-1.25bit-GGUF)
- 默认文件：`Hy-MT1.5-1.8B-1.25bit.gguf`
- 默认模型名：`Hy-MT1.5-1.8B-1.25bit-GGUF`

如果本地模型不存在，服务会自动下载。默认优先使用国内可访问镜像，再回退到 Hugging Face：

1. `https://hf-mirror.com/tencent/Hy-MT1.5-1.8B-1.25bit-GGUF/resolve/main/Hy-MT1.5-1.8B-1.25bit.gguf`
2. `https://huggingface.co/tencent/Hy-MT1.5-1.8B-1.25bit-GGUF/resolve/main/Hy-MT1.5-1.8B-1.25bit.gguf`

可以通过 Web 管理界面、`~/.rapidtrans/config.json` 或 `MACLAW_MODEL_URLS` 配置更多镜像地址，服务会按顺序尝试。

## 功能特点

- 纯 Go 推理：不依赖 Python、llama.cpp server、cgo 或外部推理进程。
- REST API：支持 `POST /v1/translate` 和 `POST /v1/translate/document`。
- 多语言互译：请求中传入 `target_lang`，默认英中互译。
- 文档翻译：保留 Markdown 标题、列表、表格、链接地址、URL、邮箱、HTML 标签、inline code 和 fenced code block。
- Web 管理界面：设置并发数、模型目录、模型路径、缓存目录、日志路径、下载镜像和生成参数。
- 并发控制：`max_concurrent` 控制同时进入模型推理的请求数。
- 持久化缓存：bbolt 缓存重复句子和文档段落，缓存命中可绕过推理并发槽。
- 性能优化：amd64 AVX2、arm64 NEON、Q4 GEMV、RMSNorm、算子融合、worker pool、热缓存和文档段去重。
- Windows 部署：支持 NT Service、自动启动和 NSIS 安装包脚本。
- 可观测性：提供 `/healthz`、`/readyz`、`/metrics` 和管理 API。

## 默认目录

首次启动会在用户目录下创建：

```text
~/.rapidtrans/config.json
~/.rapidtrans/models
~/.rapidtrans/cache
~/.rapidtrans/logs/rapidtrans.log
```

设置 `RAPIDTRANS_HOME` 可以改变根目录。普通命令行默认使用当前用户的 `~/.rapidtrans`；Windows NT Service 默认通过 Windows Known Folder API (`FOLDERID_ProgramData`) 获取 ProgramData 后使用 `RapidTransSrv` 子目录；安装包也会把 `RAPIDTRANS_HOME` 和注册表 `DataDir` 指向该目录，避免写入 `LocalSystem` 的 `systemprofile` 用户目录。

## 安装和启动

### 方式一：源码构建

需要 Go 1.26 或兼容项目 `go.mod` 的 Go toolchain。

```powershell
go build -o .\bin\maclaw-trans.exe .\cmd\maclaw-trans
go build -o .\bin\maclaw-client.exe .\cmd\maclaw-client
```

启动服务：

```powershell
.\bin\maclaw-trans.exe
```

打开管理界面：

```text
http://127.0.0.1:8080/admin
```

服务启动后 HTTP 会先可用，模型加载完成前 `/readyz` 返回 503。模型下载和加载完成后，`/readyz` 返回 200。

### 方式二：Windows 服务

先构建或安装服务端二进制，然后以管理员权限执行：

```powershell
.\bin\maclaw-trans.exe install-service
.\bin\maclaw-trans.exe start-service
```

停止和卸载：

```powershell
.\bin\maclaw-trans.exe stop-service
.\bin\maclaw-trans.exe uninstall-service
```

### 方式三：Windows NSIS 安装包

NSIS 脚本位于：

```text
scripts\package\windows\maclaw-trans.nsi
```

安装包会安装服务端程序、创建 NT Service、设置自动启动，并在首次启动时按配置自动下载模型。

### 跨平台构建

```powershell
.\scripts\build-cross.ps1
```

默认构建 `windows/amd64`、`windows/arm64` 和 `linux/arm64`。ARM64 CPU 构建保留 NEON 优化路径。

## 快速调用

### 文本翻译

```bash
curl -s http://127.0.0.1:8080/v1/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"The contract shall be governed by New York law.","source_lang":"en","target_lang":"zh","domain":"legal"}'
```

响应示例：

```json
{
  "translation": "该合同受纽约法律约束。",
  "model": "Hy-MT1.5-1.8B-1.25bit-GGUF",
  "backend_ms": 35831,
  "elapsed_ms": 35833
}
```

### 文档翻译

```http
POST /v1/translate/document
Content-Type: application/json
```

```json
{
  "text": "# Contract\n\nThe contract shall be governed by New York law.\n\n```\ncode is preserved\n```\n",
  "source_lang": "en",
  "target_lang": "zh",
  "domain": "legal",
  "concurrency": 2
}
```

文档接口会返回完整译文和分段明细。空行、代码块、URL、邮箱、链接目标和 HTML 标签会被保护。

## API 文档

- [docs/API.md](docs/API.md)
- [docs/openapi.yaml](docs/openapi.yaml)
- 运行时获取：`GET /openapi.yaml`

主要接口：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/v1/translate` | 翻译单段文本 |
| `POST` | `/v1/translate/document` | 翻译 Markdown-like 文档 |
| `GET` | `/healthz` | 进程存活检查 |
| `GET` | `/readyz` | 模型就绪检查 |
| `GET` | `/metrics` | Prometheus 指标 |
| `GET` | `/admin` | Web 管理界面 |
| `GET/POST` | `/admin/config` | 读取或更新配置 |
| `POST` | `/admin/reload` | 重新加载模型 |
| `GET/POST` | `/admin/cache` / `/admin/cache/clear` | 查看或清理缓存 |

## 语言参数

`source_lang` 和 `target_lang` 支持语言代码和常见语言名：

```text
zh, en, ja, ko, fr, de, es, ru, it, pt, ar, hi, vi, th, id, ms, tr, nl, pl
Chinese, English, Japanese, Korean, French, German, Spanish
中文, 英文, 日文, 韩文
```

默认行为：

- 输入包含中文且省略 `target_lang` 时，默认翻译为英文。
- 输入不含中文且省略 `target_lang` 时，默认翻译为中文。
- AI 工具或自动化集成建议始终显式传入 `target_lang`。

## 配置

| 环境变量 | 说明 |
| --- | --- |
| `RAPIDTRANS_HOME` | 配置、模型、缓存和日志根目录；普通命令行默认 `~/.rapidtrans`，Windows NT Service 默认通过 Windows Known Folder API 获取 ProgramData 后使用 `RapidTransSrv` 子目录 |
| `MACLAW_ADDR` | REST 监听地址 |
| `MACLAW_MODEL_PATH` | 本地 GGUF 模型路径 |
| `MACLAW_MODEL_URL` | 主模型下载 URL |
| `MACLAW_MODEL_URLS` | fallback URL 列表，支持逗号、分号、制表符或换行分隔 |
| `MACLAW_AUTO_DOWNLOAD_MODEL` | 模型不存在时是否自动下载 |
| `MACLAW_MAX_CONCURRENT` | 最大并发翻译请求数 |
| `MACLAW_SESSION_POOL_SIZE` | 推理 session pool 大小 |
| `MACLAW_MAX_TOKENS` | 最大生成 token 数 |
| `MACLAW_TEMPERATURE` | 采样温度，默认 0 |
| `MACLAW_TOP_P` | top-p 采样参数 |
| `MACLAW_DEVICE` | `auto`、`cpu` 或 `vulkan` |
| `MACLAW_KV_DTYPE` | `fp32`、`fp16`、`q4` 或 `q3` |
| `MACLAW_REQUEST_LIMIT_BYTES` | 请求体大小限制 |

Web 管理界面也可以修改这些常用配置。并发数会立即生效；模型路径、下载源、缓存目录和生成参数变更后需要 Reload model。

## 自测和质量验证

运行服务后，可用内置客户端执行质量用例：

```powershell
.\bin\maclaw-client.exe `
  -url http://127.0.0.1:8080 `
  -cases .\testdata\quality-cases.json `
  -concurrency 1 `
  -repeat 1 `
  -timeout 10m `
  -fail-on-bad
```

文档翻译示例：

```powershell
.\bin\maclaw-client.exe `
  -url http://127.0.0.1:8080 `
  -input .\testdata\sample-legal.md `
  -output .\testdata\sample-legal.zh.md `
  -source en `
  -target zh `
  -domain legal `
  -timeout 15m
```

当前真实 GGUF 模型基础质量用例包括：

- `Hello` -> `你好`
- `The contract shall be governed by New York law.` -> `该合同受纽约法律约束。`
- `本合同受纽约州法律管辖。` -> `This contract is governed by the laws of New York State.`
- `Hello` -> Japanese -> `こんにちは。`

## 适用场景

- 本地或内网私有翻译服务。
- 法律、合同、政策、技术文档翻译。
- Agent、RAG、工作流系统中的翻译工具节点。
- 不希望部署 Python 或外部模型服务的纯 Go 环境。
- 需要 Windows 自动启动、集中配置和本地缓存的服务器部署。

## 许可和模型说明

请按本仓库代码、第三方依赖和腾讯 Hy-MT GGUF 模型页面各自的许可证使用。生产部署前请确认模型许可、使用限制和合规要求。