【免费下载链接】google-research
Google Research
导读
context_aware_transliteration 是 google-research 仓库中与论文《Context-aware Transliteration of Romanized South Asian Languages》（Computational Linguistics, 2024）对应的开源配套目录，它同时提供两套可运行的转写技术路线：基于 Nisaba FST（有限状态转换器）的上下文感知转写（含已发布模型与解码工具链），以及基于 Keras Transformer 的神经转写推理。本文将以该目录下的四份官方文档为骨架，结合仓库源码，完整讲解模型的获取与目录结构、Bengali（bn）等 12 种语言的 FST 双向转写实操、论文 LaTeX 表格的复现流程、三类生成文本资源的用途，以及 Transformer 模型的推理命令与参数体系，让读者可以直接上手复现论文实验或在自有数据上运行转写。
项目定位与仓库结构
论文与代码的对应关系
该目录对应论文 Kirov, Christo, Cibu Johny, Anna Katanova, Alexander Gutkin, and Brian Roark. "Context-aware Transliteration of Romanized South Asian Languages." Computational Linguistics (2024)，doi: 10.1162/coli_a_00510。README 明确说明：目录内提供了获取论文配套代码与数据的入口，并附有标准引用格式（详见 context_aware_transliteration/README.md）。
README 将文档拆分为四个主题入口，全部位于同一目录下：
| 文档 | 主题 | 仓库相对路径 |
|---|---|---|
| 论文表格生成指南 | 用原始系统输出构建论文中的 LaTeX 表格 | generate_tables.md |
| 生成文本资源说明 | 论文使用的归一化语料、模拟平行转写语料与转写缓存 | text_resources.md |
| FST 转写运行指南 | 用已发布模型运行 Nisaba FST 转写 | fst_translit.md |
| Transformer 神经模型 | Keras Transformer 转写模型的推理与训练入口 | transformer/README.md |
从目录结构看，本仓库内直接提供了 Transformer 路线的完整实现源码（transformer/ 子目录），而 FST 路线的解码器本体依赖外部 Nisaba 库，本仓库释放的是配套的模型压缩包与脚本，两者互补。
transformer 源码目录
context_aware_transliteration/
├── README.md # 主入口文档
├── generate_tables.md # 论文 LaTeX 表格生成指南
├── text_resources.md # 生成文本资源说明
├── fst_translit.md # Nisaba FST 转写运行指南
└── transformer/ # Keras Transformer 实现
├── README.md # 神经模型使用说明
├── transformer_main.py # 训练/推理主入口
├── transformer.py # 模型定义
├── translate.py # 推理与解码逻辑
├── misc.py # 命令行参数定义
├── model_params.py # 参数集（tlit/base/big 等）
├── data_pipeline.py # 数据流水线
├── data_preprocess.py # 数据预处理
├── optimizer.py # 学习率调度与优化器
└── utils/ # 三种分词器
├── char_tokenizer.py # 字符级 Subtokenizer
├── fullstring_tokenizer.py # 整串 wordpiece 分词
└── tlit_tokenizer.py # 预留的转写专用分词器
一、基于 Nisaba FST 的转写：模型获取与双向解码
FST 路线是论文的核心实验手段之一：转写模型以"Pair-6g"（成对 6-gram 序列模型）形式编码为加权有限状态转换器，配合原生文字语言模型与 wordpiece 模型实现上下文感知的拉丁-天城体等文字的双向转写。完整的运行步骤见 fst_translit.md。
1.1 下载并解压模型
模型压缩包约 3.6GB，覆盖论文研究的全部 12 种语言：
cd $MYLOCALDIR
wget https://storage.googleapis.com/gresearch/context_aware_transliteration/models.tar
tar -xf models.tar
解压后得到三个子目录（$MYLOCALDIR/models 下）：
| 子目录 | 内容 | 说明 |
|---|---|---|
models/LM | 每种语言的上下文（contextual）与非上下文（no-context）语言模型 | 训练自维基百科文本，编码为 FST |
models/pairLM | 每种语言 25 个不同的 Pair-6g 转写模型 | 编码为 FST，编号 00~24 |
models/wordpiece | 每种语言的 wordpiece 模型 | 有序 TSV 文件 |
注意：所有模型文件都是 gzip 压缩的（.fst.gz、.tsv.gz），使用前必须先 gunzip，用完可重新 gzip 以节省磁盘。
1.2 原生文字 → 拉丁罗马化（native → Latin）
以孟加拉语（bn）为例，使用 00 号转写模型，对输入句 "এটি একটি উদাহরণ বাক্য"（"这是一个例句"）逐词返回 2 个最优罗马化结果：
L="bn"
N="00"
PAIRLM="${MYLOCALDIR}/models/pairLM/${L}.${N}.pair6g.fst"
INPUT_SENTENCE="এটি একটি উদাহরণ বাক্য"
IFILE="/tmp/tmp.input.txt"
OFILE="/tmp/tmp.output.txt"
gunzip "${PAIRLM}.gz"
echo "${INPUT_SENTENCE}" >"${IFILE}"
"${MYNISABA}"/bazel-bin/nisaba/translit/fst/pairlm_decoder \
--ifile="${IFILE}" \
--ofile="${OFILE}" \
--pairlm_config="pairlm_file: \"${PAIRLM}\"" \
--kbest=2
gzip "${PAIRLM}"
cat "${OFILE}"
输出格式为制表符分隔的五列，每词一行（kbest=2 即每词两行）：
0 0 এটি eti 0.121981
0 0 এটি etee 2.16426
0 1 একটি ekti 0.394668
0 1 একটি ektee 1.12056
0 2 উদাহরণ udaharan 0.520971
0 2 উদাহরণ udahoron 0.901262
0 3 বাক্য bakyo 0.685076
0 3 বাক্য bakya 0.701284
各列含义依次为：句子编号（从 0 开始）、词在句中的位置、输入词、输出转写、softmax 归一化权重（负对数概率，越小越优）。可以看到每个词的第一候选与第二候选都返回，便于后续重排序或集成。
1.3 拉丁罗马化 → 原生文字（Latin → native，模型求逆）
只需在 pairlm_config 中追加 invert_pairlm: true，即对 FST 做求逆运算，即可实现反向转写：
L="bn"
N="00"
PAIRLM="${MYLOCALDIR}/models/pairLM/${L}.${N}.pair6g.fst"
INPUT_SENTENCE="eti ekti udaharan bakyo"
IFILE="/tmp/tmp.input.txt"
OFILE="/tmp/tmp.output.txt"
gunzip "${PAIRLM}.gz"
echo "${INPUT_SENTENCE}" >"${IFILE}"
"${MYNISABA}"/bazel-bin/nisaba/translit/fst/pairlm_decoder \
--ifile="${IFILE}" \
--ofile="${OFILE}" \
--pairlm_config="pairlm_file: \"${PAIRLM}\" invert_pairlm: true" \
--kbest=2
gzip "${PAIRLM}"
cat "${OFILE}"
输出示例：
0 0 eti এটি 0.0735731
0 0 eti এতি 2.64603
0 1 ekti একটি 0.0549145
0 1 ekti এক্তি 2.9293
0 2 udaharan উদাহরণ 0.123822
0 2 udaharan উদাহরন 2.15018
0 3 bakyo বাক্য 0.0340729
0 3 bakyo বক্য 3.39624
1.4 加入上下文语言模型（Latin → native 场景）
语言模型与 wordpiece 模型都作用于输出侧，因此只在 Latin→native 转写时使用。配置中需同时给出 lm_file、oov_symbol 与 word_piece_model：
L="bn"
N="00"
LMNAME="${L}.wiki-filt.train.text.shuf.ws_norm.wp"
CONTEXT_LM="${MYLOCALDIR}/models/LM/${LMNAME}.context.mod.fst"
WPMOD="${MYLOCALDIR}/models/wordpiece/${L}.wp_model.32k.ordered.tsv"
PAIRLM="${MYLOCALDIR}/models/pairLM/${L}.${N}.pair6g.fst"
INPUT_SENTENCE="eti ekti udaharan bakyo"
IFILE="/tmp/tmp.input.txt"
OFILE="/tmp/tmp.output.txt"
gunzip "${PAIRLM}.gz"
gunzip "${CONTEXT_LM}.gz"
gunzip "${WPMOD}.gz"
echo "${INPUT_SENTENCE}" >"${IFILE}"
"${MYNISABA}"/bazel-bin/nisaba/translit/fst/pairlm_decoder \
--ifile="${IFILE}" \
--ofile="${OFILE}" \
--pairlm_config="pairlm_file: \"${PAIRLM}\" invert_pairlm: true \
lm_file: \"${CONTEXT_LM}\" oov_symbol: \"<unk>\" \
word_piece_model: \"${WPMOD}\"" \
--kbest=2
gzip "${PAIRLM}"
gzip "${CONTEXT_LM}"
gzip "${WPMOD}"
cat "${OFILE}"
加入上下文语言模型后解码耗时更长，且 1-best 结果与不加时相同，但每个位置的最优词得分显著更高（负对数概率更低），即概率分布更"尖"（更集中）。输出中出现的负权重是浮点精度问题所致，实际约等于零：
0 0 eti এটি 1.86845e-05
0 0 eti টি 11.1736
0 1 ekti একটি -1.51325e-05
0 1 ekti একটিই 13.0955
0 2 udaharan উদাহরণ 0.0361591
0 2 udaharan উদাহরন 3.33747
0 3 bakyo বাক্য 0.000191451
0 3 bakyo ব্যাখ্য 8.72112
1.5 使用非上下文语言模型（词级，需闭包运算）
如果只想用词级、无句子上下文的语言模型，则需对语言模型做**闭包（closure）**运算后再与转写模型复合，从而能够转写整串输入：
L="bn"
N="00"
LMNAME="${L}.wiki-filt.train.text.shuf.ws_norm.wp"
NOCONTEXT_LM="${MYLOCALDIR}/models/LM/${LMNAME}.no-context.mod.fst"
WPMOD="${MYLOCALDIR}/models/wordpiece/${L}.wp_model.32k.ordered.tsv"
PAIRLM="${MYLOCALDIR}/models/pairLM/${L}.${N}.pair6g.fst"
INPUT_SENTENCE="eti ekti udaharan bakyo"
IFILE="/tmp/tmp.input.txt"
OFILE="/tmp/tmp.output.txt"
gunzip "${PAIRLM}.gz"
gunzip "${NOCONTEXT_LM}.gz"
gunzip "${WPMOD}.gz"
echo "${INPUT_SENTENCE}" >"${IFILE}"
"${MYNISABA}"/bazel-bin/nisaba/translit/fst/pairlm_decoder \
--ifile="${IFILE}" \
--ofile="${OFILE}" \
--pairlm_config="pairlm_file: \"${PAIRLM}\" invert_pairlm: true \
lm_file: \"${NOCONTEXT_LM}\" apply_closure_to_lm: true \
oov_symbol: \"<unk>\" word_piece_model: \"${WPMOD}\"" \
--kbest=2
gzip "${PAIRLM}"
gzip "${NOCONTEXT_LM}"
gzip "${WPMOD}"
cat "${OFILE}"
与 1.4 的关键差异仅在 apply_closure_to_lm: true 这一项配置。输出示例（注意词级 LM 不使用句子上下文，第二词出现了跨词粘连的候选 "এটি"）：
0 0 eti এটি 0.00749036
0 0 eti টি 4.91153
0 1 ekti এটি 8.80764
0 1 ekti একটি -4.49489e-05
0 2 udaharan উদাহরণ 0.0113594
0 2 udaharan উদাহরন 4.46381
0 3 bakyo বাক্য -9.45233e-05
0 3 bakyo ব্যাখ্য 9.91945
1.6 前置条件：安装 Nisaba 库
FST 解码器本体（pairlm_decoder）来自 Nisaba 库，需先编译。官方指南假设宿主机为 amd64 Linux，通过 Bazelisk（Bazel 的版本管理包装器）构建：
git clone https://github.com/google-research/nisaba.git
wget https://github.com/bazelbuild/bazelisk/releases/download/v1.19.0/bazelisk-linux-amd64
chmod +x bazelisk-linux-amd64
cd nisaba
USE_BAZEL_VERSION=6.5.0 ../bazelisk-linux-amd64 build -c opt nisaba/...
MYNISABA=${PWD}
构建完成后，$MYNISABA 即指向 Nisaba 库目录，其下应存在编译产物 bazel-bin 子目录（前文命令中的 ${MYNISABA}/bazel-bin/nisaba/translit/fst/pairlm_decoder 即解码器可执行文件）。其他架构可下载对应平台的 Bazelisk 版本构建。
二、复现论文的 LaTeX 表格
论文中的实验表格可以从原始系统输出一键重建，完整步骤见 generate_tables.md。
2.1 两类表格与对应数据包
| 数据包 | 规模 | 内容 | 输出脚本 |
|---|---|---|---|
generate_single_word_tables.tar | 约 1GB | 单词转写结果及生成脚本 | single_word_scripts/generate_single_word_tables.sh |
generate_full_string_tables.tar | 约 5.2GB | 整串转写结果及生成脚本 | full_string_scripts/generate_full_string_tables.sh |
两个脚本均依赖已编译的 Nisaba 库（见上文安装步骤），且都可分阶段运行（脚本内有详细说明）。注意：由于压缩包及中间产物体积很大，官方建议预留约 20GB 磁盘空间；同时因实验条件（conditions）数量多，生成全部表格预计需要数小时。
2.2 生成单词语表
cd $MYLOCALDIR
wget https://storage.googleapis.com/gresearch/context_aware_transliteration/generate_single_word_tables.tar
tar -xf generate_single_word_tables.tar
./single_word_scripts/generate_single_word_tables.sh $MYNISABA
2.3 生成整串语表
cd $MYLOCALDIR
wget https://storage.googleapis.com/gresearch/context_aware_transliteration/generate_full_string_tables.tar
tar -xf generate_full_string_tables.tar
./full_string_scripts/generate_full_string_tables.sh $MYNISABA
两个脚本可以安全地同时运行。若 tar 文件已下载，可省略 wget 步骤。运行结束后，LaTeX 表格分别位于 $MYLOCALDIR/single_word_latex_tables 与 $MYLOCALDIR/full_string_latex_tables 目录中，其余中间结果也会保留在该目录下供检查。
三、论文使用的三类生成文本资源
text_resources.md 说明了论文中使用的生成文本资源及其获取方式。这些资源的共同生产链路是：从 Dakshina 数据集（google-research-datasets 下的南亚语言公开数据集）出发，先做文字归一化，再用训练好的模型自动罗马化/生成转写缓存。
3.1 归一化原生文字维基百科语料
约 340MB 的 text/text_normalized_native_script_corpora.tar 包含论文语言建模所用的全部归一化原生文字维基语料，文本源自 Dakshina 数据集。归一化的做法是将词表外（OOV）字符映射为空白，具体细节以论文为准。
3.2 模拟平行转写语料
利用上述原生文字维基语料，论文自动罗马化文本，模拟出平行转写语料（原文↔罗马化配对）。罗马化的采样方法见论文。为捕获多次训练运行的变异性，使用了 5 个不同训练得到的模型，生成 A~E 五个运行版本，每个约 6.6GB：
| 文件 | 大小 (GB) | 说明 |
|---|---|---|
text/text_simulated_parallel_corpora_a.tar | 6.6 | 通过采样自动罗马化生成的模拟平行转写句，运行 A |
text/text_simulated_parallel_corpora_b.tar | 6.6 | 同上，运行 B |
text/text_simulated_parallel_corpora_c.tar | 6.6 | 同上，运行 C |
text/text_simulated_parallel_corpora_d.tar | 6.6 | 同上，运行 D |
text/text_simulated_parallel_corpora_e.tar | 6.6 | 同上，运行 E |
3.3 离线构建的转写缓存
为验证在线转写中使用缓存（由相对昂贵、多系统集成得到的转写结果）的有效性，论文为各语言的高频拉丁词元构建了转写缓存。缓存构建同样采用 5 个不同训练的模型，共 5 个运行版本，每个约 2.8GB：
| 文件 | 大小 (GB) | 说明 |
|---|---|---|
text/text_transliteration_caches_a.tar | 2.8 | 供在线处理使用的转写缓存，运行 A |
text/text_transliteration_caches_b.tar | 2.8 | 同上，运行 B |
text/text_transliteration_caches_c.tar | 2.8 | 同上，运行 C |
text/text_transliteration_caches_d.tar | 2.8 | 同上，运行 D |
text/text_transliteration_caches_e.tar | 2.8 | 同上，运行 E |
各类缓存的具体构建方法与各语言缓存规模，论文正文中有详细说明。下载文件名均以上述表内相对路径（位于 text/ 子目录下）追加在存储桶地址后组成完整 URL。
四、Keras Transformer 神经转写模型
除 FST 路线外，仓库还完整发布了神经转写模型实现，使用说明见 transformer/README.md。该说明在 64GB 内存、10 核 CPU 的 Linux 机器上验证过；代码按原样提供，不同环境需要自行调整。
4.1 环境搭建
使用 Anaconda Python 创建虚拟环境并安装依赖：
conda create -n clpaper python=3.9
conda activate clpaper
pip install tf-models-official==2.13.1
注意：tf-models-official 的 2.13.1 是与本代码兼容的最新已知版本，后续版本引入了破坏性变更，需要修改代码才能运行。由于 transformer_main.py 大量复用 official 包的工具（distribute_utils、performance、flags_core、keras_utils 等），版本匹配是能否运行的关键前提。
4.2 推理命令
python transformer_main.py \
--model_dir=${CHECKPOINT} \
--vocab_file=${VOCAB} \
--max_length=64 \
--param_set=tlit \
--mode=predict_topk \
--beam_size_override=8 \
--infer_file=${INFILE} \
--num_gpus=0 \
--preds_file=${OUTFILE}
各参数含义：
| 参数 | 说明 |
|---|---|
--model_dir | 检查点路径。一个检查点通常包含 *.ckpt.data 与 *.ckpt.index 两个文件，只需指定到 *.ckpt 前缀；若传入目录，transformer_main.py 会调用 tf.train.latest_checkpoint 自动寻找最新检查点 |
--vocab_file | 词汇表文件路径 |
--max_length | 最大序列长度，示例中为 64 |
--param_set | 参数集名称，转写任务使用 tlit（另有 tiny/base/big/fullstring，见 model_params.py） |
--mode | 运行模式，train 或 predict_topk；其他值会抛出 ValueError（见 transformer_main.py） |
--beam_size_override | 覆盖参数集中默认的 beam size；> 0 时生效，否则沿用参数集默认值（transformer_main.py） |
--infer_file | 输入文件，每行一个输入词的纯文本 |
--num_gpus | GPU 数量，CPU 推理设为 0 |
--preds_file | 输出 TSV 文件路径 |
推理时，translate.py 中的 tlit_from_text 逐行读取输入、编码、beam 搜索解码，并将"输入词 / 预测 / 似然"写入输出文件。需要说明的是，predict_topk 依赖模型输出的 top-k 解码结果，--beam_size_override=8 即请求每词返回 8 个候选。
4.3 输出格式示例
输出为 TSV（制表符分隔）三列：输入词、输出预测、似然分数。以泰米尔语（Tamil）为例：
adikkum அடிக்கும் -0.17351153
adikkum அதிக்கும் -4.0013576
adikkum ஆடிக்கும் -4.337666
adikkum அடிக்கும்ஊம் -4.511404
adikkum அடைக்கும் -4.5802116
adikkum அடிக்கும்ொம் -4.601365
4.4 两种分词模式与参数集（源码级补充）
推理时词表的加载方式由 --wordpiece 标志控制（transformer_main.py）：
- 默认（
--wordpiece=False）：使用字符级 char_tokenizer.py 中的Subtokenizer。其词表以"字符即 subword"方式构建，保留<pad>/<EOS>/<UNK>三个保留 token（ID 分别为 0/1/2），编码时逐字符映射、OOV 映射为<UNK>； --wordpiece=True：使用 fullstring_tokenizer.py 的Subtokenizer，对应param_set=fullstring的整串 wordpiece 方案。
与转写任务直接相关的是 TLIT_PARAMS（model_params.py），其关键配置如下，可用于理解论文中单词语级转写模型的规模与训练设置：
| 参数 | tlit 取值 | 说明 |
|---|---|---|
vocab_size | 247 | 词表规模（字符级） |
hidden_size | 128 | 隐层维度 |
num_hidden_layers | 4 | 编码器/解码器层数 |
num_heads | 4 | 多头注意力头数 |
filter_size | 1024 | 前馈网络内层维度 |
layer_postprocess_dropout / attention_dropout / relu_dropout | 0.36 | 三类 dropout（仅训练时生效） |
label_smoothing | 0.1 | 标签平滑 |
learning_rate | 2.0 | 学习率（配合 warmup 调度） |
learning_rate_warmup_steps | 2000 | warmup 步数 |
beam_size | 8 | 默认 beam size |
alpha | 0.6 | beam search 长度归一化系数 |
max_length | 64 | 最大序列长度 |
default_batch_size | 1024 | 每批最大 token 数 |
FULLSTRING_PARAMS 则面向整串转写：vocab_size=32000、hidden_size=512、6 层、8 头、filter_size=2048、dropout 0.1、learning_rate=1.0、warmup 4000 步，规模显著大于单词语级模型。param_set 的可选值定义在 misc.py 的 PARAMS_MAP 中，多 GPU 环境下会切换到对应的 *_MULTI_GPU_PARAMS 变体（如 TLIT_MULTI_GPU_PARAMS）。
4.5 训练模式简述
--mode=train 时，transformer_main.py 会读取 --data_dir 下 *train* 命名的 TFRecord 文件，逐条解析 inputs/targets 稀疏特征、按 --max_length 过滤超长样本，然后进入训练循环。相关训练参数（--train_steps、--steps_between_evals、--learning_rate、--label_smoothing、--learning_rate_warmup_steps 等）均在 misc.py 中定义，可与参数集默认值互相覆盖。优化器采用带 warmup 的 Adam（beta1=0.9、beta2=0.997、epsilon=1e-09，见 transformer_main.py 与 optimizer.py）。
五、使用要点与注意事项汇总
综合四份文档，落地使用本目录资源时有以下几点需要留意：
- 磁盘与时间预算：FST 模型包约 3.6GB、表格数据包 1GB/5.2GB、文本资源单个 0.34~6.6GB，表格复现建议预留约 20GB 空间，且耗时以小时计。
- Nisaba 前置依赖：所有 FST 相关操作（模型解码、表格生成）都要求先编译好 Nisaba（Bazel 6.5.0 + Bazelisk 构建），并让
$MYNISABA指向含bazel-bin的库目录。 - 模型使用前需 gunzip：LM、pairLM、wordpiece 三类模型文件均为 gzip 压缩，使用前解压、使用后可重新压缩。
- 方向性差异：语言模型与 wordpiece 模型只作用于输出侧，因此只参与 Latin→native 方向的转写；纯 pairLM 模型则两个方向都可用（native→Latin 不需求逆，Latin→native 需
invert_pairlm: true）。 - 神经模型版本约束：
tf-models-official必须锁定 2.13.1，更高版本会因 API 变更无法直接运行。 - 输出列语义：FST 解码器输出五列（句号/词位/输入/输出/负对数概率），Transformer 输出三列（输入/预测/似然），下游脚本解析时注意区分。
引用方式
若在论文或研究中使用了本目录代码与数据，请按以下格式引用（来自 context_aware_transliteration/README.md）：
Kirov, Christo, Cibu Johny, Anna Katanova, Alexander Gutkin, and Brian Roark. "Context-aware Transliteration of Romanized South Asian Languages." Computational Linguistics (2024). doi: 10.1162/coli_a_00510.
另需注意：本目录不是谷歌官方产品（README 中的强制免责声明），代码按原样提供，作者不保证在所有环境下的可用性，使用时应结合实际环境调整。
【免费下载链接】google-research
Google Research
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
