好的，这确实是一次非常典型且充满学习价值的实践过程。将这些经历整理成博客，可以帮助很多遇到类似问题的人。

这是一份为你整理的Markdown格式的博客文章草稿，你可以直接复制使用，或者根据自己的风格进行修改。

---

从 pip not found 到 VLLM 成功运行的全程实录

前言

大家好！今天我想分享一次我部署本地大模型的完整经历。我的目标是在我的Windows电脑上，通过WSL2（Ubuntu）环境，使用ModelScope下载模型，并用VLLM框架来启动一个本地的API服务。整个过程一波三折，我几乎遇到了所有新手可能会踩的坑：从环境配置、网络问题，到最后的显存不足。这篇博客记录了每一个问题和它的解决方案，希望能为同样走在这条路上的朋友们提供一份避坑指南。

我的环境:

• 操作系统: Windows 11
• 虚拟环境: WSL2 (Ubuntu 24.04)
• GPU: NVIDIA GeForce RTX 2060 (6GB 显存)
• 核心框架: ModelScope, VLLM

第一章：基础环境的“下马威” - command not found

一切始于一条简单的安装命令。我信心满满地在全新的WSL2终端里敲下：

Bash

pip install modelscope

结果，终端无情地给了我一记“重击”：

Command 'pip' not found, did you mean: ...

问题诊断:

这是一个典型的环境问题。一个纯净的、新安装的Ubuntu系统，默认可能并没有安装Python的包管理工具pip。

解决方案:

使用Ubuntu自带的包管理器apt来安装pip。

Bash

# 1. 首先更新软件包列表，这是一个好习惯
sudo apt update

# 2. 安装pip
sudo apt install python3-pip

第二章：网络，永远的“拦路虎”

pip安装好后，我以为可以一帆风顺了，但当我尝试安装其他依赖时，又遇到了新的挑战。apt命令在下载软件包时，出现了大量的网络错误。

Connection timed out [IP: ...]

Failed to fetch http://archive.ubuntu.com/...

紧接着，在后面使用pip安装Python库时，也遇到了同样的网络超时问题。

问题诊断:

无论是apt的官方软件源，还是pip的PyPI官方源，它们的服务器都在国外。在国内或网络不佳的地区访问，速度极慢且非常不稳定，导致下载频繁失败。

解决方案:

为apt和pip分别更换为国内的镜像源。

1. 更换 apt 镜像源 (以阿里云为例):

备份并编辑/etc/apt/sources.list文件，将其中的内容全部替换为国内镜像站提供的配置。

2. 更换 pip 镜像源:

• 临时更换: 在安装命令后加上-i参数。 Bash

  pip install vllm -i https://mirrors.aliyun.com/pypi/simple/
  

• 永久配置 (推荐): 创建并编辑 ~/.config/pip/pip.conf 文件，一劳永逸。 Ini, TOML

  [global]
  index-url = https://mirrors.aliyun.com/pypi/simple/
  

经验之谈: 对于国内开发者来说，配置国内镜像是进行任何开发工作之前都应该做的第一步。

第三章：硬件的“灵魂拷问” - GPU显存不足

在解决了所有环境和网络问题后，我终于成功安装了VLLM，并下载了Qwen/Qwen3-4B模型，准备启动服务。我运行了启动命令，但现实再次给了我沉重一击。

第一次失败：模型太大，显存直接“爆了”

我尝试加载4B参数的Qwen模型，VLLM在加载完权重后直接报错。

ValueError: No available memory for the cache blocks.

model weights take 7.56GiB

问题诊断:

我的RTX 2060只有6GB物理显存，而未经量化的4B模型需要至少7.56GB显存才能装下。显卡“爆了”。

解决方案:

承认硬件的极限，换一个小一点的模型。

第二次失败：模型能装下，但“活动空间”不够

我采纳了建议，换用了Qwen/Qwen3-1.7B模型，并设置了--max-model-len 8192。这次模型成功加载了（仅需约3.2GB），但我又遇到了新的错误。

ValueError: The model's max seq len (8192) is larger than the maximum number of tokens that can be stored in KV cache (6848).

问题诊断:

这次模型本身是装进去了，但是加载后，剩余的显存不足以为8192这么长的上下文提供足够的KV Cache（模型的“短期记忆”空间）。

解决方案:

错误日志本身就给出了答案：decreasing 'max_model_len'（降低最大序列长度）。我将参数修改为--max-model-len 4096，问题解决！

第四章：终获成功！启动与调用

在经历了九九八十一难后，我最终选择了更小的Qwen/Qwen2-0.5B-Instruct模型（在后续的日志中显示为qwen_0.6b），并使用了合理的参数，终于看到了成功的曙光！

第一步：激活虚拟环境

您需要先激活 modelscope_env 这个环境。您当前在 (base) 环境下，需要切换过去。

1. 首先，确保您在 my_modelscope 目录下。如果不在，请返回：

   Bash

   cd ~/my_modelscope/
   

2. 然后，执行激活命令：

   Bash

   source modelscope_env/bin/activate
   

3. 激活成功后，您命令行的提示符会从 (base) 变为 (modelscope_env)。

第二步：检查 vllm 安装信息

在 (modelscope_env) 环境激活的状态下，使用以下命令来查看 vllm 包的详细信息：

Bash

pip show vllm

• 如果 vllm 已安装：该命令会显示 vllm 的版本、摘要以及最重要的 Location (位置)。这个位置（通常在 .../modelscope_env/lib/pythonX.X/site-packages 目录下）就是 vllm 代码库的实际部署位置。

• 如果 vllm 未安装：系统会提示 "Package(s) not found: vllm"。

最终成功的启动命令:

Bash

CUDA_VISIBLE_DEVICES=0 python -m vllm.entrypoints.openai.api_server \
--model ./qwen_0.6b \
--tensor-parallel-size 1 \
--port 8102 \
--max-model-len 4096 

终端最后打印出以下日志，宣告服务的正式启动：

INFO: Application startup complete.

成功调用API:

服务启动后，我打开一个新的终端，使用curl成功调用了本地的API服务，并获得了模型的回应。

Bash

curl http://localhost:8102/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "./qwen_0.6b",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己。"}
    ]
  }'

看到模型返回的JSON数据，我长舒一口气，这次折腾终于画上了圆满的句号。