# tensorflow/nmt architecture

> Architecture diagram of the GitHub repository tensorflow/nmt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tensorflow/nmt
- Repository: https://github.com/tensorflow/nmt

## Overview

##### Project Type & Purpose
- This is an open-source tutorial/toolkit for building Neural Machine Translation (NMT) systems using TensorFlow’s seq2seq API.
- It provides:
- A vanilla seq2seq model (encoder–decoder)
- Attention-based variants (Luong/Bahdanau)
- Google’s GNMT architecture
- A complete training, evaluation, and inference pipeline
- Utility scripts for data download, BLEU/ROUGE scoring, and standard hyperparameter presets

##### High-Level File Structure & Architectural Patterns
- Top-level:
- train.py – entry point for building and running the training graph
- inference.py – entry point for batch inference
- nmt/nmt.py – unified CLI that dispatches to training or inference based on flags
- nmt/scripts/ – shell + Python scripts (download data, compute BLEU/ROUGE)
- nmt/standard_hparams/ – JSON presets for common configurations (IWSLT, WMT)
- nmt/testdata/ – small sample data for unit tests
- Core package (nmt/):
- model.py – vanilla seq2seq definition (embeddings, multi-layer RNNs, loss, optimizer)
- attention_model.py – wraps decoder with tf.contrib.seq2seq.AttentionWrapper
- gnmt_model.py – GNMTAttentionMultiCell for multi-GPU, parallelizable decoding
- model_helper.py – shared helpers for graph construction and checkpoint management
- inference.py / nmt.py – build inference graph (greedy & beam-search)
- utils/ – data pipeline (iterator_utils.py), vocab lookup (vocab_utils.py), evaluation (evaluation_utils.py), misc

##### Key Insights from README
- Emphasizes three separate TensorFlow graphs: Training, Evaluation, Inference
- Uses tf.data Datasets + iterators for efficient batching, bucketing, padding
- Describes core NMT components: Embedding → Encoder RNN → (Attention) → Decoder RNN → Projection → Loss → Optimizer
- Details on greedy decoding vs. beam search and multi-GPU placement

A. Entry Layer (CLI)
- “nmt/nmt.py” reads flags → chooses TRAIN or INFER path → invokes appropriate graph builder in train.py or inference.py
B. Data Ingestion & Pre-processing
- Scripts: download_iwslt15.sh, wmt16_en_de.sh → raw parallel text files
- tf.data Pipeline (utils/iterator_utils.py):
- TextLineDataset → tokenization → vocabulary lookup (vocab_utils) → zip source/target → padded_batch → iterator
C. Graph Builders
- Training Graph (train.py + model_helper):
- Builds Embedding layers; Encoder RNN (optionally bidirectional); AttentionWrapper (if flag set) or vanilla decoder
- Projection layer; Loss (cross-entropy with padding mask); Gradient clipping; Optimizer (SGD/Adam)
- Summaries for TensorBoard; Saver for checkpoints
- Evaluation Graph (train.py):
- Shares variable scopes; same forward pass; additional ops for BLEU/perplexity
- Inference Graph (inference.py):
- Builds encoder and decoder with GreedyEmbeddingHelper or BeamSearchDecoder; no backprop ops
D. Model Variants
- Vanilla seq2seq: nmt/model.py
- Attention NMT: nmt/attention_model.py + tf.contrib.seq2seq.LuongAttention or BahdanauAttention
- GNMT: nmt/gnmt_model.py (GNMTAttentionMultiCell for multi-GPU)
E. Utilities & Scripts
- evaluation_utils.py: BLEU, ROUGE computation
- scripts/bleu.py, scripts/rouge.py: wrapper CLI scripts
- standard_hparams: JSON files tie hyperparameters to pre-trained checkpoints
F. External Services
- TensorBoard (logs from training graph)
- Filesystem (checkpoints, vocab, data, inference outputs)

##### Architectural Patterns & Design Principles
- Modular separation: CLI ↔ Data Pipeline ↔ Graph Builders ↔ Model Variants ↔ Utils
- Clear separation of graphs (training/eval/inference) via separate scopes & sessions
- Use of tf.data iterators for pipeline flexibility & performance
- Pluggable attention mechanisms and multi-GPU parallelism
- Configuration-driven (flags & JSON hparams) for reproducibility

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI & Orchestration"
        direction TB
        CLI["CLI Launcher\n(nmt/nmt.py)"]:::orchestration
    end

    %% Data Ingestion & Pre-processing
    subgraph "Data Ingestion & Pre-processing"
        direction TB
        Scripts["Download & Scoring Scripts\n(nmt/scripts/)"]:::util
        RawData["Raw Parallel Text"]:::data
        Pipeline["tf.data Pipeline\n(iterator_utils.py)"]:::data
        VocabLookup["Vocabulary Lookup\n(vocab_utils.py)"]:::data
    end

    %% Model Core Components
    subgraph "Model Core"
        direction TB
        Embedding["Embeddings"]:::model
        Encoder["Encoder RNN"]:::model
        Attention["AttentionWrapper\n(nmt/attention_model.py)"]:::model
        Decoder["Decoder RNN"]:::model
        Projection["Projection & Loss"]:::model
    end

    %% Graph Builders
    subgraph "Graph Builders"
        direction TB
        TrainGraph["Training Graph\n(train.py)"]:::orchestration
        EvalGraph["Evaluation Graph\n(train.py)"]:::orchestration
        InferGraph["Inference Graph\n(inference.py)"]:::orchestration
    end

    %% Utilities & Config
    subgraph "Utilities & Config"
        direction TB
        ModelHelper["Graph Helpers\n(model_helper.py)"]:::util
        EvalUtils["Evaluation Utilities\n(evaluation_utils.py)"]:::util
        MiscUtils["Misc Utilities\n(misc_utils.py\nnmt_utils.py)"]:::util
        HParams["Standard Hyperparameters\n(nmt/standard_hparams/)"]:::util
        TestData["Small Test Data\n(nmt/testdata/)"]:::storage
    end

    %% Storage & External Services
    subgraph "Storage & Services"
        direction TB
        Checkpoints["Checkpoints"]:::storage
        Translations["Inference Outputs"]:::storage
        Metrics["BLEU/ROUGE Scores"]:::storage
        TensorBoard["TensorBoard"]:::external
    end

    %% Flow Arrows
    CLI -->|"flags & mode"| TrainGraph
    CLI -->|"flags & mode"| InferGraph
    CLI -->|"flags & mode"| EvalGraph

    Scripts --> RawData
    RawData --> Pipeline
    Pipeline --> VocabLookup
    VocabLookup --> Pipeline
    Pipeline --> TrainGraph
    Pipeline --> EvalGraph
    Pipeline --> InferGraph

    HParams -.->|JSON presets| TrainGraph
    HParams -.->|JSON presets| InferGraph

    TrainGraph --> ModelHelper
    EvalGraph --> ModelHelper
    InferGraph --> ModelHelper

    TrainGraph --> Embedding
    TrainGraph --> Encoder
    TrainGraph --> Attention
    TrainGraph --> Decoder
    TrainGraph --> Projection

    EvalGraph --> Embedding
    EvalGraph --> Encoder
    EvalGraph --> Attention
    EvalGraph --> Decoder
    EvalGraph --> Projection

    InferGraph --> Embedding
    InferGraph --> Encoder
    InferGraph --> Attention
    InferGraph --> Decoder
    InferGraph --> Projection

    EvalGraph --> EvalUtils
    InferGraph --> Translations
    TrainGraph --> Checkpoints
    TrainGraph --> Metrics
    TrainGraph --> TensorBoard

    %% Click Events
    click CLI "https://github.com/tensorflow/nmt/blob/master/nmt/nmt.py"
    click TrainGraph "https://github.com/tensorflow/nmt/blob/master/train.py"
    click InferGraph "https://github.com/tensorflow/nmt/blob/master/inference.py"
    click Embedding "https://github.com/tensorflow/nmt/blob/master/nmt/model.py"
    click Attention "https://github.com/tensorflow/nmt/blob/master/nmt/attention_model.py"
    click ModelHelper "https://github.com/tensorflow/nmt/blob/master/nmt/model_helper.py"
    click InferGraph "https://github.com/tensorflow/nmt/blob/master/nmt/inference.py"
    click Pipeline "https://github.com/tensorflow/nmt/blob/master/nmt/utils/iterator_utils.py"
    click VocabLookup "https://github.com/tensorflow/nmt/blob/master/nmt/utils/vocab_utils.py"
    click EvalUtils "https://github.com/tensorflow/nmt/blob/master/nmt/utils/evaluation_utils.py"
    click MiscUtils "https://github.com/tensorflow/nmt/blob/master/nmt/utils/misc_utils.py"
    click MiscUtils "https://github.com/tensorflow/nmt/blob/master/nmt/utils/nmt_utils.py"
    click HParams "https://github.com/tensorflow/nmt/tree/master/nmt/standard_hparams/"
    click Scripts "https://github.com/tensorflow/nmt/blob/master/nmt/scripts/download_iwslt15.sh"
    click Scripts "https://github.com/tensorflow/nmt/blob/master/nmt/scripts/wmt16_en_de.sh"
    click Scripts "https://github.com/tensorflow/nmt/blob/master/nmt/scripts/bleu.py"
    click Scripts "https://github.com/tensorflow/nmt/blob/master/nmt/scripts/rouge.py"
    click TestData "https://github.com/tensorflow/nmt/tree/master/nmt/testdata/"

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1E88E5
    classDef model fill:#C8E6C9,stroke:#43A047
    classDef orchestration fill:#FFE0B2,stroke:#FB8C00
    classDef util fill:#E1BEE7,stroke:#8E24AA
    classDef storage fill:#BCAAA4,stroke:#6D4C41
    classDef external fill:#FFCDD2,stroke:#E53935
```
