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

[微软技术分享]

在大模型落地场景中，本地轻量化部署因低延迟、高隐私性、无需依赖云端算力等优势，成为开发者与 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 执行以下命令完成模型下载。

• 文件地址：https://www.modelscope.cn/models/Qwen/Qwen2.5-1.5B-Instruct-GGUF/files

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

# 下载 Qwen2.5-1.5B-Instruct-GGUF 完整仓库模型文件
C:> 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 模型文件
C:> 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同级目录下，同时打开命令行工具，执行启动命令：

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

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

# 执行驱动GPU加速版服务端
C:> 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，正常输出示例如下，代表本地大模型服务部署完成，可以对外提供推理服务。

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