# ecdict-model-data

**Repository Path**: aipd/ecdict-model-data

## Basic Information

- **Project Name**: ecdict-model-data
- **Description**: 基于ECDICT项目制作训练模型数据
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-01-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 单词转音标工具

一个非大模型的单词转音标工具，采用混合方案，支持美式和英式音标转换，可用于处理大量单词的音标获取。

## 功能特性

- ✅ 支持美式和英式发音转换
- ✅ 采用混合方案：CMUdict词典 + eSpeak NG后端
- ✅ 支持单个单词和批量转换
- ✅ 支持JSON格式输出
- ✅ 能够处理CMUdict词典中没有的新词
- ✅ 具有完整准确的ARPAbet到IPA映射表
- ✅ 支持处理stardict.csv文件并生成音标数据
- ✅ 支持异常关闭后继续执行
- ✅ 记录没有网络异常和没有找到音标的单词
- ✅ 新增phonetic_data目录用于存储生成的音标数据
- ✅ 支持verbose日志输出，可配置开关
- ✅ 支持eSpeak自定义路径配置
- ✅ 采用模块化设计，各组件封装为独立类
- ✅ 完善的异常处理机制，区分网络异常和无音标情况
- ✅ 支持resume功能，可从上次中断处继续执行
- ✅ 日志中包含音标的获取来源

## 安装依赖

### 基础依赖

```bash
pip install -r requirements.txt
```

### 可选依赖

- **eSpeak NG**：用于生成新词的音标
  - Windows：从 [eSpeak NG 官网](https://github.com/espeak-ng/espeak-ng/releases) 下载并安装
  - Linux：使用包管理器安装，如 `sudo apt-get install espeak-ng`
  - macOS：使用 Homebrew 安装，如 `brew install espeak-ng`

- **nltk CMUdict**：用于获取已知词的音标，首次运行时会自动下载

- **epitran**：用于生成更准确的音标，作为备选方案

### 环境配置

- 确保 Python 版本 ≥ 3.7
- 对于 Windows 用户，建议将 eSpeak NG 安装路径添加到系统环境变量 `PATH` 中

## 核心脚本说明

### 1. process_phonetic_csv.py

**功能**：处理 stardict.csv 文件，生成两个输出文件：
- `stardict_phonetic.csv`：包含有效音标数据的 CSV 文件，格式为 `word,phonetic,phonetic_us,phonetic_uk`
- `no_phonetic_words.txt`：记录无法获取音标的单词列表

**使用方法**：

```bash
# 基本使用
python process_phonetic_csv.py

# 自定义输入文件路径
python process_phonetic_csv.py --input /path/to/your/stardict.csv

# 自定义输出目录
python process_phonetic_csv.py --output_dir /path/to/output/directory

# 启用 verbose 日志
python process_phonetic_csv.py --verbose

# 从上次中断处继续执行
python process_phonetic_csv.py --resume
```

**参数说明**：

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--input` | 输入 stardict.csv 文件路径 | `dict_data/stardict.csv` |
| `--output_dir` | 输出目录路径 | `phonetic_data` |
| `--verbose` | 是否启用详细日志 | `False` |
| `--resume` | 是否从上次中断处继续执行 | `False` |

**输出文件说明**：

- `stardict_phonetic.csv`：包含有效音标数据的单词，每行格式为 `word,phonetic,phonetic_us,phonetic_uk`
- `no_phonetic_words.txt`：记录无法获取音标的单词，每行一个单词
- `processed_words.txt`：记录已处理的单词，用于 resuming 功能

### 2. word_to_phonetic.py

**功能**：核心工具类，用于单个单词或批量单词的音标转换

**使用方法**：

```bash
# 单个单词转换
python word_to_phonetic.py hello world --accent us

# 同时返回美式和英式发音
python word_to_phonetic.py hello world --accent both

# 批量转换
python word_to_phonetic.py --file test_batch.txt --accent us

# 输出到文件
python word_to_phonetic.py hello world --accent us --output results.txt
```

### 3. test_word_to_phonetic.py

**功能**：测试脚本，用于验证核心功能的正确性

**使用方法**：

```bash
python test_word_to_phonetic.py
```

### 4. test_epitran.py

**功能**：测试 epitran 后端的功能和可用性

**使用方法**：

```bash
python test_epitran.py
```

### 作为库使用

```python
from word_to_phonetic import WordToPhonetic

# 创建实例
phonetic_tool = WordToPhonetic()

# 单个单词转换
phonetic = phonetic_tool.get_phonetic("hello", "us")

# 批量转换
results = phonetic_tool.batch_get_phonetic(["hello", "world"], "us")

# JSON格式输出
json_result = phonetic_tool.get_phonetic_json("hello", include_both=True)
```

## 词典资源

- **CMUdict**: 内置词典，提供高精度的已知词发音，首次运行时会自动下载
- **eSpeak NG**: 用于生成新词的音标，支持多种语言和口音
  - Git地址: https://github.com/espeak-ng/espeak-ng/releases
- **epitran**: 用于生成更准确的音标，作为备选方案，包含多种语言的映射文件
- **simple mapping files**: 简单的字符到音标的映射文件，作为最后的备选方案

## 项目结构

```
.
├── phonetic_data/            # 生成的音标数据目录
├── ECDICT/            # 请自行下载 https://gitee.com/etl-en/ECDICT.git 并解压 stardict.7Z
├── prepare_training_data.py  # 转换成训练数据
├── process_phonetic_csv.py  # 处理音标CSV文件脚本（核心脚本）
├── word_to_phonetic.py        # 主程序文件，包含核心功能
├── test_word_to_phonetic.py  # 测试脚本，包含所有测试用例
├── requirements.txt          # 依赖列表
└── README.md                # 项目说明文档
```

## 技术原理

### 混合方案

1. **优先使用CMUdict词典**查询已知词，确保高精度
2. **新词使用eSpeak NG后端**生成发音
3. **应用口音规则**，正确区分美式和英式发音
4. **支持JSON格式输出**，便于集成到其他系统

## 训练数据准备

### 功能概述

`prepare_training_data.py` 脚本用于将ECDICT项目数据整理成适合模型训练的各种数据格式，包括：

- **预训练数据**：JSONL格式，用于语言模型预训练
- **指令微调数据**：JSONL格式，用于模型指令跟随能力训练
- **有监督微调数据**：JSONL格式，用于模型对话能力训练

### 输入数据要求

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--all` | 生成所有数据类型 | 无 |
| `--pretrain` | 仅生成预训练数据 | 无 |
| `--instruction` | 仅生成指令微调数据 | 无 |
| `--supervised` | 仅生成有监督微调数据 | 无 |
| `--num_samples` | 指定生成的指令微调样本数量 | 1000 |

### 使用示例

#### 生成所有数据类型

```bash
python prepare_training_data.py --all
```

#### 仅生成预训练数据

```bash
python prepare_training_data.py --pretrain
```

#### 生成指令微调数据（指定样本数量）

```bash
python prepare_training_data.py --instruction --num_samples 5000
```

#### 生成有监督微调数据

```bash
python prepare_training_data.py --supervised
```

### 输出结果

脚本会在当前目录下创建 `training_data` 文件夹，并生成以下文件：

| 输出文件 | 数据类型 | 格式 | 用途 |
|----------|----------|------|------|
| `training_data/pretrain_hq.jsonl` | 预训练数据 | JSONL | 语言模型预训练 |
| `training_data/sft_command.jsonl` | 指令微调数据 | JSONL | 模型指令跟随训练 |
| `training_data/sft_data.jsonl` | 有监督微调数据 | JSONL | 模型对话能力训练 |

### 数据格式说明

#### 预训练数据格式

```json
{"text": "单词 /音标/ 英文释义 中文释义"}
```

#### 指令微调数据格式

```json
{
  "instruction": "查询单词的中文释义",
  "input": "hello",
  "output": "你好"
}
```

#### 有监督微调数据格式

```json
{
  "conversations": [
    {
      "role": "user",
      "content": "hello 是什么意思？"
    },
    {
      "role": "assistant",
      "content": "音标: /həˈləʊ/\n你好\n英文释义: used as a greeting or to begin a phone conversation"
    }
  ]
}
```

## 许可证

MIT License