Phi-3-mini-128k-instruct部署教程：Ubuntu 22.04 + NVIDIA驱动 + vLLM全兼容指南

想在自己的服务器上跑一个又快又好的大语言模型，但又担心配置复杂、资源消耗大？今天，我们就来搞定一个轻量级的明星选手——Phi-3-mini-128k-instruct。它只有38亿参数，但能力却相当能打，最关键的是，它对硬件的要求非常友好。

这篇教程，我会带你从零开始，在Ubuntu 22.04系统上，一步步完成从NVIDIA驱动安装、CUDA环境配置，到使用vLLM高效部署Phi-3-mini模型，最后用Chainlit搭建一个简洁好用的聊天前端。整个过程清晰明了，即使你是第一次接触模型部署，也能跟着做下来。

我们的目标是：让你在半小时内，拥有一个属于你自己的、响应迅速的AI对话助手。

1. 环境准备：打好地基

在开始部署模型之前，我们需要确保服务器有一个坚实可靠的基础环境。这主要包括操作系统、显卡驱动和深度学习框架所依赖的CUDA工具包。

1.1 系统与硬件要求

首先，确认你的机器满足以下基本条件：

• 操作系统：Ubuntu 22.04 LTS。这是目前最稳定且对深度学习生态支持最好的Linux发行版之一。
• 显卡：至少一张NVIDIA GPU。显存建议8GB或以上，例如RTX 3070、RTX 4060 Ti或更高规格的显卡。Phi-3-mini模型本身不大，但足够的显存能保证更长的对话上下文（128K）流畅运行。
• 网络：需要能顺畅访问GitHub和Hugging Face等资源站，用于下载模型和依赖包。

打开终端，先更新一下系统软件包列表是个好习惯：

sudo apt update && sudo apt upgrade -y

1.2 安装NVIDIA显卡驱动

显卡驱动是GPU工作的基础。在Ubuntu上，我们有几种安装方法，这里推荐使用系统自带的ubuntu-drivers工具，它能自动检测并安装合适的驱动。

1. 首先，添加官方的NVIDIA驱动PPA仓库，以获取最新版本的驱动：

   sudo add-apt-repository ppa:graphics-drivers/ppa -y
   sudo apt update
   

2. 查看系统推荐的显卡驱动版本：

   ubuntu-drivers devices
   

   你会看到类似下面的输出，其中标有“recommended”的就是推荐安装的版本。

   == /sys/devices/pci0000:00/0000:00:01.0/0000:01:00.0 ==
   modalias : pci:v000010DEd00002504sv00001458sd000040B3bc03sc00i00
   vendor   : NVIDIA Corporation
   model    : GA104 [GeForce RTX 3070]
   driver   : nvidia-driver-535-server - distro non-free
   driver   : nvidia-driver-535 - distro non-free
   driver   : nvidia-driver-545 - third-party non-free
   driver   : nvidia-driver-550 - third-party non-free
   driver   : nvidia-driver-470 - distro non-free
   driver   : nvidia-driver-470-server - distro non-free
   driver   : nvidia-driver-545-server - third-party non-free
   driver   : xserver-xorg-video-nouveau - distro free builtin
   

3. 安装推荐的驱动（例如nvidia-driver-550）：

   sudo apt install nvidia-driver-550 -y
   

4. 安装完成后，必须重启系统以使驱动生效：

   sudo reboot
   

5. 重启后，再次登录系统，在终端输入以下命令验证驱动是否安装成功：

   nvidia-smi
   

   如果看到类似下图的信息，显示了GPU型号、驱动版本、CUDA版本以及GPU的使用情况，那就恭喜你，驱动安装成功了！这里显示的CUDA版本是驱动支持的最高版本，我们接下来需要安装匹配的CUDA Toolkit。

1.3 安装CUDA Toolkit与cuDNN

CUDA是NVIDIA推出的并行计算平台，cuDNN是针对深度神经网络的GPU加速库。vLLM的运行依赖于它们。

1. 访问NVIDIA CUDA Toolkit Archive，找到与你的驱动兼容的版本。根据上面nvidia-smi显示的CUDA版本（例如12.4），选择相同或更低主版本的CUDA Toolkit（例如12.4）。这里我们以CUDA 12.4为例。
2. 按照官网给出的Ubuntu 22.04安装指令执行即可。通常是一系列wget下载和sudo dpkg -i安装命令。
3. 安装完成后，将CUDA路径添加到环境变量中。编辑你的shell配置文件（如~/.bashrc）：

   echo 'export PATH=/usr/local/cuda-12.4/bin:$PATH' >> ~/.bashrc
   echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
   source ~/.bashrc
   

4. 验证CUDA安装：

   nvcc --version
   

   此命令应输出你安装的CUDA编译器版本信息。
5. cuDNN的安装相对简单，从NVIDIA开发者网站下载对应CUDA 12.4的cuDNN Local Installer for Linux (x86_64)的Debian包，然后用dpkg命令安装。

至此，基础环境就全部准备好了。接下来，我们将进入核心环节——部署模型推理服务。

2. 使用vLLM部署Phi-3-mini模型

vLLM是一个高性能、易用的大语言模型推理和服务引擎。它的核心特点是使用了PagedAttention注意力算法，能极大地提高显存利用率和推理速度，特别适合用于部署像Phi-3-mini这样的模型并提供API服务。

2.1 创建Python虚拟环境

为了避免不同项目间的Python包版本冲突，我们使用conda或venv创建一个独立的虚拟环境。这里以venv为例。

# 安装python3-venv工具包（如果尚未安装）
sudo apt install python3.10-venv -y
# 创建一个名为‘phi3-env’的虚拟环境
python3 -m venv phi3-env
# 激活虚拟环境
source phi3-env/bin/activate

激活后，你的命令行提示符前会出现(phi3-env)字样。

2.2 安装vLLM及相关依赖

在虚拟环境中，使用pip安装vLLM。vLLM会自动处理与CUDA版本的兼容性问题。

# 升级pip
pip install --upgrade pip
# 安装vLLM。这将自动安装PyTorch等核心依赖。
pip install vllm
# 安装额外的工具包，用于模型下载和Web服务
pip install huggingface-hub fastapi uvicorn

2.3 下载Phi-3-mini-128k-instruct模型

模型可以从Hugging Face模型库下载。我们可以编写一个简单的Python脚本来自动完成。

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

from huggingface_hub import snapshot_download

model_id = "microsoft/Phi-3-mini-128k-instruct"
local_dir = "./phi-3-mini-128k-instruct"

# 下载模型文件到本地目录
snapshot_download(repo_id=model_id, local_dir=local_dir, local_dir_use_symlinks=False)
print(f"模型已下载至: {local_dir}")

然后运行这个脚本：

python download_model.py

下载时间取决于你的网络速度，模型大小约为8GB。

2.4 启动vLLM OpenAI兼容的API服务器

vLLM最方便的一点是，它提供了一个与OpenAI API格式完全兼容的服务器。这意味着任何兼容OpenAI的客户端（包括我们后面要用的Chainlit）都可以直接调用它。

使用以下命令启动服务器：

python -m vllm.entrypoints.openai.api_server \
    --model ./phi-3-mini-128k-instruct \  # 指定本地模型路径
    --served-model-name phi-3-mini \       # 服务名称，客户端调用时使用
    --api-key token123456 \                # 设置一个简单的API密钥（可选，用于基础验证）
    --port 8000                            # 指定服务端口

命令参数说明：

• --model: 指定我们刚才下载的模型目录路径。
• --served-model-name: 给这个部署的模型起个名字，客户端通过这个名字调用。
• --api-key: 设置一个API密钥，虽然不是强安全措施，但可以防止服务被随意调用。
• --port: 服务监听的端口号，默认为8000。

执行命令后，你会看到大量输出，vLLM开始加载模型到GPU显存中。当看到类似"Uvicorn running on http://0.0.0.0:8000"的信息时，说明服务器已成功启动。

如何确认服务部署成功？ 你可以新建一个终端窗口，使用curl命令快速测试：

curl http://localhost:8000/v1/models

如果返回一个包含"phi-3-mini"模型的JSON信息，就证明API服务运行正常。你也可以查看服务进程的日志输出，确认没有报错信息。

3. 使用Chainlit构建聊天前端

模型服务在后台跑起来了，但我们还需要一个好看的界面来和它对话。Chainlit是一个专门为构建大模型应用而设计的框架，可以快速创建出类似ChatGPT的Web界面。

3.1 安装与配置Chainlit

在同一个虚拟环境中，安装Chainlit：

pip install chainlit

Chainlit应用的核心是一个Python脚本。创建一个名为app.py的文件，内容如下：

import chainlit as cl
from openai import OpenAI

# 配置OpenAI客户端，指向我们本地运行的vLLM服务器
client = OpenAI(
    base_url="http://localhost:8000/v1",  # vLLM OpenAI API 地址
    api_key="token123456"                  # 与启动服务器时设置的api-key一致
)

@cl.on_message
async def main(message: cl.Message):
    """
    处理用户消息的主函数。
    """
    # 创建一个消息对象，用于在UI上显示“思考中”
    msg = cl.Message(content="")
    await msg.send()

    # 调用本地的vLLM API
    response = client.chat.completions.create(
        model="phi-3-mini",  # 与 --served-model-name 一致
        messages=[
            {"role": "system", "content": "你是一个乐于助人的AI助手。"},
            {"role": "user", "content": message.content}
        ],
        temperature=0.7,  # 控制创造性，值越高回答越随机
        stream=True       # 启用流式输出，实现打字机效果
    )

    # 流式接收并显示回复
    for chunk in response:
        if chunk.choices[0].delta.content is not None:
            await msg.stream_token(chunk.choices[0].delta.content)

    # 流式传输完成，更新消息状态
    await msg.update()

这个脚本做了几件事：

1. 导入Chainlit和OpenAI库。
2. 创建一个OpenAI客户端，但把请求地址改成了我们本地的vLLM服务器（http://localhost:8000/v1）。
3. 定义了一个main函数来处理用户发送的每一条消息。
4. 在函数内部，它构造了一个请求发送给vLLM，其中包含了系统指令和用户问题。
5. 使用stream=True参数让回复以流式方式传回，并在Chainlit界面上逐字显示出来，体验更好。

3.2 启动Chainlit应用

在终端中，运行以下命令启动Chainlit应用：

chainlit run app.py -w --port 7860

参数说明：

• run app.py: 运行我们刚创建的脚本。
• -w: 启用自动重载，当你修改app.py文件后，服务会自动重启。
• --port 7860: 指定前端界面的访问端口。

启动成功后，终端会输出一个URL，通常是http://localhost:7860。在你的浏览器中打开这个地址。

3.3 与你的AI助手对话

现在，你应该能看到一个干净、现代的聊天界面了。

1. 在底部的输入框里，尝试问它一些问题，比如：“用Python写一个快速排序函数”或者“解释一下量子计算的基本概念”。
2. 按下回车或点击发送，你会看到界面顶部显示“思考中…”，然后答案会像打字一样一个个字符地出现。
3. 得益于vLLM的高效推理和Phi-3-mini模型的轻量化，响应速度通常会非常快。

至此，你已经成功搭建了一个完整的、本地部署的AI对话系统。你可以随时在浏览器里和它聊天，而所有的数据和处理都在你自己的服务器上，无需担心隐私问题。

4. 总结

回顾一下，我们完成了从零到一部署Phi-3-mini-128k-instruct模型的完整旅程：

1. 环境搭建：我们在Ubuntu 22.04上安装了合适的NVIDIA驱动、CUDA和cuDNN，为GPU计算准备好了舞台。
2. 模型服务部署：利用vLLM推理引擎，我们以OpenAI兼容的API形式启动了Phi-3-mini模型。vLLM的PagedAttention技术确保了即使在长上下文下也能高效、节省显存地运行。
3. 前端界面构建：通过Chainlit，我们用不到50行代码就创建了一个具有流式输出效果的Web聊天界面，提供了出色的交互体验。

这个组合（Ubuntu + vLLM + Chainlit）是一个非常强大且实用的技术栈。它不仅适用于Phi-3-mini，你也可以用同样的方法部署其他来自Hugging Face的模型，比如Llama、Qwen等。

下一步你可以尝试：

• 调整模型参数：在app.py中修改temperature、max_tokens等参数，观察对回答创造性和长度的影响。
• 尝试不同模型：将download_model.py和启动命令中的模型路径换成其他模型，体验不同模型的能力。
• 添加额外功能：利用Chainlit的 callback 和 element 功能，为前端添加文件上传、代码高亮、对话历史管理等功能。

希望这篇教程能帮你顺利开启本地大模型应用的大门。动手实践的过程中如果遇到问题，耐心查看终端日志，它们通常能给出最直接的错误线索。祝你玩得开心！

---

获取更多AI镜像

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