Qwen2.5-Coder-1.5B部署教程：Windows11环境配置详解

想在自己的Windows电脑上跑一个代码生成AI，但又担心配置太复杂、显卡不够用？如果你手头有一台Windows 11的电脑，哪怕显卡只有4GB显存，今天这篇文章就是为你准备的。

Qwen2.5-Coder-1.5B是一个专门为代码生成、代码推理和代码修复设计的轻量级大语言模型。它只有15亿参数，对硬件要求非常友好，但代码能力却相当不错。我最近在自己的笔记本上折腾了一番，发现整个过程比想象中简单很多，基本上跟着步骤走就能搞定。

这篇文章我会手把手带你完成从环境准备到实际运行的完整流程，过程中可能遇到的问题我也会一并告诉你解决方法。咱们的目标是让你在半小时内，就能让这个AI代码助手在你的电脑上跑起来。

1. 部署前准备：检查你的电脑

在开始安装之前，我们先花几分钟确认一下你的电脑是否符合基本要求。这能避免很多后续的麻烦。

1.1 硬件要求

Qwen2.5-Coder-1.5B对硬件的要求真的很亲民。根据我的实测经验，下面这些配置就足够了：

• 操作系统：Windows 10 64位或Windows 11（本文以Win11为例）
• 内存：至少8GB，推荐16GB或以上
• 存储空间：需要预留大约5-10GB的空间用于安装Python、模型文件等
• 显卡：这是最关键的部分。理论上，这个模型可以在纯CPU上运行，但速度会很慢。如果有独立显卡，体验会好很多：
  • 有NVIDIA显卡：显存4GB或以上（比如RTX 3050 Ti、GTX 1650等）
  • 只有集成显卡或AMD显卡：也能运行，但需要更多耐心

怎么查看自己的显卡信息？很简单，在Windows搜索框输入“设备管理器”，打开后找到“显示适配器”展开就能看到。

1.2 软件环境准备

我们需要安装几个基础软件，它们就像盖房子前要准备的工具一样。

首先是Python，这是运行AI模型的编程语言环境。我推荐安装Python 3.10版本，这个版本比较稳定，兼容性也好。

你可以去Python官网下载，安装时记得勾选“Add Python to PATH”这个选项，这样系统才能找到Python命令。

接下来是Git，我们需要用它来下载一些代码库。Git的安装很简单，一路下一步就行。

最后是Visual Studio Build Tools，这是编译某些Python包时需要的。如果你之前没安装过，可能会遇到一些奇怪的错误。

打开这个链接下载安装器，运行后选择“使用C++的桌面开发”这个工作负载安装即可。

2. 一步步搭建Python环境

环境准备好了，现在咱们开始真正的安装步骤。我会尽量把每个命令都解释清楚，让你知道自己在做什么。

2.1 创建专属的虚拟环境

为什么要有虚拟环境？想象一下，你的电脑上可能已经有其他Python项目，每个项目需要的软件包版本可能不同。虚拟环境就像给这个项目单独准备了一个房间，里面的东西不会影响到其他房间。

打开命令提示符（在开始菜单搜索“cmd”或“命令提示符”），然后依次输入下面的命令：

# 创建一个新的文件夹来存放我们的项目
mkdir qwen-coder-project
cd qwen-coder-project

# 创建Python虚拟环境
python -m venv venv

# 激活虚拟环境（每次新开命令行都需要执行这一步）
venv\Scripts\activate

激活成功后，你会看到命令行前面多了个(venv)的标记，这就表示你现在在这个虚拟环境里工作了。

2.2 安装必要的Python包

现在我们来安装运行模型需要的软件包。在激活的虚拟环境中，输入：

# 升级pip到最新版本
python -m pip install --upgrade pip

# 安装PyTorch（这是运行AI模型的核心框架）
# 注意：如果你有NVIDIA显卡，安装下面这个版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# 如果你没有NVIDIA显卡，或者只有AMD/Intel显卡，安装这个CPU版本
pip install torch torchvision torchaudio

# 安装Hugging Face的transformers库（这是加载和使用模型的关键）
pip install transformers accelerate

# 安装其他有用的工具
pip install sentencepiece einops tiktoken

这里有个小技巧：如果你在国内，下载速度很慢，可以在命令后面加上-i https://pypi.tuna.tsinghua.edu.cn/simple来使用清华的镜像源，比如：

pip install transformers -i https://pypi.tuna.tsinghua.edu.cn/simple

安装过程可能需要几分钟，取决于你的网速。如果某个包安装失败，多试几次或者换个时间再试通常就能解决。

3. 下载和加载模型

环境搭好了，现在该把模型请进来了。Qwen2.5-Coder-1.5B的模型文件大约3-4GB，第一次运行时会自动下载。

3.1 编写一个简单的测试脚本

在项目文件夹里创建一个新文件，命名为test_qwen.py，然后用文本编辑器（比如VS Code、Notepad++）打开，输入下面的代码：

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

# 设置模型名称
model_name = "Qwen/Qwen2.5-Coder-1.5B-Instruct"

print("正在加载模型和分词器，第一次运行会下载模型文件，请耐心等待...")

# 加载分词器（负责把文字转换成数字）
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)

# 加载模型
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,  # 使用半精度减少显存占用
    device_map="auto",  # 自动选择设备（GPU或CPU）
    trust_remote_code=True
)

print("模型加载完成！")

# 准备一个编程问题
prompt = "用Python写一个快速排序算法，并添加详细的注释。"

# 构建对话格式
messages = [
    {"role": "system", "content": "你是一个专业的编程助手。"},
    {"role": "user", "content": prompt}
]

# 将对话转换成模型能理解的格式
text = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)

# 将文字转换成数字（token）
inputs = tokenizer(text, return_tensors="pt").to(model.device)

print("正在生成代码，这可能需要一些时间...")

# 让模型生成回答
with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=512,  # 最多生成512个新token
        temperature=0.7,     # 控制创造性，值越低输出越确定
        do_sample=True       # 启用采样模式
    )

# 解码生成的token，转换成文字
generated_tokens = outputs[0][inputs.input_ids.shape[1]:]
response = tokenizer.decode(generated_tokens, skip_special_tokens=True)

print("\n" + "="*50)
print("模型生成的代码：")
print("="*50)
print(response)

保存文件后，回到命令提示符，确保还在虚拟环境中，然后运行：

python test_qwen.py

第一次运行会下载模型文件，这个过程可能需要一段时间，取决于你的网速。模型文件会下载到C:\Users\你的用户名\.cache\huggingface\hub这个目录下，大约占用3-4GB空间。

3.2 如果遇到下载问题

有时候因为网络原因，模型下载可能会很慢或者失败。别担心，我们有办法解决。

方法一：使用镜像源

在运行脚本前，先设置环境变量：

set HF_ENDPOINT=https://hf-mirror.com

然后再运行Python脚本，这样就会从国内的镜像站下载模型了。

方法二：手动下载

如果自动下载实在不行，你可以：

1. 访问Hugging Face的Qwen2.5-Coder-1.5B-Instruct页面
2. 手动下载所有文件（主要是pytorch_model.bin和配置文件）
3. 放到本地的一个文件夹，比如D:\models\qwen-coder-1.5b
4. 修改代码中的model_name为本地路径：

model_name = "D:/models/qwen-coder-1.5b"

4. 实际测试模型效果

模型跑起来了，咱们试试它的真实能力。我准备了几个不同难度的测试，你可以看看效果如何。

4.1 基础代码生成测试

创建一个新文件test_basic.py：

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

def ask_model(question):
    """向模型提问的辅助函数"""
    model_name = "Qwen/Qwen2.5-Coder-1.5B-Instruct"
    
    # 加载模型（如果已经加载过，可以全局只加载一次）
    tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
    model = AutoModelForCausalLM.from_pretrained(
        model_name,
        torch_dtype=torch.float16,
        device_map="auto",
        trust_remote_code=True
    )
    
    messages = [
        {"role": "user", "content": question}
    ]
    
    text = tokenizer.apply_chat_template(
        messages,
        tokenize=False,
        add_generation_prompt=True
    )
    
    inputs = tokenizer(text, return_tensors="pt").to(model.device)
    
    with torch.no_grad():
        outputs = model.generate(
            **inputs,
            max_new_tokens=256,
            temperature=0.7,
            do_sample=True
        )
    
    generated_tokens = outputs[0][inputs.input_ids.shape[1]:]
    response = tokenizer.decode(generated_tokens, skip_special_tokens=True)
    
    return response

# 测试1：简单的函数生成
print("测试1：生成一个计算斐波那契数列的函数")
result1 = ask_model("写一个Python函数，计算第n个斐波那契数")
print(result1)
print("-" * 50)

# 测试2：代码解释
print("测试2：解释下面的代码是做什么的")
result2 = ask_model("解释下面代码的功能：\ndef process_data(data):\n    return [x*2 for x in data if x > 0]")
print(result2)
print("-" * 50)

# 测试3：代码调试
print("测试3：修复有错误的代码")
result3 = ask_model("修复这段Python代码中的错误：\ndef calculate_average(numbers):\n    total = 0\n    for num in numbers:\n        total += num\n    average = total / len(number)")
print(result3)

运行这个脚本，你会看到模型如何处理不同类型的编程任务。在我的测试中，对于简单的代码生成和解释，它的表现相当不错，生成的代码通常可以直接使用。

4.2 实际项目中的使用

如果你想让模型帮你写一些实际的功能代码，可以试试这样的提示：

# 更具体的需求往往能得到更好的结果
detailed_prompt = """
我需要一个Python函数，功能如下：
1. 函数名：extract_emails_from_text
2. 输入：一段文本字符串
3. 输出：文本中所有电子邮件地址的列表
4. 要求：使用正则表达式匹配，能识别常见的邮箱格式
5. 添加适当的错误处理和文档字符串
"""

response = ask_model(detailed_prompt)
print(response)

你会发现，当你把需求描述得越详细、越结构化，模型生成的结果就越好。

5. 常见问题与解决方案

在部署和使用过程中，你可能会遇到一些问题。下面是我遇到过的几个典型问题及其解决方法。

5.1 显存不足错误

如果你看到类似CUDA out of memory的错误，说明显卡内存不够用了。试试这些方法：

方法一：使用更小的数据类型

# 修改模型加载部分，使用8位量化（需要bitsandbytes包）
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    load_in_8bit=True,  # 使用8位量化
    device_map="auto",
    trust_remote_code=True
)

不过注意，使用8位量化需要先安装bitsandbytes包，而且对Windows的支持可能有些问题。

方法二：使用CPU模式

如果显卡实在不够用，或者你没有独立显卡，可以强制使用CPU：

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float32,
    device_map="cpu",  # 明确指定使用CPU
    trust_remote_code=True
)

CPU模式会慢很多，生成一段代码可能需要几十秒到几分钟，但至少能运行起来。

方法三：减少生成长度

# 减少max_new_tokens的值
outputs = model.generate(
    **inputs,
    max_new_tokens=128,  # 从512减少到128
    temperature=0.7,
    do_sample=True
)

5.2 模型加载缓慢问题

第一次加载模型时，可能会感觉特别慢，这是正常的，因为需要从硬盘读取几GB的数据。后续再运行就会快很多。

如果你觉得加载时间太长，可以考虑使用更快的存储（比如NVMe SSD），或者确保有足够的内存（16GB以上会好很多）。

5.3 生成质量不理想

有时候模型生成的代码可能不符合你的期望，可以尝试调整生成参数：

outputs = model.generate(
    **inputs,
    max_new_tokens=512,
    temperature=0.3,  # 降低温度，输出更确定但可能缺乏创造性
    top_p=0.9,        # 使用核采样，只考虑概率最高的部分token
    do_sample=True,
    repetition_penalty=1.1,  # 避免重复
    num_return_sequences=2   # 生成2个不同版本，选最好的
)

另外，提示词的质量也很关键。试试这样改进你的问题描述：

• 明确指定编程语言
• 描述具体的输入输出格式
• 给出示例或约束条件
• 要求添加注释或测试用例

6. 进阶使用技巧

基本的部署和运行掌握了之后，咱们来看看怎么用得更好、更高效。

6.1 使用Ollama简化部署

如果你觉得上面的方式还是有点复杂，可以试试Ollama。它把很多复杂步骤都封装好了，用起来更简单。

首先去Ollama官网下载Windows版本并安装，然后打开命令提示符：

# 拉取Qwen2.5-Coder-1.5B模型
ollama pull qwen2.5-coder:1.5b

# 运行模型
ollama run qwen2.5-coder:1.5b

运行后，你会进入一个交互式界面，可以直接输入问题，比如“用Python写一个冒泡排序”。

Ollama的好处是管理方便，更新简单，而且社区支持很好。缺点是你对底层的控制会少一些。

6.2 集成到开发环境中

如果你想让这个代码助手真正帮到你日常的编程工作，可以考虑把它集成到VS Code这样的编辑器里。

安装VS Code的Continue扩展，然后在设置中配置本地模型：

{
  "continue.models": [
    {
      "title": "Qwen2.5-Coder-1.5B",
      "provider": "ollama",
      "model": "qwen2.5-coder:1.5b"
    }
  ]
}

配置好后，你可以在写代码时直接让AI助手帮你补全代码、解释代码或者重构代码。

6.3 性能优化建议

如果你经常使用这个模型，可以考虑下面这些优化：

1. 模型量化：将模型转换成4位或8位精度，可以显著减少内存占用，速度损失不大。
2. 使用GGUF格式：GGUF格式的模型通常优化得更好，在某些硬件上运行更快。
3. 批处理请求：如果需要处理多个相似的请求，可以一次性提交，比一个个处理要快。
4. 缓存机制：对于常见的问题，可以把答案缓存起来，避免重复生成。

7. 总结

走完这一整套流程，你应该已经成功在Windows 11上部署了Qwen2.5-Coder-1.5B模型。回顾一下，整个过程其实并不复杂：检查硬件、搭建Python环境、下载模型、测试运行，遇到问题就按我们提到的方法解决。

这个1.5B的模型虽然不大，但对于日常的代码生成、代码解释和简单调试任务来说，已经足够用了。特别是如果你刚开始接触AI编程助手，用它来练手是个不错的选择——对硬件要求低，响应速度也还可以接受。

实际用下来，我感觉它在生成Python、JavaScript等常见语言的代码时表现最好，对于复杂的算法问题也能给出基本正确的实现。当然，它偶尔也会犯错，生成的代码可能需要你稍微调整一下，但这不正是我们学习的机会吗？

如果你刚开始接触本地部署AI模型，我建议先从简单的任务开始，比如让它帮你写一些工具函数、解释你不理解的代码片段。熟悉了之后，再尝试更复杂的场景。记住，好的提示词往往能带来更好的结果，多试试不同的提问方式，你会逐渐找到窍门的。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。