代码收藏家 从零开始到基于docker容器和llama.cpp/llama-cpp-python部署大模型的简易教程
引言：在本地开发大模型应用和部署大模型服务时，为了方便对环境进行隔离和管理，通常会使用docker容器部署服务，而如果像在docker容器中使用gpu推理模型，需要进行相应的配置，在此以ubuntu24.04为例，介绍一下过程：
1、安装cuda和nvidia驱动
这个网上教程很多，例如：
https://blog.csdn.net/weixin_43656336/article/details/125851441
2、安装docker
卸载老版本docker
$ apt-get remove docker docker-engine docker.io containerd runc
如果不能正常卸载，出现如下情况，显示无权限时，需要添加管理员权限才可进行卸载：
我们就需要使用sudo apt-get remove docker docker-engine docker.io containerd runc命令使用root权限来进行卸载。
安装步骤
- 更新软件包
sudo apt update
sudo apt upgrade
2、安装docker依赖
apt-get install ca-certificates curl gnupg lsb-release
3、添加Docker官方GPG密钥
curl -fsSL http://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo apt-key add -
4、添加Docker软件源
sudo add-apt-repository "deb [arch=amd64] http://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable"
5、安装docker
执行以下命令来安装Docker:
apt-get install docker-ce docker-ce-cli containerd.io
#### 运行docker
启动`docker`来验证我们是否成功安装。命令如下：
```javascript
systemctl start docker
重启docker
service docker restart
验证是否成功
sudo docker run hello-world
查看docker版本
sudo docker version
上面我们拉取了hello-world的镜像，现在我们可以通过命令来查看镜像，命令如下：
sudo docker images
国内访问docker很慢，或者无法访问docker hub，因此需要配置镜像，下列是我的配置，大家可以参考
docker配置镜像源
vi /etc/docker/daemon.json
# 内容如下：
{
"registry-mirrors": [
"https://x14v2w5r.mirror.aliyuncs.com",
"http://f1361db2.m.daocloud.io",
"https://registry.docker-cn.com",
"http://hub-mirror.c.163.com",
"https://docker.mirrors.ustc.edu.cn"
]
}
# 退出并保存
:wq
# 使配置生效
systemctl daemon-reload
# 重启Docker
systemctl restart docker
ubuntu子系统，需要额外操作：
3、安装docker cuda toolkit
笔者在安装docker cuda toolkit过程中遇到一些问题，记录：
待填坑。。。
4、下载模型文件
国内环境下推荐两个网站：
1、Huggningface镜像站 hf-mirror https://hf-mirror.com
使用步骤如下：
a) 安装git-fls
sudo apt-get install git-lfs
b)确认git-lfs是否安装
git lfs install
c)执行安装语句（使用hf-mirror镜像网站）
git clone https://hf-mirror.com/Qwen/Qwen2-1.5B-Instruct
如果用这种方式无法下载，或比较慢，可使用huggingface-cli命令下载：
使用huggingface-cli的前提是安装了git-lfs:
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs
安装好git-lfs后，再安装huggingface_hub
pip install -U huggingface_hub -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com
随后写入镜像文件：
# 建议将上面这一行写入 ~/.bashrc。若没有写入，则每次下载时都需要先输入该命令
export HF_ENDPOINT=https://hf-mirror.com
#windows
$env:HF_ENDPOINT = "https://hf-mirror.com" # 暂时不知如何使用
此时，可以用huggningface-cli命令下载模型：
#命令行下载
huggingface-cli download --resume-download meta-llama/Llama-2-13b-chat-hf
#下载时指定保存目录
huggingface-cli download --resume-download meta-llama/Llama-2-13b-chat-hf --local-dir Llama-2-13b-chat-hf
2、魔搭 modelscope：https://www.modelscope.cn/home
笔者最近喜欢使用这个工具下载，速度贼快，可以直接找到模型下载路径,wget 模型链接，或者使用modelscope 命令行下载工具下载：
先通过如下命令安装ModelScope
pip install modelscope
下载完整模型repo
modelscope download --model ZhipuAI/glm-4-voice-9b
下载单个文件到指定本地文件夹（以下载README.md到当前路径下“dir”目录为例）
modelscope download --model ZhipuAI/glm-4-voice-9b README.md -
建议找模型的时候尽量找gguf模型，4bit-6bit的量化版本，易于推理
5、安装模型推理工具
5.1 使用llama.cpp
llama.cpp是一个大模型推理平台，可以运行gguf格式的量化模型，并使用C++加速模型推理，使模型可以运行在小显存的gpu上，甚至可以直接纯cpu推理，token数量也可以达到四五十每秒（8核16线程，使用qwen2.5-1.5b模型），另外，该平台几乎兼容所有主流模型。再另，根据笔者浅薄的个人经验，在相同的硬件条件下，llama.cpp的推理速度比ollama快很多（纯cpu）。
llama.cpp的仓库地址如下，推荐大家好好阅读下官方文档，这个项目超棒的：
https://github.com/ggerganov/llama.cpp
回到文章主线，我们想要构建一个可以使用gpu推理大语言模型的docker容器，那么就需要先构建一个拥有cuda和相关依赖的镜像。
llama.cpp官方提供了构建docker镜像的dockerfile文件，笔者选用server版本进行演示，该版本将自动部署一个openai兼容的服务器，可以和oneapi、simaple-one-api等工具结合进行openai式的模型key管理。文件内容如下：
ARG UBUNTU_VERSION=22.04
# This needs to generally match the container host's environment.
ARG CUDA_VERSION=12.6.0
# Target the CUDA build image
ARG BASE_CUDA_DEV_CONTAINER=nvidia/cuda:${CUDA_VERSION}-devel-ubuntu${UBUNTU_VERSION}
# Target the CUDA runtime image
ARG BASE_CUDA_RUN_CONTAINER=nvidia/cuda:${CUDA_VERSION}-runtime-ubuntu${UBUNTU_VERSION}
FROM ${BASE_CUDA_DEV_CONTAINER} AS build
# CUDA architecture to build for (defaults to all supported archs)
ARG CUDA_DOCKER_ARCH=default
RUN apt-get update && \
apt-get install -y build-essential git cmake libcurl4-openssl-dev
WORKDIR /app
COPY . .
# Use the default CUDA archs if not specified
RUN if [ "${CUDA_DOCKER_ARCH}" != "default" ]; then \
export CMAKE_ARGS="-DCMAKE_CUDA_ARCHITECTURES=${CUDA_DOCKER_ARCH}"; \
fi && \
cmake -B build -DGGML_CUDA=ON -DLLAMA_CURL=ON ${CMAKE_ARGS} -DCMAKE_EXE_LINKER_FLAGS=-Wl,--allow-shlib-undefined . && \
cmake --build build --config Release --target llama-server -j$(nproc)
FROM ${BASE_CUDA_RUN_CONTAINER} AS runtime
RUN apt-get update && \
apt-get install -y libcurl4-openssl-dev libgomp1 curl
COPY --from=build /app/build/ggml/src/libggml.so /libggml.so
COPY --from=build /app/build/src/libllama.so /libllama.so
COPY --from=build /app/build/bin/llama-server /llama-server
# Must be set to 0.0.0.0 so it can listen to requests from host machine
ENV LLAMA_ARG_HOST=0.0.0.0
HEALTHCHECK CMD [ "curl", "-f", "http://localhost:8080/health" ]
ENTRYPOINT [ "/llama-server" ]
将上述内容保存为llama-server-cuda文件，并在文件目录下执行以下命令：
docker build -t llama.cpp:server-cuda -f llama-server-cuda .
docker build成功后，将在本地生成一个镜像，名为llama.cpp:server-cuda，其中，llama.cpp为镜像名，server-cuda为tag，随后，运行一个该镜像的容器实例：
docker run --gpus all -v /path/to/models:/models llama.cpp:server-cuda -m /models/7B/ggml-model-q4_0.gguf --port 8000 --host 0.0.0.0 -n 512 --n-gpu-layers 1
其中，各参数作用简单介绍如下：
—gpus all：使用所有gpu，可使用–gpus 指定gpu推理
-v /path/to/models:/models ：表示 把宿主机的/path/to/models路径挂载到容器的/models路径，
-m /models/7B/ggml-model-q4_0.gguf ：指定gguf模型的路径为 /models/7B，模型文件名为ggml-model-q4_0.gguf，
–port 8000：指定服务器的工作端口为8000
–host 0.0.0.0 ：指定服务器监听所有网络接口的连接请求
-n 512 代表模型生成内容的最大token数
–n-gpu-layers 1：指定使用多少层神经网络模型在GPU上执行计算，根据gpu显存大小可适当调大
值得注意的是，笔者使用了为了命名简洁，修改了镜像名和文件名（有点点强迫症，不喜欢太长的命名…），如有困惑，或想了解其他版本，敬请阅读官方文档：
https://github.com/ggerganov/llama.cpp/blob/master/docs/docker.md
这样，你就可以访问http://127.0.0.1:8000，从而可以直接和你部署的模型对话，因为llama.cpp的server提供了一个c++的前端，你可以在该界面修改参数、增加提示词，以和模型交互
实际上，docker run默认是bridge的网络模式，因此需要手动把服务器的端口暴露出来，比如使用-p 8080:8000，就是把容器的8000端口映射到宿主机的8080端口，也可以设置网络为host模式，经笔者踩坑发现，在某些环境中，host模式的容器才可与外界正常通信。
另外，如果想要把本地局域网服务器的服务暴露给外网访问，需要使用工具进行内网穿透，再买个域名自己解析一下就更好了，这部分内容笔者也有所研究，如果读者感兴趣，笔者后续可以更新我的踩坑记录。
5.2 使用llama-cpp-python官方提供的dockerfile
llama-cpp-python是基于llama.cpp的python绑定，相比于llama.cpp，它更为易用，提供了llama.cpp暂未支持的函数调用功能，这意味着您可以使用llama-cpp-python的openai兼容的服务器构建自己的AI tools。
不仅如此，他还兼容llamaindex，支持多模态模型推理。
llama-cpp-python docker的使用方式与llama.cpp类似，Dockrefile文件内容如下：
ARG CUDA_IMAGE="12.5.0-devel-ubuntu22.04"
FROM nvidia/cuda:${CUDA_IMAGE}
# We need to set the host to 0.0.0.0 to allow outside access
ENV HOST 0.0.0.0
RUN apt-get update && apt-get upgrade -y \
&& apt-get install -y git build-essential \
python3 python3-pip gcc wget \
ocl-icd-opencl-dev opencl-headers clinfo \
libclblast-dev libopenblas-dev \
&& mkdir -p /etc/OpenCL/vendors && echo "libnvidia-opencl.so.1" > /etc/OpenCL/vendors/nvidia.icd
COPY . .
# setting build related env vars
ENV CUDA_DOCKER_ARCH=all
ENV GGML_CUDA=1
# Install depencencies
RUN python3 -m pip install --upgrade pip pytest cmake scikit-build setuptools fastapi uvicorn sse-starlette pydantic-settings starlette-context
# Install llama-cpp-python (build with cuda)
RUN CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python
# Run the server
CMD python3 -m llama_cpp.server
保存为Dockerfile文件，随后使用docker built构建docker镜像，镜像名为cuda_simple，随后docker run 运行：
docker build -t cuda_simple .
docker run --gpus=all --cap-add SYS_RESOURCE -e USE_MLOCK=0 -e MODEL=/var/model/<model-path> -v <model-root-path>:/var/model -t cuda_simple
先这样吧，如果有人看，我再考虑多更新一些自己踩过的坑
作者：不良少年。
