手把手教你在Windows WSL2上安装Guidance，新手必看教程 (2025年05月)

引言

Guidance是微软推出的一个强大的AI编程辅助工具，能够帮助开发者更高效地编写代码。本教程将详细介绍如何在Windows WSL2环境中安装和配置Guidance，即使是完全没有Linux经验的新手也能轻松上手。

准备工作

在开始之前，请确保你的系统满足以下要求：

Windows 10版本2004或更高（建议使用Windows 11）
已启用WSL2功能
至少8GB内存（推荐16GB）
至少20GB可用磁盘空间

检查WSL2状态

首先，我们需要确认WSL2已经正确安装并启用：

代码片段

wsl --list --verbose

如果看到类似下面的输出，说明WSL2已安装：

代码片段

  NAME      STATE           VERSION
* Ubuntu    Running         2

如果没有安装WSL2，可以参考微软官方文档先进行安装。

第一步：更新系统包

打开WSL终端（可以直接在开始菜单搜索你的Linux发行版名称），执行以下命令更新系统：

代码片段

sudo apt update && sudo apt upgrade -y

原理说明：
– sudo：以管理员权限执行命令
– apt update：更新软件包列表
– apt upgrade：升级所有可升级的软件包
– -y：自动回答”yes”确认操作

第二步：安装Python环境

Guidance需要Python 3.8或更高版本。我们推荐使用Python 3.10：

代码片段

sudo apt install python3 python3-pip python3-venv -y

验证安装是否成功：

代码片段

python3 --version
pip3 --version

实践经验：
建议为Guidance创建一个独立的虚拟环境，避免与其他Python项目冲突：

代码片段

python3 -m venv guidance-env
source guidance-env/bin/activate

你会看到命令行提示符前面多了(guidance-env)，表示已经进入虚拟环境。

第三步：安装Guidance

现在我们可以通过pip安装Guidance了：

代码片段

pip install guidance --upgrade

为了确保所有依赖项都正确安装，建议也安装这些常用库：

代码片段

pip install numpy pandas jupyterlab torch transformers

注意事项：
– 如果遇到网络问题，可以尝试使用国内镜像源：

代码片段

pip install guidance -i https://pypi.tuna.tsinghua.edu.cn/simple/<br>

– GPU用户需要额外安装CUDA版本的PyTorch

第四步：验证安装

让我们运行一个简单的测试程序验证Guidance是否正常工作：

创建一个名为test_guidance.py的文件：

代码片段

import guidance

# 初始化guidance模型（这里使用较小的模型做测试）
gpt = guidance.models.Transformers("gpt2")

# 定义一个简单的对话程序
program = guidance('''
{{#system~}}
你是一个乐于助人的AI助手。
{{~/system}}

{{#user~}}
你好！请介绍一下你自己。
{{~/user}}

{{#assistant~}}
{{gen 'response' max_tokens=100}}
{{~/assistant}}
''')

# 执行程序并打印结果
result = program()
print(result["response"])

运行脚本：

代码片段

python test_guidance.py

如果看到AI助手的自我介绍输出，说明安装成功！

第五步：配置Jupyter Notebook（可选）

如果你想在Jupyter中使用Guidance，可以这样设置：

首先确保已安装jupyterlab：

代码片段

pip install jupyterlab ipywidgets widgetsnbextension pandas numpy matplotlib seaborn scikit-learn tqdm ipython-autotime

启动Jupyter Lab：

代码片段

jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root &

Windows主机上访问：
在浏览器中输入 http://localhost:8888

Jupyter中测试Guidance：
新建一个Notebook，输入以下代码并运行：

代码片段

import guidance

llm = guidance.models.Transformers("gpt2")

def ask_ai(question):
    program = guidance(f'''
    {{#system~}}
    你是一个知识渊博的AI助手。
    {{~/system}}

    {{#user~}}
    {question}
    {{~/user}}

    {{#assistant~}}
    {{gen 'answer' max_tokens=200 temperature=0.7}}
    {{~/assistant}}
    ''')
    return program()["answer"]

print(ask_ai("如何学习Python编程？"))

常见问题解决

CUDA错误：
如果你有NVIDIA显卡但遇到CUDA错误，尝试：

代码片段

pip uninstall torch torchvision torchaudio -y && \
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 --force-reinstall

内存不足：
大型模型需要大量内存。如果遇到OOM错误：
- 使用较小的模型（如gpt2-medium代替gpt2-xl）
- 增加WSL内存限制（在Windows用户目录下创建或修改.wslconfig文件）:
  代码片段
```
[wsl2]
memory=16GB #根据你的硬件调整大小 
swap=8GB <br>
```
下载速度慢：
设置pip和conda的国内镜像源。

GPU加速配置（可选）

如果你有NVIDIA显卡并想利用GPU加速：

WSL中安装CUDA驱动：

代码片段

wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb && \
sudo dpkg -i cuda-keyring_1.1-1_all.deb && \
sudo apt-get update && \
sudo apt-get -y install cuda-toolkit-12-4 libcudnn8-dev libcudnn8 libnccl-dev

验证CUDA是否可用：

代码片段

nvidia-smi #应该显示GPU信息 

python -c "import torch; print(torch.cuda.is_available())" #应该返回True

总结

通过本教程，你已经成功在WSL2上安装了Guidance AI编程助手。关键步骤回顾：

[✓] WSL2环境准备和验证
[✓] Python环境和虚拟环境设置
[✓] Guidance及其依赖项的安装
[✓] Jupyter Notebook集成
[✓] GPU加速配置

现在你可以开始体验Guidance带来的高效编程体验了！试着用它来生成代码、回答问题或进行数据分析吧！

如果在使用过程中遇到任何问题，欢迎在评论区留言讨论。