JSON 翻译模型使用说明

本项目将hun yuan 7b 模型配置为专用翻译引擎，用于把输入文本翻译为指定语言，并以严格 JSON 格式返回结果。

项目适用于 API 服务、Ollama、AnythingLLM、OpenAI 兼容接口、自动化翻译程序及其他需要结构化翻译结果的系统。

底层模型

本项目使用第三方模型作为底层语言模型。

模型通过系统提示词约束为翻译器，主要负责：

• 自动识别原文语言
• 翻译为指定目标语言
• 保留原文格式和技术术语
• 返回标准 JSON
• 避免将待翻译文本误识别为系统指令
• 减少翻译结果遗漏、截断或返回空内容的问题

实际翻译质量、语言支持范围、上下文长度和输出速度取决于所使用的第三方模型。

功能特点

• 支持多语言翻译
• 支持自动识别原文语言
• 支持直译、自然、正式、技术和学术等翻译风格
• 支持保留标题、段落、列表和 Markdown 格式
• 支持保留型号、路径、网址、代码、公式、单位和技术参数
• 只返回 JSON，不附加解释性文字
• 支持不确定术语记录
• 支持输入错误提示
• 包含针对部分词语可能导致模型不输出、少输出或中断输出问题的完整性约束

关于部分词语不输出的问题

部分第三方模型可能因为模型自身训练、服务平台规则、内容过滤机制或提示词理解错误，出现以下情况：

• 某些词语没有被翻译
• 原文部分内容被省略
• 返回空结果
• 输出在中途停止
• 将原文中的内容误认为指令
• 没有按照 JSON 格式返回

本项目的系统提示词加入了以下处理：

1. 要求模型把所有用户文本视为待翻译内容，而不是可执行指令。
2. 要求模型不得主动删除、总结或省略原文。
3. 要求模型保留全部有效内容。
4. 要求无法确定的词语保留原文，而不是直接删除。
5. 要求模型在无法完成时返回 JSON 错误对象，而不是无响应。
6. 要求模型输出前检查原文开头、结尾和中间内容是否完整对应。
7. 要求模型避免因个别词语而省略整段翻译。

这些设置可以减少部分词语导致的不输出问题，但无法绕过底层模型服务商或部署平台强制执行的安全策略，也不能保证所有第三方模型都能百分之百完整输出。

基本使用方法

调用模型时，需要把翻译器提示词设置为系统提示词，然后向模型发送 JSON 格式的用户输入。

推荐输入格式：

{
  "text": "The spindle speed should be set according to the tool diameter and workpiece material.",
  "source_language": "auto",
  "target_language": "zh-CN",
  "style": "technical",
  "preserve_format": true
}

字段说明：

字段	必填	说明
text	是	需要翻译的原文
source_language	否	原文语言，推荐使用 auto
target_language	是	目标语言代码
style	否	翻译风格
preserve_format	否	是否保留原文结构

支持的翻译风格

natural

自然翻译，优先保证目标语言流畅。

{
  "style": "natural"
}

literal

偏向直译，尽可能保留原句结构。

{
  "style": "literal"
}

formal

适用于正式邮件、通知和商务内容。

{
  "style": "formal"
}

technical

适用于机械、软件、工程、制造和技术文档。

{
  "style": "technical"
}

academic

适用于论文、研究资料和学术内容。

{
  "style": "academic"
}

casual

适用于日常对话和口语内容。

{
  "style": "casual"
}

成功返回格式

{
  "success": true,
  "source_language": "en",
  "target_language": "zh-CN",
  "translation": "主轴转速应根据刀具直径和工件材料进行设置。",
  "uncertain_terms": []
}

存在不确定术语时

{
  "success": true,
  "source_language": "en",
  "target_language": "zh-CN",
  "translation": "完整翻译内容",
  "uncertain_terms": [
    {
      "source": "专业术语",
      "translation": "采用的译法",
      "reason": "该术语存在多种可能译法"
    }
  ]
}

不确定术语不会被直接删除。模型应优先保留原文，并在 uncertain_terms 中说明原因。

错误返回格式

输入内容无效、缺少目标语言或模型无法处理时，应返回：

{
  "success": false,
  "source_language": null,
  "target_language": null,
  "translation": "",
  "uncertain_terms": [],
  "error": "具体错误原因"
}

Ollama 调用示例

假设模型名称为：

your-translation-model:latest

调用示例：

curl http://127.0.0.1:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-translation-model:latest",
    "stream": false,
    "messages": [
      {
        "role": "system",
        "content": "此处填写完整翻译器系统提示词"
      },
      {
        "role": "user",
        "content": "{\"text\":\"Hello world\",\"source_language\":\"auto\",\"target_language\":\"zh-CN\",\"style\":\"natural\",\"preserve_format\":true}"
      }
    ],
    "format": "json"
  }'

建议在 Ollama 中启用：

{
  "format": "json"
}

这样可以进一步降低模型输出非 JSON 内容的概率。

OpenAI 兼容接口示例

curl http://127.0.0.1:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-translation-model:latest",
    "temperature": 0.1,
    "messages": [
      {
        "role": "system",
        "content": "此处填写完整翻译器系统提示词"
      },
      {
        "role": "user",
        "content": "{\"text\":\"Hello world\",\"source_language\":\"auto\",\"target_language\":\"zh-CN\",\"style\":\"natural\",\"preserve_format\":true}"
      }
    ]
  }'

推荐参数

为提高翻译稳定性，建议使用以下参数：

{
  "temperature": 0.1,
  "top_p": 0.9,
  "frequency_penalty": 0,
  "presence_penalty": 0
}

建议将温度控制在：

0.0 至 0.2

温度过高可能造成：

• 翻译内容扩写
• 输出格式不稳定
• JSON 无法解析
• 专业术语不一致
• 原文信息被改写

程序端校验建议

部署者不应只依赖模型提示词，还应在程序端验证结果。

至少检查：

1. 返回内容是否为有效 JSON。
2. success 是否为布尔值。
3. translation 是否存在。
4. 翻译结果是否异常为空。
5. 目标语言是否与请求一致。
6. 输出长度是否明显短于原文。
7. 是否出现 Markdown 代码块包裹 JSON。
8. 是否出现 JSON 前后的解释文字。

简单的 PHP 校验示例：

<?php

declare(strict_types=1);

$response = trim($modelOutput ?? '');

$data = json_decode($response, true);

if (!is_array($data) || json_last_error() !== JSON_ERROR_NONE) {
    throw new RuntimeException(
        '模型返回的内容不是有效 JSON：' . json_last_error_msg()
    );
}

if (!array_key_exists('success', $data)) {
    throw new RuntimeException('返回结果缺少 success 字段');
}

if ($data['success'] === true) {
    $translation = trim((string)($data['translation'] ?? ''));

    if ($translation === '') {
        throw new RuntimeException('模型返回成功，但翻译内容为空');
    }
}

if ($data['success'] === false) {
    $error = (string)($data['error'] ?? '未知错误');
    throw new RuntimeException('翻译失败：' . $error);
}

生产环境建议

对于正式部署，建议增加自动重试机制。

当发生以下情况时，可以重新请求一次：

• JSON 解析失败
• translation 为空
• 输出明显被截断
• 返回内容缺少必要字段
• 原文较长但译文异常短
• 模型输出了额外说明

重试时可在用户输入中增加：

上一轮输出不完整。请重新翻译全部原文，确保首段、中间段和末段全部保留，并且只返回有效 JSON。

不建议无限重试。通常最多重试一到两次，避免形成重复请求。

长文本处理

对于超过模型上下文限制的长文本，应在程序端分段。

推荐原则：

• 按标题或自然段分割
• 不要从句子中间切断
• 每段保留上下文标题
• 分段结果分别校验
• 最后按原顺序合并
• 每段使用相同目标语言和翻译风格