一字一诗
用户使用手册

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

先选适合你的入口

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

下载、解压与认识学习包

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

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

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

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

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

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

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

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

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

ls

第二步：准备 uv

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

uv --version

若显示版本号，可继续下一步。若提示找不到 uv，可按 uv 官方安装说明 中的 macOS 方法安装：

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

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

第三步：安装本项目环境

sh scripts/setup.sh

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

./poet doctor

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

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

日常打开

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

./poet course --start

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

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

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

下次继续与正常结束

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

./poet course --status

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

./poet course --stop

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

./poet course --start --port 8767

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

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

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

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

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

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

整个学习包的基础流程

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

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

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

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

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

体验已有模型

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

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

拆一条接字题

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

从零训练 50 步

打开 第 16 课：完成一次训练，在右侧选择“从零训练”，填写以下设置：

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

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

恢复到总共 75 步

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

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

检查自己训练的模型

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

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

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

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

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

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

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

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

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

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 使用同一个本地模型。安装完成、进入项目根目录后，可以运行：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.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 课 开始：先提出一个具体问题，只改一个设置，保留原模型与记录，再比较效果和耗时。