Phi-3-mini-128k-instruct快速部署教程3步搞定Ubuntu环境配置你是不是刚拿到Phi-3-mini-128k-instruct这个模型想在Ubuntu上跑起来试试结果被一堆环境依赖和配置问题搞得头大别担心我之前也踩过不少坑。今天这篇教程就是帮你绕过那些弯路用最直接的方法在10分钟之内把模型部署好让它能正常响应你的指令。这个模型虽然个头不大但能力挺强尤其适合在本地或者云端快速搭建一个智能助手。整个过程其实就三件事准备好系统环境、装好必要的软件包、最后把模型跑起来。我会把每一步的命令和可能遇到的问题都讲清楚你跟着做就行。1. 动手前的准备工作在开始敲命令之前我们先花两分钟看看你的电脑“底子”怎么样。这就像做饭前要检查一下灶台和食材能避免做到一半发现缺东西的尴尬。1.1 检查你的Ubuntu系统首先确保你用的是Ubuntu 18.04或更新的版本。太老的系统可能会缺少一些新的软件库支持。打开终端输入下面这个命令看看lsb_release -a你会看到类似Ubuntu 20.04.6 LTS这样的信息。只要主版本号是18、20、22或者更高就都没问题。1.2 确认Python和Pip模型运行需要Python环境。我们推荐使用Python 3.8到3.11之间的版本。在终端里输入python3 --version pip3 --version如果显示Python 3.10.12和pip 23.0.1之类的信息说明已经装好了。如果没装或者版本不对可以用下面的命令安装或更新sudo apt update sudo apt install python3 python3-pip -y1.3 搞定CUDA驱动如果你有NVIDIA显卡这一步是可选的。如果你有NVIDIA显卡并且想用GPU来加速模型推理那才需要做。如果只用CPU跑可以跳过。检查你的显卡驱动和CUDA版本nvidia-smi这个命令会弹出一个表格右上角会显示CUDA版本比如CUDA Version: 12.1。Phi-3-mini对CUDA版本要求比较宽松11.7以上基本都可以。如果没有这个命令或者提示未找到说明你可能需要安装驱动。一个比较省心的安装方法是使用系统自带的驱动管理工具sudo ubuntu-drivers autoinstall sudo reboot重启后再运行nvidia-smi确认一下。好了准备工作做完你的系统已经就绪。接下来我们进入正题开始安装运行模型所需要的各种“零件”。2. 三步搭建运行环境环境搭建是核心但别怕我把它拆解成了三个非常清晰的步骤。你只要按顺序执行就不会乱。2.1 第一步安装关键的底层工具有些基础工具是后续安装的“脚手架”我们先把它搭好。打开终端一次性执行下面这组命令sudo apt update sudo apt install -y git curl wget build-essential software-properties-commongit用来下载模型代码。curl和wget是下载文件的常用工具。后面几个是编译和安装其他软件时可能需要的开发工具。2.2 第二步创建独立的Python工作空间强烈建议你为这个项目创建一个独立的Python虚拟环境。这就像给你的模型项目一个单独的“房间”里面装的软件包不会和系统里其他项目冲突以后想清理也特别方便。安装创建虚拟环境的工具sudo apt install -y python3-venv python3-dev然后为你这个Phi-3项目创建一个虚拟环境我习惯把它放在项目目录里名字叫venvcd ~ # 可以切换到你想放项目的任何目录 python3 -m venv phi3-env创建好后激活这个环境。激活后你的命令行前面通常会显示环境名(phi3-env)source phi3-env/bin/activate记住以后每次打开新终端想运行这个模型都需要先切换到项目目录然后执行source phi3-env/bin/activate来激活环境。2.3 第三步安装PyTorch和模型依赖现在在这个干净的“房间”里安装最重要的深度学习框架PyTorch。去PyTorch官网根据你的系统选择命令是最准的但这里我给你一个通用的参考如果你有CUDA 12.1的显卡用这个命令pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121如果你只有CPU或者想先确保能跑起来用这个更简单的CPU版本pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu安装完PyTorch接下来安装运行Phi-3-mini模型必需的软件包。我们主要用到transformers和accelerate这两个库前者是加载模型的核心后者能帮助优化运行效率。pip3 install transformers accelerate有时候网络问题可能导致安装慢或失败可以尝试设置国内的镜像源来加速pip3 install transformers accelerate -i https://pypi.tuna.tsinghua.edu.cn/simple到这里所有软件环境就全部配置完成了。是不是比想象中简单我们马上进入最激动人心的环节——请出主角并让它开口说话。3. 下载模型并运行你的第一个对话环境好了模型就好请了。我们直接从公开的模型仓库下载并用几行代码让它运行起来。3.1 下载Phi-3-mini-128k-instruct模型模型文件有点大大概几个GB我们可以用git命令来下载这种方式支持断点续传更稳定。在终端里执行git lfs install git clone https://huggingface.co/microsoft/Phi-3-mini-128k-instruct这个命令会把模型的所有文件包括配置文件和大大的权重文件下载到当前目录下的Phi-3-mini-128k-instruct文件夹里。下载时间取决于你的网速喝杯咖啡等一下。3.2 编写一个最简单的推理脚本模型下载好后我们创建一个Python脚本来调用它。在你项目的目录下和Phi-3-mini-128k-instruct文件夹同级新建一个文件比如叫run_phi3.py然后用文本编辑器打开它把下面的代码贴进去from transformers import AutoModelForCausalLM, AutoTokenizer import torch # 1. 指定模型路径就是刚才下载的文件夹路径 model_path ./Phi-3-mini-128k-instruct # 2. 加载模型的分词器和模型本身 # 这里设置 torch_dtypetorch.float16 可以显著减少内存占用并且大多数GPU支持这种计算更快。 tokenizer AutoTokenizer.from_pretrained(model_path) model AutoModelForCausalLM.from_pretrained( model_path, torch_dtypetorch.float16, # 使用半精度浮点数 device_mapauto, # 自动分配模型层到可用的设备GPU/CPU trust_remote_codeTrue # 信任并执行模型仓库中的自定义代码 ) # 3. 将模型切换到评估模式推理模式 model.eval() # 4. 准备你的问题 prompt 给我写一首关于春天的短诗。 # 按照Phi-3-instruct模型的对话格式组织输入 messages [ {role: user, content: prompt} ] # 5. 将对话格式转换为模型能理解的输入文本 input_text tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) # 6. 将文本转换为模型输入的数字IDToken inputs tokenizer(input_text, return_tensorspt).to(model.device) # 7. 让模型生成回答禁止梯度计算以节省内存 with torch.no_grad(): outputs model.generate( **inputs, max_new_tokens256, # 生成回答的最大长度 do_sampleTrue, # 使用采样使输出更有创造性 temperature0.7, # 采样温度控制随机性0.1-1.0 top_p0.9, # 核采样参数控制输出多样性 ) # 8. 解码并打印模型的回答 # 跳过输入部分只解码新生成的Token generated_ids outputs[:, inputs[input_ids].shape[1]:] response tokenizer.decode(generated_ids[0], skip_special_tokensTrue) print(f模型回答\n{response})3.3 运行脚本查看结果保存好脚本文件。确保你的终端还在虚拟环境(phi3-env)中并且当前目录下有这个脚本和模型文件夹然后运行python3 run_phi3.py第一次运行可能会需要一点时间加载模型到内存。稍等片刻你就能在终端里看到模型生成的关于春天的短诗了。恭喜你你已经成功在Ubuntu上部署并运行了Phi-3-mini模型4. 常见问题与进阶技巧第一次跑通很有成就感但实际使用中你可能会遇到一些小状况。这里我列几个常见的帮你提前扫清障碍。问题一运行脚本时提示CUDA out of memory这说明显卡内存不够了。Phi-3-mini虽然小但在高精度下也需要几个GB的显存。解决办法在加载模型的代码里把torch_dtypetorch.float16改成torch_dtypetorch.float32试试但需要更多内存。更有效的方法是使用accelerate进行CPU卸载或者直接修改脚本在from_pretrained里加上load_in_8bitTrue或load_in_4bitTrue参数来量化加载这能大幅减少内存占用需要先安装bitsandbytes库。问题二下载模型速度太慢或失败除了用git lfs你也可以在Hugging Face页面上手动下载pytorch_model.bin等大文件然后放到对应目录。或者使用一些国内的镜像源。问题三想用更简单的方式部署和管理如果你觉得手动配置环境还是有点麻烦或者希望有更稳定、带图形界面的部署方式可以考虑一些云端的AI平台。这些平台通常提供了预配置好的环境你只需要选择模型镜像点击一下就能运行起来完全不用操心系统依赖和版本冲突。一个实用小技巧调整生成参数上面脚本里的temperature和top_p是控制生成文本“创意度”的关键。temperature温度值越低如0.1输出越确定、保守值越高如1.0输出越随机、有创意。top_p核采样值越低选词范围越小输出更集中值越高选词范围越大输出更多样。 你可以根据任务需要调整它们。比如写代码需要严谨就把温度调低写故事需要创意就把温度调高。整体走一遍下来你会发现部署一个开源大模型并没有那么神秘。核心就是准备环境、安装依赖、加载模型这三板斧。Phi-3-mini这个模型对硬件要求相对友好在消费级显卡甚至CPU上都能跑起来非常适合开发者拿来学习和构建原型。遇到问题别慌大部分都是环境配置或者路径设置的小错误仔细检查一下命令行和脚本里的路径通常就能解决。下一步你可以尝试用Flask或FastAPI给它包一个简单的Web API或者集成到你的其他应用里让它真正为你所用。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
Phi-3-mini-128k-instruct快速部署教程：3步搞定Ubuntu环境配置
发布时间：2026/6/19 11:27:31
Phi-3-mini-128k-instruct快速部署教程3步搞定Ubuntu环境配置你是不是刚拿到Phi-3-mini-128k-instruct这个模型想在Ubuntu上跑起来试试结果被一堆环境依赖和配置问题搞得头大别担心我之前也踩过不少坑。今天这篇教程就是帮你绕过那些弯路用最直接的方法在10分钟之内把模型部署好让它能正常响应你的指令。这个模型虽然个头不大但能力挺强尤其适合在本地或者云端快速搭建一个智能助手。整个过程其实就三件事准备好系统环境、装好必要的软件包、最后把模型跑起来。我会把每一步的命令和可能遇到的问题都讲清楚你跟着做就行。1. 动手前的准备工作在开始敲命令之前我们先花两分钟看看你的电脑“底子”怎么样。这就像做饭前要检查一下灶台和食材能避免做到一半发现缺东西的尴尬。1.1 检查你的Ubuntu系统首先确保你用的是Ubuntu 18.04或更新的版本。太老的系统可能会缺少一些新的软件库支持。打开终端输入下面这个命令看看lsb_release -a你会看到类似Ubuntu 20.04.6 LTS这样的信息。只要主版本号是18、20、22或者更高就都没问题。1.2 确认Python和Pip模型运行需要Python环境。我们推荐使用Python 3.8到3.11之间的版本。在终端里输入python3 --version pip3 --version如果显示Python 3.10.12和pip 23.0.1之类的信息说明已经装好了。如果没装或者版本不对可以用下面的命令安装或更新sudo apt update sudo apt install python3 python3-pip -y1.3 搞定CUDA驱动如果你有NVIDIA显卡这一步是可选的。如果你有NVIDIA显卡并且想用GPU来加速模型推理那才需要做。如果只用CPU跑可以跳过。检查你的显卡驱动和CUDA版本nvidia-smi这个命令会弹出一个表格右上角会显示CUDA版本比如CUDA Version: 12.1。Phi-3-mini对CUDA版本要求比较宽松11.7以上基本都可以。如果没有这个命令或者提示未找到说明你可能需要安装驱动。一个比较省心的安装方法是使用系统自带的驱动管理工具sudo ubuntu-drivers autoinstall sudo reboot重启后再运行nvidia-smi确认一下。好了准备工作做完你的系统已经就绪。接下来我们进入正题开始安装运行模型所需要的各种“零件”。2. 三步搭建运行环境环境搭建是核心但别怕我把它拆解成了三个非常清晰的步骤。你只要按顺序执行就不会乱。2.1 第一步安装关键的底层工具有些基础工具是后续安装的“脚手架”我们先把它搭好。打开终端一次性执行下面这组命令sudo apt update sudo apt install -y git curl wget build-essential software-properties-commongit用来下载模型代码。curl和wget是下载文件的常用工具。后面几个是编译和安装其他软件时可能需要的开发工具。2.2 第二步创建独立的Python工作空间强烈建议你为这个项目创建一个独立的Python虚拟环境。这就像给你的模型项目一个单独的“房间”里面装的软件包不会和系统里其他项目冲突以后想清理也特别方便。安装创建虚拟环境的工具sudo apt install -y python3-venv python3-dev然后为你这个Phi-3项目创建一个虚拟环境我习惯把它放在项目目录里名字叫venvcd ~ # 可以切换到你想放项目的任何目录 python3 -m venv phi3-env创建好后激活这个环境。激活后你的命令行前面通常会显示环境名(phi3-env)source phi3-env/bin/activate记住以后每次打开新终端想运行这个模型都需要先切换到项目目录然后执行source phi3-env/bin/activate来激活环境。2.3 第三步安装PyTorch和模型依赖现在在这个干净的“房间”里安装最重要的深度学习框架PyTorch。去PyTorch官网根据你的系统选择命令是最准的但这里我给你一个通用的参考如果你有CUDA 12.1的显卡用这个命令pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121如果你只有CPU或者想先确保能跑起来用这个更简单的CPU版本pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu安装完PyTorch接下来安装运行Phi-3-mini模型必需的软件包。我们主要用到transformers和accelerate这两个库前者是加载模型的核心后者能帮助优化运行效率。pip3 install transformers accelerate有时候网络问题可能导致安装慢或失败可以尝试设置国内的镜像源来加速pip3 install transformers accelerate -i https://pypi.tuna.tsinghua.edu.cn/simple到这里所有软件环境就全部配置完成了。是不是比想象中简单我们马上进入最激动人心的环节——请出主角并让它开口说话。3. 下载模型并运行你的第一个对话环境好了模型就好请了。我们直接从公开的模型仓库下载并用几行代码让它运行起来。3.1 下载Phi-3-mini-128k-instruct模型模型文件有点大大概几个GB我们可以用git命令来下载这种方式支持断点续传更稳定。在终端里执行git lfs install git clone https://huggingface.co/microsoft/Phi-3-mini-128k-instruct这个命令会把模型的所有文件包括配置文件和大大的权重文件下载到当前目录下的Phi-3-mini-128k-instruct文件夹里。下载时间取决于你的网速喝杯咖啡等一下。3.2 编写一个最简单的推理脚本模型下载好后我们创建一个Python脚本来调用它。在你项目的目录下和Phi-3-mini-128k-instruct文件夹同级新建一个文件比如叫run_phi3.py然后用文本编辑器打开它把下面的代码贴进去from transformers import AutoModelForCausalLM, AutoTokenizer import torch # 1. 指定模型路径就是刚才下载的文件夹路径 model_path ./Phi-3-mini-128k-instruct # 2. 加载模型的分词器和模型本身 # 这里设置 torch_dtypetorch.float16 可以显著减少内存占用并且大多数GPU支持这种计算更快。 tokenizer AutoTokenizer.from_pretrained(model_path) model AutoModelForCausalLM.from_pretrained( model_path, torch_dtypetorch.float16, # 使用半精度浮点数 device_mapauto, # 自动分配模型层到可用的设备GPU/CPU trust_remote_codeTrue # 信任并执行模型仓库中的自定义代码 ) # 3. 将模型切换到评估模式推理模式 model.eval() # 4. 准备你的问题 prompt 给我写一首关于春天的短诗。 # 按照Phi-3-instruct模型的对话格式组织输入 messages [ {role: user, content: prompt} ] # 5. 将对话格式转换为模型能理解的输入文本 input_text tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) # 6. 将文本转换为模型输入的数字IDToken inputs tokenizer(input_text, return_tensorspt).to(model.device) # 7. 让模型生成回答禁止梯度计算以节省内存 with torch.no_grad(): outputs model.generate( **inputs, max_new_tokens256, # 生成回答的最大长度 do_sampleTrue, # 使用采样使输出更有创造性 temperature0.7, # 采样温度控制随机性0.1-1.0 top_p0.9, # 核采样参数控制输出多样性 ) # 8. 解码并打印模型的回答 # 跳过输入部分只解码新生成的Token generated_ids outputs[:, inputs[input_ids].shape[1]:] response tokenizer.decode(generated_ids[0], skip_special_tokensTrue) print(f模型回答\n{response})3.3 运行脚本查看结果保存好脚本文件。确保你的终端还在虚拟环境(phi3-env)中并且当前目录下有这个脚本和模型文件夹然后运行python3 run_phi3.py第一次运行可能会需要一点时间加载模型到内存。稍等片刻你就能在终端里看到模型生成的关于春天的短诗了。恭喜你你已经成功在Ubuntu上部署并运行了Phi-3-mini模型4. 常见问题与进阶技巧第一次跑通很有成就感但实际使用中你可能会遇到一些小状况。这里我列几个常见的帮你提前扫清障碍。问题一运行脚本时提示CUDA out of memory这说明显卡内存不够了。Phi-3-mini虽然小但在高精度下也需要几个GB的显存。解决办法在加载模型的代码里把torch_dtypetorch.float16改成torch_dtypetorch.float32试试但需要更多内存。更有效的方法是使用accelerate进行CPU卸载或者直接修改脚本在from_pretrained里加上load_in_8bitTrue或load_in_4bitTrue参数来量化加载这能大幅减少内存占用需要先安装bitsandbytes库。问题二下载模型速度太慢或失败除了用git lfs你也可以在Hugging Face页面上手动下载pytorch_model.bin等大文件然后放到对应目录。或者使用一些国内的镜像源。问题三想用更简单的方式部署和管理如果你觉得手动配置环境还是有点麻烦或者希望有更稳定、带图形界面的部署方式可以考虑一些云端的AI平台。这些平台通常提供了预配置好的环境你只需要选择模型镜像点击一下就能运行起来完全不用操心系统依赖和版本冲突。一个实用小技巧调整生成参数上面脚本里的temperature和top_p是控制生成文本“创意度”的关键。temperature温度值越低如0.1输出越确定、保守值越高如1.0输出越随机、有创意。top_p核采样值越低选词范围越小输出更集中值越高选词范围越大输出更多样。 你可以根据任务需要调整它们。比如写代码需要严谨就把温度调低写故事需要创意就把温度调高。整体走一遍下来你会发现部署一个开源大模型并没有那么神秘。核心就是准备环境、安装依赖、加载模型这三板斧。Phi-3-mini这个模型对硬件要求相对友好在消费级显卡甚至CPU上都能跑起来非常适合开发者拿来学习和构建原型。遇到问题别慌大部分都是环境配置或者路径设置的小错误仔细检查一下命令行和脚本里的路径通常就能解决。下一步你可以尝试用Flask或FastAPI给它包一个简单的Web API或者集成到你的其他应用里让它真正为你所用。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
