feat(translator): 添加llama-cpp-python库可用性检查
在翻译功能中添加对llama-cpp-python库的可用性检查，当库未安装时显示警告信息并禁用翻译功能
This commit is contained in:
194
README.md
Normal file
194
README.md
Normal file
@@ -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 <repository-url>
|
||||||
|
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 <wheel-file>` 安装
|
||||||
|
|
||||||
|
### 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 文件导入导出
|
||||||
|
- 支持高级辅助功能
|
||||||
|
- 支持系统资源监控
|
||||||
|
|
||||||
|
## 未来计划
|
||||||
|
|
||||||
|
- 支持更多语言对
|
||||||
|
- 实现批量翻译功能
|
||||||
|
- 添加翻译历史记录
|
||||||
|
- 支持更多文档格式
|
||||||
|
- 优化模型加载速度
|
||||||
|
- 添加翻译质量评估
|
||||||
|
|
||||||
|
## 联系方式
|
||||||
|
|
||||||
|
如有问题或建议，请通过以下方式联系：
|
||||||
|
|
||||||
|
- 项目地址: <repository-url>
|
||||||
|
- 作者: <your-name>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**PrivaTrans** - 您的本地翻译专家，保护您的隐私，提供高质量翻译服务。
|
||||||
@@ -1,16 +1,29 @@
|
|||||||
from llama_cpp import Llama
|
|
||||||
import os
|
import os
|
||||||
from utils.logger import logger
|
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:
|
class Translator:
|
||||||
def __init__(self, model_path=None):
|
def __init__(self, model_path=None):
|
||||||
self.model = None
|
self.model = None
|
||||||
self.model_path = model_path
|
self.model_path = model_path
|
||||||
self.is_ready = False
|
self.is_ready = False
|
||||||
self.model_name = ""
|
self.model_name = ""
|
||||||
|
self.llama_cpp_available = llama_cpp_available
|
||||||
|
|
||||||
def load_model(self, model_path=None):
|
def load_model(self, model_path=None):
|
||||||
"""加载模型"""
|
"""加载模型"""
|
||||||
|
if not self.llama_cpp_available:
|
||||||
|
logger.error("llama-cpp-python库未找到，无法加载模型")
|
||||||
|
return False
|
||||||
|
|
||||||
if model_path:
|
if model_path:
|
||||||
self.model_path = model_path
|
self.model_path = model_path
|
||||||
|
|
||||||
@@ -41,6 +54,10 @@ class Translator:
|
|||||||
|
|
||||||
def translate(self, text, context="", terms=None):
|
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:
|
if not self.is_ready or not self.model:
|
||||||
logger.error("模型未就绪，无法执行翻译")
|
logger.error("模型未就绪，无法执行翻译")
|
||||||
return ""
|
return ""
|
||||||
|
|||||||
@@ -338,6 +338,10 @@ class MainWindow(QMainWindow):
|
|||||||
QMessageBox.warning(self, "警告", "原文内容为空，无法翻译")
|
QMessageBox.warning(self, "警告", "原文内容为空，无法翻译")
|
||||||
return
|
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:
|
if not self.translator.is_ready:
|
||||||
QMessageBox.warning(self, "警告", "模型未就绪，无法翻译")
|
QMessageBox.warning(self, "警告", "模型未就绪，无法翻译")
|
||||||
return
|
return
|
||||||
|
|||||||
Reference in New Issue
Block a user