# yan-gao-gy/muti-teacherkd architecture

> Architecture diagram of the GitHub repository yan-gao-gy/muti-teacherkd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yan-gao-gy/muti-teacherkd
- Repository: https://github.com/yan-gao-gy/muti-teacherkd

## Overview

This repository implements multi-teacher knowledge distillation for joint CTC/attention speech recognition. The user workflow prepares Common Voice manifests, runs teacher inference and stores predictions, then trains and evaluates a student using those predictions. Student training supports average, top-1, top-k, and WER-weighted teacher selection. The graph preserves the documented stages and artifact handoff; source excerpts do not expose every internal call, so unsampled implementation details are not inferred.

Main entry points: [`train_kd.py`](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py) (Student training), [`save_teachers.py`](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/save_teachers.py) (Teacher inference), [`common_voice_prepare.py`](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/common_voice_prepare.py) (Manifest preparation), [`hparams/save_teachers.yaml`](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/hparams/save_teachers.yaml) (Teacher settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Speech data"]
  node_prepare["Manifest preparation"]
  node_csv["Dataset CSVs"]
end

subgraph group_teacher["Teacher inference"]
  node_teacherdata["Teacher data pipeline<br/>[save_teachers.py]"]
  node_inference["Teacher inference<br/>[save_teachers.py]"]
  node_predictions[("Teacher predictions")]
end

subgraph group_student["Student distillation"]
  node_studentdata["Student data pipeline<br/>[train_kd.py]"]
  node_selection["WER teacher selection<br/>[train_kd.py]"]
  node_distillation["Student training<br/>[train_kd.py]"]
  node_metrics["WER and CER evaluation<br/>[train_kd.py]"]
end

subgraph group_config["Experiment settings"]
  node_teacherconfig["Teacher settings<br/>[save_teachers.yaml]"]
  node_trainconfig["Training settings<br/>[train_kd.yaml]"]
end

node_user(("Experimenter"))
node_commonvoice[("Common Voice data")]
node_teachermodels[("Teacher checkpoints")]
node_studentmodel[("Trained student")]

node_user -->|"prepares data"| node_prepare
node_commonvoice -->|"provides recordings"| node_prepare
node_prepare -->|"writes manifests"| node_csv
node_csv -->|"loads data"| node_teacherdata
node_csv -->|"loads matching data"| node_studentdata
node_user -->|"runs inference"| node_inference
node_teachermodels -->|"provides checkpoints"| node_inference
node_teacherdata -->|"supplies batches"| node_inference
node_inference -->|"stores outputs"| node_predictions
node_predictions -->|"loads predictions"| node_studentdata
node_user -->|"trains student"| node_distillation
node_studentdata -->|"supplies batches"| node_distillation
node_distillation -->|"selects teachers"| node_selection
node_selection -->|"weights teacher losses"| node_distillation
node_distillation -->|"evaluates outputs"| node_metrics
node_distillation -->|"trains model"| node_studentmodel
node_teacherconfig -->|"configures run"| node_inference
node_trainconfig -->|"sets strategy"| node_distillation

click node_prepare "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/common_voice_prepare.py"
click node_teacherdata "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/save_teachers.py"
click node_inference "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/save_teachers.py"
click node_studentdata "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py"
click node_selection "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py"
click node_distillation "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py"
click node_metrics "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py"
click node_teacherconfig "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/hparams/save_teachers.yaml"
click node_trainconfig "https://github.com/yan-gao-gy/muti-teacherkd/blob/main/hparams/train_kd.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_prepare,node_csv toneBlue
class node_teacherdata,node_inference,node_predictions,node_commonvoice,node_teachermodels,node_studentmodel toneAmber
class node_studentdata,node_selection,node_distillation,node_metrics toneMint
class node_teacherconfig,node_trainconfig toneRose
class node_user toneIndigo
```

## Components

### Speech data

- [Manifest preparation](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/common_voice_prepare.py): `common_voice_prepare.py`
- **Dataset CSVs**

### Teacher inference

- [Teacher data pipeline](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/save_teachers.py): `save_teachers.py`
- [Teacher inference](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/save_teachers.py): `save_teachers.py`
- **Teacher predictions**

### Student distillation

- [Student data pipeline](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py): `train_kd.py`
- [WER teacher selection](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py): `train_kd.py`
- [Student training](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py): `train_kd.py`
- [WER and CER evaluation](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/train_kd.py): `train_kd.py`

### Experiment settings

- [Teacher settings](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/hparams/save_teachers.yaml): `hparams/save_teachers.yaml`
- [Training settings](https://github.com/yan-gao-gy/muti-teacherkd/blob/main/hparams/train_kd.yaml): `hparams/train_kd.yaml`

### Other components

- **Experimenter**
- **Common Voice data**
- **Teacher checkpoints**
- **Trained student**

## Connections

- Experimenter → Manifest preparation: prepares data (evidence: `README.md`)
- Common Voice data → Manifest preparation: provides recordings (evidence: `common_voice_prepare.py`)
- Manifest preparation → Dataset CSVs: writes manifests (evidence: `common_voice_prepare.py`)
- Dataset CSVs → Teacher data pipeline: loads data (evidence: `save_teachers.py`)
- Dataset CSVs → Student data pipeline: loads matching data (evidence: `README.md`)
- Experimenter → Teacher inference: runs inference (evidence: `README.md`)
- Teacher checkpoints → Teacher inference: provides checkpoints (evidence: `README.md`)
- Teacher data pipeline → Teacher inference: supplies batches (evidence: `save_teachers.py`)
- Teacher inference → Teacher predictions: stores outputs (evidence: `save_teachers.py`)
- Teacher predictions → Student data pipeline: loads predictions (evidence: `README.md`)
- Experimenter → Student training: trains student (evidence: `README.md`)
- Student data pipeline → Student training: supplies batches (evidence: `train_kd.py`)
- Student training → WER teacher selection: selects teachers (evidence: `train_kd.py`)
- WER teacher selection → Student training: weights teacher losses (evidence: `train_kd.py`)
- Student training → WER and CER evaluation: evaluates outputs (evidence: `train_kd.py`)
- Student training → Trained student: trains model (evidence: `README.md`)
- Teacher settings → Teacher inference: configures run (evidence: `README.md`)
- Training settings → Student training: sets strategy (evidence: `README.md`)
