【大模型课程笔记】斯坦福大学CS336 课程环境配置与讲座生成完整指南

CS336课程环境配置与讲座生成完整指南

斯坦福大学CS336: Language Models From Scratch
本指南将帮助您从零开始配置环境并生成交互式讲座课件

📋 目录

项目简介
准备工作
阶段一：环境配置
阶段二：依赖安装
阶段三：API配置（可选）
阶段四：生成讲座
阶段五：查看讲座
故障排查
进阶使用

项目简介

这是一个可执行的讲座系统，通过运行Python脚本来生成交互式课程内容。

工作原理：

复制代码

lecture_01.py (Python代码)

    ↓ 通过 execute.py 追踪执行过程

var/traces/lecture_01.json (追踪数据)

    ↓ 通过 trace-viewer 前端可视化

浏览器中的交互式讲座

特点：

✅ 可以看到代码执行的每一步
✅ 可以查看变量的实时值
✅ 包含图片、链接、代码引用等丰富内容
✅ 完全交互式的学习体验

准备工作

重要说明：关于终端类型

本指南的所有命令都针对PyCharm内置终端（CMD）编写。

PyCharm默认使用CMD（命令提示符）而非PowerShell，两者命令语法不同：

| 操作 | CMD（PyCharm终端）✅ | PowerShell ❌ |

|------|---------------------|--------------|

| 设置环境变量 | set KEY=value | $env:KEY = "value" |

| 查看环境变量 | echo %KEY% | echo $env:KEY |

| 注释 | REM 注释 | # 注释 |

如果您在PyCharm外使用PowerShell，需要调整命令语法。本指南统一使用CMD语法。

系统要求

操作系统：Windows 10/11（本指南基于Windows）
IDE：PyCharm（推荐）或其他Python IDE
Python：3.8 或更高版本
包管理器：Conda（推荐）或 Python venv
磁盘空间：至少 5GB（包含依赖和生成的文件）
网络：需要下载Python包和访问外部资源

预检查

打开 PyCharm终端，执行以下命令检查环境：

cmd 复制代码

REM 检查Python版本

python --version

  

REM 检查Conda版本（如果使用Conda）

conda --version

  

REM 检查项目路径

cd "E:\PycharmProject\004 LLM\spring2025-lectures-main"

cd

预期输出：

Python版本：3.8.x 或更高
Conda版本：4.x 或更高
当前路径：E:\PycharmProject\004 LLM\spring2025-lectures-main

阶段一：环境配置

使用Conda创建虚拟环境（推荐）

步骤1：创建虚拟环境

在PyCharm终端中执行：

cmd 复制代码

REM 进入项目目录

cd "E:\PycharmProject\004 LLM\spring2025-lectures-main"

  

REM 创建名为cs336的虚拟环境，指定Python 3.10

conda create -n cs336 python=3.10 -y

预期输出：

复制代码

Collecting package metadata...

Solving environment...

...

Preparing transaction: done

Verifying transaction: done

Executing transaction: done

步骤2：激活虚拟环境

cmd 复制代码

conda activate cs336

预期输出：

命令提示符前缀变为 (cs336)

验证：

cmd 复制代码

REM 验证Python版本

python --version

  

REM 验证当前环境

conda info --envs

预期输出：

Python 3.10.x
cs336 环境前面有 * 标记

阶段二：依赖安装

步骤3：升级pip

cmd 复制代码

REM 确保虚拟环境已激活（提示符前有 (cs336)）

python -m pip install --upgrade pip

预期输出：

复制代码

Successfully installed pip-24.x.x

步骤4：安装依赖

cmd 复制代码

REM 安装所有依赖（文件已存在于项目中）

pip install -r requirements.txt

预期时间：3-10分钟（取决于网络速度）

可能失败的包：

triton：仅支持Linux，Windows会失败（可以忽略）
kenlm：需要C++编译环境
fasttext：可能需要Visual Studio Build Tools

处理策略：

✅ 如果全部安装成功，恭喜您！
⚠️ 如果某些包失败，不用担心，这些包不是lecture_01的必需依赖

步骤4.1：验证关键包

cmd 复制代码

REM 测试PyTorch

python -c "import torch; print('PyTorch版本:', torch.__version__)"

  

REM 测试Numpy

python -c "import numpy; print('Numpy版本:', numpy.__version__)"

  

REM 测试tiktoken

python -c "import tiktoken; print('tiktoken安装成功')"

  

REM 测试openai

python -c "import openai; print('openai安装成功')"

预期输出：

复制代码

PyTorch版本: 2.x.x

Numpy版本: 1.x.x

tiktoken安装成功

openai安装成功

阶段三：API配置（可选）

lecture_01.py 会调用大语言模型API。您可以选择以下任一方案：

方案A：使用OpenAI API（如果有OpenAI API密钥）

步骤5：设置环境变量

powershell 复制代码

# 临时设置（仅当前会话有效）

$env:OPENAI_API_KEY = "your-api-key-here"

  

# 验证

echo $env:OPENAI_API_KEY

永久设置（可选）：

powershell 复制代码

# 添加到用户环境变量

[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-api-key-here", "User")

注意：使用OpenAI需要修改回lecture_01.py第52行，将query_deepseek_v3改回query_gpt4o。

方案B：使用DeepSeek API（推荐，已配置）✨

DeepSeek提供兼容OpenAI接口的API，性能优秀且价格实惠。本项目已经配置好DeepSeek支持。

步骤5：设置DeepSeek API密钥

在PyCharm终端（CMD）中执行：

cmd 复制代码

set DEEPSEEK_API_KEY=XXXXXXXXXXXX

验证设置：

cmd 复制代码

echo %DEEPSEEK_API_KEY%

预期输出：

复制代码

XXXXXXXXXXXX

永久设置（可选）：

cmd 复制代码

setx DEEPSEEK_API_KEY "XXXXXXXXXXXX"

注意： setx 设置后需要重启终端才能生效。

测试API连接：

cmd 复制代码

python test_deepseek_api.py

预期输出：

复制代码

============================================================

DeepSeek API 配置测试

============================================================

✓ API密钥已设置

  密钥前缀: sk-60fab2d...

  密钥长度: 35 字符

  

------------------------------------------------------------

测试API连接...

------------------------------------------------------------

✓ OpenAI客户端初始化成功

  Base URL: https://api.deepseek.com

  

发送测试请求...

✓ API调用成功！

  响应: Hello

  模型: deepseek-chat

  

------------------------------------------------------------

测试model_util.py集成...

------------------------------------------------------------

✓ 成功导入 query_deepseek_v3

  

调用 query_deepseek_v3（可能需要几秒钟）...

✓ 使用DeepSeek API (模型: deepseek-chat)

✓ 函数调用成功！

  响应: Hello! 👋 How can I assist you today?...

  

============================================================

测试完成: 3/3 通过

============================================================

  

✓ 所有测试通过！现在可以运行：

  python execute.py -m lecture_01

代码修改说明：

✅ model_util.py已添加DeepSeek API支持
✅ lecture_01.py已修改为使用query_deepseek_v3
✅ 响应会自动缓存到var/query_model_cache.db

方案C：使用模拟数据（无API密钥）

如果您没有任何API密钥，可以修改代码返回模拟响应。

步骤5：修改model_util.py

在query_model函数开头添加模拟数据检查：

找到第6行的query_model函数，在函数开头添加：

python 复制代码

def query_model(model: str, prompt: str) -> str:

    """Query `model` with the `prompt` and return the top-1 response."""

    # 添加这段代码：检查是否有API密钥，没有则返回模拟数据

    import os

    if model.startswith("gpt-") and not os.getenv("OPENAI_API_KEY"):

        return f"[模拟GPT响应] 关于'{prompt[:50]}...'的回答"

    if model.startswith("deepseek") and not os.getenv("DEEPSEEK_API_KEY"):

        return f"[模拟DeepSeek响应] 关于'{prompt[:50]}...'的回答"

    # 下面是原有代码，保持不变

    ensure_directory_exists("var")

    cache = SqliteDict("var/query_model_cache.db")

    # ... 其余代码保持不变

保存文件后验证：

powershell 复制代码

python -c "from model_util import query_deepseek_v3; print(query_deepseek_v3('测试'))"

阶段四：生成讲座

步骤6：生成lecture_01

cmd 复制代码

REM 确保在项目根目录

cd "E:\PycharmProject\004 LLM\spring2025-lectures-main"

  

REM 确保虚拟环境已激活

conda activate cs336

  

REM 生成lecture_01

python execute.py -m lecture_01

预期执行时间：2-5分钟

预期输出：

复制代码

Executing lecture_01...

  [0 lecture_01.py:24] welcome()

  [1 lecture_01.py:39] text("## CS336: Language Models From Scratch (Spring 2025)")

  [2 lecture_01.py:41] image("images/course-staff.png", width=600)

  ...

  [250 lecture_01.py:736] text("Next time: PyTorch building blocks")

250 steps

Saving trace to var/traces/lecture_01.json...

步骤7：验证生成结果

cmd 复制代码

REM 检查文件是否生成

dir var\traces\lecture_01.json

  

REM 查看文件大小

dir var\traces\lecture_01.json | find "lecture_01.json"

预期输出：

文件存在
文件大小 > 500KB

成功标志：

✅ var/traces/lecture_01.json 文件存在
✅ 文件大小 > 500KB
✅ 控制台输出显示 "Saving trace to..."
✅ 没有Python错误或异常

阶段五：查看讲座

方案A：使用Python本地服务器（推荐）✨

这是最简单可靠的方法，无需安装额外软件。

步骤8：启动HTTP服务器

在项目根目录（重要！）启动服务器：

cmd 复制代码

REM 确保在项目根目录

cd "E:\PycharmProject\004 LLM\spring2025-lectures-main"

  

REM 启动HTTP服务器

python -m http.server 8000

预期输出：

复制代码

Serving HTTP on :: port 8000 (http://[::]:8000/) ...

步骤9：在浏览器中打开

正确的URL格式（使用HashRouter）：

复制代码

http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_01.json

URL说明：

trace-viewer/dist/index.html - 前端入口页面
#/ - HashRouter的路由标记
?trace=var/traces/lecture_01.json - trace文件路径（相对于项目根目录）

查看其他讲座： 只需更改URL中的文件名：

复制代码

http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_02.json

http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_06.json

方案B：使用npm开发服务器（开发调试用，需Node.js）

需要先安装Node.js（https://nodejs.org/）

步骤8：检查Node.js

cmd 复制代码

node --version

npm --version

预期输出：

Node.js: v16.x.x 或更高
npm: 8.x.x 或更高

步骤9：安装前端依赖

cmd 复制代码

REM 进入前端目录

cd trace-viewer

  

REM 安装依赖（首次运行）

npm install

预期时间：2-5分钟

步骤10：启动开发服务器

cmd 复制代码

npm run dev

预期输出：

复制代码

  VITE v6.x.x  ready in 500 ms

  

  ➜  Local:   http://localhost:5173/

  ➜  Network: use --host to expose

步骤11：在浏览器中打开

复制代码

http://localhost:5173/?trace=../var/traces/lecture_01.json

注意： 开发模式下trace路径需要加 ../ 前缀。

方案C：构建生产版本

如果需要重新构建前端（例如修改了源码）：

步骤8：构建静态文件

cmd 复制代码

cd trace-viewer

npm run build

预期输出：

复制代码

vite v6.x.x building for production...

✓ built in 1s

dist/index.html  x KB

步骤9：使用方案A查看

构建完成后，使用方案A的方法启动服务器并访问。

验证讲座内容

在浏览器中检查以下元素：

✅ 标题显示：

"CS336: Language Models From Scratch (Spring 2025)"

✅ 图片加载：

课程团队照片
各种技术图表（如GPT-4架构图）

✅ 代码块：

Python代码可以折叠/展开
行号正确显示

✅ 变量inspect：

某些行旁边显示变量值（如 response = "..."）

✅ 链接可点击：

论文引用链接
外部文章链接

✅ 交互功能：

可以点击代码跳转到定义
可以搜索内容

故障排查

问题1：pip安装失败

症状：

复制代码

ERROR: Could not find a version that satisfies the requirement triton

解决方案：

powershell 复制代码

# triton仅支持Linux，Windows可以忽略

# 跳过triton单独安装其他包

pip install torch numpy sympy requests sqlitedict warcio markdownify tiktoken openai einops jaxtyping readable-number matplotlib wandb mmh3 bitarray

问题2：execute.py运行出错

症状：

复制代码

ModuleNotFoundError: No module named 'xxx'

解决方案：

powershell 复制代码

# 安装缺失的模块

pip install xxx

  

# 或者检查虚拟环境是否激活

conda activate cs336

问题3：生成的JSON文件很小（<100KB）

症状：

JSON文件存在但内容不完整

解决方案：

powershell 复制代码

# 检查执行过程中的错误输出

python execute.py -m lecture_01 2>&1 | Tee-Object -FilePath error.log

  

# 查看错误日志

cat error.log

问题4：浏览器无法加载JSON

症状：

浏览器显示"Failed to load trace"

解决方案：

powershell 复制代码

# 检查JSON格式是否正确

python -m json.tool var/traces/lecture_01.json > nul

# 如果没有输出，说明JSON格式正确

  

# 检查路径是否正确

# 确保URL参数 ?trace= 后的路径相对于HTML文件正确

问题5：PowerShell执行策略错误

症状：

复制代码

无法加载文件 xxx.ps1，因为在此系统上禁止运行脚本

解决方案：

powershell 复制代码

# 临时允许（仅当前会话）

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

  

# 或者使用CMD的.bat文件激活

.\cs336\Scripts\activate.bat

问题6：OpenAI API错误

症状：

复制代码

openai.error.AuthenticationError: Invalid API key

解决方案：

检查API密钥是否正确设置
或者使用方案B修改代码使用模拟数据

问题7：CUDA相关错误（如果没有GPU）

症状：

复制代码

RuntimeError: CUDA error: no kernel image is available

解决方案：

powershell 复制代码

# 安装CPU版本的PyTorch

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

进阶使用

生成其他讲座

可用的讲座文件：

| 文件名 | 内容 | 说明 |

|--------|------|------|

| lecture_01.py | 课程介绍与Tokenization | ✅ 推荐首先生成 |

| lecture_02.py | PyTorch基础 | 基础内容 |

| lecture_06.py | MLP优化 | 需要 lecture_06_mlp.py, lecture_06_utils.py |

| lecture_08.py | GPU编程 | 需要CUDA环境（可选） |

| lecture_10.py | 模型训练 | 进阶内容 |

| lecture_12.py | Scaling Laws | 进阶内容 |

| lecture_13.py | 数据处理 | 进阶内容 |

| lecture_14.py | 模型对齐 | 进阶内容 |

| lecture_17.py | 高级主题 | 进阶内容 |

生成命令：

cmd 复制代码

REM 确保在项目根目录并激活环境

cd "E:\PycharmProject\004 LLM\spring2025-lectures-main"

conda activate cs336

  

REM 设置API密钥（每次新开终端都需要）

set DEEPSEEK_API_KEY=XXXXXXXXXXXX

  

REM 生成单个讲座

python execute.py -m lecture_02

  

REM 生成多个讲座（依次执行）

python execute.py -m lecture_06

python execute.py -m lecture_10

生成时间参考：

lecture_01: 2-5 分钟
lecture_02: 3-8 分钟
其他讲座: 5-15 分钟（取决于内容复杂度和API调用次数）

访问其他讲座

启动服务器（如果未运行）：

cmd 复制代码

cd "E:\PycharmProject\004 LLM\spring2025-lectures-main"

python -m http.server 8000

访问URL格式：

复制代码

http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/[讲座文件名].json

各讲座访问链接：

| 讲座 | URL |

|------|-----|

| Lecture 01 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_01.json |

| Lecture 02 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_02.json |

| Lecture 06 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_06.json |

| Lecture 08 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_08.json |

| Lecture 10 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_10.json |

| Lecture 12 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_12.json |

| Lecture 13 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_13.json |

| Lecture 14 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_14.json |

| Lecture 17 | http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_17.json |

查看已有讲座列表

CMD命令：

cmd 复制代码

REM 列出所有讲座源文件

dir lecture_*.py /b

  

REM 查看已生成的trace文件

dir var\traces\*.json

预期输出：

复制代码

lecture_01.py

lecture_02.py

lecture_06.py

...

  

var\traces\lecture_01.json

var\traces\lecture_02.json

...

自定义讲座内容

您可以编辑 lecture_01.py 或创建自己的讲座文件：

python 复制代码

# my_lecture.py

from execute_util import text, image, link

  

def main():

    text("## 我的自定义讲座")

    text("这是一个示例内容")

    image("path/to/image.png", width=400)

  

# 生成

python execute.py -m my_lecture

inspect变量功能

在代码中使用 # @inspect variable_name 来捕获变量值：

python 复制代码

x = 42  # @inspect x

y = [1, 2, 3]  # @inspect y

result = x + sum(y)  # @inspect result

生成的trace会包含这些变量的值。

跳过某些代码的追踪

使用 # @stepover 标记不需要追踪的代码：

python 复制代码

slow_function()  # @stepover

完整工作流总结

在PyCharm终端（CMD）中使用DeepSeek API（推荐）

cmd 复制代码

REM 1. 激活虚拟环境（如果未激活）

conda activate cs336

  

REM 2. 进入项目目录

cd "E:\PycharmProject\004 LLM\spring2025-lectures-main"

  

REM 3. 升级pip并安装依赖

python -m pip install --upgrade pip

pip install -r requirements.txt

  

REM 4. 设置DeepSeek API密钥

set DEEPSEEK_API_KEY=XXXXXXXXXXXX

  

REM 5. 验证设置

echo %DEEPSEEK_API_KEY%

  

REM 6. 测试API连接（推荐）

python test_deepseek_api.py

  

REM 7. 生成讲座

python execute.py -m lecture_01

  

REM 8. 查看讲座

python -m http.server 8000

浏览器访问： http://localhost:8000/trace-viewer/dist/index.html#/?trace=var/traces/lecture_01.json

一行命令快速执行

cmd 复制代码

set DEEPSEEK_API_KEY=XXXXXXXXXXXX && python test_deepseek_api.py && python execute.py -m lecture_01

下一步

✅ 完成lecture_01后，您可以：

按顺序生成其他讲座（lecture_02, lecture_06等）
阅读 nonexecutable/ 目录中的PDF讲座（lecture 3, 4, 5等）
尝试修改讲座内容，创建自己的版本
深入研究代码实现，理解trace系统的工作原理

✅ 推荐学习路径：

Lecture 01: 课程介绍与Tokenization
Lecture 02: PyTorch基础
Lecture 06: MLP优化
Lecture 08: GPU编程
Lecture 10: 模型训练
Lecture 12-17: 高级主题

附录

A. 项目文件结构

复制代码

spring2025-lectures-main/

├── lecture_01.py          # 第1讲：课程介绍

├── lecture_02.py          # 第2讲：PyTorch基础

├── lecture_*.py           # 其他讲座

├── execute.py             # 执行引擎

├── execute_util.py        # 工具函数（text, image, link等）

├── model_util.py          # OpenAI API调用

├── requirements.txt       # Python依赖

├── var/

│   └── traces/            # 生成的trace JSON文件

├── trace-viewer/          # React前端应用

│   ├── src/               # 源代码

│   └── dist/              # 构建输出

├── images/                # 讲座中使用的图片

└── nonexecutable/         # PDF格式的讲座

B. 常用命令速查

powershell 复制代码

# 环境管理

conda activate cs336              # 激活环境

conda deactivate                  # 退出环境

conda env list                    # 列出所有环境

  

# 包管理

pip list                          # 列出已安装的包

pip show torch                    # 查看包详情

pip freeze > installed.txt        # 导出已安装包列表

  

# 生成讲座

python execute.py -m lecture_01   # 生成单个讲座

python execute.py -m lecture_01 lecture_02  # 批量生成

  

# 启动服务器

python -m http.server 8000        # Python简易服务器

cd trace-viewer && npm run dev    # 开发服务器

  

# 文件检查

Test-Path var/traces/lecture_01.json           # 检查文件是否存在

Get-Item var/traces/lecture_01.json            # 查看文件信息

Get-Content var/traces/lecture_01.json -Head 5 # 查看文件前5行

C. 资源链接

课程主页: https://stanford-cs336.github.io/
GitHub仓库: https://github.com/stanford-cs336/spring2025-lectures
PyTorch文档: https://pytorch.org/docs/
OpenAI API: https://platform.openai.com/docs/

🎉 恭喜！

如果您已经成功生成并查看了lecture_01，说明您已经掌握了这个系统的使用方法。

现在可以继续探索其他讲座，深入学习语言模型的构建技术！

祝学习愉快！ 🚀

最后更新：2026-02-01

适用版本：CS336 Spring 2025