EulerStack

核心功能

Layer Templates & Schedule

定义具名的层模板(mixer + FFN + norm + residual)，通过schedule指定排列顺序与重复次数。

混合器类型	Attention, Mamba, RetNet, Hyena
FFN类型	MLP, Gated MLP (SwiGLU), MoE (top-k routing)
Norm	RMSNorm, LayerNorm (pre/post)
Residual	Sequential, Parallel

校验 & 现实性

模式结构校验 → 跨字段兼容性 → 启发式现实性检查的三阶段流程，在编译前捕获设计错误。所有错误均以三行格式输出(Category: what / Fix: / See:)。

结构	未知键、类型/enum、必填字段、正数约束
兼容性	mixer↔state 不匹配（例如禁止mamba + kv_cache）
现实性	head_dim范围(32–256)、target_params偏差(>30%)、MoE专家比例、seq_len/d_model比例、family_hint一致性、vocab/tokenizer一致性、tie_weight一致性、rope_scaling范围
错误类别	`ValidationError`, `CompatibilityError`, `CompileError`, `NormalizationError`

从一份YAML开始

约10行的声明式规格即可完整描述模型形态。

schema_version: 2
model: { name: "my-llm", d_model: 2048, vocab_size: 32000, max_seq_len: 4096, n_heads: 16 }
tokenizer_contract: { type: hf, pretrained: gpt2 }
embedding: { type: learned, positional: rope }
layer_templates:
  decoder:
    mixer: { type: attention, attention: {} }
    ffn:   { type: gated_mlp, activation: swiglu }
layer_schedule:
  - { template: decoder, repeat: 24 }
head: { type: causal_lm }
            

预设：两轴共31个

两个正交维度：llm_(规模×变体，16个)与arch_(技能级走查，15个)。预设仅为起点——编辑d_model、n_heads与层数即可组装任意规模的模型。

`llm_` — 规模×架构变体 (16个)

4个规模(0.8B / 2B / 4B / 16B) × 4个变体(simple / mistral / jamba / moe)。

规模	simple	mistral	jamba	moe
0.8B	`llm_0p8b_simple` (~810M)	`llm_0p8b_mistral` (~810M)	`llm_0p8b_jamba` (~1.04B)	`llm_0p8b_moe` (~770M)
2B	`llm_2b_simple` (~2.01B)	`llm_2b_mistral` (~2.01B)	`llm_2b_jamba` (~2.39B)	`llm_2b_moe` (~2.05B)
4B	`llm_4b_simple` (~3.97B)	`llm_4b_mistral` (~3.97B)	`llm_4b_jamba` (~4.67B)	`llm_4b_moe` (~4.03B)
16B	`llm_16b_simple` (~15.26B)	`llm_16b_mistral` (~15.26B)	`llm_16b_jamba` (~18.18B)	`llm_16b_moe` (~15.71B)

变体语义：simple = 纯Attention(Llama)；mistral = Attention + Sliding Window(每4层1全局:3滑动)；jamba = Mamba + Attention 混合(3:1)；moe = Attention + MoE FFN(每4层1个，8 experts, top-2)。

`arch_` — 技能级走查 (15个，均为~2B)

全部固定在~2B预算，使对比隔离架构选择本身。Expert 级以 MoE × 混合器 作为二维设计空间进行交叉，其中2个条目是文献中尚未发表的speculative组合。

级别	预设	~参数	一句话描述	研究来源
beginner	`arch_beginner_gpt2`	2.07B	Classic Transformer (MHA + LayerNorm post + GeLU)	Vaswani 2017, GPT-2
beginner	`arch_beginner_llama`	2.01B	现代基线 (GQA + RMSNorm pre + SwiGLU)	Llama 2/3
intermediate	`arch_intermediate_mistral`	2.01B	1全局 : 3滑动 attention	Mistral 7B
intermediate	`arch_intermediate_gemma2`	2.08B	1:1 全局/局部交替	Gemma 2
intermediate	`arch_intermediate_qwen_longctx`	2.01B	RoPE scaling factor 4，32K ctx	Qwen 2/3
advanced	`arch_advanced_jamba`	2.39B	Mamba + Attention 3:1 混合	Jamba-1.5 (AI21)
advanced	`arch_advanced_samba`	1.99B	Mamba + Sliding attention 1:1	Samba (Microsoft)
advanced	`arch_advanced_retnet`	2.21B	纯 RetNet (attention-free)	Sun 2023
expert	`arch_expert_research`	2.22B	4 mixers + MoE 3-phase	Research-grade
expert	`arch_expert_mixtral_moe`	1.89B	纯 attn + 每层 MoE (8 × top-2)	Mixtral 8x7B
expert	`arch_expert_striped_hyena`	1.96B	Hyena + Attention 4:1，128K	StripedHyena
expert	`arch_expert_blackmamba_moe`	2.10B	Mamba + MoE (在 non-attn 混合器上加 MoE)	BlackMamba, MoE-Mamba
expert	`arch_expert_deepseek_moe`	1.84B	Fine-grained MoE (32 × top-3)	DeepSeek-V2/V3
expert	`arch_expert_retnet_moe`	1.98B	RetNet + MoE (speculative，无论文)	Sun 2023 + MoE-Mamba 外推
expert	`arch_expert_frontier_full_moe`	1.93B	Attention-free、多混合器 + 全 MoE (最为 speculative)	组合预测

无上限——预设仅为起点。通过编辑d_model、n_heads与层数，EulerStack可以组装任意规模的模型。

CLI参考

遵循eulerwa产品家族的通用CLI约定。所有错误均以三行格式(Category: what / Fix: / See:)输出。

顶层命令

`validate`	校验YAML规格(`--report`包含现实性报告)
`explain`	模型结构摘要(层、参数估计)
`compile`	IR → JSON运行时配置(`--output`) 或 HF模型目录(`--output-dir`)
`schema`	打印YAML模式结构
`presets list` / `show`	列出预设或查看某个预设的详情

通用选项

`--lang`	输出语言(ko/en/zh/ja/es)。根选项，默认ko
`--preset`	YAML规格文件路径
`--validate-only`	仅校验并退出
`--output / -o`	JSON运行时配置输出路径
`--output-dir`	HF模型目录输出(config.json + model.safetensors)
`--print-config` / `--dry-run`	将解析后的配置输出到stdout

5语言 i18n CLI

所有CLI的help、日志、警告与错误信息均翻译为ko / en / zh / ja / es。默认语言为韩语(ko)，可通过根选项--lang或环境变量EULERSTACK_LANG切换。命令名、选项名以及三行错误格式中的Fix: / See:标签保持不翻译，以确保脚本兼容性。

eulerstack validate --preset my_model.yml
# 韩语(默认)

eulerstack --lang zh validate --preset my_model.yml
# 中文

EULERSTACK_LANG=en eulerstack validate --preset my_model.yml
# 环境变量同样生效

HF模型目录 → EulerForge训练

compile --output-dir生成HuggingFace兼容的模型目录(config.json + model.safetensors)——这是交付给EulerForge训练管线的主要路径。

eulerstack compile --preset my_model.yml --output-dir ./my_model

# 在Python中加载
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("./my_model", trust_remote_code=True)

5层架构

从YAML规格到可训练模型——5层各司其职，严格分离。

Layer 1: DSL	用户编写的YAML v2规格(声明式模型定义)
Layer 2: Schema	结构校验——未知键、类型/enum、必填字段、跨字段兼容性
Layer 3: IR	规范化的Canonical结构表示(默认值填充、模板展开)
Layer 4: Compiler	IR → JSON运行时配置或 HF模型目录(config.json + model.safetensors)——可通过`AutoModelForCausalLM.from_pretrained()`加载以交付EulerForge训练
Layer 5: CLI	`validate` / `explain` / `compile` / `schema` / `presets`——全部消息均应用5语言i18n

教程

教程以韩语(ko)与英语(en)并行维护，位于上游仓库的docs/tutorials/{ko,en}/。本页仅列出目录；完整教程请在仓库中查阅。

核心教程

`quickstart.md`	语言中立的CLI起始页(使用`--lang`)
`01_validate_a_spec.md`	校验YAML规格
`02_use_presets.md`	使用预设
`03_compile_and_explain.md`	Compile & explain
`04_prepare_data.md`	准备训练数据
`05_sanity_train.md`	Sanity 训练循环
`06_arch_walkthrough.md`	NEW — 15个`arch_`预设的逐步走查(技能级)

混合器深入 (`mixers/`)

`00_overview.md`	混合器概念概述——为何混合 attention / mamba / retnet / hyena
`01_attention.md`	Attention 详解
`02_mamba.md`	Mamba 详解
`03_retnet.md`	RetNet 详解
`04_hyena.md`	Hyena 详解

所有教程均可在仓库中查阅。

安装与快速开始

安装

pip install -e .

# 或包含开发依赖
pip install -e ".[dev]"

快速开始

# 浏览预设(默认韩语)
eulerstack presets list

# 校验 + 现实性报告
eulerstack validate --preset my_model.yml --report

# 生成HF模型目录 → 交付 EulerForge 训练
eulerstack compile --preset my_model.yml --output-dir ./my_model

# 切换输出为中文
eulerstack --lang zh validate --preset my_model.yml

用EulerStack设计LLM架构

一份YAML组合Attention、Mamba、RetNet、Hyena与MoE构建混合模型，并将HuggingFace模型目录直接交付给EulerForge训练。

在GitHub上开始