diff --git a/README.md b/README.md new file mode 100644 index 0000000..ec46426 --- /dev/null +++ b/README.md @@ -0,0 +1,194 @@ +# PrivaTrans 翻译工具 + +基于 PySide6 和 GGUF 模型的本地化翻译工具,支持文本翻译、Word 文件导入导出、高级辅助功能和系统资源监控。 + +## 功能特点 + +### 🔤 核心翻译功能 +- 使用本地 GGUF 模型进行翻译,保护隐私 +- 支持中文到英文的翻译 +- 可添加文本背景和场景介绍,提高翻译准确性 +- 支持自定义术语定义,确保专业术语翻译一致性 + +### 📁 Word 文件支持 +- 支持 `.docx` 文件的导入,提取文本内容 +- 支持译文的 `.docx` 文件导出 +- 保持文档段落结构 + +### ⚙️ 模型管理 +- 支持模型文件的选择和切换 +- 显示模型状态(就绪/加载中/失败) +- 支持多种 GGUF 模型格式 + +### 📊 系统资源监控 +- 实时显示 CPU 使用率 +- 实时显示内存使用率 +- 实时显示 GPU 内存使用率(如果有 GPU) +- 每秒更新一次状态栏显示 + +### 🎨 友好的 GUI 界面 +- 简洁现代的设计 +- 可折叠的高级辅助面板 +- 清晰的操作流程 +- 友好的错误提示 + +## 系统要求 + +- Windows 10/11 +- Python 3.8+ +- 至少 4GB RAM(推荐 8GB+) +- GPU(可选,用于加速模型推理) + +## 安装说明 + +### 1. 克隆或下载项目 + +```bash +git clone +cd translate +``` + +### 2. 安装依赖 + +```bash +pip install -r requirements.txt +``` + +#### 注意事项 +- `llama-cpp-python` 库可能需要编译安装,这可能需要一些时间 +- 如果遇到编译错误,可以尝试使用预编译的轮子: + ```bash + pip install llama-cpp-python --only-binary :all: + ``` +- 或者访问 [llama-cpp-python 发布页](https://github.com/abetlen/llama-cpp-python/releases) 下载适合您系统的轮子文件,然后使用 `pip install ` 安装 + +### 3. 准备模型文件 + +将 GGUF 模型文件(如 `HY-MT1.5-1.8B_bf16_Q4_K_M.gguf`)放入 `models/` 目录。 + +## 使用方法 + +### 1. 启动应用 + +```bash +python main.py +``` + +### 2. 加载模型 + +- 应用启动时会自动尝试加载默认模型 +- 点击「更换」按钮可以选择其他模型文件 + +### 3. 输入原文 + +- 在「原文内容」文本框中输入要翻译的文本 +- 或点击「导入 Word」按钮导入 `.docx` 文件 + +### 4. 配置高级辅助(可选) + +- 展开「高级辅助 (背景与术语)」面板 +- 在「文本背景 / 场景介绍」中输入文本的背景信息 +- 在「术语簿」中添加专业术语定义,格式为 `术语 = 翻译` + +### 5. 执行翻译 + +- 点击「开始翻译」按钮 +- 等待翻译完成(根据文本长度和模型大小,时间会有所不同) + +### 6. 查看结果 + +- 翻译结果会显示在「译文结果」文本框中 +- 点击「导出 Word」按钮将结果保存为 `.docx` 文件 +- 点击「复制内容」按钮将结果复制到剪贴板 + +## 项目结构 + +``` +translate/ +├── main.py # 主程序入口 +├── translator.py # 翻译核心逻辑 +├── requirements.txt # 依赖库列表 +├── README.md # 项目说明文档 +├── .gitignore # Git 忽略文件 +├── models/ # 模型文件目录 +├── ui/ +│ └── main_window.py # GUI 界面设计 +├── utils/ +│ ├── logger.py # 日志配置 +│ ├── system_monitor.py # 系统资源监控 +│ └── word_handler.py # Word 文件处理 +└── logs/ # 日志文件目录(自动创建) +``` + +## 日志管理 + +- 日志文件会自动生成在 `logs/` 目录下 +- 控制台显示 INFO 级别的日志 +- 文件记录 DEBUG 级别的日志,便于调试 +- 日志文件会自动旋转、压缩和保留 7 天 + +## 故障排除 + +### 1. 模型加载失败 + +- 检查模型文件路径是否正确 +- 确认模型文件格式是否为 GGUF +- 检查系统内存是否足够 + +### 2. 翻译功能不可用 + +- 确保 `llama-cpp-python` 库已正确安装 +- 查看日志文件了解详细错误信息 + +### 3. GPU 监控不可用 + +- 确保 `GPUtil` 库已正确安装 +- 确认系统中是否有可用的 NVIDIA GPU +- 查看日志文件了解详细错误信息 + +### 4. Word 文件导入导出失败 + +- 确保 `python-docx` 库已正确安装 +- 确认文件格式为 `.docx`(不支持 `.doc` 格式) +- 检查文件路径是否包含特殊字符 + +## 技术栈 + +- **GUI 框架**: PySide6 +- **模型推理**: llama-cpp-python +- **Word 处理**: python-docx +- **日志管理**: loguru +- **系统监控**: psutil, GPUtil + +## 许可证 + +MIT License + +## 更新日志 + +### v1.0.0 (2026-01-14) +- 初始版本发布 +- 支持基本翻译功能 +- 支持 Word 文件导入导出 +- 支持高级辅助功能 +- 支持系统资源监控 + +## 未来计划 + +- 支持更多语言对 +- 实现批量翻译功能 +- 添加翻译历史记录 +- 支持更多文档格式 +- 优化模型加载速度 +- 添加翻译质量评估 + +## 联系方式 + +如有问题或建议,请通过以下方式联系: + +- 项目地址: +- 作者: + +--- + +**PrivaTrans** - 您的本地翻译专家,保护您的隐私,提供高质量翻译服务。 \ No newline at end of file diff --git a/translator.py b/translator.py index 232a64a..cdfd709 100644 --- a/translator.py +++ b/translator.py @@ -1,16 +1,29 @@ -from llama_cpp import Llama import os from utils.logger import logger +# 尝试导入llama_cpp,如果失败则设置Llama为None +try: + from llama_cpp import Llama + llama_cpp_available = True +except ImportError: + logger.warning("llama-cpp-python库未找到,将禁用翻译功能") + Llama = None + llama_cpp_available = False + class Translator: def __init__(self, model_path=None): self.model = None self.model_path = model_path self.is_ready = False self.model_name = "" + self.llama_cpp_available = llama_cpp_available def load_model(self, model_path=None): """加载模型""" + if not self.llama_cpp_available: + logger.error("llama-cpp-python库未找到,无法加载模型") + return False + if model_path: self.model_path = model_path @@ -41,6 +54,10 @@ class Translator: def translate(self, text, context="", terms=None): """执行翻译""" + if not self.llama_cpp_available: + logger.error("llama-cpp-python库未找到,无法执行翻译") + return "" + if not self.is_ready or not self.model: logger.error("模型未就绪,无法执行翻译") return "" diff --git a/ui/main_window.py b/ui/main_window.py index ae1fbb3..fac1846 100644 --- a/ui/main_window.py +++ b/ui/main_window.py @@ -338,6 +338,10 @@ class MainWindow(QMainWindow): QMessageBox.warning(self, "警告", "原文内容为空,无法翻译") return + if not hasattr(self.translator, 'llama_cpp_available') or not self.translator.llama_cpp_available: + QMessageBox.warning(self, "警告", "llama-cpp-python库未安装,无法执行翻译功能") + return + if not self.translator.is_ready: QMessageBox.warning(self, "警告", "模型未就绪,无法翻译") return