跳到主要内容

Llama.cpp

概览​

OPL 数据空间可以很方便地接入和管理本地运行的 Llama.cpp 服务器，让你在本机运行高效的量化模型。无论你是自己编译 Llama.cpp，还是直接使用预编译二进制，本指南都会带你完成：

  • 搭建 Llama.cpp 服务
  • 在本地加载大模型
  • 接入 OPL 数据空间，获得统一聊天界面

第 1 步：安装 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*"],
)

下载后的目录结构大致如下：

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 步：用 Llama.cpp 启动模型服务​

使用 llama-server 启动服务。进入你的 llama.cpp 目录后运行：

./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：上下文长度
  • --n-gpu-layers：卸载到 GPU 的层数

启动后，它会暴露一个本地 OpenAI 兼容 API：

http://127.0.0.1:10000
提示

对于支持该规范的 provider， OPL 数据空间也支持实验性的 Open Responses。

第 4 步：把 Llama.cpp 接入 OPL 数据空间​

  1. 在浏览器中打开 OPL 数据空间。
  2. 前往 ⚙️ 管理设置 → 连接 → OpenAI。
  3. 点击 ➕ 添加连接。
  4. 填入以下内容：
    • URL：http://127.0.0.1:10000/v1 如果 OPL 数据空间跑在 Docker 中，可用 http://host.docker.internal:10000/v1。注意结尾必须带 /v1。
    • API Key：none，或留空

保存后， OPL 数据空间就会把本地 Llama.cpp 服务当成后端来使用。

连接超时配置

如果 Llama.cpp 启动较慢或你遇到超时问题，可以提高模型列表请求超时：

AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=30

如果你保存了一个不可达的 URL，导致设置页都难以打开，可以参考 模型列表加载问题。

Llama.cpp Connection in OPL 数据空间

开始聊天​

连接成功后，在 OPL 数据空间的模型选择器中选中该模型，直接开始聊天即可。

Model Chat Preview

完成​

配置完成后，你就可以：

  • 管理和切换由 Llama.cpp 提供的本地模型
  • 不依赖外部 API Key，直接使用 OpenAI 兼容接口
  • 在自己的机器上实验大型模型，如 DeepSeek-R1