使用 ONNX Runtime 在 CPU 环境下跑本地大模型

Shi Yi2026/8/23aiai onnx

没有显卡也想在本地跑大模型？用 ONNX Runtime + int4 量化模型，纯 CPU 也能跑起 Phi-3.5 Mini 和 Qwen3-4B，分享一下从零搭建的完整流程。

📖 ONNX Runtime 是什么

ONNX Runtime 是微软开源的高性能推理引擎，直接运行 ONNX 格式的模型，Windows / Linux / macOS 都支持，CPU、GPU 通吃。

而 onnxruntime-genai 是它在生成式 AI 场景的封装包，把 tokenizer、KV Cache、采样策略这些麻烦事全包了，几行代码就能和本地大模型对话。

✨ 用它跑本地模型的好处

🖥️ 不需要显卡 —— int4 量化后，4B 级别的模型 CPU 就能跑
📦 部署简单 —— pip 一装就用，不用折腾 CUDA 那一套
🔋 省内存 —— int4 模型体积只有原版的一小部分
🪟 Windows 友好 —— 官方直接支持，开箱即用

🛠️ 环境准备

运行前需要有 Python 环境，推荐 Python 3.12。

安装依赖：

python -m pip install onnxruntime
python -m pip install --pre onnxruntime-genai
python -m pip install huggingface_hub psutil

验证安装：

python -c "import onnxruntime as ort; print(ort.__version__, ort.get_available_providers())"
python -c "import onnxruntime_genai as og; print(og.__version__)"

能正常打印版本号和 provider 列表就说明装好了。

⚙️ 配置 Hugging Face 命令行

下载模型要用 hf 命令。如果提示命令不存在，可以把 Python 的 scripts 目录加进用户 Path：

$scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";" + $scripts,
  "User"
)

验证：

hf --help

📦 下载并运行 Phi-3.5 Mini

先 cd 到你的工作目录，下载微软官方转好的 int4 量化模型：

hf download microsoft/Phi-3.5-mini-instruct-onnx `
  --include "cpu_and_mobile/cpu-int4-awq-block-128-acc-level-4/*" `
  --local-dir models

交互式运行：

python .\outputs\chat_phi35.py `
  --model-path .\models\cpu_and_mobile\cpu-int4-awq-block-128-acc-level-4

也可以单次提问：

python .\outputs\chat_phi35.py `
  --model-path .\models\cpu_and_mobile\cpu-int4-awq-block-128-acc-level-4 `
  --prompt "请介绍一下 ONNX Runtime。" `
  --max-new-tokens 128

TIP

运行 Phi-4 Mini Instruct 也是一样的操作，换一下仓库名和 --model-path 就行。

🔧 运行 Qwen3-4B-Instruct-2507

Qwen 就没那么省心了：原始 Qwen 仓库不能直接交给 ONNX Runtime GenAI，需要先转换为包含 genai_config.json 的模型目录。

先装转换工具：

python -m pip install onnx-ir onnxscript transformers torch

然后用 builder 转换：

python -m onnxruntime_genai.models.builder `
  -m Qwen/Qwen3-4B-Instruct-2507 `
  -o .\models\qwen3-4b-int4 `
  -p int4 `
  -e cpu `
  --extra_options block_size=128 accuracy_level=4 hf_token=false

确认转换结果：

Test-Path .\models\qwen3-4b-int4\genai_config.json

返回 True 就可以跑了：

python .\outputs\chat_phi35.py `
  --model-path .\models\qwen3-4b-int4

WARNING

转换阶段比推理阶段更吃内存，4B 模型转换时建议关掉大型程序，耐心等它跑完。

🩹 常见问题

huggingface-cli 找不到：使用新版命令 hf download ...。

Builder 报 Token required：公开模型转换时增加 --extra_options hf_token=false。

中文输出乱码：在当前 PowerShell 中执行：

$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new()

内存不足：优先关闭浏览器、IDE 和其他模型进程；减少 --max-new-tokens；保持单并发。

📝 总结

CPU 也能跑大模型，关键就是 ONNX Runtime GenAI + int4 量化
Phi 系列官方有转好的 ONNX 模型直接下载，Qwen 要用 builder 自己转
转换比推理更吃内存，机器内存小的话优先注意

TIP

如果想让 GPU 也动起来，把 -e cpu 换成 -e dml（DirectML，A/N/I 卡通吃）并安装 onnxruntime-genai-directml 就行，之后有空再单独写一篇 GPU 篇。

使用 ONNX Runtime 在 CPU 环境下跑本地大模型

ON THIS PAGE