onnx-genai Wiki
本目录是一个兼容 Obsidian 的知识库,收录解释性笔记、学习路径,以及实现概念之间的
关联。它不替代 docs/ 下的规范、实测证据与已接受的设计文档。
发布后的读者请从 onnx-genai Knowledge Base 开始。
笔记只在这里编辑。站点由 justinchuby/onnx-genai-wiki 发布:它定时镜像本目录,并派生一份英文版,发布成中英双语站点 https://www.justinchuby.com/onnx-genai-wiki/。那边的中文内容是镜像,直接改动会 被下一次同步覆盖。
来源优先级
当 wiki 笔记与正式文档或代码不一致时,按以下顺序采信:
- 当前代码与可复现的实测数据
docs/下的权威文档- 已接受的设计决策
- 解释性的 wiki 笔记
内容地图
- 从这里开始: Repository Map
- 架构: Crate Architecture
- 运行时流程: Inference Request Lifecycle
- 执行: Execution Backends
- EP 契约: Execution Provider Contract
- CPU EP: CPU Execution Provider
- CUDA EP: CUDA Execution Provider
- 插件 EP: Plugin Execution Providers
- 内存: Memory Management for Beginners
- KV cache 虚拟内存: Virtual Memory for KV Cache
- MoE 路由倾斜: MoE Router Skew and Always-On Experts
- 对话模板: Chat Templates
- 追踪: Tracing and Profiling
- 性能工程: Performance Engineering Playbook
- 分块 prefill: Chunked Prefill
- API 设计: API Design Principles
- 契约: Runtime Contracts
- 形式化验证: Formal Verification with TLA+
- 测试与验证: Testing and Verification
- 元数据: Metadata Driven Runtime
- 模型包: Model Packages and Variants
- 文档: Documentation Guide
- Wiki 维护: Using this Wiki
笔记写作规范
每篇笔记都应当:
-
使用英文文件名和英文
title,使链接在跨语言时保持稳定。 -
包含 YAML frontmatter,字段为
title、aliases、tags、status、lang、created、updated。 -
开篇先用一句话说明这篇笔记回答的是什么问题。
-
只回答一个主要问题,通常保持在 5–10 分钟可读完的篇幅。
-
当缩短会迫使初学者跑到其他文件里去补前置知识时,保留较长的教程体例。
-
用
[[wikilinks]]链接到其他笔记,而不是在多篇之间重复同一段解释。 -
用 Obsidian callout 标注不变量、警告、示例与背景。
-
对目标读者做到自包含。指向
docs/和代码的链接是证据和实现细节,不是必须 先读完的功课。 -
明确标注”提议中”的行为,绝不把目标设计写成已实现的样子。
-
**写给不在场的读者。**笔记可能诞生于一次问答,但读者看不到那次问答。绝不把某个 论断或想法归给读者,也不要回指一段只在对话里出现过的上下文 —— 这类写法会让读者 一头雾水,也让笔记读起来像别人聊天记录的片段。把提问改写成笔记自己的陈述,让每个 论断都自带 context。下表是最常见的几种,左列全部禁止:
不要 要 ## "模型是不是从模板后面开始预测?"## 三、生成从模板的末尾开始你的观察是对的,两者确实同族 gpt-oss 与 Muse Glimmer 共享同一套骨架 你说的”预测第一个字” 这一步常被说成”预测第一个字” 泛指实现者的”你”(如”你的转接层需要…”)本身没问题,但当它可以被”调用方""传入的” 替换而不损失信息时,优先用后者。
这条规则由
scripts/lint_wiki_voice.py执行,PR 改动wiki/**时在 CI 里跑。 需要像上表这样引用反例时,用<!-- voice-lint: off -->/<!-- voice-lint: on -->圈出范围 —— 豁免只覆盖圈出的行,并且会出现在 diff 里。
语言
Wiki 正文用中文写,标题保留英文
本 wiki 的正文使用简体中文。以下内容保持英文:
- 文件名与目录路径 —— 例如
execution/CUDA Execution Provider.md- frontmatter 的
title字段- 页面的一级标题(H1) —— 与
title保持一致tags—— 标签始终用英文[[wikilinks]]的链接目标 —— 需要中文显示文本时用[[目标|显示文本]], 绝不改动竖线左边的目标本身- 代码、标识符、crate 名、文件路径、环境变量、函数名、命令行
- Obsidian callout 的类型关键字 —— 如
> [!important],这是语法章节标题(H2 及以下)、正文、表格内容、callout 的标题文字都应译为中文。
aliases可以同时包含中英文条目 —— 它的作用是让人用任一语言都能搜到这篇笔记, 因此中文别名是鼓励的,但不要删除既有的英文别名,那会破坏已有链接。技术术语首次出现时保留英文原词并在括号中给出中文,例如 “execution provider(执行提供者,EP)“;此后可只用英文缩写。当英文术语本身就是 业界通用称呼时(如 kernel、arena、allocator),直接沿用英文,不必强译。
lang 字段会被 Quartz 直接用作发布页面的 <html lang> 属性,因此它影响的是真实
的可访问性与搜索引擎行为,不只是元数据。
中文笔记写 lang: zh-CN。
创建与修改日期
Obsidian 可以在 Properties 视图里显示受版本控制的
created与updated属性。 Obsidian 同样知道本地文件系统的创建与修改时间,但那些时间在 clone、checkout 和 rebase 之后并不可靠。Obsidian 核心功能不会在每次编辑时自动维护自定义的updatedfrontmatter;请随笔记一起更新它,或配置自动化/插件来处理。参见 Using this Wiki。