跳到主要内容

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 /your/full/path/to/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
提示

Open WebUI 还为实现了该规范的提供商提供了实验性的 Open Responses 规范支持。

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

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

  1. 在浏览器中打开 Open WebUI
  2. 转到 ⚙️ 管理员设置 → 外部连接 → OpenAI。
  3. 点击 ➕ 添加连接。
  4. 填入以下内容（如果选项卡可见，则在 Standard / Compatible 选项下）：
    • URL: http://127.0.0.1:10000/v1 （如果是在 Docker 容器内运行 Open WebUI，请使用 http://host.docker.internal:10000/v1。请注意末尾的 /v1！）
    • API Key: none（如果配置了特定密钥，请填写，否则留空）
    • 提供商: 从 提供商 下拉菜单中选择 llama.cpp。这将解锁模型选择器中的已加载模型指示器以及管理员的 卸载 (Eject) 按钮——参见下面的 卸载已加载的模型。如果您不需要此功能，请保持为 Default。

💡 保存后，Open WebUI 将开始使用您的本地 Llama.cpp 服务器作为后端！

连接超时配置

如果您的 Llama.cpp 服务器初始化缓慢或者您看到了超时错误，可以增加模型列表获取的超时时间：

# 为较慢的模型加载增加超时时间（默认是 10 秒）
AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=30

如果您保存了一个无法访问的 URL 并导致 UI 变得无响应，请参阅 模型列表加载问题 故障排除指南。

Llama.cpp Connection in Open WebUI

卸载已加载的模型​

一旦模型被 llama-server 实例加载到内存中，Open WebUI 会在模型选择器中用绿色的 “Loaded” 指示器标记它。管理员还可以在行上看到一个 卸载（Eject） 按钮，以便在不重启服务器的情况下卸载模型——它会调用 POST /api/models/unload，从而在兼容 OpenAI 连接的根 URL 上触发 Llama.cpp 的 POST /models/unload 端点。

为了让此功能正常工作，在 管理员设置 → 外部连接 → OpenAI 中匹配的连接的 提供商 必须设置为 llama.cpp（Open WebUI 使用此提示来选择正确的卸载机制）。在管理员尝试卸载模型时，保持默认的“兼容 OpenAI”提供商类型的连接会返回错误。

小贴士：通过对话界面体验模型​

连接成功后，从 Open WebUI 对话菜单中选择该模型并开始互动！

Model Chat Preview

准备就绪！​

配置完成后，Open WebUI 可以帮您轻松：

  • 管理和切换由 Llama.cpp 提供服务的本地模型
  • 使用无需 API Key 的兼容 OpenAI 的 API
  • 直接在您的计算机上体验像 DeepSeek-R1 这样的庞大模型！

🚀 祝您在实验和构建中获得乐趣！

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.