本地大模型推理系统完整部署（本地模型 + vLLM + Agent）

Bonnienienie
4 阅读5分钟

本地大模型推理系统完整部署（本地模型 + vLLM + Agent）

📝 整体架构

[模型层]     [本地模型文件]            职责：提供参数（不运行）
                  ↓
[推理层]     [vLLM 推理服务]  ← GPU    职责：加载模型 + 提供API
                  ↓  HTTP(OpenAI API)
[应用层]     [Agent]                  职责：调度任务、调用LLM

🔧 标准流程

下载模型（离线）
启动 vLLM（加载本地模型） 
验证 API 
配置 Agent 
Agent 调用 vLLM

✅ 一、环境

  • 硬件要求：
组件    	要求
GPU       推荐 3090（24GB）
显存     	≥ 16GB（7B模型）
  • 验证GPU：
nvidia-smi
  • 软件要求
  • Docker
  • NVIDIA
  • Container Toolkit CUDA 驱动

镜像容器的使用，详见👉 服务器Docker实例化容器 -- 踩坑大全

✅ 二、准备模型（核心👀）

举例模型（适合3090）：

Qwen2.5-7B-Instruct   ✅（主力）
Qwen2.5-3B-Instruct   ✅（保底）

执行：

pip install huggingface_hub

huggingface-cli download Qwen/Qwen2.5-7B-Instruct \
  --local-dir /data/your_project/models/qwen2.5-7b

📁 最终结构：

/data/your_project/models/
    └── qwen2.5-7b/
         ├── config.json
         ├── tokenizer.json
         ├── model.safetensors

📦 下载模型可能遇到的报错/问题：

👉报错1.遇到的错误 TypeError: Typer.__init__() got an unexpected keyword argument 'suggest_commands'通常是因为 typer 库的版本不兼容导致的。这个错误与 huggingface_hub 的使用无关，而是 typer 的一个已知问题，尤其是在较新版本中移除了 suggest_commands 参数。 可以尝试以下方法解决：（推荐方法2 (●'◡'●)）

方法一：降级 typer 版本 执行以下命令，将 typer 降级到兼容的版本（如 0.4.1）：

pip install typer==0.4.1

方法二：升级 huggingface_hub 和 typer 确保你使用的是最新版本的 huggingface_hub 和 typer，以避免版本冲突：

pip install --upgrade huggingface_hub typer

方法三：使用 huggingface-cli 下载模型 如果你仍然希望使用命令行下载模型，可以使用 huggingface-cli 命令，例如：

huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir /data/your_project/models/qwen2.5-7b

注意：huggingface-cli 是 huggingface_hub 包的一部分，需要先安装 huggingface_hub。

如需进一步确认是否是 typer 版本问题，可以运行以下命令查看当前版本：

pip show typer

如果版本高于 0.4.1，建议降级以避免该错误。

👉报错2.当你在尝试从 Hugging Face 下载模型 Qwen/Qwen2.5-7B-Instruct 时遇到 huggingface_hub.errors.LocalEntryNotFoundError: Got: ConnectError: [Errno 101] Network is unreachable错误，这通常意味着你的系统无法连接到互联网，或者网络配置存在问题，导致无法访问 Hugging Face 的服务器。

解决： 1️⃣ 检查网络连接‌： 确保你的设备可以正常访问互联网。你可以通过 ping 或 curl 命令测试网络连通性，例如：

ping huggingface.co

如果无法 ping 通，可能是网络配置或防火墙限制了访问。

2️⃣ 使用国内镜像源加速下载‌： 由于 Hugging Face 官方服务器可能在国内访问受限，建议使用国内镜像站点来加速下载。例如，可以使用阿里云提供的 Hugging Face 镜像服务：

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

3️⃣ 然后再执行下载命令：

hf download Qwen/Qwen2.5-7B-Instruct --local-dir /data/your_project/models/qwen2.5-7b

💡 ‌预防措施‌

  • 使用稳定的网络环境‌：建议在服务器或网络稳定的环境中下载大模型
  • 分片下载‌：对于超大模型，可以考虑分片下载
  • ‌使用国内源‌：在中国大陆地区强烈推荐使用镜像源
  • ‌监控下载进度‌：可以使用 htop 或 nethogs 监控下载状态

✅ 三、启动 vLLM 推理服务

💡 理解vLLM的作用 核心作用在于提升大语言模型在 GPU 上运行的效率，特别适用于需要处理大量并发请求或对延迟敏感的应用场景。

vLLM 的主要功能和优势 👇

  • ‌高速令牌生成‌：vLLM 采用连续批处理技术，显著提升令牌生成速度。
  • ‌高效内存管理‌：通过 PagedAttention 技术，vLLM 能够有效控制 GPU 内存消耗，即使在处理长上下文窗口时也能保持良好的性能。
  • ‌支持高并发与大规模部署‌：vLLM 优化了多卡并行和动态批处理，适合构建高性能的 AI 服务，例如实时对话系统或 API 服务。
  • ‌兼容性强‌：vLLM 与主流深度学习平台（如 PyTorch、TensorFlow）兼容，易于融入现有的 AI 工作流程。
  • ‌OpenAI API 兼容‌：vLLM 支持 OpenAI 接口，使得开发者可以轻松将模型集成到现有应用中。

不用折腾 Ollama 咧 😆

博主这里服务器上已存在 vLLM Docker 镜像，因此直接创建容器并运行 😆 1️⃣ 启动命令（标准版）

docker run -d \ 
	--gpus all \ 
	--name vllm-server \ 
	-p 8000:8000 \ 
	-v /data/your_project/models:/models \ 
	vllm/vllm-openai:latest \ 
	--model /models/qwen2.5-7b \

🔍 参数解释：

参数作用
--gpus all使用 GPU
-p 8000:8000暴露 API
vllm-openaiOpenAI兼容接口
--model你加载的模型
--gpu-memory-utilization 0.9控制模型推理过程中 GPU 显存的使用比例,默认值为 0.9，即 90% 的显存被用于推理任务，剩余 10% 保留给系统开销（如 CUDA 上下文、驱动程序、其他进程等）
--max-model-len 4096上下文窗口的大小

2️⃣ 验证 vLLM 是否成功

curl http://127.0.0.1:8000/v1/models

成功返回：

{
  "data": [
    {"id": "/models/qwen2.5-7b"}
  ]
}

3️⃣ 让你的容器访问 vLLM 前面已经把 vLLM 服务跑起来了，但现在只是宿主机能访问（127.0.0.1:8000），如果你还有其他容器（比如 FastAPI / RAG 服务），默认是访问不到的，这一步就是把它们打通 👇 🧠 方式一：使用 Docker 网络（推荐） 这是最干净、最稳定的方式 👍 ① 创建一个共享网络

docker network create llm-net

② 启动 vLLM 时加入网络

docker run -d \
  --gpus all \
  --name vllm-server \
  --network llm-net \
  -p 8000:8000 \
  -v /data/your_project/models:/models \
  vllm/vllm-openai:latest \
  --model /models/qwen2.5-7b

③ 启动你的业务容器（例如 FastAPI）

docker run -d \
  --name my-api \
  --network llm-net \
  -p 9016:9016 \
  your_image_name

④ 容器内访问方式 在你的 API 服务代码中，把地址改成：http://vllm-server:8000/v1 👉 注意： ❌ 不要再用 127.0.0.1 ❌ 不要用宿主机 IP ✅ 直接用容器名 vllm-server

🧠 方式二：用宿主机IP（通用） 👉 查宿主机IP：

ip addr

比如：192.168.1.100 👉 在容器里：

curl http://192.168.1.100:8000/v1/models

👉 环境变量：

LOCAL_LLM_URL=http://192.168.1.100:8000/v1

🥇🥇🥇 完结撒花 o(￣▽￣)ブ

avatar
文章
阅读
粉丝