# 翻译与跨语言支持

1. 目的与范围 #

本文档介绍Ragflow-Plus的多语言能力，包括跨语言搜索功能和翻译服务。系统提供全面的国际化支持，使用户能够用一种语言查询知识库，同时检索另一种语言的内容。

关于用户界面本地化和语言选择，请参阅 国际化与本地化。关于知识库配置选项，请参阅 知识库管理系统。

2. 系统架构 #

Ragflow-Plus通过多个集成组件实现翻译和跨语言支持：使用T5模型的专用翻译服务、跨语言搜索能力以及全面的前端国际化。

2.1 翻译服务架构 #

┌─────────────────────────────────────────┐
│      前端层 (Frontend Layer)             │
│  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │ Chat UI  │  │Knowledge │  │Locale│  │
│  │          │  │Base Test │  │Files │  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────────────────────────────┘
                   ↕
┌─────────────────────────────────────────┐
│      翻译处理 (Translation Processing)    │
│  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │Translation│  │Cross-Lang│  │T5    │  │
│  │Service   │  │Detection │  │Trans │  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────────────────────────────┘
                   ↕
┌─────────────────────────────────────────┐
│      后端服务 (Backend Services)          │
│  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │Translate │  │Conversation│  │Dialog│  │
│  │API       │  │API       │  │API  │  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────────────────────────────┘
                   ↕
┌─────────────────────────────────────────┐
│      AI模型 (AI Models)                   │
│  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │T5 Model  │  │T5Tokenizer│  │Model │  │
│  │          │  │          │  │Path  │  │
│  └──────────┘  └──────────┘  └──────┘  │
└─────────────────────────────────────────┘
                   ↕
┌─────────────────────────────────────────┐
│      存储与配置 (Storage & Config)        │
│  ┌──────────┐  ┌──────────┐            │
│  │Model Path│  │Prompt    │            │
│  │./models  │  │Config    │            │
│  └──────────┘  └──────────┘            │
└─────────────────────────────────────────┘

核心文件：

• api/apps/translate_app.py - 后端翻译API
• web/src/services/translationService.ts - 前端翻译服务
• web/src/hooks/logic-hooks.ts - 跨语言搜索逻辑
• web/src/hooks/knowledge-hooks.ts - 知识库测试集成

2.2 跨语言搜索流程 #

跨语言搜索的完整流程：

关键步骤：

1. 中文检测：使用正则表达式 /[\u4e00-\u9fff]/ 检测文本是否包含中文字符
2. 配置检查：从对话或对话配置中获取 cross_language_search 设置
3. 翻译请求：如果启用，将中文文本发送到翻译API，参数为 source_lang: 'zh' 和 target_lang: 'en'
4. 消息更新：用翻译后的英文文本替换原始消息内容
5. 搜索执行：使用翻译后的查询执行搜索

核心实现：

• web/src/hooks/logic-hooks.ts:187-300 - 前端翻译逻辑
• web/src/hooks/knowledge-hooks.ts:225-250 - 知识库测试集成

3. 跨语言搜索实现 #

3.1 前端翻译逻辑 #

跨语言搜索功能主要在 useSendMessageWithSse hook中实现，当功能启用时自动检测中文文本并将其翻译为英文。

处理流程：

实现细节：

1. 消息分析：使用正则表达式 /[\u4e00-\u9fff]/ 检测用户消息是否包含中文字符
2. 配置查找：检索对话和对话配置，检查 cross_language_search 是否启用
3. 翻译请求：将中文文本发送到翻译API，参数为 source_lang: 'zh' 和 target_lang: 'en'
4. 消息更新：用翻译后的英文文本替换原始消息内容
5. 搜索执行：使用翻译后的查询继续搜索

核心实现： web/src/hooks/logic-hooks.ts:179-355

3.2 知识库测试集成 #

知识库测试功能也集成了跨语言搜索：

处理流程：

1. 问题检测：检查测试问题是否包含中文
2. 翻译处理：如果启用跨语言搜索且问题包含中文，先翻译为英文
3. 参数更新：将翻译后的文本更新到测试参数中
4. 禁用后端处理：设置 cross_language_search: false，因为前端已处理翻译

核心实现： web/src/hooks/knowledge-hooks.ts:225-250

4. 翻译服务API #

4.1 后端翻译服务 #

后端翻译服务使用T5模型提供翻译功能：

模型配置：

• 模型名称：utrobinmv/t5_translate_en_ru_zh_small_1024
• 模型路径：./models（本地）或从Hugging Face加载
• 支持语言：中文（zh）、英文（en）、俄文（ru）

API端点：

翻译函数：

def translate_text(text, source_lang="zh", target_lang="en"):
    """翻译文本"""
    # 根据目标语言设置前缀
    if target_lang == "en":
        prefix = "translate to en: "
    elif target_lang == "zh":
        prefix = "translate to zh: "

    # 编码输入
    input_ids = tokenizer(prefix + text, ...)

    # 生成翻译
    generated_tokens = model.generate(...)

    # 解码结果
    translated_text = tokenizer.decode(...)

    return translated_text

核心实现： api/apps/translate_app.py:60-100

4.2 前端翻译服务 #

前端翻译服务提供简化的API接口：

TranslationService类：

class TranslationService {
  // 将中文翻译成英文
  async translateToEnglish(chineseText: string): Promise<string>

  // 检测文本是否包含中文
  containsChinese(text: string): boolean

  // 检查模型是否已准备就绪
  async isModelReady(): Promise<boolean>
}

使用方法：

// 获取单例实例
const translationService = TranslationService.getInstance();

// 翻译中文到英文
const englishText = await translationService.translateToEnglish("你好世界");

// 检测中文
if (translationService.containsChinese(text)) {
  // 处理中文文本
}

核心实现： web/src/services/translationService.ts

4.3 模型配置 #

模型加载：

1. 本地优先：首先尝试从 ./models 目录加载
2. 远程加载：如果本地不存在，从Hugging Face下载
3. 设备选择：支持CPU和GPU（CUDA）模式
4. 全局缓存：模型和分词器作为全局变量缓存

模型参数：

• max_length: 512（最大输入/输出长度）
• num_beams: 4（束搜索数量）
• early_stopping: True（早停机制）
• do_sample: False（不使用采样）

核心实现： api/apps/translate_app.py:30-58

5. 使用场景 #

5.1 对话中的跨语言搜索 #

在对话界面中，用户可以：

1. 输入中文查询：用户输入中文问题
2. 自动翻译：系统检测到中文并自动翻译为英文
3. 执行搜索：使用英文查询在知识库中搜索
4. 返回结果：返回相关的中文文档内容

配置方式：

在对话配置中启用 cross_language_search：

{
  "prompt_config": {
    "cross_language_search": true,
    ...
  }
}

5.2 知识库测试 #

在知识库测试界面中：

1. 输入测试问题：可以是中文或英文
2. 自动翻译：如果启用跨语言搜索且问题包含中文，自动翻译
3. 执行检索：使用翻译后的查询测试检索效果
4. 查看结果：查看检索到的文档片段

配置方式：

在测试参数中设置 cross_language_search: true

5.3 文档编写模式 #

在文档编写模式中，跨语言搜索可以帮助：

1. 多语言内容检索：从英文知识库中检索中文相关内容
2. 内容翻译：自动翻译检索到的内容
3. 上下文理解：理解不同语言的内容关联

6. 技术实现细节 #

6.1 中文检测 #

使用正则表达式检测中文字符：

// 检测中文字符
const containsChinese = /[\u4e00-\u9fff]/.test(text);

Unicode范围：

• \u4e00-\u9fff：CJK统一汉字（常用汉字）

6.2 翻译API调用 #

请求格式：

{
  "text": "要翻译的文本",
  "source_lang": "zh",
  "target_lang": "en"
}

响应格式：

{
  "code": 0,
  "data": {
    "translated_text": "Translated text"
  }
}

6.3 错误处理 #

翻译失败处理：

• 如果翻译API调用失败，返回原始文本
• 如果模型未加载，返回原始文本
• 记录错误日志，但不中断流程

核心实现： web/src/services/translationService.ts:21-30

7. 性能优化 #

7.1 模型缓存 #

• 全局缓存：模型和分词器作为全局变量，避免重复加载
• 懒加载：首次使用时才加载模型
• 健康检查：提供健康检查端点，验证模型状态

7.2 翻译优化 #

• 批量处理：支持批量翻译（未来扩展）
• 缓存结果：可以缓存常见翻译结果（未来扩展）
• 异步处理：前端异步调用，不阻塞UI

7.3 前端优化 #

• 条件翻译：只在需要时进行翻译
• 错误恢复：翻译失败时使用原始文本
• 用户提示：可以显示翻译状态（未来扩展）

8. 配置管理 #

8.1 对话配置 #

在对话配置中启用跨语言搜索：

{
  "prompt_config": {
    "cross_language_search": true,
    "system": "...",
    "parameters": [...]
  }
}

8.2 模型配置 #

环境变量：

• MODEL_PATH: 模型本地路径（可选）
• DEVICE: 设备类型（cpu/cuda）

模型文件：

• 模型文件存储在 ./models 目录
• 包含模型权重和分词器配置

9. 最佳实践 #

9.1 使用建议 #

• 知识库语言：确保知识库内容与查询语言匹配
• 嵌入模型：使用支持多语言的嵌入模型
• 翻译质量：根据实际需求调整翻译模型

9.2 性能考虑 #

• 模型大小：T5模型需要一定内存，注意资源限制
• 翻译延迟：翻译会增加查询延迟，考虑用户体验
• 缓存策略：对常见查询可以缓存翻译结果

9.3 错误处理 #

• 优雅降级：翻译失败时使用原始查询
• 用户提示：告知用户翻译状态
• 日志记录：记录翻译错误以便调试

10. 故障排查 #

10.1 常见问题 #

问题：翻译不工作

• 检查模型是否已加载（调用 /v1/translate/health）
• 检查 cross_language_search 配置是否正确
• 查看后端日志了解模型加载状态

问题：翻译质量差

• 检查模型版本和配置
• 考虑使用更高质量的翻译模型
• 优化输入文本格式

问题：翻译延迟高

• 检查模型加载方式（本地vs远程）
• 考虑使用GPU加速
• 优化模型参数

10.2 调试技巧 #

• 日志查看：检查前端和后端日志
• API测试：直接测试翻译API端点
• 模型验证：使用健康检查端点验证模型状态

11. 未来扩展 #

11.1 支持的语言 #

当前主要支持中文到英文的翻译，未来可以扩展：

• 更多语言对（英文到中文、日文、韩文等）
• 多语言混合查询
• 自动语言检测

11.2 功能增强 #

• 翻译缓存：缓存常见翻译结果
• 批量翻译：支持批量文本翻译
• 翻译质量评估：评估翻译质量并提供反馈

11.3 性能优化 #

• 模型优化：使用更轻量的模型
• GPU加速：支持GPU加速翻译
• 异步处理：异步翻译，不阻塞主流程

12. 总结 #

翻译与跨语言支持是Ragflow-Plus的重要功能，使用户能够用不同语言查询知识库。通过T5翻译模型、前端自动检测和配置管理，系统提供了完整的跨语言搜索能力。

系统的主要特点包括：

• 自动检测：自动检测中文文本并触发翻译
• T5模型：使用先进的T5模型提供高质量翻译
• 灵活配置：通过对话配置启用/禁用跨语言搜索
• 优雅降级：翻译失败时使用原始查询，确保系统可用性
• 前端集成：无缝集成到对话和知识库测试流程
• 健康检查：提供模型状态检查功能

通过合理使用这些功能，可以构建支持多语言的智能问答系统，为用户提供更好的跨语言检索体验。