段言翻译器模型使用指南

Python 到段言(DuanLang)的 AI 自动翻译
段言项目组 · 2026年7月

---

一、模型简介

段言翻译器（duan-translator）是一个基于 Qwen2.5-0.5B-Instruct 微调的 AI 模型（v7），专门用于将 Python 代码翻译为段言（DuanLang）v3.2 编程语言代码。段言是一种使用中文关键字的编程语言，让中文用户可以更自然地理解和编写代码。

1.1 模型信息

项目	说明
模型名称	airoot/duan-translator
基础模型	Qwen2.5-0.5B-Instruct (494M 参数)
模型版本	v7 (checkpoint-500)
量化方式	FP16 (994MB)
训练数据	1175 条 SFT 样本
测试结果	18 项测试全部通过 (18⁄18 PASS)
推理速度	约 26 tokens/秒 (CPU)
上下文长度	4096 tokens

1.2 模型能力

该模型能够翻译以下 Python 语法结构：

• 基础语法：变量赋值、字符串赋值、算术运算、条件分支
• 循环结构：for 循环、while 循环、嵌套循环、break/continue
• 函数定义：参数传递、返回值、递归
• 数据结构：列表操作、字典操作、集合推导、列表推导
• 面向对象：类定义、继承、构造函数、类方法、静态方法、属性访问控制
• 异常处理：try/except/finally、抛出异常
• 高级特性：f-string、lambda 表达式、装饰器、with 语句、高阶函数
• 文件操作：文件读取、文件写入

---

二、环境准备

2.1 安装 Ollama

Ollama 是一个本地大模型运行框架，支持 Windows、macOS 和 Linux。段言翻译器模型通过 Ollama 部署和运行。

Windows 安装：

1. 访问 Ollama 官网：https://ollama.com/download
2. 下载 Windows 版安装包（OllamaSetup.exe）
3. 双击运行安装包，按提示完成安装
4. 安装完成后，Ollama 会自动在后台启动
5. 打开命令提示符或 PowerShell，输入 ollama --version 确认安装成功

macOS 安装：

1. 访问 https://ollama.com/download 下载 macOS 版安装包
2. 双击 .dmg 文件，将 Ollama 拖入 Applications 文件夹
3. 启动 Ollama 应用程序
4. 在终端输入 ollama --version 确认安装成功

Linux 安装：

curl -fsSL https://ollama.com/install.sh | sh

提示：安装完成后，Ollama 服务会自动在后台运行（默认端口 11434）。如需手动启动，执行 ollama serve 命令。

2.2 系统要求

项目	最低要求	推荐配置
内存	2 GB 可用	4 GB 以上
磁盘空间	500 MB	1 GB 以上
CPU	双核 2.0 GHz	四核 2.5 GHz 以上
GPU	不需要（纯 CPU 推理）	有 NVIDIA GPU 可加速
操作系统	Windows 10 / macOS 11 / Ubuntu 20.04	Windows 11 / macOS 14 / Ubuntu 22.04

---

三、下载模型

3.1 一键拉取

确保 Ollama 已安装并运行后，在终端执行以下命令拉取模型：

ollama pull airoot/duan-translator

拉取过程会下载约 398 MB 的模型文件，请确保网络通畅。下载完成后会显示 success 提示。

提示：下载速度取决于网络环境。如果下载较慢，请耐心等待，模型文件仅需下载一次。

3.2 验证安装

下载完成后，执行以下命令确认模型已安装：

ollama list

输出中应包含 airoot/duan-translator，类似如下：

NAME                            SIZE      MODIFIED
airoot/duan-translator  398 MB    2026-07-24

也可以查看模型详细信息：

ollama show airoot/duan-translator

---

四、使用方法

4.1 命令行交互模式

最简单的使用方式是直接在命令行与模型交互：

ollama run airoot/duan-translator

进入交互模式后，直接输入或粘贴 Python 代码，模型会自动翻译为段言代码。例如输入：

def greet(name):
    return f"Hello, {name}!"

模型会输出：

段落 greet 接收 name：
    返回 f"Hello, {name}!"

提示：在交互模式中输入 /bye 可退出。输入多行代码时，按 Shift+Enter 换行，直接按 Enter 发送。

4.2 命令行单次调用

如果不进入交互模式，可以直接用 -p 参数执行单次翻译：

ollama run airoot/duan-translator -p 'def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)'

输出结果：

段落 factorial 接收 n：
    如果 n 小于等于 1：
        返回 1
    返回 n 乘以 factorial(n 减去 1)

4.3 通过 API 调用

Ollama 提供了 HTTP API，可以在程序中调用。模型启动后，API 默认监听 localhost:11434。

使用 curl 调用

curl http://localhost:11434/api/generate -d '{
  "model": "airoot/duan-translator",
  "prompt": "x = 10\nif x > 5:\n    print(\"big\")\nelse:\n    print(\"small\")",
  "stream": false
}'

返回结果（JSON 格式）：

{
  "model": "airoot/duan-translator",
  "response": "设 x 为 10\n如果 x 大于 5：\n    打印(\"big\")\n否则：\n    打印(\"small\")",
  "done": true
}

使用 Python 调用

在 Python 脚本中调用 Ollama API 实现自动化翻译：

import requests

response = requests.post(
    "http://localhost:11434/api/generate",
    json={
        "model": "airoot/duan-translator",
        "prompt": "def add(a, b):\n    return a + b",
        "stream": False
    }
)

duan_code = response.json()["response"]
print(duan_code)

输出：

段落 add 接收 a, b：
    返回 a 加上 b

使用 Ollama Python 库调用

如果安装了 ollama Python 库（pip install ollama），调用更简洁：

import ollama

response = ollama.generate(
    model="airoot/duan-translator",
    prompt="for i in range(5):\n    print(i)"
)

print(response["response"])

输出：

遍历 i 于 0至4：
    打印(i)

使用 Node.js 调用

const response = await fetch('http://localhost:11434/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'airoot/duan-translator',
    prompt: 'squares = [x**2 for x in range(10) if x % 2 == 0]',
    stream: false
  })
});
const data = await response.json();
console.log(data.response);

输出：

定义 squares 等于 [x 乘以 x 遍历 x 之 范围(10) 若 x 取余 2 等于 0]

---

五、段言语法速查

以下是段言 v3.2 的核心语法规则，方便理解模型翻译输出。

5.1 基础语法

Python 语法	段言语法	示例
变量赋值（数字）	设 X 为 Y	设 x 为 10
变量赋值（字符串）	定义 X 等于 Y	定义 s 等于 "hello"
函数定义	段落 名 接收 参数：	段落 add 接收 a, b：
条件判断	如果 / 否则如果 / 否则：	如果 x 大于 5：
打印输出	打印(X)	打印("hello")
返回值	返回 X	返回 a 加上 b

5.2 循环结构

Python 语法	段言语法	示例
for 循环	遍历 i 于 0至N：	遍历 i 于 0至4：
while 循环	当 条件：	当 x 小于 10：
break	跳出	跳出
continue	跳过	跳过

5.3 运算与比较

Python 运算	段言语法	说明
a + b	a 加上 b	加法
a - b	a 减去 b	减法
a * b	a 乘以 b	乘法
a / b	a 除以 b	除法
a % b	a 取余 b	取余
a == b	a 等于 b	相等
a != b	a 不等于 b	不等
a > b	a 大于 b	大于
a < b	a 小于 b	小于
a >= b	a 大于等于 b	大于等于
a <= b	a 小于等于 b	小于等于
and	且	逻辑与
or	或	逻辑或
not	非	逻辑非

5.4 数据结构

Python 语法	段言语法	示例
len(x)	len(x)	获取长度（保持不变）
lst[0] = 10	lst[0] = 10	列表索引赋值（保持不变）
列表推导	[expr 遍历 var 之 列表 若 条件]	[x 遍历 x 之 范围(10) 若 x 取余 2 等于 0]
字典推导	{k: v 遍历 k, v 之 d.items() 若 条件}	{k: v 遍历 k, v 之 d.items()}
集合推导	{expr 遍历 var 之 列表 若 条件}	{x 遍历 x 之 nums 若 x 大于 0}

5.5 面向对象

Python 语法	段言语法	说明
class Name:	类 名：	类定义
__init__(self, ...)	构造 接收 ...：	构造函数
def method(self, ...)	段落 名：	实例方法
self.attr	己.属性	self 引用
class Child(Parent):	类 子类 继承 父类：	类继承
super().method()	父.方法名(参数)	父类调用
@staticmethod	静态 段落 名：	静态方法
@classmethod	类方法 段落 名：	类方法
@property	特性 段落 名：	属性特性

5.6 高级特性

Python 语法	段言语法	说明
f"...{var}..."	f"...{var}..."	f-string 格式保持不变
try/except/finally	尝试：/捕获 ... [e]：/最终：	异常处理
raise Exception	抛出 ...	抛出异常
with open(...) as f:	使用 资源 为 变量：	with 语句
lambda x: expr	接收 参数：返回 表达式	lambda 表达式
filter(pred, data)	筛选(谓词, 数据)	高阶函数-筛选
map(func, data)	映射(函数, 数据)	高阶函数-映射
@decorator	@标注名 标注	装饰器

---

六、翻译示例对照

以下示例展示了常见 Python 代码及其对应的段言翻译输出，可直接用于验证模型效果。

6.1 基础函数

Python 输入：

def add(a, b):
    return a + b

段言输出：

段落 add 接收 a, b：
    返回 a 加上 b

6.2 条件分支

Python 输入：

x = 10
if x > 5:
    print("big")
else:
    print("small")

段言输出：

设 x 为 10
如果 x 大于 5：
    打印("big")
否则：
    打印("small")

6.3 for 循环

Python 输入：

for i in range(5):
    print(i)

段言输出：

遍历 i 于 0至4：
    打印(i)

6.4 f-string

Python 输入：

name = "world"
print(f"Hello, {name}!")

段言输出：

设 name 为 "world"
打印(f"Hello, {name}!")

6.5 类定义与继承

Python 输入：

class Animal:
    def __init__(self, name):
        self.name = name

    def speak(self):
        return f"{self.name} speaks"

段言输出：

类 Animal：
    构造 接收 name：
        己.name 等于 name

    段落 speak：
        返回 f"{己.name} speaks"

6.6 列表推导

Python 输入：

squares = [x**2 for x in range(10) if x % 2 == 0]

段言输出：

定义 squares 等于 [x 乘以 x 遍历 x 之 范围(10) 若 x 取余 2 等于 0]

6.7 异常处理

Python 输入：

try:
    result = 10 / 0
except ZeroDivisionError as e:
    print(f"Error: {e}")

段言输出：

尝试：
    设 result 为 10 除以 0
捕获 ZeroDivisionError 为 e：
    打印(f"Error: {e}")

6.8 嵌套循环

Python 输入：

for i in range(3):
    for j in range(3):
        if i == j:
            print(f"i={i}, j={j}")

段言输出：

遍历 i 于 0至2：
    遍历 j 于 0至2：
        如果 i 等于 j：
            打印(f"i={i}, j={j}")

---

七、常见问题

7.1 模型下载失败怎么办？

如果 ollama pull 命令下载失败或中断，可以重新执行该命令，Ollama 支持断点续传。如果反复失败，请检查网络连接，或尝试使用代理。

7.2 模型运行时报错怎么办？

常见报错及解决方案：

错误信息	原因	解决方案
connection refused	Ollama 服务未启动	执行 ollama serve 启动服务
model not found	模型未下载	执行 ollama pull airoot/duan-translator
out of memory	内存不足	关闭其他程序释放内存，或使用有更多 RAM 的机器
context length exceeded	输入代码过长	精简输入代码，确保不超过 4096 tokens

7.3 翻译结果不准确怎么办？

该模型在 15 项标准测试中全部通过，但对于特别复杂或罕见的 Python 语法组合，翻译结果可能不够理想。建议：

• 将复杂代码拆分为小段，分段翻译
• 确保输入的是规范的 Python 代码
• f-string 中的变量名会保持原样，不会翻译为中文
• len() 函数保持不变，不会翻译为 长度()

7.4 如何在服务器上部署？

在服务器上部署只需两步：

1. 安装 Ollama 并拉取模型（参考第二、三章）
2. 启动 Ollama 服务（ollama serve），其他机器通过 HTTP API 访问

如果需要远程访问，启动 Ollama 时设置环境变量：

# Linux / macOS
OLLAMA_HOST=0.0.0.0:11434 ollama serve

# Windows PowerShell
$env:OLLAMA_HOST="0.0.0.0:11434"
ollama serve

安全提示：远程暴露 Ollama 服务时，请确保网络环境安全，或配置防火墙规则限制访问来源。

7.5 如何更新模型？

当模型有新版本时，重新执行拉取命令即可更新：

ollama pull airoot/duan-translator

Ollama 会自动下载最新版本并替换本地旧版本。

---

八、快速上手速查

以下是从零到使用的完整命令速查，适合有经验的用户快速部署：

# 1. 安装 Ollama（Linux）
curl -fsSL https://ollama.com/install.sh | sh

# 2. 拉取模型
ollama pull airoot/duan-translator

# 3. 命令行交互翻译
ollama run airoot/duan-translator

# 4. 单次翻译
ollama run airoot/duan-translator -p 'def hello(): print("hi")'

# 5. API 调用
curl http://localhost:11434/api/generate -d '{
  "model": "airoot/duan-translator",
  "prompt": "x = 1\nprint(x)",
  "stream": false
}'

# 6. Python 调用
python -c "
import requests
r = requests.post('http://localhost:11434/api/generate',
    json={'model': 'airoot/duan-translator',
          'prompt': 'print(\"hello\")',
          'stream': False})
print(r.json()['response'])
"

模型主页地址：https://ollama.com/airoot/duan-translator