# 一字一诗 · 用户使用手册

这份手册带你完成：拿到完整学习包 → 在本机打开 → 跟着课程理解 GPT → 亲手训练小模型 → 用网页和命令行写诗。会读简单 Python 即可开始，模型计算从具体例子讲起。

## 先选适合你的入口

| 你现在的情况 | 从哪里开始 | 做完应该看到什么 |
| --- | --- | --- |
| 直接从外网学习 | 访问 [在线学习站](https://poetry.saymagic.cn/) | 直接阅读课程；登录实验室后可运行服务器实验 |
| 就用当前已配置好的电脑 | 打开学习站；若未启动，运行 `./poet course --start` | 右侧显示“已连接本机 Python” |
| 刚下载学习包，或换了电脑 | 按“下载与解压”和“首次准备环境”操作 | 环境检查成功，浏览器能打开课程 |
| 暂时只想读手册 | 双击包内的 `使用手册.html` | 不安装 Python 也能阅读本手册及配图 |
| 已学过，今天继续 | 启动服务，进入上次课程；训练从已有记录恢复 | 课程勾选和训练进度分别找回 |

> 本手册中的命令，除安装 uv 外，都在“项目根目录”执行：就是同时放着 `poet`、`start.command`、`course` 和 `poetry_gpt` 的文件夹。代码框里的命令可复制到终端；不要把命令的输出也复制进去。

在线学习不需要先安装 Python，也不需要启动自己电脑上的服务。右侧使用实验室访问密码登录后，计算发生在 ECS，进度也保存在服务器；课程、图解、手册和完整包下载可直接使用。在线练习使用小模型，最多 500 步、每批最多 8 条，一次运行一个任务。下面的安装与启动步骤，是把学习包下载到自己电脑时使用的。在服务器进行第一次 50 步练习时，每批数量填 8；本机练习可以按照后文填 24。

## 下载、解压与认识学习包

完整包名为 `poetry-gpt-workbench.zip`，与本手册一起提供。本页顶部有下载入口，学习工作台右侧底部也有“下载完整学习包”。这个下载由你当前电脑的学习服务提供；把项目交给别人时，发送 ZIP 文件。

下载完成后，在 macOS 访达中双击 ZIP。解压出来的 `poetry-gpt-workbench` 文件夹就是完整项目，把整个文件夹放到你容易找到的位置。先双击其中的 `使用手册.html`。请保留其内部目录结构，程序会根据自身所在位置寻找课程、数据和模型。

| 包内内容 | 用来做什么 |
| --- | --- |
| `使用手册.html`、`USER_GUIDE.md` | 阅读本手册；HTML 可直接打开，Markdown 是可编辑文字版 |
| `start.command`、`poet` | 启动本机学习站、使用命令行程序 |
| `course/dist/` | 网页课程、图解、配图和可阅读的源码 |
| `lessons/` | 逐课实验、留空练习、参考答案；第 24 课包含 CLI 的渐进版本 |
| `poetry_gpt/`、`configs/` | 模型、材料整理、训练、生成、本机服务的源码与设置 |
| `全唐诗/` 等诗词目录 | 原始诗词材料；入门主线使用整理后的唐宋诗 |
| `artifacts/data/` | 已准备好的学习、验证、测试材料及字表 |
| `artifacts/runs/poet/` | 已训练的正式模型、训练前模型、阶段模型与训练记录 |
| `scripts/`、`tests/`、`reports/` | 安装与打包工具、程序检查、既有运行记录 |

随包已有整理数据和训练好的模型，所以安装完成后可以立即体验写诗，再按课程从零做自己的实验。正式结构约 488 万参数，小规模练习约 145 万参数；这里的“参数”就是训练会反复调整的一组数字。

学习包没有复制原电脑的 `.venv` 环境和 `artifacts/workbench/` 下的个人实验记录。换电脑时需要建立自己的环境。首次安装会联网下载 Python 和所需程序包；准备完成后，课程、实验、训练和写诗在本机运行。

## 首次准备环境：新下载或换电脑时做

以下以 macOS 为主。本项目已在 M1 Pro、32 GB 内存电脑上运行；其他电脑先从小模型与短训练开始，用实际检查确认可用设备。

### 第一步：在正确的文件夹打开终端

打开 macOS 的“终端”应用，输入 `cd `，注意末尾有一个空格。把刚解压的 `poetry-gpt-workbench` 文件夹从访达拖入终端，再按回车。这样就进入项目根目录，路径中有空格也不用自己猜写法。

运行下面的命令，核对你看到的文件名中有 `poet`、`start.command`、`scripts` 和 `course`：

```bash
ls
```

### 第二步：准备 uv

uv 是帮助本项目安装合适 Python 和程序包的工具。先检查是否已安装：

```bash
uv --version
```

若显示版本号，可继续下一步。若提示找不到 uv，可按 [uv 官方安装说明](https://docs.astral.sh/uv/getting-started/installation/) 中的 macOS 方法安装：

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

安装完成后重新打开终端，再按第一步进入项目目录，重新运行 `uv --version`。此命令只安装工具；模型和诗词已经在学习包中。

### 第三步：安装本项目环境

```bash
sh scripts/setup.sh
```

脚本会准备 Python 3.12，在项目内创建 `.venv`，按固定清单安装所需程序包，最后检查环境。首次下载需要等待；出错时保留终端信息，按后面的排错表处理，再重试同一条命令。

```bash
./poet doctor
```

重点看“材料已准备”和“模型已训练”：使用完整交付包时都应为 `true`。“默认设备”为 `mps` 表示使用 Mac 的图形处理器；为 `cpu` 表示普通处理器。CPU 也能做实验，训练速度由电脑决定。不要因为显示 CPU 就重新下载诗词。

> 当前已配置好的工作目录不需要每天重新安装。新解压的副本即使在同一台电脑上，也需要自己的 `.venv`，首次按本节准备。

## 打开学习站，以及下次怎样继续

### 日常打开

环境准备好后，macOS 可双击项目根目录的 `start.command`。它会在后台启动学习服务，并打开浏览器。终端方式如下：

```bash
./poet course --start
```

打开 [本机学习站](http://127.0.0.1:8766/)。成功时，右侧“动手实验”下面显示“已连接本机 Python”。第一次可选择“检查本机环境”，点击“运行并观察”，确认网页能收到输出。

`127.0.0.1` 指你正在使用的这台电脑。换到另一台电脑，要在那台电脑解压并启动学习包；把这个网址发给别人，不会把你的课程服务一起发过去。

双击 `使用手册.html` 可以直接读说明；双击 `course/dist/index.html` 可以阅读课文和操作教学图解。要运行右侧 Python 实验，请通过上面的本机服务地址进入。

### 下次继续与正常结束

关闭浏览器页面不会停止后台任务；再次打开站点，可以从“最近的实验”找回输出。电脑重启后，重新执行启动命令。课程的学习勾选保存在当前浏览器，模型与实验日志保存在项目文件夹中，它们是两种不同的进度。

```bash
./poet course --status
```

准备关机或结束学习时，若还在训练，先点右侧“停止并保存”，等待状态显示“已停止”。需要关闭学习服务时再运行：

```bash
./poet course --stop
```

如果同时放着两份项目，8766 端口可能已经被旧副本使用。可以在旧副本目录停止它，或者在新副本目录选另一个端口：

```bash
./poet course --start --port 8767
```

这时打开 `http://127.0.0.1:8767/`；查询和停止也要带 `--port 8767`。一台电脑上先使用一个工作台做训练，比较容易管理进度。

## 认清页面：哪里是在讲解，哪里真的在运行

左侧是课文、图解和小练习。右侧“动手实验”负责把你的选择交给本机 Python，并展示运行结果。窗口较窄时，点顶部“动手实验”展开；点“收起”回到正文。课程目录可从顶部按钮打开。

| 你做的动作 | 实际发生什么 |
| --- | --- |
| 改左侧图解里的文字、滑块或开关 | 改变教学示意；不会改模型，也不会自动改写 Python 源码 |
| 点“在右侧运行”或“运行本课 Python 示例” | 把功能和参数填入右侧，等待你检查 |
| 点右侧“运行并观察” | 本机启动真实程序，输出会逐步出现 |
| 展开“本次执行的命令” | 看这一次实际启动的命令、模型或输出目录 |
| 点“停止并保存” | 请求结束进程；训练会尝试保存已完成的进度 |
| 选“最近的实验”或“保存这次输出” | 查看历史结果，或把当前命令和文字输出另存下来 |

{{manual-image:pairs}}

图中左侧把句子改为“明月照山河”，右侧 Python 运行的是课文固定例子“春江花月夜”。应比较的是“输入和答案错开一位”这条规则，不要求两个字表里的编号相同。

网页为训练自动分配独立目录；正文供终端使用的路径，会转换成右侧显示的实际路径。如果要用自己训练的模型，必须在“使用哪个模型”里选对应记录。工作台一次执行一个计算任务，正在运行时先观察或停止，再启动下一项。

安装环境、改写 Python 文件和终端连续输入仍在自己的编辑器、终端完成。网页提供课程中的固定实验和可调整参数，使用方法会在相应课程中说明。

## 整个学习包的基础流程

可以先把项目理解成两段：先让模型学习并保存，再读取保存的结果写诗。训练改变模型内部数字；每次写诗使用这些数字做计算，并不会自动开始新一轮训练。

{{manual-flow}}

| 步骤 | 在做什么 | 得到什么 |
| --- | --- | --- |
| 整理材料 | 把原诗清理、去重，分成学习、验证和最后检查用的三份 | 整理后的诗文与字表 |
| 制作接字题 | 把汉字转成编号，让每个位置预测下一个字 | 输入与对应答案 |
| 搭建 GPT | 把字与位置的表示、注意力等计算连接起来 | 能输出候选字分数的程序 |
| 训练 | 预测、看答案、算误差、调整内部数字，反复进行 | 保存的模型与训练日志 |
| 检查结果 | 在未用于参数更新的材料上检查，用固定条件写诗 | 可比较的误差和真实输出 |
| 使用 CLI | 读取开头或关键词，加载模型，逐字选择并输出 | 网页诗文、终端诗文或 JSON 文件 |

你在网页点击运行时，后台程序接到请求，启动对应 Python 功能，再把输出送回右侧。因此可以一边读计算原理，一边观察同一项目怎样实际执行。

“重新整理材料”会把练习结果另存到 `artifacts/workbench/data/`；网页训练默认使用包内已准备好的 `artifacts/data/`。若以后要训练自己整理的新材料，第 3、16 课会讲终端中的 `--data` 设置。

## 第一次动手：从看到结果到完成短训练

第一次可以按下面顺序操作，分几次完成也可以。先用现成模型体验最终结果，再用独立的小模型走一遍训练。短训练用于理解流程，写诗能力需要更充分的学习。

### 体验已有模型

右侧选择“用本地模型写诗”，模型选“已交付的正式模型”，开头填“春”，五言，生成 1 首；其余保持默认，点击运行。应该看到四行诗，每行五个汉字，第一行从“春”开始。

再把开头清空，关键词填“秋雨,故乡”，选择七言，运行一次。关键词是引导线索，不保证每次完整出现；读完诗，检查主题、语义和重复，而不只看字数。

### 拆一条接字题

打开 [第 4 课：把接字变成练习题](course/dist/lessons/04.html)。在左侧换一句话，观察输入和答案怎样错开；再点“运行本课 Python 示例”。先写下预测，再检查右侧实际输出。

### 从零训练 50 步

打开 [第 16 课：完成一次训练](course/dist/lessons/16.html)，在右侧选择“从零训练”，填写以下设置：

| 设置 | 第一次填写 |
| --- | --- |
| 模型规模 | 小模型 · 约 145 万参数 |
| 总目标步数 | 50 |
| 每批练习数量 | 24 |
| 计算设备 | 自动选择 |

点击运行，先等加载材料和训练前检查完成，再观察步数与误差。50 步表示完成 50 次“取题、预测、算误差、更新”，不是读完所有诗 50 遍。结束时应该显示“已完成”，结果里有第 50 步的验证误差，并给出这次模型目录。

{{manual-image:training}}

图里蓝色曲线来自固定验证题，浅色曲线来自每批抽取的学习题。两者可以波动；比较模型时，要固定检查材料和抽样设置。图中的数值是这次运行记录，不要求你在不同设备上得到逐位相同的小数。

### 恢复到总共 75 步

选择“继续上次训练”，找到刚才 50 步的那条记录，目标填 75。运行后应看到开始步数为 50，结束为 75；它只继续做 25 次更新。

恢复还没完成的训练也用这个入口：先点“停止并保存”，等状态变成“已停止”，再选择这条记录和大于已完成步数的目标。不要选“从零训练”，那会建立一份新模型。

### 检查自己训练的模型

选择“检查模型误差”，模型选刚才的练习记录，材料选“验证材料”，抽取 10 批。再选择“用本地模型写诗”，同样选这份练习模型。短训练的诗可能不通顺，这正好用来比较“流程跑通”和“学得充分”的区别。

### 观察训练前后，开始编写 CLI

选择“观察真实模型”，前文填“春江”，分别运行“正式结构 · 尚未训练”和“已交付的正式模型”。看候选字概率怎样变化，再切换第一层的注意力头。权重只是某一次汇总的比例，不能当成对整首诗的完整解释。

最后打开 [第 24 课：编写命令行](course/dist/lessons/24.html)，依次运行“读取参数”“接上模型”“保存 JSON 与处理报错”三个阶段。第一阶段先确认程序读到了什么；第二阶段调用模型；第三阶段让输出能被其他程序读取和保存。

## 正式学习：按顺序读，每节课做一小轮

入门体验结束后，从第 1 课按顺序学。遇到公式时先看小数字例子，再回到 Python 代码；不需要一次记住全部英文名字。

| 学习阶段 | 对应课程 | 这一段完成后应能解释 |
| --- | --- | --- |
| 准备材料 | [第 1—3 课](course/dist/lessons/01.html) | 项目怎样打开；哪些诗用于学习，哪些留作检查 |
| 模型怎样学习 | [第 4—7 课](course/dist/lessons/04.html) | 接字题怎样组成；猜错怎样评分；参数怎样更新 |
| GPT 内部计算 | [第 8—15 课](course/dist/lessons/08.html) | 字与位置怎样变成数字；注意力怎样汇总前文；怎样阻止偷看答案 |
| 完整训练与判断 | [第 16—19 课](course/dist/lessons/16.html) | 怎样训练、保存、恢复，怎样区分学会和背熟 |
| 控制写诗 | [第 20—23 课](course/dist/lessons/20.html) | 怎样选下一个字，开头、关键词和格式怎样参与 |
| 做成工具并改进 | [第 24—26 课](course/dist/lessons/24.html) | 怎样编写 CLI、检查结果，再做条件明确的改进实验 |

每节课都按“读 → 猜 → 改 → 跑 → 讲”做一轮：

- **读**：先读“这一课完成什么”，知道当前要解决哪个问题。
- **猜**：看图中的输入，写下你认为程序会输出什么。
- **改**：在教学图解里只改一项，观察结果为什么变化。
- **跑**：运行完整实验；然后把 `starter.py` 复制为自己的文件，补全代码并运行。
- **讲**：用自己的话解释输入、计算和输出。能讲清楚，再勾选完成。

例如做第 4 课的代码练习：

```bash
cp lessons/04/starter.py lessons/04/my_exercise.py
# 用编辑器补全 my_exercise.py，再执行：
.venv/bin/python lessons/04/my_exercise.py
# 需要对照时查看或运行参考答案：
.venv/bin/python lessons/04/solution.py
```

`starter.py` 是有意留空的练习，尚未补全时出现 `NotImplementedError` 属于预期情况。`experiment.py` 是完整示例，`solution.py` 是参考答案。课程构建时会重新导出部分示例，因此把自己的改动放在 `my_exercise.py` 里更容易保留。

每次结束前留下四句话：今天改了什么、原来猜会怎样、实际发生什么、下一次想验证什么。学习勾选只记录“学到哪一课”；实验结论还需要你自己的文字。

## 用终端运行 CLI

CLI 就是在终端里用文字操作程序。网页和 CLI 使用同一个本地模型。安装完成、进入项目根目录后，可以运行：

```bash
# 按开头写五言诗
./poet write --start 春 --form five
# 按关键词写七言诗，并输出三首
./poet write --keywords 秋雨,故乡 --form seven --count 3
# 查看完整用法
./poet write --help
```

`--start` 是开头，`--keywords` 是逗号分开的关键词，`five` 和 `seven` 分别是五言和七言，`--count` 是输出数量。先用这些选项，变化程度和候选筛选等设置到第 20—23 课再逐项实验。

```bash
# 把结果保存为其他程序可以读取的 JSON
./poet write --keywords 明月 --json --output reports/my-poems.json
# 在终端连续输入条件
./poet chat
```

进入连续输入模式后，可以输入 `/start 春`；输入 `/quit` 退出。它用于古诗条件输入，使用方法见第 24 课。

想用网页中训练出来的模型在终端写诗，先找到右侧显示的实际目录，再把该目录下的 `best.pt` 传给 `--checkpoint`。目录名中的 `wb-…` 每次不同，不要照抄别人的编号。

模型负责选字，程序负责四句、每句字数和标点。句数正确不等于符合全部平仄、押韵与对仗要求；关键词命中和查重信息也不能代替自己阅读诗意。

## 文件和学习进度保存在哪里

| 你想保留的东西 | 保存位置或方法 |
| --- | --- |
| 课程完成勾选 | 当前浏览器的本地存储；换浏览器可能看不到原勾选 |
| 网页训练的模型 | `artifacts/workbench/runs/wb-…/`，以面板显示的具体路径为准 |
| 每次运行的参数与文字日志 | `artifacts/workbench/jobs/…/`，也可点“保存这次输出” |
| 网页写诗的结构化结果 | 对应任务目录内的 `poems.json` |
| 自己写的代码 | 例如 `lessons/04/my_exercise.py`；由你在编辑器中保存 |
| 终端写诗另存的文件 | 由 `--output` 指定，例如 `reports/my-poems.json` |

模型目录里，`best.pt` 用于写诗和评估，`latest.pt` 用于继续训练，`initial.pt` 用于训练前对照；`metrics.jsonl` 记录训练过程，`run.json` 记录状态与设置。继续训练还需要保存的调整状态，所以恢复时选 `latest.pt`。

**下载的标准学习包是一份课程起点。** 打包脚本不会收集你的 `artifacts/workbench/` 私人练习记录。想迁移自己的进度，先停止并保存，再另外备份这一整个目录和自己修改的练习文件；新电脑准备环境后，放回同名位置。浏览器里的课程勾选需要自行记下，不能只靠复制模型文件迁移。

移动已经安装过环境的项目到新路径时，Python 环境中的部分路径可能仍指向旧位置。保留课程、数据和模型，重新准备项目环境更稳妥；可以把旧 `.venv` 改名备份后，再运行 `sh scripts/setup.sh`。

## 常见问题：先找到卡在哪一步

| 看到的情况 | 可以先做什么 |
| --- | --- |
| 网页提示无法访问 | 在项目根目录运行 `./poet course --status`；未运行就执行 `./poet course --start`，核对端口 |
| 能读课文，右侧显示未连接 | 确认地址是 `http://127.0.0.1:端口/`，不是直接打开的 HTML 文件；启动服务后刷新 |
| 提示 `uv: command not found` | 完成官方 uv 安装，重新打开终端，再用 `uv --version` 检查 |
| 提示“还没有学习环境” | 在这份项目的根目录执行 `sh scripts/setup.sh`，等待安装成功 |
| `start.command` 没有顺利启动 | 打开终端进入项目根目录，运行 `sh start.command`，根据保留下来的提示处理 |
| 提示 `Permission denied`，无法执行 `./poet` | 安装脚本会设置执行权限；也可在项目根目录执行 `chmod +x poet start.command` 后重试 |
| 提示找不到 `poet` 或 `scripts/setup.sh` | 当前目录不对，回到同时包含这些文件的项目根目录 |
| 提示端口已被占用 | 用 `--port 8767` 启动，浏览器也改用 8767；后续查询、停止带同一端口 |
| 页面说连接已失效 | 后台可能重启过，刷新页面，再查看“最近的实验”和保存的进度 |
| 正在训练，暂时没有新输出 | 首次会加载材料和做检查，训练日志按间隔输出；先等当前任务，不要重复启动 |
| 电脑较慢或提示内存不足 | 先停止并保存；新练习选小模型，把每批数量降低到 8 或 16，先做短训练 |
| 找不到刚训练的模型 | 等任务保存完成；切换右侧操作刷新模型列表，必要时刷新页面并查看实际目录 |
| 恢复时说目标步数不够大 | 目标是累计总数，必须大于已经完成的步数 |
| 练习报 `NotImplementedError` | 这是留空练习尚未补全；先运行完整实验，再补代码或对照参考答案 |
| 写诗不通顺或没出现全部关键词 | 确认选的是哪份模型；短训练能力有限，读第 19—23 课做比较和改进 |
| 新解压的副本没有“下载完整学习包”链接 | 这个文件夹已经是完整项目；需要再次分享时按下节重新打包 |

需要定位问题时，保留：当时的命令或右侧设置、完整错误输出、使用的模型目录。这样更容易判断是环境、文件位置、输入参数还是模型能力问题。

## 分享给别人，以及学习到什么程度算完成

要分享标准课程包，在项目根目录运行：

```bash
.venv/bin/python scripts/build_course.py
.venv/bin/python scripts/package_workbench.py
```

生成的 ZIP 在 `packages/poetry-gpt-workbench.zip`。将这个文件交给对方，对方解压后先打开 `使用手册.html`，再按首次安装流程操作。包内的 `PACKAGE-MANIFEST.json` 是文件校验清单，用于检查材料有没有缺失或改变。

新电脑第一次安装需要网络；本项目的搬迁检查复用了本机已有 Python 依赖，并不等于已验证所有操作系统的首次安装。本手册以 macOS 为主，其他系统先从第 1 课检查环境，再做短训练。

当你能独立做到下面这些事，就完成了这套课程的主线：

- 能打开项目并判断网页是否连接到本机程序。
- 能解释汉字怎样组成输入和答案，为什么预测时不能偷看后文。
- 能讲清“预测 → 评分 → 求调整方向 → 更新参数”的一次训练。
- 能从零开始一次训练，保存、停止、恢复，并找到对应文件。
- 能用相同检查条件比较两个模型，再读实际生成的诗。
- 能逐步编写 CLI，处理输入、加载模型、显示或保存输出，并解释错误提示。

后续改进从 [第 26 课](course/dist/lessons/26.html) 开始：先提出一个具体问题，只改一个设置，保留原模型与记录，再比较效果和耗时。