Skip to main content

Llama.cpp 使用入门

概述​

Open WebUI 提供了一种简单且灵活的方式来连接和管理本地 Llama.cpp 服务器，从而运行高效的量化语言模型。无论您是自己编译了 Llama.cpp 还是使用预编译的二进制文件，本指南都将引导您完成以下操作：

  • 设置您的 Llama.cpp 服务器
  • 在本地加载大型模型
  • 与 Open WebUI 集成以获得无缝界面

让我们开始吧！

第 1 步：安装 Llama.cpp​

要在 Llama.cpp 中运行模型，您首先需要在本地安装 Llama.cpp 服务器。

您可以选择：

安装完成后，请确保 llama-server 在您的本地系统路径中可用，或者记下它的位置。

第 2 步：下载支持的模型​

您可以使用 Llama.cpp 加载并运行各种 GGUF 格式的量化大语言模型 (LLM)。一个令人印象深刻的例子是由 UnslothAI 优化的 DeepSeek-R1 1.58-bit 模型。要下载此版本：

  1. 访问 Hugging Face 上的 Unsloth DeepSeek-R1 仓库
  2. 下载 1.58-bit 量化版本 —— 大约 131GB。

或者，使用 Python 进行编程下载：


# pip install huggingface_hub hf_transfer

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id = "unsloth/DeepSeek-R1-GGUF",
    local_dir = "DeepSeek-R1-GGUF",
    allow_patterns = ["*UD-IQ1_S*"],  # 仅下载 1.58-bit 变体
)

这将把模型文件下载到如下目录：

DeepSeek-R1-GGUF/
└── DeepSeek-R1-UD-IQ1_S/
    ├── DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf
    ├── DeepSeek-R1-UD-IQ1_S-00002-of-00003.gguf
    └── DeepSeek-R1-UD-IQ1_S-00003-of-00003.gguf

📍 请记下第一个 GGUF 文件的完整路径 —— 您在第 3 步中会用到它。

第 3 步：使用 Llama.cpp 提供模型服务​

使用 llama-server 二进制文件启动模型服务器。导航到您的 llama.cpp 文件夹（例如 build/bin）并运行：

./llama-server \
  --model /您的/模型文件/完整路径/DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf \
  --port 10000 \
  --ctx-size 1024 \
  --n-gpu-layers 40

🛠️ 根据您的机器调整参数：

  • --model: 您的 .gguf 模型文件的路径
  • --port: 10000（或选择另一个空闲端口）
  • --ctx-size: Token 上下文长度（如果 RAM 允许可以增加）
  • --n-gpu-layers: 卸载到 GPU 的层数，以获得更快的性能

服务器运行后，它将在以下地址暴露一个本地 OpenAI 兼容的 API：

http://127.0.0.1:10000

第 4 步：将 Llama.cpp 连接到 Open WebUI​

要直接从 Open WebUI 控制和查询本地运行的模型：

  1. 在浏览器中打开 Open WebUI。
  2. 转到 ⚙️ 管理员设置 → 外部集成 → OpenAI。
  3. 点击 ➕ 添加连接。
  4. 进行如下设置：
    • API 基础 URL: http://127.0.0.1:10000/v1 (如果是通过 Docker 运行 Open WebUI，请改用 http://host.docker.internal:10000/v1)
    • API 密钥: no-key (Llama.cpp 默认不需要密钥)
  5. 点击 验证连接 (Verify Connection)。

Llama.cpp OpenAI 连接设置

第 5 步：查看对话效果​

连接成功后，您可以从模型选择器中选择该模型并开始对话！

模型对话预览

恭喜！您现在正通过 Open WebUI 直接在本地硬件上运行世界上最先进的量化模型之一。🚀