安装

相关源文件

• .devops/nix/devshells.nix
• .devops/nix/docker.nix
• .devops/nix/jetson-support.nix
• .devops/nix/nixpkgs-instances.nix
• .devops/nix/package-gguf-py.nix
• .devops/nix/package.nix
• .devops/nix/python-scripts.nix
• .devops/nix/scope.nix
• .devops/nix/sif.nix
• .github/actions/get-tag-name/action.yml
• .github/actions/windows-setup-cuda/action.yml
• .github/workflows/build.yml
• .github/workflows/release.yml
• cmake/common.cmake
• common/CMakeLists.txt
• flake.lock
• flake.nix
• ggml/CMakeLists.txt
• ggml/cmake/common.cmake
• ggml/src/CMakeLists.txt
• ggml/src/ggml-cpu/CMakeLists.txt
• ggml/src/ggml-cpu/ggml-cpu-aarch64.cpp
• ggml/src/ggml-cpu/ggml-cpu-impl.h
• ggml/src/ggml-cpu/ggml-cpu-quants.c
• ggml/src/ggml-cpu/ggml-cpu.c
• ggml/src/ggml-cpu/kleidiai/kernels.cpp
• ggml/src/ggml-cpu/kleidiai/kernels.h
• ggml/src/ggml-cpu/kleidiai/kleidiai.cpp
• ggml/src/ggml-cpu/kleidiai/kleidiai.h
• tests/CMakeLists.txt

本页面介绍了如何使用可用的构建系统从源代码构建和安装 llama.cpp。有关安装后的基本用法信息，请参阅 基本用法。有关构建系统实现的详细信息，请参阅 构建系统。

概述

llama.cpp 提供了多种构建方法，以支持不同的平台、硬件加速后端和可重现性要求。主要的构建系统使用 CMake，并提供广泛的跨平台支持，而 Nix 提供可重现的构建，Docker 则支持容器化部署。

构建系统架构

该构建系统通过模块化架构支持多种硬件加速后端和平台。

来源： CMakeLists.txt1-50 ggml/CMakeLists.txt1-50 ggml/src/CMakeLists.txt1-50 flake.nix1-50

先决条件

系统依赖项

平台	必填	可选
Linux	build-essential, cmake, git	libcurl4-openssl-dev, pkg-config
macOS	Xcode Command Line Tools, cmake	curl (通过 Homebrew)
Windows	Visual Studio 2019+, cmake	Ninja, Git

特定于硬件的依赖项

后端	依赖项	CMake 选项
CUDA	CUDA Toolkit 11.7+	GGML_CUDA=ON
Metal	macOS 10.15+, Xcode	GGML_METAL=ON
Vulkan	Vulkan SDK	GGML_VULKAN=ON
SYCL	Intel oneAPI DPC++	GGML_SYCL=ON
ROCm	ROCm 5.0+	GGML_HIP=ON

来源： .github/workflows/build.yml126-131 .github/workflows/build.yml290-296 .github/workflows/build.yml380-407

CMake 构建系统

基本构建流程

标准 CMake 构建遵循此工作流程。

基本构建命令

关键 CMake 配置选项

选项	默认	描述
GGML_NATIVE	ON	启用原生 CPU 优化
GGML_BACKEND_DL	OFF	将后端构建为动态库
GGML_CPU_ALL_VARIANTS	OFF	构建多个 CPU 变体
LLAMA_BUILD_SERVER	ON	构建 HTTP 服务器
LLAMA_CURL	ON	启用 cURL 支持
BUILD_SHARED_LIBS	特定于平台	构建共享库

来源： ggml/CMakeLists.txt78-82 ggml/CMakeLists.txt134-153 CMakeLists.txt45-60

平台特定安装

Linux

CI 构建演示了标准的 Linux 构建过程。

对于 GPU 支持，需要额外的依赖项。

来源： .github/workflows/build.yml126-138 .github/workflows/build.yml290-303

macOS

macOS 构建使用 Accelerate 框架和可选的 Metal。

来源： .github/workflows/build.yml47-56 .github/workflows/build.yml500-515

Windows

Windows 构建支持 MSVC 和 MinGW。

来源： .github/workflows/build.yml662-677 .github/workflows/build.yml777-779

Nix 构建系统

可复现构建

Nix 提供确定性的、可重现的构建，具有适当的依赖项管理。

Nix 包变体

该 flake 提供多种包变体。

包配置

Nix 包通过函数参数支持广泛的配置。

参数	类型	描述
useCuda	bool	启用 CUDA 支持
useVulkan	bool	启用 Vulkan 支持
useRocm	bool	启用 ROCm 支持
useBlas	bool	使用系统 BLAS
enableCurl	bool	启用 HTTP 支持
enableStatic	bool	静态链接

来源： flake.nix157-172 .devops/nix/package.nix21-44 .devops/nix/package.nix168-197

Docker 安装

预构建的镜像

Docker 镜像通过 Nix 基础架构构建。

容器化构建

用于容器化开发

来源： .devops/nix/docker.nix10-25 .devops/nix/scope.nix38-39

构建验证

测试安装

构建完成后，使用测试套件验证安装。

后端验证

测试硬件加速后端。

来源： .github/workflows/build.yml140-144 tests/CMakeLists.txt160-162

故障排除

常见构建问题

问题	解决方案
CMAKE_CUDA_ARCHITECTURES 未设置	指定目标 GPU 架构：-DCMAKE_CUDA_ARCHITECTURES=75
缺少 SSSE3 支持	使用 -DGGML_NATIVE=OFF 禁用原生优化。
Vulkan 验证错误	安装 Vulkan SDK 并设置 VULKAN_SDK 环境变量
未找到 Metal 着色器	启用嵌入： -DGGML_METAL_EMBED_LIBRARY=ON

调试版本

为开发启用调试版本

来源： ggml/CMakeLists.txt84-95 .github/workflows/build.yml157-210