qwen-mt-cli 0.3.8

Qwen-MT CLI - Command-line translation tool powered by Qwen-MT with vector-based term matching

QMT - Qwen-MT CLI

基于通义千问机器翻译模型 (Qwen-MT) 的命令行翻译工具。支持单句翻译、交互式 REPL、CSV/Excel 批量翻译，并提供术语表、翻译记忆、领域提示、向量语义匹配等专业翻译辅助功能。

安装

需要 Python >= 3.10。

pip install qwen-mt-cli

或从源码安装：

git clone https://github.com/leoleils/qwen-mt-cli.git
cd qwen-mt-cli
pip install -e .

安装后即可使用 qmt 命令。

配置

设置 DashScope API Key（申请地址）：

export DASHSCOPE_API_KEY="sk-xxxxxxxx"

也可以通过 --api-key 参数逐次传入。

快速开始

# 翻译文本
qmt "你好世界" -t English

# 指定模型
qmt "Hello World" -t Chinese -m qwen-mt-plus

# 翻译文件
qmt -f article.txt -t English

# 管道输入
echo "你好" | qmt -t English

# 流式输出
qmt "你好世界" -t English --stream

# 交互式模式
qmt -i -t English

可用模型

模型	特点	流式	语言数
qwen-mt-plus	最高翻译质量，适用于专业领域	-	92
qwen-mt-flash	通用首选，效果/速度/成本平衡 (默认)	支持	92
qwen-mt-lite	最快响应速度，适用于实时场景	支持	31

批量翻译

支持 CSV (.csv/.tsv) 和 Excel (.xlsx/.xls) 文件的批量翻译。翻译文件第一列内容，结果追加为新列。

# CSV 批量翻译
qmt -B input.csv -t English

# Excel 批量翻译（所有 sheet）
qmt -B input.xlsx -t Korean

# 指定输出文件
qmt -B input.csv -O output.csv -t English

# 首行也翻译（无表头模式）
qmt -B input.csv -t English --no-header

# 断点恢复（中断后从上次位置继续）
qmt -B input.csv -t English --resume

默认行为：

• 首行视为表头，不翻译（--no-header 可改变此行为）
• 输出文件自动命名为 原文件名_translated.ext
• Excel 文件翻译所有工作表
• 触发 API 限流时自动指数退避重试（2s -> 4s -> 8s -> 16s -> 32s，最多 5 次）
• 支持 --resume 断点恢复，中断后可继续翻译

术语管理

固定术语确保特定词汇翻译一致。保存在项目目录 .qmt/terms.csv。

# 添加术语
qmt terms add "React" "React"
qmt terms add "组件" "コンポーネント"

# 查看术语列表
qmt terms list

# 删除术语
qmt terms remove "React"

# 清空所有术语
qmt terms clear

# 从 CSV/TSV 文件批量导入
qmt terms import terms.csv

# 翻译时使用内联术语（不保存）
qmt "React组件开发" -t Japanese --terms "React:React,组件:コンポーネント"

翻译记忆

提供参考翻译对，帮助模型保持翻译风格一致。保存在 .qmt/memory.csv。

# 添加翻译记忆
qmt memory add "你好世界" "Hello World"

# 查看记忆列表
qmt memory list

# 删除记忆
qmt memory remove "你好世界"

# 清空所有记忆
qmt memory clear

# 从文件批量导入
qmt memory import memory.csv

向量语义匹配

当术语或翻译记忆条目较多时（默认超过 20 条），QMT 自动启用向量语义匹配，从大量条目中智能筛选与当前翻译内容最相关的 Top-K 条（默认 10 条）传给模型，而不是全量传入。

底层使用 zvec 向量数据库（HNSW 索引 + 余弦距离）存储嵌入向量，通过 DashScope text-embedding-v3 模型生成向量嵌入进行语义检索。向量索引以二进制格式存储在 .qmt/terms.zvec/ 和 .qmt/memory.zvec/，首次翻译时自动构建，后续增量同步。

# 默认行为：术语/记忆超过 20 条时自动启用
qmt "进入副本后需要先组队" -t Korean -v

# 控制返回条数（默认 10）
qmt "进入副本" -t Korean --top-k 5

# 调整启用阈值（默认 20，设高则不启用）
qmt "进入副本" -t Korean --threshold 50

# 批量翻译时自动预嵌入所有源文本，逐行筛选最相关术语/记忆
qmt -B input.xlsx -t Korean -v

--learn 自动学习

翻译结果可自动写回翻译记忆库，并即时同步向量索引：

# 单条翻译 + 自动学习
qmt "锻造装备需要金币" -t Korean --learn

# 批量翻译 + 批量学习（所有成功翻译自动写入记忆）
qmt -B input.csv -t Korean --learn

# 交互模式中切换学习
qmt -i -t Korean
# 输入 /learn 开启自动学习

向量索引管理

当术语库条目较多时（如 25000+），首次翻译需要嵌入所有术语会非常耗时。推荐提前构建向量索引：

# 查看当前索引状态
qmt vectordb status

# 从 CSV 重建全部向量索引（术语 + 翻译记忆）
qmt vectordb rebuild

# 清除所有向量索引（不影响 CSV 数据）
qmt vectordb clear

rebuild 会调用 DashScope embedding API 逐批嵌入所有术语/记忆，构建完成后后续翻译即可使用向量语义匹配。如果未预先构建索引且术语超过 500 条，翻译时会自动降级为截取前 N 条。

领域提示

领域提示告诉模型翻译的专业领域和风格要求，支持两级存储：

• 项目级 — 保存在当前目录 .qmt/domain.md，优先级最高
• 全局级 — 保存在 ~/.qmt/domain.md，作为默认值

# 设置项目级领域
qmt domain set "technology"

# 设置全局级领域
qmt domain set "medical translation, formal tone" --global

# 查看当前配置
qmt domain show

# 清除项目级领域
qmt domain clear

# 清除全局级领域
qmt domain clear --global

优先级：命令行 -d 参数 > 项目级 > 全局级。

翻译时自动加载已保存的领域提示，无需每次手动指定：

# 先设置领域
qmt domain set "game localization, martial arts world view"

# 后续翻译自动生效
qmt "仙缘副本" -t Korean
qmt -B game_strings.xlsx -t Korean

交互式模式

qmt -i -t English

交互模式下可用命令：

命令	说明
/help	显示帮助
/target <lang>	切换目标语言
/source <lang>	切换源语言
/model <name>	切换模型
/stream	切换流式输出
/domain <text>	设置领域提示
/domain save [global]	保存当前领域到项目/全局
/domain clear	清除当前领域
/topk <n>	设置语义匹配 Top-K
/learn	切换翻译记忆自动学习
/info	显示当前设置
exit / quit	退出

完整参数一览

qmt [TEXT] [OPTIONS]

参数:
  TEXT                    待翻译文本

选项:
  -t, --target TEXT       目标语言 (默认 Chinese)
  -s, --source TEXT       源语言 (默认 auto)
  -m, --model TEXT        模型 (plus/flash/lite, 默认 flash)
  -f, --file PATH         翻译文件内容
  -d, --domain TEXT       领域提示
  -i, --interactive       交互式模式
  --stream                流式输出
  --terms TEXT            内联术语 (源:译,源:译)
  --terms-file PATH       术语文件 (CSV/TSV)
  --memory-file PATH      记忆文件 (CSV/TSV)
  -B, --batch PATH        批量翻译文件 (CSV/Excel)
  -O, --output PATH       批量翻译输出文件
  --no-header             CSV/Excel 无表头模式
  --resume                断点恢复
  --top-k INT             语义匹配返回条数 (默认 10)
  --threshold INT         语义匹配启用阈值 (默认 20)
  --learn                 翻译结果自动写入翻译记忆
  --api-key TEXT          API Key
  -v, --verbose           显示详细信息
  --no-store              不加载本地术语/记忆库
  -h, --help              显示帮助
  -V, --version           显示版本

项目结构

src/qmt/
  cli.py          # CLI 入口与命令定义
  client.py       # Qwen-MT API 客户端
  batch.py        # CSV/Excel 批量翻译
  interactive.py  # 交互式 REPL
  matcher.py      # 向量语义匹配编排层
  embedding.py    # DashScope text-embedding-v3 嵌入 (zvec QwenDenseEmbedding)
  vectorstore.py  # 向量索引存储 (zvec HNSW)
  store.py        # 本地持久化存储 (术语/记忆/领域)
  models.py       # 数据模型
  parsers.py      # 输入解析
  formatters.py   # 终端输出格式化
  constants.py    # 常量定义
  exceptions.py   # 自定义异常

开发

# 安装开发依赖
pip install -e ".[dev]"

# 代码检查
ruff check src/qmt/

# 格式化
ruff format src/qmt/

# 运行测试
pytest

License

Apache-2.0