Windows 环境下 Llama.cpp 编译与运行指南

llama.cpp 是一套轻量级开源大模型推理引擎，支持在普通消费级硬件完成大模型本地推理，无需高性能显卡即可运行 GGUF 量化模型。本文面向 Windows 平台开发者，完整介绍环境准备、源码编译、魔搭社区下载 GGUF 量化模型、命令行交互、llama‑server API 服务部署全过程，并提供原生 Python 接口调用示例，帮助读者快速搭建属于自己的本地大模型推理服务。

在大模型落地场景中，本地轻量化部署因低延迟、高隐私性、无需依赖云端算力等优势，成为开发者与 AI 爱好者的热门需求。本文聚焦 Windows 环境，详细拆解 llama.cpp 工具的编译流程，并指导如何通过 modelscope 下载 GGUF 格式的模型，最终实现模型本地启动与 API 服务搭建。

1、编译源码之前需要自行安装 Visual Studio 18 2026 开发工具，并打开VS2026 x64 兼容工具命令提示，执行如下命令克隆仓库。

Microsoft Visual Studio 18.0> git clone https://github.com/ggml-org/llama.cpp
Microsoft Visual Studio 18.0> mkdir build
Microsoft Visual Studio 18.0> cd build

2、基础编译（仅 CPU 支持）或者选用GPU 加速编译（已安装 CUDA Toolkit）版。

如果只使用 CPU 模式则执行如下配置

Microsoft Visual Studio 18.0> cmake .. -G "Visual Studio 18 2026" -A x64 -DLLAMA_CURL=OFF
Microsoft Visual Studio 18.0> cmake --build . --config Release

如果已安装 CUDA Toolkit 工具包，则添加 -DLLAMA_CUDA=ON 开启 GPU 加速支持

Microsoft Visual Studio 18.0> cmake .. -G "Visual Studio 18 2026" -A x64 -DLLAMA_CUDA=ON
Microsoft Visual Studio 18.0> cmake --build . --config Release

编译完成后则会在build目录生成对应的可执行文件，其中的llama-server.exe则为主程序

3、下载 GGUF 格式的模型权重文件，模型权重已同步上线两大主流渠道，开发者任选其一即可。

• HuggingFace：https://huggingface.co/models
• 魔搭社区：https://www.modelscope.cn/models

以魔搭社区为例，直接使用官方PIP包拉取仓库内容到本地，下载后的保存位置为 C:\Users\Admin\dir 执行以下命令完成模型下载。

• 文件地址：qwen2.5-1.5b-instruct-q4_k_m.gguf

# 安装魔搭
CMD> pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple modelscope

# 下载 Qwen2.5-1.5B-Instruct-GGUF 完整仓库模型文件
CMD> modelscope download --model Qwen/Qwen2.5-1.5B-Instruct-GGUF

# 下载 Qwen2.5-1.5B-Instruct-GGUF 仓库下 qwen2.5-1.5b-instruct-q4_k_m.gguf 模型文件
CMD> modelscope download --model Qwen/Qwen2.5-1.5B-Instruct-GGUF qwen2.5-1.5b-instruct-q4_k_m.gguf --local_dir ./dir

4、将下载好的qwen2.5-1.5b-instruct-q4_k_m.gguf模型文件，放在llama-server.exe同级目录下，同时打开命令行工具，执行启动命令：

# 执行命令行启动
CMD> chcp 65001
CMD> llama-cli.exe -m qwen2.5-1.5b-instruct-q4_k_m.gguf -c 4096

# 执行启动CPU版本服务端
CMD> llama-server.exe -m qwen2.5-1.5b-instruct-q4_k_m.gguf --host 127.0.0.1 --port 11433 -c 4096

# 执行启动GPU加速版服务端
CMD> llama-server.exe -m qwen2.5-1.5b-instruct-q4_k_m.gguf --host 127.0.0.1 --port 11433 -c 1024 --n-gpu-layers 32

5、直接调用 /completion 接口，原生Python标准库，无需额外第三方包，验证服务可用性。

import json
from urllib import request, error

url = "http://127.0.0.1:11433/completion"
headers = {"Content-Type": "application/json"}

prompt = """<|im_start|>user
你好，简单介绍一下自己<|im_end|>
<|im_start|>assistant
"""

data = {
    "model": "qwen2.5-1.5b-instruct-q4_k_m.gguf",
    "prompt": prompt,
    "temperature": 0.7,
    "max_tokens": 512,
    "ctx_size": 4096,
    "stop": ["<|im_end|>"],
    "stream": False
}

try:
    data_json = json.dumps(data).encode("utf-8")
    req = request.Request(url, data=data_json, headers=headers, method="POST")
    with request.urlopen(req, timeout=60) as response:
        result = json.loads(response.read().decode("utf-8"))

    print("生成结果：")
    print(result["content"].strip())

except error.HTTPError as e:
    print(f"调用失败（HTTP错误）：{e.code} - {e.reason}")
except error.URLError as e:
    print(f"调用失败（连接/网络错误）：{e.reason}")
except Exception as e:
    print(f"调用失败（其他异常）：{e}")

运行main.py，正常输出示例如下，代表本地大模型服务部署完成，可以对外提供推理服务。

CMD> python main.py
生成结果：
您好！我是来自阿里巴巴的AI助手，我叫通义千问。