Pular para o conteúdo
Jefferson Gonçalves
← Voltar para projetos

Grok Field Guide

Evidence-grounded Chinese technical field guide to xAI Grok, Grok-1 MoE architecture, source code, and API

#Grok 技术图谱

一份用 Astro + TypeScript + MDX 构建的中文深度技术教材：从大模型基础、Grok 产品与模型边界、Grok-1 的 314B Top-2 MoE 架构，走到真实 JAX 源码、KV Cache、训练生命周期和 xAI Responses API。

核心原则不是“把 Grok 讲得神秘”，而是让每个结论都能落入四种证据状态：源码确认、官方声明、合理推断、未公开。Grok-1 的公开架构不会被外推成当前 Grok 4.x / 4.5 的内部实现。

在线阅读：https://tt-a1i.github.io/grok-field-guide/

#快速开始

需要 Node.js 20+ 和 pnpm。

pnpm install
pnpm dev

打开 http://localhost:4321。

生产构建与预览：

pnpm build
pnpm preview

类型与内容检查：

pnpm check

#API 示例

示例使用 Node 内置 fetch，不把 API key 发送到浏览器。先导出环境变量：

export XAI_API_KEY="xai-..."
export XAI_MODEL="grok-4.5" # 可选；以账户当前可用模型为准

然后运行：

pnpm example:basic "解释 Grok-1 的 GQA"
pnpm example:stream "解释 Router 与 Expert"
pnpm example:tools
  • examples/basic.ts：Responses API、超时、错误分类与 typed output 解析。
  • examples/stream.ts：正确缓冲和拆分 SSE frame，不把网络 chunk 当 JSON 事件。
  • examples/tool-loop.ts：只读 allowlist 工具、参数校验、call_id 回传和最大轮数。

API 价格、模型别名和限制会变化。运行前查看 xAI Models、Pricing 与 Release Notes。

#课程结构

src/content/docs/
├── start/          # Grok 四层对象与证据规则
├── foundations/    # LLM、token、embedding、attention、Transformer
├── journey/        # Grok 代际演进与公开断点
├── product/        # 搜索、代码、视觉、工具与产品编排
├── architecture/   # Grok-1 蓝图、MoE、推理与 KV Cache
├── source/         # 固定 commit 的源码调用链
├── training/       # 预训练、后训练、RL、对齐与工具学习
├── api/            # Responses、stream、tools、structured outputs
├── comparison/     # 相同层级的主流系统设计比较
├── conclusion/     # 现代 LLM 系统综合
└── references/     # 一手资料与审稿边界

#项目结构

.
├── astro.config.mjs
├── DESIGN.md                     # Design DNA 与设计 token
├── SOURCE_MANIFEST.md            # 研究快照与源码锚点
├── docs/research/source-notes.md # 417 行一手研究底稿
├── examples/                     # 三个可运行 API 示例
├── public/
└── src/
    ├── components/
    │   ├── figures/              # 体系、Transformer、时间线、API、源码图
    │   └── interactive/          # Token、Attention、MoE、KV Cache 实验
    ├── content/docs/             # 16 章 MDX 正文
    ├── data/                     # 站点与证据状态常量
    ├── layouts/                  # 基础与三栏文档布局
    ├── pages/                    # 首页、动态文档路由、搜索索引、404
    ├── styles/                   # 全局设计系统
    └── utils/

#已实现的阅读体验

  • 桌面左侧章节导航、中央正文、右侧页内目录；移动端抽屉导航
  • 深浅色模式与本地偏好记忆
  • 构建时内容索引 + ⌘/Ctrl K 全局搜索
  • 阅读进度、当前段落追踪、前后章节
  • 代码复制与 Shiki 高亮
  • 图表缩放、说明文字和真实证据边界
  • Token、Attention、Top-2 MoE、KV Cache 四个零框架交互演示
  • KaTeX 公式与中英文混排
  • 键盘焦点、reduced motion 和响应式表格/图表

#新增章节

在 src/content/docs/<group>/<slug>.mdx 新建文件，并填写 frontmatter：

title: "章节标题"
description: "一句摘要"
chapter: "导航分组"
chapterOrder: 11
order: 1
duration: "25 min"
keywords: [keyword]
updated: 2026-07-26

动态路由、章节导航、前后页和搜索索引会自动生成。技术断言优先使用 FactBoundary 标注证据类型，并在来源档案登记一手链接。

#研究与许可边界

本站固定研究 xai-org/grok-1：

  • branch: main
  • commit: 7050ed204b8206bb8645c7b7bbef7252f79561b0
  • verified: 2026-07-26

Grok-1 源码和权重的许可范围以官方 Apache-2.0 声明为准。本项目只短量引用必要代码并链接原文件。本站教材内容不代表 xAI；Grok、xAI 和相关商标归各自权利人。

Nova versão disponível.