Hw2 环境准备与最小检查

使用说明

本页整理完成 Hw2 前需要做好的准备工作。请先完成本页内容，再返回 Hw2 作业说明 阅读题目并提交答案。

本页默认你已经完成 lab0 与 lab1

本页不再重复 lab0 / lab1 中已经介绍过的普通 make qemu 启动流程、QEMU 退出方法或 shell 基本操作，只说明完成本次 Hw2 所需的新增准备。

如果你对基础启动流程不熟悉，请先回看 实验0：编译并启动 Kernel；如果你对在 shell 中执行用户程序和测试程序不熟悉，请回看 实验1。

获取 Hw2 对应代码（切换到 AI 分支）

前提说明

下面的命令默认你已经按 实验0：希冀平台与课程仓库接入 完成了双远程配置，即：

• upstream 指向课程公共仓库；
• origin 指向你自己的希冀 GitLab 仓库。

Hw2 当前对应的代码位于课程仓库的 AI 分支，因此应当从 upstream/AI 获取，而不是从你自己的 origin 获取。

首次切换到 AI 分支

在课程仓库根目录执行：

# 先确认当前工作区是否干净
git status

# 获取课程仓库的最新分支信息
git fetch upstream --prune

# 首次切换：创建本地 AI 分支并跟踪 upstream/AI
git switch -c AI --track upstream/AI
# 或者（旧写法）
# git checkout -b AI upstream/AI

如果你本地已经有 AI 分支

直接切换并同步即可：

git status
git switch AI
git pull --rebase upstream AI

如果你同时在做 lab1，切换分支前请先处理当前改动

很多同学此时可能仍在 lab1 分支上继续做实验。由于切换分支会直接修改工作区文件，因此请特别注意：

• 先执行 git status 检查当前是否有未提交改动；
• 如果你在 lab1 分支上已经写了一部分代码，请先提交到 lab1，或者先用 git stash 暂存；
• 不要把 lab1 的代码改动直接带到 AI 分支继续写，也不要把 AI 分支上的改动直接混到 lab1 分支；
• 更推荐的做法是：lab1 相关工作始终留在 lab1 分支，Hw2 的代码阅读、调试和尝试始终留在 AI 分支，需要来回切换时用 git switch 即可。

一个常见的切换习惯

如果你只是临时从 lab1 切到 AI 看代码，可以先暂存当前工作：

git stash push -u -m "lab1-wip"
git switch AI

等你回到 lab1 后，再恢复刚才的暂存：

git switch lab1
git stash pop

如果提示找不到 upstream/AI

先确认：

• 你已经完成了 实验0：希冀平台与课程仓库接入 中的远程配置；
• 课程仓库远程名确实叫 upstream；
• 已经执行过 git fetch upstream --prune。

你也可以用下面的命令检查远端分支列表：

git branch -r

切到 AI 分支后，建议先阅读仓库根目录 README.md

当前 AI 分支的根目录 README.md 包含了最直接的运行说明，例如：

• 模型压缩包应当如何放置；
• make qemu-smol、make qemu-qwen、make qemu-llm 分别会做什么；
• llmrun_smol、llmrun_qwen 的基本使用背景。

如果你当前不想切换工作分支，只想先预览课程仓库 AI 分支上的 README.md，可以执行：

git fetch upstream --prune
git show upstream/AI:README.md

本次作业需要额外了解什么

1. 本次作业使用 AI 分支中的 LLM 相关目标，启动时应优先使用 make qemu-smol、make qemu-qwen 或 make qemu-llm，而不是普通的 make qemu。
2. LLM 相关目标会把 /AI/SMOL 或 /AI/QWEN 模型资产目录额外打包进镜像，供 llmrun_smol、llmrun_qwen 读取。
3. 本次作业仍然沿用你在 lab0 中已经见过的“启动内核并进入 shell”路径；新增内容是在进入 shell 之后，手动执行 llmrun_* 完成一次 LLM 推理。
4. 当前 guest 内没有 tokenizer，因此 llmrun_* 的输入和输出都是 token id，而不是自然语言文本。

模型压缩包下载与放置

请先准备助教提供的模型资产压缩包

本次 Hw2 使用的不是原始 HuggingFace 权重，而是助教预先导出的二进制模型资产压缩包。

下载地址如下：

• SmolLM2-135M：smol.zip
• Qwen3.5-0.8B：qwen.zip

下载后请放到仓库根目录的 models/ 下，并保持文件名分别为 smol.zip 和 qwen.zip。例如：

your-os-repo/
├── Makefile
├── models/
│   ├── smol.zip
│   └── qwen.zip
└── ...

不需要手动解压。make qemu-smol、make qemu-qwen、make qemu-llm 会自动解压并生成对应镜像。

Part 1 的最小准备

如果你当前只准备先完成 SmolLM2-135M 的测量，可以先只下载 smol.zip 并执行 make qemu-smol；完成 Part 1 中的跨模型对比时，再补下载 qwen.zip 并执行 make qemu-qwen。

不要用 make qemu 代替 make qemu-smol

make qemu 生成的是普通 fs.img，其中虽然包含 llmrun_smol 和 llmrun_qwen 两个用户程序，但并不包含 /AI/SMOL 或 /AI/QWEN 这两个模型资产目录。因此它适合做普通 OS 实验，不适合完成本次 Hw2 的 LLM 推理测量。

本次作业的 LLM 测量统一按单核路径进行

make qemu-smol、make qemu-qwen、make qemu-llm 在 Makefile 中固定为 CPUS=1。本次 Hw2 的测量与分析请以这条单核路径为准，不要把手工改成多核后的结果和课上讨论混在一起。

建议先完成一次最小检查

1. 将助教提供的 smol.zip 放到仓库根目录 models/smol.zip。
2. 在仓库根目录执行 make qemu-smol。
3. 系统启动后会先进入你在 lab0 中已经熟悉的 shell；此时与普通 make qemu 的区别在于，镜像中额外包含 /AI/SMOL 资产目录。
4. 在 shell 中执行 llmrun_smol --predict 4 1 2 3 4。程序会先进入 /AI/SMOL，再调用 llm_runtime_init() 读取模型配置和权重，随后分配 KV Cache 与工作区，并完成一次基于 token id 的 Prefill / Decode 推理。
5. 若要测量 Qwen3.5-0.8B，则将上述命令分别替换为 make qemu-qwen、/AI/QWEN 和 llmrun_qwen。

报告中请区分不同层次的耗时

在本次作业中，至少要区分两层含义：

1. 宿主机侧的构建与启动时间：包括编译、解压模型资产、生成镜像和拉起 QEMU。
2. llmrun_* 的模型加载时间：从用户程序启动，到 llm_runtime_init()、KV Cache 和工作区准备完成为止。

Part 1 中讨论的 Model Loading Time 更接近第 2 层，而不是把整个 make qemu-smol 的耗时都算进去。

宿主机侧 tokenizer 依赖

请使用 venv，不要使用 sudo pip install

如果你需要使用 tools/translate_llm_io.py 在宿主机上完成文本和 token id 的互转，不要直接在较新的 Ubuntu / Debian 上执行 python3 -m pip install --user tokenizers。它很可能报：

error: externally-managed-environment
This environment is externally managed

这是系统 Python 的保护机制，不是课程仓库的问题。为避免把虚拟环境目录留在仓库中、上传到云端或在切换分支时干扰工作区，推荐将虚拟环境建在仓库外，例如：

sudo apt update
sudo apt install python3-venv
python3 -m venv ~/.venvs/oslab-hw2
. ~/.venvs/oslab-hw2/bin/activate
python -m pip install -U pip
python -m pip install tokenizers

需要注意：venv 的激活状态只对当前终端有效。每次新开一个终端，或重新登录后再次进入仓库时，都需要重新执行：

. ~/.venvs/oslab-hw2/bin/activate

如果你不想记住“先激活再运行”，也可以直接使用虚拟环境中的解释器，例如：

~/.venvs/oslab-hw2/bin/python tools/translate_llm_io.py encode --model smol --text "hello"

如果你已经习惯把虚拟环境放在仓库根目录，也请至少确保它不会被提交；本仓库会忽略 venv/ 和 .venv/。对本次作业而言，这样就足够了；不需要安装 Conda，也不要使用 sudo pip install。