# N-Orca：用 Markdown 声明、验证和可视化神经网络架构的 DSL

> N-Orca 是一个基于 Markdown 的领域特定语言，让开发者和 LLM 能够用纯文本声明神经网络架构，自动验证形状一致性，生成可视化图表，并编译成可执行的 PyTorch 代码。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-03T11:45:38.000Z
- 最近活动: 2026-06-03T11:49:05.517Z
- 热度: 152.9
- 关键词: N-Orca, 神经网络, DSL, Markdown, PyTorch, 架构验证, 深度学习, Transformer, 领域特定语言
- 页面链接: https://www.zingnex.cn/forum/thread/n-orca-markdown-dsl
- Canonical: https://www.zingnex.cn/forum/thread/n-orca-markdown-dsl
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：jascal
- 来源平台：github
- 原始标题：n-orca
- 原始链接：https://github.com/jascal/n-orca
- 来源发布时间/更新时间：2026-06-03T11:45:38Z

## 原作者与来源\n\n- **原作者/维护者：** jascal\n- **来源平台：** GitHub\n- **原始标题：** n-orca: Neural-network Orchestrated Architecture Language\n- **原始链接：** https://github.com/jascal/n-orca\n- **发布时间：** 2026年6月3日\n\n---\n\n## 引言：为什么需要 N-Orca？\n\n在深度学习开发中，神经网络架构的定义往往分散在多个地方：设计文档里的图表、代码中的类定义、以及团队沟通时的口头描述。这种碎片化导致了信息不一致、理解偏差和沟通成本。\n\n**N-Orca**（Neural-network Orchestrated Architecture Language）试图用一个简单的想法解决这个问题：既然 Markdown 已经是开发者和 AI 最熟悉的文本格式，为什么不直接用它来描述神经网络？\n\n这个项目的核心洞察是：给 LLM 和人类一个统一的载体，同时覆盖架构设计的五个关键需求——编写、阅读、可视化、验证和执行。\n\n---\n\n## 核心理念：一个文件，五种能力\n\nN-Orca 是 Orca 语言的神经网络专用方言。Orca 本身用于描述有限状态机，而 N-Orca 专注于类型化的张量流层 DAG（有向无环图）。\n\n它的设计哲学非常简洁：\n\n| 能力 | 实现方式 | 为什么有效 |\n|------|----------|-----------|\n| **编写** | 纯 Markdown | LLM 已经能可靠生成 GitHub 风格的表格和标题 |\n| **阅读** | 章节标题作为导航 | 每个 `##` 都是地标，一行就是一个层 |\n| **可视化** | 编译为 Mermaid 流程图 | 任何 Markdown 阅读器都能渲染 |\n| **解释** | 结构化错误码 | 如 `SHAPE_MISMATCH`、`UNREACHABLE_LAYER`，附带修复建议 |\n| **执行** | 编译为 PyTorch nn.Module | 验证器保证形状匹配后才生成代码 |\n\n这种设计让架构描述从"文档"变成了"可执行代码"，但又保持了文档的可读性。\n\n---\n\n## 语言结构：如何用 Markdown 写神经网络\n\nN-Orca 的语法非常直观。以下是一个真实的 Transformer 块定义示例：\n\n```markdown\n# architecture TransformerBlock\n\n## hyperparameters\n\n| Name | Type | Default |\n|------|------|---------|\n| d_model | int | 512 |\n| n_heads | int | 8 |\n| d_ff | int | 2048 |\n| dropout | float | 0.1 |\n\n## tensors\n\n| Name | Shape | Dtype |\n|------|-------|-------|\n| x | (B, S, d_model) | float32 |\n| y | (B, S, d_model) | float32 |\n\n## layer x [input]\n## layer attn_norm\n- op: LayerNorm(d_model)\n## layer attn\n- op: MultiHeadAttention(d_model, n_heads, dropout)\n## layer add_1\n- op: Add\n## layer ff_norm\n- op: LayerNorm(d_model)\n## layer ff\n- op: FeedForward(d_model, d_ff, dropout)\n## layer add_2\n- op: Add\n## layer y [output]\n\n## flow\n\n| Source | Target | Tensor |\n|--------|--------|--------|\n| x | attn_norm | x |\n| attn_norm | attn | x_normed |\n| attn | add_1 | attn_out |\n| x | add_1 | x_skip |\n| add_1 | ff_norm | h |\n| ff_norm | ff | h_normed |\n| ff | add_2 | ff_out |\n| add_1 | add_2 | h_skip |\n| add_2 | y | y_out |\n\n## invariants\n- output_shape: (B, S, d_model)\n```\n\n这段代码声明了一个完整的 Transformer 块，包括超参数、输入输出张量、层定义、数据流和不变量约束。\n\n---\n\n## 验证系统：五阶段静态检查\n\nN-Orca 的验证器是其最强大的特性之一。它在代码运行前就捕获潜在错误，分为五个阶段：\n\n### 阶段一：命名检查\n- 确保所有流边端点都能解析\n- 验证有且仅有一个 `[input]` 和一个 `[output]`\n- 检测重复的层名称\n- 错误码：`UNKNOWN_LAYER_REFERENCE`、`NO_INPUT_LAYER`、`DUPLICATE_LAYER`\n\n### 阶段二：结构检查\n- 验证图是 DAG（无环）\n- 确保每个层都能从输入到达\n- 确保每个层都能到达输出\n- 错误码：`CYCLE_DETECTED`、`UNREACHABLE_LAYER`、`LAYER_NOT_REACHING_OUTPUT`\n\n### 阶段三：形状检查\n- 验证每层输入形状符合操作规则\n- 检查声明形状与实际推断形状是否匹配\n- 错误码：`SHAPE_MISMATCH`、`INPUT_ARITY_MISMATCH`、`DECLARED_SHAPE_MISMATCH`\n\n### 阶段四：资源检查\n- 对比参数数量、深度、输出形状与声明的不变量\n- 错误码：`PARAM_BUDGET_EXCEEDED`、`DEPTH_BUDGET_EXCEEDED`、`OUTPUT_SHAPE_INVARIANT`\n\n### 阶段五：操作覆盖检查\n- 验证每层操作在标准库中存在\n- 未知操作会产生警告但仍可编译为 `nn.Identity()` 占位符\n- 错误码：`UNKNOWN_OP`\n\n验证失败的输出示例：\n```\nArchitecture: ResidualBlock\n Result: INVALID\n [ERR] SHAPE_MISMATCH: layer 'add': Add inputs have mismatched shapes:\n   [('B', 'C', 'H', 'W'), ('B', '2C', 'H', 'W')]\n -> check the layer's op args and incoming shapes\n```\n\n---\n\n## 操作符库：从基础到高级\n\nN-Orca 提供了丰富的预定义操作符，覆盖常见深度学习需求：\n\n**基础层**：`Linear`、`Conv2d`、`MaxPool2d`、`AvgPool2d`\n\n**归一化**：`LayerNorm`、`BatchNorm1d`、`BatchNorm2d`\n\n**激活函数**：`ReLU`、`GELU`、`SiLU`、`Tanh`、`Sigmoid`、`Softmax`\n\n**Transformer 专用**：`MultiHeadAttention`、`FeedForward`\n\n**嵌入层**：`Embedding`、`PatchEmbed`（ViT）、`TubeletEmbed`（V-JEPA 2 视频）\n\n**实用操作**：`Add`、`Mul`（残差连接）、`Concat`、`Mean`、`Flatten`、`Reshape`、`Identity`\n\n未知操作不会阻止验证，而是生成警告并编译为占位符，这对原型设计非常友好。\n\n---\n\n## 工具链与生态集成\n\nN-Orca 提供了完整的 CLI 工具链：\n\n```bash\n# 验证文件\nn-orca verify examples/transformer-block.n.orca.md\nn-orca verify examples/transformer-block.n.orca.md --json\nn-orca verify examples/transformer-block.n.orca.md --strict\n\n# 编译输出\nn-orca compile mermaid examples/transformer-block.n.orca.md\nn-orca compile pytorch examples/transformer-block.n.orca.md --out model.py\n\n# 查看架构信息\nn-orca info examples/transformer-block.n.orca.md\n```\n\n验证成功时的输出示例：\n```\nArchitecture: TransformerBlock\n Result: VALID\n Parameters: 3,152,384\n Depth: 7\n```\n\n此外，N-Orca 还支持 HuggingFace 生态：\n```bash\n# 下载模型配置\nn-orca hf download gpt2 --config-only\nn-orca hf download facebook/vjepa2-vitl-fpc64-256 --config-only --include-processor\n```\n\n以及 MCP（Model Context Protocol）服务器支持，可以直接从 Claude 或其他 MCP 客户端驱动。\n\n---\n\n## 安装与使用\n\nN-Orca 支持 Python 3.10+，核心库零依赖：\n\n```bash\npip install n-orca              # 核心 CLI、解析器、验证器、编译器\npip install "n-orca[torch]"     # + PyTorch 支持\npip install "n-orca[hf]"        # + HuggingFace Hub 支持\npip install "n-orca[mcp]"       # + MCP 服务器\npip install "n-orca[all]"       # 全部功能\n```\n\n或从源码安装：\n```bash\ngit clone https://github.com/jascal/n-orca && cd n-orca\npip install -e ".[all]"\n```\n\n---\n\n## 项目状态与路线图\n\nN-Orca 目前处于活跃开发阶段。从仓库的 OpenSpec 变更记录可以看到两个重要的正在进行的工作：\n\n1. **时序世界模型支持**（`add-temporal-world-model`）：添加对时序/循环世界模型的支持，用于经济 SAE 中的状态传递和窗口特征恢复。\n\n2. **Cosmos MoT 世界模型**（`add-cosmos-mot-world-models`）：实现 Mixture of Transformers 双塔架构 + 联合注意力 + 扩散时间步世界模型构建器，支持物理 AI、多模态和扩散基底。\n\n这些特性表明 N-Orca 正在向更复杂的架构模式扩展，不仅仅是静态的层堆叠。\n\n---\n\n## 总结与思考\n\nN-Orca 代表了一种有趣的范式转变：将架构描述从代码中抽离出来，用声明式的方式表达。这种做法有几个显著优势：\n\n1. **人机协作**：Markdown 格式让非技术人员也能理解和参与架构设计\n2. **LLM 友好**：结构化的文本比 Python 代码更容易让 AI 生成和修改\n3. **早期验证**：在训练开始前就发现形状不匹配等常见错误\n4. **可视化内建**：架构图不再是事后补充，而是自动生成的产物\n\n当然，这种方案也有权衡：对于高度动态的架构（如条件计算、动态图），声明式描述可能显得笨拙。但对于大多数标准深度学习架构，N-Orca 提供了一种更干净、更可维护的表达方式。\n\n如果你正在寻找一种让架构设计更透明、更可验证的方法，N-Orca 值得尝试。