# AstrAI 宣传视频制作指南

> 本文档为制作 AstrAI 宣传视频提供完整的技术参考、分镜建议和录制脚本。
> 目标时长：**2-3 分钟**

---

## 目录

1. [项目定位与核心卖点](#1-项目定位与核心卖点)
2. [技术架构速览](#2-技术架构速览)
3. [分镜脚本](#3-分镜脚本)
4. [演示录制指南](#4-演示录制指南)
5. [动画场景说明](#5-动画场景说明)
6. [旁白文案草稿](#6-旁白文案草稿)
7. [素材清单](#7-素材清单)

---

## 1. 项目定位与核心卖点

**一句话定位：**
> 一个能在单张消费级 GPU 上训练和推理的 1B 参数中英双语语言模型框架。

**核心卖点（视频中需突出）：**

| 卖点 | 说明 | 视觉表达 |
|------|------|---------|
| **单卡可跑** | 1B 参数，RTX 3090/4090 即可运行 | 巨大服务器集群 vs 单张显卡对比 |
| **连续批处理** | 动态合并请求，吞吐量 3x+ | 任务流经 Cleanup→Refill→Prefill→Decode 动画 |
| **前缀缓存零拷贝** | 相同前缀直接复用 KV，无需重算 | Radix Tree 生长动画 |
| **OpenAI 兼容 API** | 一行代码切换 | curl 命令对比 |
| **流式输出** | 逐 token 返回，低首延迟 | 终端逐字喷出效果 |
| **全过程开源** | 训练+推理+权重全部开源 | GitHub 页面展示 |

---

## 2. 技术架构速览

### 整体架构

```
┌──────────────────────────────────────────────────┐
│  FastAPI Server  (OpenAI-Compatible API)         │
├──────────────────────────────────────────────────┤
│  InferenceEngine  (Streaming + Async + Batch)    │
├──────────────────────────────────────────────────┤
│  Continuous Batching Scheduler                   │
│  ┌────────┐  ┌──────┐  ┌────────┐  ┌────────┐   │
│  │Cleanup │→ │Refill│→ │Prefill │→ │ Decode │   │
│  └────────┘  └──────┘  └────────┘  └────────┘   │
├──────────────────────────────────────────────────┤
│  Prefix Cache (Radix Tree)  +  KV Cache          │
├──────────────────────────────────────────────────┤
│  Transformer  (24层 GQA, RoPE, SwiGLU)           │
└──────────────────────────────────────────────────┘
```

### 关键技术指标

| 指标 | 值 |
|------|------|
| 参数量 | ~1.0B |
| 词表大小 | 100,000（中英 BPE） |
| 层数 | 24 |
| 注意力头 | 24 Q-heads / 4 KV-heads（GQA） |
| 最大长度 | 2048 tokens |
| 精度 | bfloat16 |
| 最低显存 | ~6GB（推理）/~12GB（训练） |

---

## 3. 分镜脚本

总时长 **2:30**，分为 6 个段落。

### Segment 1：Hook + 问题陈述（0:00 - 0:20）

| 镜头 | 画面 | 旁白 | 时长 |
|------|------|------|------|
| 1.1 | 黑屏，逐字打出"大语言模型很强大" | "大语言模型很强大——" | 3s |
| 1.2 | 切到数据中心照片 / 巨大 GPU 集群 | "——但跑起来需要几十张 GPU，普通人根本碰不到。" | 5s |
| 1.3 | 画面分屏：左边集群，右边一张 RTX 4090 | "但如果我告诉你，只要一张显卡就够了呢？" | 5s |
| 1.4 | Logo 出现：**AstrAI**，下方副标题 "1B 参数单卡推理框架" | "AstrAI——单卡跑大模型。" | 7s |

**视觉素材**：数据中心图片（可免版权下载）、RTX 4090 产品图、Logo 动画

---

### Segment 2：模型架构速览（0:20 - 0:45）

| 镜头 | 画面 | 旁白 | 时长 |
|------|------|------|------|
| 2.1 | Transformer 架构图逐层展开：embed → 24层 decoder → norm → head | "1B 参数，24 层 Transformer，100k 词表的中英 BPE 分词器。" | 8s |
| 2.2 | 高亮 GQA：24个 Q head 映射到 4个 KV head | "GQA 分组查询注意力——24 个查询头只对应 4 个 KV 头，KV 缓存直接减少 83%。" | 10s |
| 2.3 | RoPE 旋转变换可视化 | "RoPE 旋转位置编码，支持动态长度外推。" | 5s |
| 2.4 | fade 到模型 card：vocab=100k, dim=1536, layers=24, heads=24, kv_heads=4 | 静默 | 2s |

**视觉素材**：`architecture.py` 动画、模型参数 card

---

### Segment 3：连续批处理（0:45 - 1:20）

| 镜头 | 画面 | 旁白 | 时长 |
|------|------|------|------|
| 3.1 | 3 个请求同时到达服务器 | "当多个请求同时到达时——" | 3s |
| 3.2 | 静态批处理对比：最长补齐，3个请求串行 → 总耗时 max_len × 3 | "传统做法是静态批处理，把请求补齐到相同长度，串行处理，GPU 利用率低下。" | 8s |
| 3.3 | 连续批处理动画：任务流入 Waiting Queue → Cleanup → Refill → Prefill → Decode | "AstrAI 采用连续批处理：任务动态进出，GPU 每一刻都在满负荷运转。" | 10s |
| 3.4 | 放大 Decode 阶段：同一位置的任务合并成一批 | "特别地，只有处于相同 KV 缓存位置的任务才一起解码，从根本上避免了 RoPE 位置错乱的问题。" | 8s |
| 3.5 | 吞吐对比柱状图：Static Batch vs Continuous Batching (3x+) | "实测吞吐量提升 3 倍以上。" | 6s |

**视觉素材**：`continuous_batching.py` 动画、对比图表

---

### Segment 4：前缀缓存（1:20 - 1:50）

| 镜头 | 画面 | 旁白 | 时长 |
|------|------|------|------|
| 4.1 | 两个请求有相同 system prompt："你是一个AI助手" | "如果两个请求有相同的前缀——比如相同的系统提示词——" | 5s |
| 4.2 | 普通做法：两个请求各自独立计算前 20 个 token | "普通框架会各自从头计算一遍，白白浪费算力。" | 5s |
| 4.3 | Radix Tree 生长动画：第一个请求插入，第二个请求匹配共享前缀 | "AstrAI 用一颗字典树缓存所有前缀的 KV——第二个请求直接命中。" | 8s |
| 4.4 | 高亮 Slot 复用：直接用原 slot 继续写，零拷贝 | "如果原始 slot 空闲，直接原地续写，连 GPU 内存拷贝都不需要。" | 7s |
| 4.5 | 首 token 延迟对比：有缓存 vs 无缓存（-50%） | "首 token 延迟降低一半以上。" | 5s |

**视觉素材**：`prefix_cache.py` 动画、延迟对比

---

### Segment 5：Demo 演示（1:50 - 2:15）

| 镜头 | 画面 | 旁白 | 时长 |
|------|------|------|------|
| 5.1 | 侧录终端：启动 stream_chat.py，逐行输出对话 | "来实际看看效果。" | 10s |
| 5.2 | 多轮对话：中文问答，逐 token 喷出 | 静默 + 打字音效 | 8s |
| 5.3 | 切到 HTTP 模式：服务端 + curl 请求，流式返回 | "也提供 OpenAI 兼容的 HTTP API，一行 curl 就能调用。" | 7s |

**视觉素材**：终端录屏（OBS 录制）

---

### Segment 6：收尾 + CTA（2:15 - 2:30）

| 镜头 | 画面 | 旁白 | 时长 |
|------|------|------|------|
| 6.1 | 全栈流程回顾（缩略架构图） | "训练用 SEQ → SFT → DPO/GRPO，推理用连续批处理——" | 5s |
| 6.2 | GitHub 页面 + Star 引导 | "——全部开源。点个 Star，一起让大模型更普惠。" | 7s |
| 6.3 | Logo + URL + "Open Source • Single GPU" | 静默 | 3s |

**视觉素材**：GitHub 页面录屏、Logo 定版

---

## 4. 演示录制指南

### 4.1 准备工作

```bash
# 1. 安装依赖
pip install -e ".[dev]"

# 2. 下载模型（约 7GB）
python scripts/demo/download.py

# 3. 验证模型加载
python scripts/demo/generate_ar.py
```

### 4.2 录制场景 A：交互式对话

```bash
# 终端 1：启动交互式对话
python scripts/demo/stream_chat.py

# 预期交互
>> 你好？
AstrAI: 你好！有什么我可以帮你的吗？
>> 请用中文介绍一下你自己
AstrAI: ...（逐 token 输出）
>> 编一个关于人工智能的短故事
AstrAI: ...（逐 token 输出）
```

**录制重点**：
- 逐 token 流式输出效果（用 OBS 录制终端窗口）
- 多轮对话的记忆能力（跨轮上下文保持）
- 打字音效叠加

### 4.3 录制场景 B：HTTP 服务 + 并发

```bash
# 终端 1：启动服务器
python -m scripts.tools.server --port 8000 --device cuda

# 终端 2：发送请求（非流式）
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello!"}],"stream":false}'

# 终端 3：流式请求
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Write a poem"}],"stream":true}'

# 终端 4：并发压测（用 scripts/demo/generate_batch.py）
python scripts/demo/generate_batch.py
```

**录制重点**：
- 同时多个 curl 请求展示并发处理
- 服务端日志显示批处理合并
- `/stats` 端点展示实时统计

### 4.4 录制规格

| 参数 | 建议 |
|------|------|
| 分辨率 | 1920×1080 |
| 帧率 | 30fps |
| 终端 | Windows Terminal 或 iTerm2，深色主题 |
| 字号 | 16-18px，等宽字体（JetBrains Mono / Cascadia Code） |
| 录屏工具 | OBS Studio（免费） |
| 音频 | 旁白用 USB 麦克风，音效后期叠加 |

---

## 5. 动画场景说明

位于 `promo/` 目录，使用 Manim 引擎。

### 安装 Manim

```bash
# conda 环境内安装
pip install manim

# 验证
python -c "import manim; print(manim.__version__)"
```

### 渲染命令

```bash
# 单独渲染一个场景
manim -qh promo/continuous_batching.py ContinuousBatching

# 全部场景渲染
python promo/render_all.py

# 快速草稿（480p，适合调试）
manim -ql promo/continuous_batching.py ContinuousBatching
```

输出文件为 `promo/output/videos/` 下的 `.mp4` 文件，可直接导入剪辑软件。

### 场景清单

| 文件 | 导出场景名 | 内容 | 建议时长 |
|------|-----------|------|---------|
| `transformer.py` | `Transformer` | 模型架构：Embed → GQA → SwiGLU → ×24 → LM Head | ~35s |
| `continuous_batching.py` | `ContinuousBatching` | 4 阶段流水线动画 + 吞吐对比 | ~30s |
| `prefix_cache.py` | `PrefixCache` | Radix Tree 生长 + 多分支前缀复用 | ~30s |
| `architecture.py` | `Architecture` | 全栈架构逐层展开 + 数据流 | ~25s |

### 自定义动画

如需修改动画内容：
- Manim 语法参考：https://docs.manim.community/
- 所有动画元素（颜色、位置、速度）在场景类中通过参数调整
- 中文字体渲染需额外配置：

```python
# 在场景类开头添加
Text.set_default(font="Microsoft YaHei")
```

---

## 6. 旁白文案草稿

### 中文版（完整 2:30）

```
[00:00] 大语言模型很强大——
[00:03] 但跑起来需要几十张 GPU，普通人根本碰不到。
[00:08] 但如果我告诉你，只要一张显卡就够了呢？
[00:13] AstrAI——单卡跑大模型。

[00:20] 1B 参数，24 层 Transformer，100k 词表的中英 BPE 分词器。
[00:28] GQA 分组查询注意力——24 个查询头只对应 4 个 KV 头，KV 缓存直接减少 83%。
[00:38] RoPE 旋转位置编码，支持动态长度外推。

[00:45] 当多个请求同时到达时——
[00:48] 传统做法是静态批处理，把请求补齐到相同长度串行处理，GPU 利用率低下。
[00:56] AstrAI 采用连续批处理：任务动态进出，GPU 每一刻都在满负荷运转。
[01:06] 只有处于相同 KV 缓存位置的任务才一起解码，从根本上避免 RoPE 位置错乱。
[01:14] 实测吞吐量提升 3 倍以上。

[01:20] 如果两个请求有相同的前缀，普通框架会各自从头计算。
[01:25] AstrAI 用一颗字典树缓存所有前缀的 KV——第二个请求直接命中。
[01:33] 如果原始 slot 空闲，直接原地续写，连 GPU 内存拷贝都不需要。
[01:40] 首 token 延迟降低一半以上。

[01:50] 来实际看看效果。
[01:52] （现场演示部分，自由发挥）

[02:15] 训练到推理，全流程开源，点个 Star，一起让大模型更普惠。
[02:25] AstrAI — Open Source, Single GPU.
```

---

## 7. 素材清单

### 视频素材

| 素材 | 来源 | 状态 |
|------|------|------|
| 数据中心 / GPU 集群图片 | Pexels / Unsplash 免版权 | 需下载 |
| RTX 4090 产品图 | NVIDIA 官网 / 实物拍摄 | 需准备 |
| AstrAI Logo | `assets/images/logo.png` | ✅ 已有 |
| 终端录屏（对话） | OBS 录制 `scripts/demo/stream_chat.py` | 需录制 |
| 终端录屏（HTTP） | OBS 录制 curl + server | 需录制 |
| 终端录屏（并发） | OBS 录制 `generate_batch.py` | 需录制 |
| GitHub 页面 | 浏览器录屏 | 需录制 |
| Transformer 架构动画 | Manim 渲染 `transformer.py` | ✅ 已渲染 |
| 架构动画 | Manim 渲染 `architecture.py` | ✅ 已渲染 |
| 连续批处理动画 | Manim 渲染 `continuous_batching.py` | ✅ 已渲染 |
| 前缀缓存动画 | Manim 渲染 `prefix_cache.py` | ✅ 已渲染 |

### 音频素材

| 素材 | 建议 |
|------|------|
| 旁白 | USB 麦克风录制，男声或女声，中文普通话 |
| 背景音乐 | Epidemic Sound / YouTube Audio Library 搜索 "technology ambient" |
| 音效 | 打字音效（terminal keystrokes）、转场 swoosh、whoosh |

### 软件工具

| 用途 | 推荐工具 | 价格 |
|------|---------|------|
| 录屏 | OBS Studio | 免费 |
| 剪辑 | DaVinci Resolve | 免费 |
| 动画渲染 | Manim (`pip install manim`) | 免费 |
| 音频处理 | Audacity | 免费 |
| 字幕 | DaVinci Resolve 内建 / Aegisub | 免费 |

---

## 附录：关键文件索引

| 文件路径 | 说明 |
|---------|------|
| `README.md` | 项目主页 README，含快速开始 |
| `assets/docs/introduction.md` | 模型架构深度介绍 |
| `assets/docs/design.md` | 设计文档 + UML 类图 |
| `astrai/inference/scheduler.py` | 连续批处理调度器核心代码 |
| `astrai/inference/engine.py` | 推理引擎统一接口 |
| `astrai/inference/server.py` | FastAPI 服务器 |
| `astrai/model/transformer.py` | Transformer 模型 |
| `astrai/model/module.py` | GQA、MLA、MLP 等模块 |
| `scripts/demo/stream_chat.py` | 交互式对话演示 |
| `scripts/demo/generate_batch.py` | 批量生成演示 |
| `scripts/tools/server.py` | HTTP 服务启动脚本 |
| `scripts/tools/benchmark.py` | 性能基准测试 |
| `scripts/promo/README.md` | 动画渲染说明（已移至 promo/） |
| `promo/render_all.py` | 一键渲染所有动画 |
| `promo/continuous_batching.py` | 连续批处理 Manim 场景 |
| `promo/prefix_cache.py` | 前缀缓存 Manim 场景 |
| `promo/architecture.py` | 架构总览 Manim 场景 |
| `params/config.json` | 模型配置 |