llama.cpp RPC-server Docker镜像

项目源码托管于GitHub。

本项目基于llama.cpp构建，仅编译了RPC服务器及运行在RPC客户端模式的辅助工具，这些工具是实现分布式推理GGUF格式大语言模型(LLMs)和嵌入模型的必要组件。

镜像概述

使用RPC服务器的应用架构如下：

!架构图

除llama-server外，还可使用标准容器包中包含的llama-cli或llama-embedding。

Docker镜像支持以下架构：

• 仅CPU - amd64、arm64、arm/v7
• CUDA - amd64

目前arm64架构的CUDA构建因错误失败，暂被禁用。

核心功能与特性

• 分布式推理支持：通过RPC协议实现大语言模型和嵌入模型的分布式推理
• 多运行模式：支持server（服务端）、backend（后端节点）和none三种运行模式
• 多架构兼容：覆盖主流CPU架构（amd64/arm64/arm/v7）及amd64架构的CUDA加速
• 灵活资源配置：可通过环境变量配置内存/显存分配、模型路径、重复惩罚等参数
• 完整工具链：包含llama-server、llama-cli、llama-embedding等客户端工具

使用场景与适用范围

• 需构建分布式LLM推理系统，利用多节点CPU/GPU资源
• 需要部署GGUF格式大语言模型（如Llama系列、TinyLlama等）的场景
• 开发基于RPC协议的LLM推理应用，需服务端与客户端分离架构
• 资源受限环境下，通过多节点协同提升推理性能

环境变量配置

使用方法与部署示例

docker-compose部署示例

以下示例启动llama-server（容器main），并初始化模型TinyLlama-1.1B-q4_0.gguf（需预先下载至与docker-compose.yml同级的./models目录）。./models目录将挂载到容器内/app/models路径。

version: "3.9"

services:

  main:
    image: evilfreelancer/llama.cpp-rpc:latest
    restart: unless-stopped
    volumes:
      - ./models:/app/models
    environment:
      # 运行模式（API服务器格式的RPC客户端）
      APP_MODE: server
      # 容器内预加载的模型权重路径
      APP_MODEL: /app/models/TinyLlama-1.1B-q4_0.gguf
      # 客户端将交互的RPC服务器地址
      APP_RPC_BACKENDS: backend-cuda:50052,backend-cpu:50052
    ports:
      - "127.0.0.1:8080:8080"

  backend-cpu:
    image: evilfreelancer/llama.cpp-rpc:latest
    restart: unless-stopped
    environment:
      # 运行模式（RPC服务器）
      APP_MODE: backend
      # RPC服务器可用的系统内存量（兆字节）
      APP_MEM: 2048

  backend-cuda:
    image: evilfreelancer/llama.cpp-rpc:latest-cuda
    restart: "unless-stopped"
    environment:
      # 运行模式（RPC服务器）
      APP_MODE: backend
      # RPC服务器可用的GPU内存量（兆字节）
      APP_MEM: 1024
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [ gpu ]

推理请求示例

启动后可通过以下HTTP请求进行推理：

curl \
    --request POST \
    --url http://localhost:8080/completion \
    --header "Content-Type: application/json" \
    --data '{"prompt": "构建网站可以通过10个简单步骤完成："}'