企业官网建设流程全解析

• 人工智能
• 深度学习
• NLP
• 计算机视觉
• 强化学习

导读

ReadTwice 是 Google Research 提出的"带记忆的超长文档阅读"（Reading Very Large Documents with Memories）模型实现，核心思想是让模型对文档进行两次阅读：第一次读取生成全局摘要（记忆），第二次阅读时携带这些摘要信息重新处理原文，从而突破 Transformer 输入长度限制、更好地处理跨段长距离依赖。本文以readtwice/README.md为主干，结合仓库源码，完整讲解该模型的架构原理、依赖安装、预训练权重加载，以及 HotpotQA、TriviaQA、NarrativeQA 三个阅读理解任务从数据预处理、TFRecord 生成到 TPU 微调的全流程实操，并附上配置项与关键源码的对照解析。

模型概述与仓库结构

ReadTwice 仓库对应论文ReadTwice: Reading Very Large Documents with Memories，部分函数最初为 ETC（Enhanced Transformer Capture，同样位于本仓库etcmodel目录）项目实现，在此基础上演进出"二次阅读 + 全局记忆"的机制。

仓库核心目录结构如下：

• readtwice/data_utils：数据工具，包含 Beam 流水线工具、TF 示例构造（data_utils.py）、SentencePiece 分词（tokenization.py）及对应测试；
• readtwice/layers：模型层实现，如侧输入注意力 attention.py、Transformer 主体 transformer.py、嵌入层、重计算梯度、TPU 工具（tpu_utils.py）等；
• readtwice/models：模型主体（modeling.py、config.py）、优化器、损失函数，以及 HotpotQA / TriviaQA / NarrativeQA 三个下游任务的预处理与微调脚本；
• readtwice/run.sh：一键脚本，创建虚拟环境、安装依赖并运行全部单元测试。

依赖安装与环境要求

安装命令

README 推荐的获取与安装方式如下：

svn export https://github.com/google-research/google-research/trunk/readtwice pip install -r readtwice/requirements.txt

仓库为只读镜像，实际使用中也可直接以本仓库readtwice目录为工作目录，其依赖清单见 requirements.txt。

依赖清单（readtwice/requirements.txt）主要包括：tensorflow>=1.15.0（使用 TF1 兼容 API）、absl-py、apache-beam（预处理阶段用于并行生成 TFRecord）、nltk（句子切分与答案标注）、numpy、sentencepiece（RoBERTa 同款分词）、intervaltree、sortedcontainers以及bert-tensorflow。

重要硬件前提

WARNING：当前代码依赖部分自定义算子（特别是cross_replica_concat），要求TPU（或 CPU）环境。从源码看，该算子位于 readtwice/layers/tpu_utils.py，其实现通过xla.replica_id()获取当前 TPU 核编号，用tf.scatter_nd把本地张量散落到"复制副本"维度，再经tpu.cross_replica_sum跨核求和、tf.reshape展平，从而把分布在num_replicas个 TPU 核上的张量拼接成首维扩大num_replicas倍的完整张量（详见 losses.py 中cross_batch_softmax等跨批操作的使用）。README 也提示：可以通过调整代码使其适配 GPU，但需要自行改造。

此外还需安装：

pip install cloud-tpu-client

运行单元测试

单元测试通过 unittest 发现机制运行，前提是当前工作目录必须为readtwice文件夹的父目录（即仓库根目录），否则模块导入会失败：

python -m unittest discover -s readtwice -p '*_test.py'

该命令会扫描readtwice下所有*_test.py，覆盖数据工具、各网络层、模型、损失、优化器与三个任务的评估代码。readtwice/run.sh则等价地封装了"虚拟环境 + 安装依赖 + 跑测试"的完整流程。

预训练模型与分词器

官方发布了一个预训练 checkpoint（readtwice.tar.gz，存放于公共存储桶），可用于复现论文实验。模型词汇表与 RoBERTa 完全一致，SentencePiece 分词器由本仓库的 bertseq2seq 项目提供（vocab_gpt.model）。

微调前需要准备：

export PRETRAINED_MODEL_DIR=gs://path/to/directory/with/pretrained/model export CONFIG_PATH=${PRETRAINED_MODEL_DIR}/read_it_twice_bert_config.json export PRETRAINED_MODEL_CHECKPOINIT=${PRETRAINED_MODEL_DIR}/model.ckpt-1000000 export SPM_MODEL_PATH=/path/to/vocab_gpt.model export NLTK_DATA_PATH=/tmp/nltk_dir

其中read_it_twice_bert_config.json是模型配置文件，model.ckpt-1000000是预训练 checkpoint（README 原文如此拼写CHECKPOINIT，实际为 checkpoint 之意），NLTK_DATA_PATH用于 nltk 句子切分所需数据的存放位置。

配置文件的完整字段

配置类ReadItTwiceBertConfig定义在 readtwice/models/config.py，由from_json_file从 JSON 加载、to_json_string序列化。完整字段及含义如下：

模型配置加载逻辑get_model_config（config.py）支持三种来源：优先读取model_dir下的read_it_twice_bert_config.json；若不存在，可从source_file或 Base64 编码的source_base64读取，并（默认）把源配置写入模型目录以便后续复用。

核心机制：两次读取（Read-It-Twice）架构

从 readtwice/models/modeling.py 的实现看，ReadItTwiceBertModel的处理流程为：

1. 第一次读取：transformer_with_side_inputs（TransformerWithSideInputLayers）对块内 token 做标准自注意力，同时通过FusedSideAttention（layers/attention.py）把侧输入（第一次读取时可无）作为额外的 K/V 参与注意力。该层不使用相对注意力，是标准 Transformer 层的直接推广，因此可以方便地从预训练 BERT/RoBERTa 直接迁移权重。
2. 摘要提取：SummaryExtraction从第一次读取的隐藏状态中提取块级摘要（Summary结构体含states、processed_states、block_ids、block_pos、labels），并通过get_cross_block_att（modeling.py）依据文档 ID 计算块间注意力掩码——cross_block_attention_mode决定了不同块摘要之间的交互范围（block/doc/batch/other_blocks）。必要时借助cross_replica_concat在 TPU 多核间汇聚全局摘要，实现"全局记忆"。
3. 第二次读取：依据second_read_type决定如何利用摘要：
   • from_scratch（默认）：把第一次读取的输出从零重新处理，将全局摘要的processed_states作为侧输入，att_mask_with_side_input同时包含 token-token 掩码与 token-摘要映射掩码（modeling.py）；
   • new_layers/new_layers_cross_attention：在第一次读取结果之上堆叠second_read_num_new_layers个新 Transformer 层；
   • cross_attend_once：先用SideAttention残差块让 token 一次性关注全局摘要（支持cross_attention_top_kTop-K 截断与块位置嵌入），再送入新层（modeling.py）。

这种"两遍 + 记忆"设计使模型无需把整个长文档硬塞进单一上下文窗口，而是以摘要为媒介实现跨块、跨文档的信息传递，这正是应对超长文档阅读的核心思路。模型测试 modeling_test.py 中的test_model、test_get_cross_block_att等用例覆盖了不同second_read_type、cross_block_attention_mode与摘要后处理的组合，可作为理解各配置行为的参考。

下游任务微调实战

三个任务的通用流程均为：① 下载数据并设置路径 → ② 用preprocess脚本生成 TFRecord 示例并拷贝到 GCS → ③ 用run_finetuning在 TPU 上微调（先训练后评估）。

HotpotQA（多跳抽取式问答）

下载hotpot_train_v1.1.json、hotpot_dev_distractor_v1.json到${HOTPOTQA_DATA_DIR}后：

export HOTPOTQA_DATA_DIR=/path/to/HotpotQA export HOTPOTQA_EXAMPLE_DIR=${HOTPOTQA_DATA_DIR}/examples export HOTPOTQA_EXAMPLE_GCP_BUCKET=gs://path/to/gcp/bucket export HOTPOTQA_OUTPUT_FOLDER=gs://path/to/HotpotQA/output/folder mkdir -p ${HOTPOTQA_EXAMPLE_DIR}

生成 TFRecord（验证集不生成答案标注，训练集加--generate_answers）：

python -m readtwice.models.hotpot_qa.preprocess \ --spm_model_path=${SPM_MODEL_PATH} \ --input_file=${HOTPOTQA_DATA_DIR}/hotpot_dev_distractor_v1.json \ --output_prefix=${HOTPOTQA_EXAMPLE_DIR}/valid \ --nltk_data_path=${NLTK_DATA_PATH} python -m readtwice.models.hotpot_qa.preprocess \ --spm_model_path=${SPM_MODEL_PATH} \ --input_file=${HOTPOTQA_DATA_DIR}/hotpot_train_v1.1.json \ --output_prefix=${HOTPOTQA_EXAMPLE_DIR}/train \ --generate_answers \ --nltk_data_path=${NLTK_DATA_PATH} gcloud storage cp ${HOTPOTQA_EXAMPLE_DIR}/* ${HOTPOTQA_EXAMPLE_GCP_BUCKET} gcloud storage cp ${HOTPOTQA_DATA_DIR}/hotpot_dev_distractor_v1.json ${HOTPOTQA_EXAMPLE_GCP_BUCKET}

TPU 微调（训练阶段）：

python -m readtwice.models.hotpot_qa.run_finetuning \ --read_it_twice_bert_config_file=${CONFIG_PATH} \ --input_file=${HOTPOTQA_EXAMPLE_GCP_BUCKET}/train.tfrecord-* \ --output_dir=${HOTPOTQA_OUTPUT_FOLDER} \ --init_checkpoint=${PRETRAINED_MODEL_CHECKPOINIT} \ --enable_side_inputs \ --cross_block_attention_mode=doc \ --do_train \ --nodo_eval \ --optimizer=adamw \ --learning_rate=3e-05 \ --num_train_epochs=6 \ --warmup_proportion=0.1 \ --learning_rate_schedule=inverse_sqrt \ --poly_power=1 \ --start_warmup_step=0 \ --save_checkpoints_steps=5000 \ --iterations_per_loop=1000 \ --nouse_one_hot_embeddings \ --use_tpu \ --tpu_job_name=??? \ --num_tpu_cores=16 \ --num_tpu_tasks=1 \ --decode_top_k=40 \ --decode_max_size=10 \ --tpu_name=??? \ --cross_attention_top_k=100

评估阶段仅把--do_train改为--nodo_train --do_eval、--nodo_eval改为--do_eval，其余参数不变（注意 README 中nodo_eval/nodo_train为原文写法，其语义即关闭对应开关）。

WARNING：对输出结果的正式评估还需要论文附录中的额外步骤（HotpotQA 的完整打分包含 yes/no、支持事实等，仓库 hotpot_qa/evaluation.py 与 hotpot_qa/losses.py 分别实现了评估指标与含cross_replica_concat的跨核损失）。

TriviaQA（开放域长文档问答）

下载 TriviaQA 官方数据（wikipedia/web 证据 + QA json）后：

export TRIVIAQA_DATA_DIR=/path/to/TriviaQA export TRIVIAQA_EXAMPLE_DIR=${TRIVIAQA_DATA_DIR}/examples export TRIVIAQA_EXAMPLE_GCP_BUCKET=gs://path/to/gcp/bucket export TRIVIAQA_OUTPUT_FOLDER=gs://path/to/TriviaQA/output/folder mkdir -p ${TRIVIAQA_EXAMPLE_DIR}

生成 TFRecord 时需额外指定证据语料目录：

python -m readtwice.models.trivia_qa.preprocess \ --spm_model_path=${SPM_MODEL_PATH} \ --input_file=${TRIVIAQA_DATA_DIR}/qa/wikipedia-dev.json \ --wikipedia_dir=${TRIVIAQA_DATA_DIR}/evidence/wikipedia \ --web_dir=${TRIVIAQA_DATA_DIR}/evidence/web \ --output_prefix=${TRIVIAQA_EXAMPLE_DIR}/valid \ --nltk_data_path=${NLTK_DATA_PATH} python -m readtwice.models.trivia_qa.preprocess \ --spm_model_path=${SPM_MODEL_PATH} \ --input_file=${TRIVIAQA_DATA_DIR}/qa/wikipedia-train.json \ --wikipedia_dir=${TRIVIAQA_DATA_DIR}/evidence/wikipedia \ --web_dir=${TRIVIAQA_DATA_DIR}/evidence/web \ --output_prefix=${TRIVIAQA_EXAMPLE_DIR}/train \ --generate_answers \ --nltk_data_path=${NLTK_DATA_PATH} gcloud storage cp ${TRIVIAQA_EXAMPLE_DIR}/* ${TRIVIAQA_EXAMPLE_GCP_BUCKET} gcloud storage cp ${TRIVIAQA_DATA_DIR}/qa/wikipedia-dev.json ${TRIVIAQA_EXAMPLE_GCP_BUCKET}

微调命令与 HotpotQA 的差异点：学习率更低（--learning_rate=1e-05）、学习率调度为--learning_rate_schedule=poly_decay、--save_checkpoints_steps=3000、--iterations_per_loop=200、--decode_top_k=8 --decode_max_size=20，并新增--eval_json_path与--eval_data_split=valid：

python -m readtwice.models.trivia_qa.run_finetuning \ --read_it_twice_bert_config_file=${CONFIG_PATH} \ --input_file=${TRIVIAQA_EXAMPLE_GCP_BUCKET}/train.tfrecord-* \ --eval_json_path=${TRIVIAQA_EXAMPLE_GCP_BUCKET}/wikipedia-dev.json \ --output_dir=${TRIVIAQA_OUTPUT_FOLDER} \ --init_checkpoint=${PRETRAINED_MODEL_CHECKPOINIT} \ --enable_side_inputs \ --cross_block_attention_mode=doc \ --do_train \ --nodo_eval \ --optimizer=adamw \ --learning_rate=1e-05 \ --num_train_epochs=6 \ --warmup_proportion=0.1 \ --learning_rate_schedule=poly_decay \ --poly_power=1 \ --start_warmup_step=0 \ --save_checkpoints_steps=3000 \ --iterations_per_loop=200 \ --nouse_one_hot_embeddings \ --use_tpu \ --tpu_job_name=??? \ --num_tpu_cores=16 \ --num_tpu_tasks=1 \ --decode_top_k=8 \ --decode_max_size=20 \ --eval_data_split=valid \ --spm_model_path=${SPM_MODEL_PATH} \ --tpu_name=??? \ --cross_attention_top_k=100

评估阶段同样切换为--nodo_train --do_eval。TriviaQA 的评估实现（evaluate_triviaqa）位于 trivia_qa/evaluation.py，包含答案归一化（去冠词、标点、下划线、统一大小写与空白）以及基于 ground-truth 集合的 EM/F1 计算。

NarrativeQA（整本故事书阅读）

从 NarrativeQA 官网下载后，NarrativeQA 特殊之处在于复用trivia_qa.run_finetuning入口，且预处理需要 qaps（问答对）与 documents（故事文本）两份 CSV：

export NARRATIVEQA_DATA_DIR=/path/to/NarrativeQA export NARRATIVEQA_EXAMPLE_DIR=${NARRATIVEQA_DATA_DIR}/examples export NARRATIVEQA_EXAMPLE_GCP_BUCKET=gs://path/to/gcp/bucket export NARRATIVEQA_OUTPUT_FOLDER=gs://path/to/NarrativeQA/output/folder mkdir -p ${NARRATIVEQA_EXAMPLE_DIR}

python -m readtwice.models.narrative_qa.preprocess \ --spm_model_path=${SPM_MODEL_PATH} \ --input_qaps=${NARRATIVEQA_DATA_DIR}/qaps.csv \ --input_documents=${NARRATIVEQA_DATA_DIR}/documents.csv \ --data_split=valid \ --stories_dir=${NARRATIVEQA_DATA_DIR}/tmp/ \ --output_prefix=${NARRATIVEQA_EXAMPLE_DIR}/valid \ --nltk_data_path=${NLTK_DATA_PATH} python -m readtwice.models.narrative_qa.preprocess \ --spm_model_path=${SPM_MODEL_PATH} \ --input_qaps=${NARRATIVEQA_DATA_DIR}/qaps.csv \ --input_documents=${NARRATIVEQA_DATA_DIR}/documents.csv \ --data_split=train \ --stories_dir=${NARRATIVEQA_DATA_DIR}/tmp/ \ --output_prefix=${OUTPUT_NARRATIVE_QA}/train \ --generate_answers \ --nltk_data_path=${NLTK_DATA_PATH} gcloud storage cp ${NARRATIVEQA_DATA_DIR}qaps.csv ${NARRATIVEQA_EXAMPLE_DIR}

NarrativeQA 的预处理实现了基于 ROUGE-L oracle 的抽取式答案搜索（extractive_oracle.py）与故事文本解析（Gutenberg/电影剧本格式），评估逻辑见 narrative_qa/evaluation.py。

微调时使用trivia_qa.run_finetuning，学习率进一步降至5e-06，并关闭默认侧输入：

python -m readtwice.models.trivia_qa.run_finetuning \ --read_it_twice_bert_config_file=${CONFIG_PATH} \ --input_file=${NARRATIVEQA_EXAMPLE_DIR}/train.tfrecord-* \ --input_qaps=${NARRATIVEQA_EXAMPLE_DIR}/qaps.csv \ --eval_data_split=valid \ --output_dir=${NARRATIVEQA_OUTPUT_FOLDER} \ --init_checkpoint=${PRETRAINED_MODEL_CHECKPOINIT} \ --enable_side_inputs \ --cross_block_attention_mode=doc \ --do_train \ --nodo_eval \ --optimizer=adamw \ --learning_rate=5e-06 \ --nosummary_enable_default_side_input \ --num_train_epochs=6 \ --warmup_proportion=0.1 \ --learning_rate_schedule=inverse_sqrt \ --poly_power=1 \ --start_warmup_step=0 \ --save_checkpoints_steps=15000 \ --spm_model_path=${SPM_MODEL_PATH} \ --iterations_per_loop=1000 \ --nouse_one_hot_embeddings \ --use_tpu \ --tpu_job_name=??? \ --num_tpu_cores=16 \ --num_tpu_tasks=1 \ --decode_top_k=40 \ --decode_max_size=10 \ --tpu_name=??? \ --cross_attention_top_k=100

评估阶段切换为--nodo_train --do_eval，参数与训练基本一致。

微调命令行参数速查

综合三个任务的run_finetuning命令，核心参数及其作用如下（实现见各任务的 run_finetuning.py 与 trivia_qa/run_finetuning.py）：

训练目标方面，微调采用 masked language model 与跨度预测等损失（models/losses.py 提供LanguageModelLoss、批量共指消解损失等；HotpotQA 另有 yes/no 与 supporting-fact 损失）。预训练阶段的核心配置（如mlm_fraction_to_mask=0.15、mention_mask_mode、mlm_use_whole_word、num_replicas_concat等）可在预训练 demo 脚本 run_pretraining_demo.py 中查看。

预训练说明与 demo

README 明确说明：预训练代码尚未完整发布，主要有两个待解决事项：

1. 预训练依赖自定义 TF 算子，用于在训练过程中动态执行词与实体掩码（对应run_pretraining_demo.py中的mention_mask_mode、mlm_use_whole_word等掩码策略，以及input_utils.py的mask_same_entity_mentions等函数）；
2. 数据预处理目前依赖内部专有基础设施，无法直接开源。

作为替代，仓库发布了预训练 demo（run_pretraining_demo.py）：该脚本虽不可直接执行，但完整展示了核心实现细节，包括：MLM 与共指消解（coreference resolution）损失的组合、source_model_config_file/source_model_config_base64两种模型配置注入方式、num_replicas_concat跨副本摘要汇聚、以及cross_block_attention_mode的块交互策略等，是理解 ReadTwice 预训练目标与数据流的关键入口。

小结

ReadTwice 通过"两次阅读 + 块级全局记忆"的机制，把超长文档阅读理解转化为可并行的块级处理：第一次读取生成摘要记忆，第二次读取携带记忆精读原文。本文从架构原理（ReadItTwiceBertModel与FusedSideAttention、SummaryExtraction的配合）、配置字段（ReadItTwiceBertConfig全参数）、依赖与测试，到 HotpotQA / TriviaQA / NarrativeQA 三大任务的数据预处理与 TPU 微调命令，完整复现了官方 README 的实操路径，并补充了对应的源码级证据。实际复现时请注意：环境需 TPU（或 CPU）、tpu_name等参数需按集群实际填写、评估还需论文附录的额外步骤。

• 人工智能
• 深度学习
• NLP
• 计算机视觉
• 强化学习