Skip to content

RapidAI/RapidTransSrv

BranchesTags

Repository files navigation

RapidTransSrv

English | 中文

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

模型来源

默认模型来自腾讯 Hy-MT 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。

默认目录

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

~/.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。

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

启动服务：

.\bin\maclaw-trans.exe

打开管理界面：

http://127.0.0.1:8080/admin

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

方式二：Windows 服务

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

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

停止和卸载：

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

方式三：Windows NSIS 安装包

NSIS 脚本位于：

scripts\package\windows\maclaw-trans.nsi

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

跨平台构建

.\scripts\build-cross.ps1

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

快速调用

文本翻译

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"}'

响应示例：

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

文档翻译

POST /v1/translate/document
Content-Type: application/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 文档

主要接口：

方法 路径 说明
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 支持语言代码和常见语言名：

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。

自测和质量验证

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

.\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

文档翻译示例：

.\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 模型页面各自的许可证使用。生产部署前请确认模型许可、使用限制和合规要求。

About

高效语言翻译服务器软件，支持硬件加速。

Resources

Readme
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

V1.0 Inital Release Latest
May 16, 2026

Contributors

Languages