通义千问1.5-1.8B-Chat-GPTQ-Int4在VSCode中的开发环境配置指南

最近在折腾一些本地大模型，发现通义千问1.5-1.8B-Chat的GPTQ-Int4量化版本是个挺有意思的“小钢炮”。模型不大，但对硬件要求友好，在消费级显卡上就能跑起来，特别适合在本地做点小实验或者学习大模型推理。

不过，刚开始用的时候，我发现虽然模型本身跑起来了，但在VSCode里写代码调用它的时候，体验总有点磕磕绊绊。要么是代码提示不灵光，要么是调试起来不方便。所以，我花了一些时间，把整个开发环境好好配置了一番，现在用起来顺手多了。

今天这篇文章，我就把自己这套配置流程完整地分享出来。如果你也想在VSCode里舒舒服服地开发和调试这个模型，跟着下面的步骤走一遍，应该能帮你省下不少折腾的时间。

1. 准备工作：理清思路与检查清单

在动手配置之前，我们先花两分钟把要做的事情和需要的东西理清楚。这样后面操作起来才不会手忙脚乱。

首先，你得确保模型本身已经能在你的机器上正常运行。这篇文章的重点是“开发环境配置”，而不是“模型部署”。所以，我默认你已经按照官方文档或相关教程，成功下载并加载了Qwen1.5-1.8B-Chat-GPTQ-Int4这个模型。如果你还没走到这一步，建议先完成模型的基础部署。

接下来，我们配置环境的目标很明确，就是让VSCode成为我们调用和测试这个模型的得力助手。具体来说，我们希望达到三个效果：

  1. 智能代码提示：写代码调用模型时，VSCode能自动提示相关的函数、参数和类名，不用老去翻文档。
  2. 顺畅的调试体验：可以方便地设置断点、单步执行，查看模型推理过程中变量（比如生成的tokens）的变化。
  3. 便捷的运行与测试：能快速运行单个脚本，或者针对不同的输入进行测试，而不用反复在终端里敲命令。

你需要准备的东西很简单：

  • 一台已经安装了Python（建议3.8以上版本）和VSCode的电脑。
  • 一个能正常加载上述通义千问模型的Python环境（通常是一个独立的conda或venv虚拟环境）。
  • 基础的Python和深度学习库（如PyTorch、Transformers）应该已经安装好了。

好了，思路理清了，清单也列好了，我们这就开始动手。

2. 核心步骤：一步步搭建舒适环境

配置过程可以分成几个清晰的阶段，我们按顺序来，遇到问题也不用慌，后面有专门的章节帮你解决。

2.1 第一步：创建并关联专属的Python环境

这是最重要的一步，目的是让VSCode知道我们想用哪个Python环境来运行和调试代码。

首先，打开你的终端（比如VSCode内置的终端，或者系统自带的命令行），激活你用来运行通义千问模型的那个Python虚拟环境。如果你用的是conda，命令大概是 conda activate your_env_name；如果是venv，在Windows上是 your_env_path\Scripts\activate，在Mac/Linux上是 source your_env_path/bin/activate。

激活环境后，在终端里输入 python -c "import sys; print(sys.executable)"。这个命令会打印出当前Python解释器的完整路径，把它记下来。

然后，在VSCode里打开你的项目文件夹。按下 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（Mac）打开命令面板，输入并选择 Python: Select Interpreter。

这时，VSCode会列出它找到的所有Python解释器。你应该能在列表里看到刚才记下的那个路径（或者以你环境名称为标识的选项），选中它。选好后，你可以在VSCode窗口的左下角看到当前使用的Python环境已经切换过来了。

2.2 第二步：安装必备的VSCode插件

光有Python解释器还不够，我们需要几个插件来增强功能。打开VSCode的扩展市场（左侧边栏的方块图标）。

第一个必装的是官方的 Python 插件，由Microsoft发布。它提供了代码补全、 linting、调试等核心功能。安装后可能需要重新加载一下窗口。

第二个强烈推荐的是 Pylance。它是Python的语言服务器，能提供更强大、更准确的代码补全和类型提示。安装完Python插件后，它通常会作为推荐插件出现，直接安装即可。安装后，你可以在VSCode的设置（settings.json）里确认一下是否已将语言服务器设置为Pylance。

// 在 settings.json 中添加或检查
{
    "python.languageServer": "Pylance"
}

对于深度学习开发，Jupyter 插件也很有用，尤其当你喜欢用Notebook做快速实验和原型验证时。虽然我们主要写.py脚本，但有个Jupyter环境备用会很方便。

2.3 第三步：配置调试与运行任务

现在环境关联好了，插件也齐了，我们来配置怎么方便地运行和调试代码。

配置调试（Debugging） 在项目根目录下，VSCode会自动生成一个 .vscode 文件夹，里面存放配置文件。如果没有，你可以手动创建一个。

在 .vscode 文件夹里，创建一个名为 launch.json 的文件。这个文件告诉VSCode如何启动调试器。一个针对Python脚本的简单配置如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 调试当前文件",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": false // 如果你想深入跟踪到第三方库（如transformers）内部，可以设为false
        }
    ]
}

保存后，打开一个调用通义千问模型的Python脚本，在代码行号旁边点击就可以设置断点。然后点击VSCode左侧的“运行和调试”图标，选择刚才配置好的 Python: 调试当前文件，再点击绿色的播放按钮，就可以开始调试了。你可以查看变量、单步执行，观察模型生成文本的过程。

配置运行任务（Tasks） 除了调试，我们经常需要直接运行脚本。你可以配置一个运行任务。在 .vscode 文件夹下创建 tasks.json 文件：

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "运行当前Python脚本",
            "type": "shell",
            "command": "${config:python.pythonPath}", // 或直接写你的python解释器路径
            "args": ["${file}"],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "presentation": {
                "reveal": "always",
                "panel": "shared"
            }
        }
    ]
}

配置好后，按 Ctrl+Shift+B 就可以直接运行当前打开的Python文件了，结果会显示在终端里。

2.4 第四步：优化代码提示与类型感知

为了让代码补全更“懂”我们用的模型，可以进行一些优化。Pylance依赖于类型存根（stub files）来提供更好的提示。对于像Transformers这样的库，其类型提示通常已经包含在库中了。

但是，如果你在代码中通过字符串名称（如 "Qwen/Qwen1.5-1.8B-Chat-GPTQ-Int4"）加载模型，Pylance可能无法直接推断出返回的模型对象的具体类型。这时，你可以使用类型注释来帮助它。

在你的模型加载代码附近，可以这样写：

from transformers import AutoModelForCausalLM, AutoTokenizer
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # 这里是为了给代码分析工具看的，不会实际执行
    from transformers import PreTrainedModel, PreTrainedTokenizerFast

# 实际加载代码
model_name = "Qwen/Qwen1.5-1.8B-Chat-GPTQ-Int4"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, device_map="auto")

# 如果你希望有更明确的类型提示，可以（非必须）进行类型断言
# 这不会改变运行时行为，但能让Pylance更开心
model = model # type: PreTrainedModel
tokenizer = tokenizer # type: PreTrainedTokenizerFast

此外，确保你的VSCode设置中启用了类型检查。在设置里搜索 python.analysis.typeCheckingMode，可以将其设置为 basic 或 strict（strict更严格，但可能对现有代码报错较多，建议先从 basic 开始）。

3. 实战演练：编写并运行一个测试脚本

环境配好了，我们写个简单的脚本来测试一下，确保一切工作正常。在你的项目里创建一个新文件，比如叫 test_qwen.py。

# test_qwen.py
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

# 指定模型路径（请确保此路径正确，或者使用HF Hub名称）
model_name = "Qwen/Qwen1.5-1.8B-Chat-GPTQ-Int4"
# 如果你的模型下载在本地，也可以使用本地路径
# model_name = "./path/to/your/local/model"

print(f"正在加载模型和分词器: {model_name}")
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 注意：GPTQ量化模型通常需要 trust_remote_code=True
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16, # 根据你的硬件和模型要求调整
    device_map="auto",         # 自动分配模型层到可用设备（GPU/CPU）
    trust_remote_code=True    # 对于通义千问模型通常是需要的
)
print("模型加载完成！")

# 准备对话
messages = [
    {"role": "system", "content": "你是一个乐于助人的助手。"},
    {"role": "user", "content": "请用一句话介绍一下你自己。"}
]

# 应用聊天模板
text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
model_inputs = tokenizer([text], return_tensors="pt").to(model.device)

# 生成回复
print("正在生成回复...")
with torch.no_grad():
    generated_ids = model.generate(
        **model_inputs,
        max_new_tokens=512,
        do_sample=True,
        temperature=0.6,
        top_p=0.9
    )
generated_ids = [
    output_ids[len(input_ids):] for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids)
]

response = tokenizer.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(f"\n模型回复: {response}")

print("\n测试完成！")

保存这个文件。现在，你可以用我们刚才配置好的方式来运行它：

  • 方法一（调试）：在 print("模型加载完成！") 这一行设个断点，然后按F5启动调试，看看变量加载是否正常。
  • 方法二（直接运行）：确保当前Python环境已选中，直接在文件编辑器内右键，选择“在终端中运行Python文件”，或者按 Ctrl+Shift+B（如果你配置了任务）。

如果一切顺利，你应该能在终端里看到模型加载的日志，并最终看到通义千问模型的一句自我介绍。这证明你的开发环境已经可以正常工作了。

4. 常见问题与解决思路

配置过程中难免会遇到一些小麻烦，这里我整理了几个常见的情况和解决办法。

问题1：VSCode找不到我想要的Python解释器。

  • 检查：首先在终端里确认你的虚拟环境是否已激活，并且 python 命令指向的是正确的环境。
  • 解决：在VSCode的命令面板里，除了选择已发现的解释器，你还可以直接输入路径。点击 Python: Select Interpreter 后，选择 Enter interpreter path...，然后粘贴你之前用 sys.executable 命令获取的完整路径。

问题2：代码提示（补全）对Transformers库不工作或很弱。

  • 检查：确认Pylance插件已安装并启用。查看VSCode底部状态栏，语言服务器是否显示为 Pylance。
  • 解决：尝试在项目根目录下创建一个空的 pyrightconfig.json 文件，或者检查 settings.json 中 python.analysis.extraPaths 设置，确保没有错误地排除了你的site-packages目录。有时候，重启VSCode也能解决临时性的索引问题。

问题3：调试时无法进入（Step Into）Transformers库的内部代码。

  • 检查：launch.json 中的 "justMyCode" 设置。如果为 true，调试器会跳过库代码。
  • 解决：将其设置为 false。请注意，步入大型深度学习库的内部可能会比较慢。更常见的做法是在你自己的代码中设置断点，观察输入输出。

问题4：运行脚本时提示找不到模块（如transformers）。

  • 检查：VSCode左下角显示的当前Python解释器，是否就是你安装了这些包的那个环境。
  • 解决：重新执行 2.1 步骤，确保VSCode关联到了正确的环境。也可以在VSCode的集成终端里，手动 pip install transformers 等缺失的包（确保终端顶部显示的环境前缀是正确的）。

问题5：加载模型时出现关于trust_remote_code的警告或错误。

  • 分析：这是使用通义千问、ChatGLM等一些国内模型时的常见要求，因为它们的模型实现可能不在Transformers库的主干中。
  • 解决：正如我们在测试脚本中做的，在 from_pretrained 方法中明确传入 trust_remote_code=True 参数。请务必只从可信来源加载模型。

如果遇到其他问题，一个很好的排查方法是：先在VSCode外部的系统终端（确保环境已激活）里运行你的脚本。如果外部终端能跑通，那问题就出在VSCode的环境配置上。如果外部终端也报错，那可能是模型、依赖包或系统环境本身的问题。

5. 总结

走完这一套流程，你的VSCode应该已经成为一个相当称手的通义千问模型开发工具了。我们来简单回顾一下关键点：核心是让VSCode精准地绑定到你的模型运行环境；然后通过Python和Pylance插件获得智能编码辅助；接着配置好调试和运行任务，让测试迭代变得高效；最后用一个小脚本验证整个链路是否通畅。

这套配置方法其实不止适用于通义千问这个特定模型，对于其他基于Transformers的本地大模型开发，思路也是相通的。环境配好了，后面无论是想尝试不同的提示词、测试模型性能，还是集成到更大的应用里，都会顺手很多。

刚开始可能会觉得步骤有点多，但配好之后就是一劳永逸的事情。希望这篇指南能帮你扫清环境配置的障碍，让你能把更多精力放在模型本身的应用和探索上。如果在实践中还有更具体的问题，多利用调试功能和终端输出信息，大部分都能找到答案。

获取更多AI镜像

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

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

Gemini3.1Pro中文提示词工程化指南

avatar DeepSeek技术社区
cover

20个Gemini3.1Pro开源项目精选指南

avatar DeepSeek技术社区
cover

学术编辑革命：Gemini3.1Pro重塑论文质检流程

avatar DeepSeek技术社区