"""
GPT 语言模型的完整定义，全部浓缩在这一个文件中。
参考资料：
1) OpenAI 发布的官方 GPT-2 TensorFlow 实现:
https://github.com/openai/gpt-2/blob/master/src/model.py
2) huggingface/transformers 的 PyTorch 实现:
https://github.com/huggingface/transformers/blob/main/src/transformers/models/gpt2/modeling_gpt2.py
"""

import math
import inspect
from dataclasses import dataclass

import torch
import torch.nn as nn
from torch.nn import functional as F

class LayerNorm(nn.Module):
    """ 带可选偏置项（bias）的层归一化（LayerNorm）。PyTorch 原生不支持直接设置 bias=False """

    def __init__(self, ndim, bias):
        super().__init__()
        # [详细注释]：归一化后，数据会被缩放和平移。weight 是缩放因子，bias 是平移因子。
        self.weight = nn.Parameter(torch.ones(ndim))
        self.bias = nn.Parameter(torch.zeros(ndim)) if bias else None

    def forward(self, input):
        # 1e-5 是为了防止分母为 0 的极小数 (epsilon)
        return F.layer_norm(input, self.weight.shape, self.weight, self.bias, 1e-5)

class CausalSelfAttention(nn.Module):

    def __init__(self, config):
        super().__init__()
        # [详细注释]：确保隐藏层维度能够被注意力头数整除，这样才能把特征平均分给每个头
        assert config.n_embd % config.n_head == 0
        # 为所有头在一个批次中计算键（key）、查询（query）和值（value）的投影
        # [详细注释]：这里将 Q, K, V 的计算合并成了一个矩阵乘法（输出维度是 3 * n_embd），能大幅提升计算效率
        self.c_attn = nn.Linear(config.n_embd, 3 * config.n_embd, bias=config.bias)
        # 输出投影
        self.c_proj = nn.Linear(config.n_embd, config.n_embd, bias=config.bias)
        # 正则化（防止过拟合）
        self.attn_dropout = nn.Dropout(config.dropout)
        self.resid_dropout = nn.Dropout(config.dropout)
        self.n_head = config.n_head
        self.n_embd = config.n_embd
        self.dropout = config.dropout
        
        # Flash Attention 能让 GPU 速度起飞，但仅在 PyTorch >= 2.0 中支持
        self.flash = hasattr(torch.nn.functional, 'scaled_dot_product_attention')
        if not self.flash:
            print("警告：正在使用慢速注意力机制。Flash Attention 需要 PyTorch >= 2.0")
            # 因果掩码（causal mask），确保注意力只能应用到输入序列中左侧（过去）的内容
            # [详细注释]：生成一个下三角矩阵，右上角全为 0。模型在位置 t 只能看到 0 到 t 的信息，无法“偷看” t+1 的答案。
            self.register_buffer("bias", torch.tril(torch.ones(config.block_size, config.block_size))
                                        .view(1, 1, config.block_size, config.block_size))

    def forward(self, x):
        B, T, C = x.size() # 批次大小 (Batch), 序列长度 (Time/Sequence length), 嵌入维度 (Channels/n_embd)

        # 计算批次中所有头的 query, key, values，并将头的维度移动到批次维度之后
        # [详细注释]：split 沿着最后一个维度将大矩阵切分成三个等大的矩阵 Q, K, V
        q, k, v  = self.c_attn(x).split(self.n_embd, dim=2)
        
        # [详细注释]：维度重塑和转置，从 (B, T, C) 变成 (B, 头数, T, 每个头的维度)
        # transpose(1, 2) 交换了“时间”和“头”的维度，使得每个头可以独立且并行地处理序列
        k = k.view(B, T, self.n_head, C // self.n_head).transpose(1, 2) # (B, nh, T, hs)
        q = q.view(B, T, self.n_head, C // self.n_head).transpose(1, 2) # (B, nh, T, hs)
        v = v.view(B, T, self.n_head, C // self.n_head).transpose(1, 2) # (B, nh, T, hs)

        # 因果自注意力计算; Self-attend: (B, nh, T, hs) x (B, nh, hs, T) -> (B, nh, T, T)
        if self.flash:
            # 使用 Flash Attention CUDA 内核的极速注意力实现
            # [详细注释]：这是近几年大模型领域最重要的底层优化之一，极大减少了显存的读写（IO-aware）。
            y = torch.nn.functional.scaled_dot_product_attention(q, k, v, attn_mask=None, dropout_p=self.dropout if self.training else 0, is_causal=True)
        else:
            # 手动实现的注意力机制
            # [详细注释]：Q 乘以 K 的转置，再除以根号下维度（缩放因子，防止梯度消失/爆炸）
            att = (q @ k.transpose(-2, -1)) * (1.0 / math.sqrt(k.size(-1)))
            # [详细注释]：应用掩码，把未来的位置填上负无穷 (-inf)
            att = att.masked_fill(self.bias[:,:,:T,:T] == 0, float('-inf'))
            # [详细注释]：Softmax 后，负无穷会变成 0，这意味着未来的词对当前词的权重为 0
            att = F.softmax(att, dim=-1)
            att = self.attn_dropout(att)
            # [详细注释]：注意力权重矩阵与 V 相乘，得到最终的上下文表示
            y = att @ v # (B, nh, T, T) x (B, nh, T, hs) -> (B, nh, T, hs)
            
        # 重新组装所有头的输出，拼接在一起
        # [详细注释]：contiguous() 确保内存连续，以便 view 能正常工作，恢复回原始维度 (B, T, C)
        y = y.transpose(1, 2).contiguous().view(B, T, C)

        # 输出投影（信息整合）
        y = self.resid_dropout(self.c_proj(y))
        return y

class MLP(nn.Module):
    """ 多层感知机（前馈神经网络） """
    def __init__(self, config):
        super().__init__()
        # [详细注释]：经典的 Transformer 结构，隐藏层维度扩展为原来的 4 倍，让模型有更多空间做特征变换
        self.c_fc    = nn.Linear(config.n_embd, 4 * config.n_embd, bias=config.bias)
        self.gelu    = nn.GELU() # 高斯误差线性单元，比 ReLU 更平滑，表现更好
        self.c_proj  = nn.Linear(4 * config.n_embd, config.n_embd, bias=config.bias) # 降维回原来的维度
        self.dropout = nn.Dropout(config.dropout)

    def forward(self, x):
        x = self.c_fc(x)
        x = self.gelu(x)
        x = self.c_proj(x)
        x = self.dropout(x)
        return x

class Block(nn.Module):
    """ Transformer 的核心构件块 """
    def __init__(self, config):
        super().__init__()
        self.ln_1 = LayerNorm(config.n_embd, bias=config.bias)
        self.attn = CausalSelfAttention(config)
        self.ln_2 = LayerNorm(config.n_embd, bias=config.bias)
        self.mlp = MLP(config)

    def forward(self, x):
        # [详细注释]：这里使用的是 "Pre-LN" 结构（即在进入 Attention 和 MLP 之前做归一化）。
        # x = x + ... 是残差连接（Residual Connection），允许梯度直接流向早期的层，防止深层网络退化。
        x = x + self.attn(self.ln_1(x))
        x = x + self.mlp(self.ln_2(x))
        return x

@dataclass
class GPTConfig:
    """ 模型的配置超参数 """
    block_size: int = 1024 # 上下文窗口大小（模型一次最多能看多少个词）
    vocab_size: int = 50304 # GPT-2 原词表大小为 50257，为了计算效率向上对齐到 64 的倍数
    n_layer: int = 12 # Transformer 层数
    n_head: int = 12 # 注意力头数
    n_embd: int = 768 # 词向量的维度
    dropout: float = 0.0 # 丢弃率
    bias: bool = True # True：在 Linear 和 LayerNorm 中使用 bias，同 GPT-2。False：稍微好点且快点

class GPT(nn.Module):

    def __init__(self, config):
        super().__init__()
        assert config.vocab_size is not None
        assert config.block_size is not None
        self.config = config

        # [详细注释]：使用 ModuleDict 将组件打包。
        self.transformer = nn.ModuleDict(dict(
            wte = nn.Embedding(config.vocab_size, config.n_embd), # 词嵌入 (Word Token Embeddings)
            wpe = nn.Embedding(config.block_size, config.n_embd), # 位置嵌入 (Word Position Embeddings)
            drop = nn.Dropout(config.dropout),
            h = nn.ModuleList([Block(config) for _ in range(config.n_layer)]), # 堆叠 N 个 Block
            ln_f = LayerNorm(config.n_embd, bias=config.bias), # 最终的层归一化
        ))
        # 语言模型头（将最终的特征向量映射回词表大小的 logits 概率）
        self.lm_head = nn.Linear(config.n_embd, config.vocab_size, bias=False)
        
        # 使用 torch.compile() 进行权重绑定时会产生一些警告：
        # "UserWarning: functional_call was passed multiple values for tied weights..."
        # 目前不确定这是什么原因，但看起来无害。待调查。
        # [详细注释]：【权重共享 (Weight Tying)】 这是个极其重要的技巧。输入层的词嵌入矩阵和输出层的预测矩阵共享同一套参数！这不仅节省了大概 30% 的参数量，还能提升模型效果。
        self.transformer.wte.weight = self.lm_head.weight # https://paperswithcode.com/method/weight-tying

        # 初始化所有权重
        self.apply(self._init_weights)
        # 根据 GPT-2 论文，对残差投影应用特殊的缩放初始化
        # [详细注释]：随着网络变深，残差连接累加的方差会越来越大。按照层数的倒数缩放可以稳定深层网络的初期训练。
        for pn, p in self.named_parameters():
            if pn.endswith('c_proj.weight'):
                torch.nn.init.normal_(p, mean=0.0, std=0.02/math.sqrt(2 * config.n_layer))

        # 报告参数数量
        print("模型参数量: %.2fM" % (self.get_num_params()/1e6,))

    def get_num_params(self, non_embedding=True):
        """
        返回模型中的参数数量。
        默认计算非嵌入参数，这会减去位置嵌入的数量。
        由于参数共享，词嵌入参数实际上也作为最后一层的权重使用，所以我们将其包含在内。
        """
        n_params = sum(p.numel() for p in self.parameters())
        if non_embedding:
            n_params -= self.transformer.wpe.weight.numel()
        return n_params

    def _init_weights(self, module):
        """ [详细注释]：按照正态分布初始化权重，标准差设定为 0.02，这是 OpenAI 训练 GPT 系列的经验值 """
        if isinstance(module, nn.Linear):
            torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)
            if module.bias is not None:
                torch.nn.init.zeros_(module.bias)
        elif isinstance(module, nn.Embedding):
            torch.nn.init.normal_(module.weight, mean=0.0, std=0.02)

    def forward(self, idx, targets=None):
        device = idx.device
        b, t = idx.size()
        assert t <= self.config.block_size, f"无法前向传播长度为 {t} 的序列，块大小（上下文窗口）仅为 {self.config.block_size}"
        # 生成位置索引 [0, 1, 2, ..., t-1]
        pos = torch.arange(0, t, dtype=torch.long, device=device) # 形状 (t)

        # GPT 模型的前向传播
        tok_emb = self.transformer.wte(idx) # 词嵌入，形状为 (b, t, n_embd)
        pos_emb = self.transformer.wpe(pos) # 位置嵌入，形状为 (t, n_embd)
        # [详细注释]：把词语的意思（tok_emb）和词语在句子里的位置（pos_emb）直接加在一起
        x = self.transformer.drop(tok_emb + pos_emb)
        # 依次穿过所有的 Transformer 层
        for block in self.transformer.h:
            x = block(x)
        x = self.transformer.ln_f(x)

        if targets is not None:
            # 如果提供了目标（targets），则计算损失（Loss）
            logits = self.lm_head(x)
            # [详细注释]：交叉熵损失（Cross Entropy Loss）。将三维的 logits 展平为二维再计算，忽略索引 -1（通常用于 padding）。
            loss = F.cross_entropy(logits.view(-1, logits.size(-1)), targets.view(-1), ignore_index=-1)
        else:
            # 推理时的微小优化：只为序列的最后一个位置前向计算 lm_head
            # [详细注释]：因为在生成文本时，我们只关心基于前 t 个词预测出的第 t+1 个词是什么。
            logits = self.lm_head(x[:, [-1], :]) # 注意：使用列表 [-1] 是为了保留时间维度
            loss = None

        return logits, loss

    def crop_block_size(self, block_size):
        # 对模型进行“手术”，在需要时减小 block size（上下文窗口）
        # 比如我们加载了 GPT-2 的预训练检查点（block size 1024）
        # 但想为一个更小、更简单的模型使用较小的 block size
        assert block_size <= self.config.block_size
        self.config.block_size = block_size
        self.transformer.wpe.weight = nn.Parameter(self.transformer.wpe.weight[:block_size])
        for block in self.transformer.h:
            if hasattr(block.attn, 'bias'):
                block.attn.bias = block.attn.bias[:,:,:block_size,:block_size]

    @classmethod
    def from_pretrained(cls, model_type, override_args=None):
        """ [详细注释]：这是一个极其硬核的函数，用于强行把 HuggingFace 里 OpenAI 官方预训练好的 GPT-2 权重（如 124M 模型）“塞进”我们手写的这个类里。"""
        assert model_type in {'gpt2', 'gpt2-medium', 'gpt2-large', 'gpt2-xl'}
        override_args = override_args or {} # 默认为空字典
        # 只能覆盖 dropout 设置，参见下方更多注释
        assert all(k == 'dropout' for k in override_args)
        from transformers import GPT2LMHeadModel
        print("正在从预训练的 gpt 加载权重: %s" % model_type)

        # n_layer, n_head 和 n_embd 由模型类型决定
        config_args = {
            'gpt2':         dict(n_layer=12, n_head=12, n_embd=768),  # 1.24 亿参数
            'gpt2-medium':  dict(n_layer=24, n_head=16, n_embd=1024), # 3.5 亿参数
            'gpt2-large':   dict(n_layer=36, n_head=20, n_embd=1280), # 7.74 亿参数
            'gpt2-xl':      dict(n_layer=48, n_head=25, n_embd=1600), # 15.58 亿参数
        }[model_type]
        print("强制设定 vocab_size=50257, block_size=1024, bias=True")
        config_args['vocab_size'] = 50257 # 对于 GPT 模型检查点，总是 50257
        config_args['block_size'] = 1024 # 对于 GPT 模型检查点，总是 1024
        config_args['bias'] = True # 对于 GPT 模型检查点，总是 True
        
        # 如果需要，我们可以覆盖 dropout 率
        if 'dropout' in override_args:
            print(f"将 dropout 率覆盖为 {override_args['dropout']}")
            config_args['dropout'] = override_args['dropout']
            
        # 创建一个从零初始化的 minGPT 模型
        config = GPTConfig(**config_args)
        model = GPT(config)
        sd = model.state_dict()
        sd_keys = sd.keys()
        sd_keys = [k for k in sd_keys if not k.endswith('.attn.bias')] # 丢弃掩码/缓冲区，它不是一个参数

        # 初始化一个 huggingface/transformers 模型
        model_hf = GPT2LMHeadModel.from_pretrained(model_type)
        sd_hf = model_hf.state_dict()

        # 复制参数，同时确保所有参数在名称和形状上对齐并匹配
        sd_keys_hf = sd_hf.keys()
        sd_keys_hf = [k for k in sd_keys_hf if not k.endswith('.attn.masked_bias')] # 忽略这些，只是缓冲区
        sd_keys_hf = [k for k in sd_keys_hf if not k.endswith('.attn.bias')] # 同上，只是掩码 (缓冲区)
        transposed = ['attn.c_attn.weight', 'attn.c_proj.weight', 'mlp.c_fc.weight', 'mlp.c_proj.weight']
        
        # 基本上 openai 的检查点使用的是 "Conv1D" 模块，但我们只想使用原生的 Linear 模块
        # 这意味着我们在导入这些权重时必须对它们进行转置 (Transpose)
        assert len(sd_keys_hf) == len(sd_keys), f"键不匹配: {len(sd_keys_hf)} != {len(sd_keys)}"
        for k in sd_keys_hf:
            if any(k.endswith(w) for w in transposed):
                # 对需要转置的 Conv1D 权重进行特殊处理
                assert sd_hf[k].shape[::-1] == sd[k].shape
                with torch.no_grad():
                    sd[k].copy_(sd_hf[k].t()) # .t() 就是转置
            else:
                # 正常覆盖其他参数
                assert sd_hf[k].shape == sd[k].shape
                with torch.no_grad():
                    sd[k].copy_(sd_hf[k])

        return model

    def configure_optimizers(self, weight_decay, learning_rate, betas, device_type):
        """ [详细注释]：配置优化器，这里主要为了解决哪些权重需要“权重衰减”（防止过拟合），哪些不需要 """
        # 从所有候选参数开始
        param_dict = {pn: p for pn, p in self.named_parameters()}
        # 过滤掉不需要计算梯度的参数
        param_dict = {pn: p for pn, p in param_dict.items() if p.requires_grad}
        
        # 创建优化组。任何维度是 2D 的参数都将应用权重衰减，否则不应用。
        # 即：矩阵乘法中的所有权重张量 + 嵌入层进行衰减；所有的偏置项 (biases) 和层归一化 (layernorms) 不衰减。
        decay_params = [p for n, p in param_dict.items() if p.dim() >= 2]
        nodecay_params = [p for n, p in param_dict.items() if p.dim() < 2]
        optim_groups = [
            {'params': decay_params, 'weight_decay': weight_decay},
            {'params': nodecay_params, 'weight_decay': 0.0}
        ]
        num_decay_params = sum(p.numel() for p in decay_params)
        num_nodecay_params = sum(p.numel() for p in nodecay_params)
        print(f"衰减的参数张量数: {len(decay_params)}, 包含 {num_decay_params:,} 个参数")
        print(f"不衰减的参数张量数: {len(nodecay_params)}, 包含 {num_nodecay_params:,} 个参数")
        
        # 创建 AdamW 优化器，如果可用的话使用 fused（融合）版本以加速计算
        fused_available = 'fused' in inspect.signature(torch.optim.AdamW).parameters
        use_fused = fused_available and device_type == 'cuda'
        extra_args = dict(fused=True) if use_fused else dict()
        optimizer = torch.optim.AdamW(optim_groups, lr=learning_rate, betas=betas, **extra_args)
        print(f"正在使用 fused AdamW: {use_fused}")

        return optimizer

    def estimate_mfu(self, fwdbwd_per_iter, dt):
        """ 以 A100 bfloat16 峰值 FLOPS 为单位，估算模型浮点运算利用率 (MFU) """
        # [详细注释]：这是一个纯工程向的性能监控指标。衡量你的代码究竟榨干了显卡多少理论算力。
        # 首先估算我们在单次迭代中执行的浮点运算次数。
        # 参考文献：PaLM 论文附录 B: https://arxiv.org/abs/2204.02311
        N = self.get_num_params()
        cfg = self.config
        L, H, Q, T = cfg.n_layer, cfg.n_head, cfg.n_embd//cfg.n_head, cfg.block_size
        flops_per_token = 6*N + 12*L*H*Q*T
        flops_per_fwdbwd = flops_per_token * T
        flops_per_iter = flops_per_fwdbwd * fwdbwd_per_iter
        
        # 将我们的吞吐量表达为 A100 bfloat16 峰值 flops 的比率
        flops_achieved = flops_per_iter * (1.0/dt) # 每秒实际运算次数
        flops_promised = 312e12 # A100 GPU bfloat16 的理论峰值 flops 是 312 TFLOPS
        mfu = flops_achieved / flops_promised
        return mfu

    @torch.no_grad()
    def generate(self, idx, max_new_tokens, temperature=1.0, top_k=None):
        """
        [详细注释]：文本生成的推理循环。
        传入一个条件序列的索引 idx (LongTensor 形状为 (b,t)) 并完成序列续写，
        生成 max_new_tokens 次，每次都将预测结果重新喂回模型。
        最有可能的是，你会希望在此操作时确保处于 model.eval() 模式。
        """
        for _ in range(max_new_tokens):
            # 如果序列上下文变得太长，我们必须将其截断在 block_size 处
            # [详细注释]：模型不能处理比它设定的最大上下文更长的文本
            idx_cond = idx if idx.size(1) <= self.config.block_size else idx[:, -self.config.block_size:]
            
            # 前向传播模型，获取序列当前索引的 logits
            logits, _ = self(idx_cond)
            
            # 提取最后一步的 logits 并按所需的温度（temperature）进行缩放
            # [详细注释]：temperature > 1 会让分布变平缓（输出更随机/创造性），< 1 会让分布变尖锐（输出更确定）
            logits = logits[:, -1, :] / temperature
            
            # 备选项：将 logits 裁剪到只保留前 k 个选项 (Top-K 采样)
            if top_k is not None:
                v, _ = torch.topk(logits, min(top_k, logits.size(-1)))
                logits[logits < v[:, [-1]]] = -float('Inf') # 把没有排进前 K 的词的概率设为负无穷
                
            # 应用 softmax 将 logits 转换为（归一化的）概率
            probs = F.softmax(logits, dim=-1)
            
            # 从概率分布中采样
            # [详细注释]：并非总是选择概率最高的词，而是根据概率掷骰子，增加生成文本的多样性
            idx_next = torch.multinomial(probs, num_samples=1)
            
            # 将采样的索引拼接到运行序列中并继续循环
            idx = torch.cat((idx, idx_next), dim=1)

        return idx