大模型本地化部署指南

• 1. LLM 本地化部署（一）：安装 CUDA 环境
  • 1.1. 安装 CUDA Toolkit
    • 1.1.1. 检查 CUDA 支持
    • 1.1.2. 在线安装（新版本）
    • 1.1.3. 离线安装（旧版本）
      • 1.1.3.1. 下载安装包
      • 1.1.3.2. 环境设置
      • 1.1.3.3. 检查卸载
  • 1.2. 安装 Container Toolkit
    • 1.2.1. 安装 Docker
    • 1.2.2. 安装 container-toolkit
    • 1.2.3. 配置 Docker 运行时
• 2. LLM 本地化部署（二）：安装 Python 环境
  • 2.1. 使用 Conda 虚拟环境
    • 2.1.1. 安装 Anaconda
    • 2.1.2. 解决 GLIBCXX not found 问题
    • 2.1.3. 常用 conda 命令
    • 2.1.4. conda 和 pip 区别
      • 2.1.4.1. 通过 conda 安装
      • 2.1.4.2. 通过 pip 安装包
  • 2.2. 使用 uv 虚拟环境
    • 2.2.1. 安装 uv
    • 2.2.2. 镜像设置
    • 2.2.3. 常用命令
• 3. LLM 本地化部署（三）：安装本地模型推理引擎
  • 3.1. 安装 Transformers 引擎
    • 3.1.1. PyTorch 和 Transformers 关系
    • 3.1.2. 使用 pip 安装 pytorch
    • 3.1.3. 使用 conda 安装 pytorch（不推荐）
    • 3.1.4. 验证 Torch/CUDA 版本
  • 3.2. 安装 llama.cpp 引擎
    • 3.2.1. 安装依赖
    • 3.2.2. 导入 CUDA 环境
    • 3.2.3. 源码编译 llama.cpp
    • 3.2.4. llama.cpp 命令补全
  • 3.3. 安装 vLLM 引擎
• 4. LLM 本地化部署（四）：Transformers 模型量化
  • 4.1. 下载 Transformers 模型
  • 4.2. Transformers 模型转 GGUF 格式
  • 4.3. GGUF 模型量化
  • 4.4. 运行 GGUF 模型
• 5. LLM 本地化部署（五）：安装 xinference 模型推理平台
  • 5.1. 安装 xinference
  • 5.2. 查询模型推理引擎
  • 5.3. 启动和停止模型
  • 5.4. 管理模型
• 6. LLM 本地化部署（六）：安装 Ollama 模型推理平台
  • 6.1. 安装
  • 6.2. 配置
  • 6.3. 自启动
  • 6.4. 卸载
  • 6.5. 导入GGUF模型
    • 6.5.1. 创建 Modelfile 文件
    • 6.5.2. 创建、运行模型

1. LLM 本地化部署（一）：安装 CUDA 环境

1.1. 安装 CUDA Toolkit

1.1.1. 检查 CUDA 支持

首先，确保你的 GPU 支持 CUDA

https://developer.nvidia.com/cuda-gpus

1.1.2. 在线安装（新版本）

https://developer.nvidia.com/cuda-downloads

# cu13.0
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get -y install cuda-toolkit-13-0
sudo apt-get install -y cuda-drivers

注：最新版 cu13 存在非常非常多的兼容问题，大量第三方框架没有适配，不推荐安装。

1.1.3. 离线安装（旧版本）

https://developer.nvidia.com/cuda-toolkit-archive

1.1.3.1. 下载安装包

# cuda 12.9 (ubuntu24.04)
# pytorch 最新稳定版适配到 cu129
# https://pytorch.org/get-started/locally/
wget https://developer.download.nvidia.com/compute/cuda/12.9.1/local_installers/cuda_12.9.1_575.57.08_linux.run
sudo sh cuda_12.9.1_575.57.08_linux.run

# cuda 12.4
# cu124 兼容性最好，但只能在 ubuntu22.4 中安装
wget https://developer.download.nvidia.com/compute/cuda/12.4.1/local_installers/cuda_12.4.1_550.54.15_linux.run
sudo sh cuda_12.4.1_550.54.15_linux.run

注：若第一次安装失败，需重启后再安装。

1.1.3.2. 环境设置

# sudo vim /etc/profile
PATH=$PATH:/usr/local/cuda-12.9/bin
export PATH

1.1.3.3. 检查卸载

nvidia-smi
cuda-uninstaller
nvidia-uninstall

1.2. 安装 Container Toolkit

NVIDIA Container Toolkit 是一组库和实用程序，使用户能够构建和运行 GPU 加速的容器。它目前包括：

• NVIDIA Container Runtime (nvidia-container-runtime)
• NVIDIA Container Toolkit CLI (nvidia-ctk)
• NVIDIA CDI Hooks (nvidia-cdi-hook)
• NVIDIA Container Runtime Hook (nvidia-container-runtime-hook)
• NVIDIA Container CLI (nvidia-container-cli)
• NVIDIA Container Library (libnvidia-container1)

1.2.1. 安装 Docker

https://docs.docker.com/engine/install/ubuntu/

curl https://code.wangyan.cloud/wangyan/docker-compose/raw/branch/main/shell-script/docker-setup-ubuntu-aliyun.sh | bash

1.2.2. 安装 container-toolkit

https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

1.2.3. 配置 Docker 运行时

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

2. LLM 本地化部署（二）：安装 Python 环境

2.1. 使用 Conda 虚拟环境

2.1.1. 安装 Anaconda

https://docs.anaconda.com/anaconda/install/

# 安装
curl -O https://repo.anaconda.com/archive/Anaconda3-2025.06-0-Linux-x86_64.sh
bash ~/Anaconda3-2025.06-0-Linux-x86_64.sh

# 设置默认是否进入base环境
conda config --set auto_activate_base True
conda config --set auto_activate_base False

# 手动初始化
source <PATH_TO_CONDA>/bin/activate
conda init --all

# 更新Conda环境
conda update --all

2.1.2. 解决 GLIBCXX not found 问题

# 查看系统 libstdcxx 版本
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX

# 查询 conda libstdcxx 版本
cd ~/anaconda3/envs/xinference/lib/
strings libstdc++.so.6| grep GLIBCXX

# 升级 conda libstdcxx 版本
conda install conda-forge::libstdcxx-ng --update-deps
conda install conda-forge::libgcc-ng --update-deps

# 或者做软链接
rm libstdc++.so.6
ln -s /usr/lib/x86_64-linux-gnu/libstdc++.so.6 libstdc++.so.6

2.1.3. 常用 conda 命令

conda 会检查当前环境安装的 Python 版本，并仅安装与该 Python 版本兼容的包。

# 查看
conda env list

# 搜索
conda search <PACKAGE>
conda search <CHANNEL>::<PACKAGE>
conda search python

# 新建
conda create --name <ENVIRONMENT> python=<VERSION>
conda create --name python311 python=3.11
conda create --name pytorch251_cu126 --clone python311
conda create --name xinference --clone pytorch251_cu126

# 激活、退出、删除
conda activate xinference
conda deactivate
conda env remove --name xinference

# 导出、导入
conda env export --name pytorch251 > pytorch251.yml
conda env create -f pytorch251.yml

2.1.4. conda 和 pip 区别

• conda 可以管理非python包，pip只能管理python包。
• conda 可以用来创建虚拟环境，pip不能，需要依赖virtualenv之类的包。
• conda 安装的包是编译好的二进制文件，pip安装的包是wheel或源码，需要解禁依赖问题。
• conda 安装的包会统一下载到当前虚拟环境对应的目录下，下载一次多次安装，pip是直接下载到对应环境中。

2.1.4.1. 通过 conda 安装

https://docs.anaconda.com/working-with-conda/packages/install-packages/

# 全局代理
vim ~/.condarc

proxy_servers:
    http: http://127.0.0.1:7890
    https: http://127.0.0.1:7890

# 安装包
conda install <PACKAGE>
conda install <PACKAGE> --name <ENVIRONMENT>
conda install <PACKAGE_PATH/PACKAGE>.conda
conda install conda-forge::transformers

2.1.4.2. 通过 pip 安装包

https://docs.anaconda.com/working-with-conda/packages/pip-install/

# 全局代理
pip config set global.proxy http://127.0.0.1:7890

# 安装包
pip install <PACKAGE>

2.2. 使用 uv 虚拟环境

2.2.1. 安装 uv

https://docs.astral.sh/uv/getting-started/installation/

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Shell 自动补全
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# 安装 python
uv python list
uv python install 3.13

2.2.2. 镜像设置

https://docs.astral.sh/uv/reference/settings

vim ~/.config/uv/uv.toml

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true

2.2.3. 常用命令

默认缓存目录：$HOME/.cache/uv

安装包： https://docs.astral.sh/uv/pip/packages

# 设置代理
export HTTPS_PROXY=http://192.168.60.181:7890
export HTTP_PROXY=http://192.168.60.181:7890
export UV_HTTP_TIMEOUT=300

# 新建
uv venv pytorch --python 3.12 --seed
source pytorch/bin/activate

# 退出
deactivate

3. LLM 本地化部署（三）：安装本地模型推理引擎

3.1. 安装 Transformers 引擎

3.1.1. PyTorch 和 Transformers 关系

• PyTorch 是由 Facebook 开发的机器学习框架，基于 Torch 库，底层由 C++ 实现，提供了丰富的工具和API，使得构建和训练神经网络变得更加简单和高效。

• TensorFlow 是由 Google 开发的机器学习框架，具有静态计算图和高度优化的执行引擎，使其适用于大规模的分布式训练和部署。

• Transformers 库是由 Hugging Face 开发的，它建立在 PyTorch 和 TensorFlow 之上，支持几乎有所的最新模型。

3.1.2. 使用 pip 安装 pytorch

注意：当前 pytorch 稳定版(2.8.0) 只支持到 CUDA 12.9，

https://pytorch.org/get-started/locally

最新稳定版：ptorch-2.8.0/cuda-12.9

# conda 虚拟环境
conda create --name pytorch280_cu129 python=3.12
conda activate pytorch280_cu129
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu129

# uv 虚拟环境
uv venv pytorch280_cu129 --python 3.12 --seed
source pytorch280_cu129/bin/activate
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu129

3.1.3. 使用 conda 安装 pytorch（不推荐）

https://pytorch.org/get-started/previous-versions/

# CUDA 12.4
conda install pytorch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 pytorch-cuda=12.4 -c pytorch -c nvidia

# CPU Only
conda install pytorch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 cpuonly -c pytorch

3.1.4. 验证 Torch/CUDA 版本

python ~/torch-test.py

import torch

# 显示当前torch版本
print(torch.__version__)

# 检查CUDA是否可用
print(torch.cuda.is_available())

# 显示当前CUDA版本
print(torch.version.cuda)

3.2. 安装 llama.cpp 引擎

llama.cpp 是一个用纯C/C++编写的开源大语言模型推理库,旨在实现高性能、跨平台的LLM推理。如果资源有限，可以优先使用 llama.cpp 引擎，因为他提供了更多的量化选项。

3.2.1. 安装依赖

# conda 虚拟环境
conda create --name llama_cpp python=3.12
conda activate llama_cpp
pip install -r requirements.txt

# uv 虚拟环境
# 注意目前只支持到 python 3.12
uv venv llama_cpp --python 3.12 --seed
source llama_cpp/bin/activate
git clone https://ghfast.top/https://github.com/ggml-org/llama.cpp
cd llama.cpp
uv pip install numpy==1.26.4 huggingface-hub==0.23.2 matplotlib==3.10.0
uv pip install -r requirements.txt --prerelease=allow

3.2.2. 导入 CUDA 环境

vim ~/.cuda.env
# set cuda environment
export CUDA_HOME=/usr/local/cuda
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda/lib64:/usr/local/cuda/extras/CUPTI/lib64
export PATH=$PATH:$CUDA_HOME/bin

vim ~/.bashrc
# import cuda environment
source ~/.cuda.env

3.2.3. 源码编译 llama.cpp

https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md

# 安装编译工具
sudo apt -y install build-essential g++ cmake libcurl4-openssl-dev

# CUDA Build
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -- -j 8

# CPU Build
cmake -B build
cmake --build build --config Release -- -j 8

3.2.4. llama.cpp 命令补全

~/llama.cpp/build/bin/llama-cli --completion-bash > ~/.llama-completion.bash

vim ~/.profile

# set llama PATH if it exists
if [ -d "$HOME/llama.cpp/build/bin" ] ; then
    PATH="$HOME/llama.cpp/build/bin:$PATH"
fi

# llama completion
source ~/.llama-completion.bash

3.3. 安装 vLLM 引擎

vLLM 专为高效服务大型语言模型（LLM）而设计，通过有效管理注意力键和值来改善内存管理，吞吐量能够达到 Transformers 的 24 倍，因此 vLLM 适合在生产环境中使用，应对高并发的用户访问。

由于 vLLM 编译了许多 CUDA 内核，导致与有 CUDA 和 PyTorch 出现很多兼容问题，因此官方建议在全新环境中部署。

详细安装方法见官方文档： https://docs.vllm.ai/en/latest/getting_started/installation/gpu/index.html

uv venv vllm --python 3.12 --seed
source vllm/bin/activate
uv pip install vllm 

需要注意的是，vllm 默认安装的是 cu124 版本，请确保与系统的一致。

4. LLM 本地化部署（四）：Transformers 模型量化

大语言模型（Large Language Model，LLM），可以通过量化（Quantization）操作来节约内存/显存的使用，并且降低了通讯开销，进而达到加速模型推理的效果。比如将权重（weight）为浮点数模型 FP32 转换为定点数模型 INT8。

• 低精度模型：表示模型权重数值格式为 FP16（半精度浮点）或者 INT8（8位的定点整数）。
• 常规精度模型：表示模型权重数值格式为 FP32（32位浮点，单精度）。
• 混合精度（Mixed precision）：表示模型中同时使用 FP32 和 FP16 的权重数值格式。 FP16 减少了一半的内存大小，但有些参数或操作符必须采用 FP32 格式才能保持准确度。

4.1. 下载 Transformers 模型

#

4.2. Transformers 模型转 GGUF 格式

~/llama.cpp/convert_hf_to_gguf.py DeepSeek-R1-Distill-Qwen-14B --outfile DeepSeek-R1-Distill-Qwen-14B-GGUF/DeepSeek-R1-Distill-Qwen-14B-F16.gguf

• --outtype f32 参数可以指定量化精度

4.3. GGUF 模型量化

# 评估量化效果
llama-quantize-stats -m DeepSeek-R1-Distill-Qwen-7B-F16.gguf

# Q 代表量化。
# 5 表示量化过程中使用的位数。
# K 表示在量化中使用 k 均值聚类。
# M 表示量化后的模型大小。S = 小，M = 中，L = 大。
llama-quantize DeepSeek-R1-Distill-Qwen-7B-F16.gguf DeepSeek-R1-Distill-Qwen-7B-Q5_K_M.gguf Q5_K_M

# 14B
llama-quantize DeepSeek-R1-Distill-Qwen-14B-F16.gguf DeepSeek-R1-Distill-Qwen-14B-Q4_K_M.gguf Q4_K_M

• q4_0：这是最初的量化方案，使用 4 位精度。
• q4_1 和 q4_k_m、q4_k_s：这些提供了不同程度的准确性和推理速度，适合需要平衡资源使用的场景。
• q5_0、q5_1、q5_k_m、q5_k_s：这些版本在保证更高准确度的同时，会使用更多的资源并且推理速度较慢。
• q6_k 和 q8_0：这些提供了最高的精度，但是因为高资源消耗和慢速度，可能不适合所有用户。
• fp16 和 f32: 不量化，保留原始精度。

4.4. 运行 GGUF 模型

llama-cli -m DeepSeek-R1-Distill-Qwen-7B-Q5_K_M.gguf
llama-cli -m DeepSeek-R1-Distill-Qwen-7B-Q5_K_M.gguf--port 8080

5. LLM 本地化部署（五）：安装 xinference 模型推理平台

Xinference 是一款开源模型推理平台，支持多种推理引擎（如 Transformers、vLLM 和 GGML），它提供多种灵活的 API 和接口，除了支持 LLM，它还可以部署 Embedding 和 ReRank 模型，这在企业级 RAG 构建中非常关键。Xinference 还支持分布式多机部署，能够在多个设备或机器间高效分配模型推理任务，满足多模型和高可用的部署需要。

5.1. 安装 xinference

https://inference.readthedocs.io/zh-cn/latest/getting_started/installation.html
https://inference.readthedocs.io/zh-cn/latest/user_guide/client_api.html

# uv 虚拟环境 （官方推荐3.10环境）
#pip install Cython
#uv pip install "xinference[all]" --no-build-isolation
#sudo apt-get install python3.12-dev libfst-dev
uv venv xinference --python 3.10 --seed
source xinference/bin/activate
uv pip install "xinference[all]"

5.2. 查询模型推理引擎

# 启动 xinference 本地服务
XINFERENCE_MODEL_SRC=modelscope xinference-local --host 0.0.0.0 --port 9997

# 查询LLM模型支持的所有的推理引擎
xinference engine -e http://0.0.0.0:9997 --model-name deepseek-r1

# 进一步查询vllm引擎所支持的参数组合
xinference engine -e http://0.0.0.0:9997 --model-name deepseek-r1 --model-engine vllm

# 进一步查询ggufv2格式所支持的参数组合
xinference engine -e http://0.0.0.0:9997 --model-name deepseek-r1 -f ggufv2

5.3. 启动和停止模型

xinference launch --model-name <MODEL_NAME> \
                  [--model-engine <MODEL_ENGINE>] \
                  [--model-type <MODEL_TYPE>] \
                  [--model-uid <MODEL_UID>] \
                  [--endpoint "http://<XINFERENCE_HOST>:<XINFERENCE_PORT>"] \

示例：deepseek-r1

xinference launch --model-name deepseek-r1-distill-qwen \
                  --model-engine llama.cpp \
                  --model-type LLM \
                  --model-uid deepseek/deepseek-r1-distill-qwen \
                  --endpoint "http://0.0.0.0:9997" \
                  --model-format ggufv2 \
                  --size-in-billions 7 \
                  --quantization Q4_K_M \
                  --n-gpu auto \
                  --replica 1 \
                  --n-worker 1 \
                  --model-path DeepSeek-R1-Distill-Qwen-7B-Q4_K_M.gguf \
                  --n_ctx 10240

示例：whisper-large-v3-turbo

xinference launch --model-name whisper-large-v3-turbo --model-type audio

5.4. 管理模型

# 列出 Xinference 中所有可以启动的、某种类型的模型
# type: LLM / embedding / image /audio / rerank video
xinference registrations --model-type LLM --endpoint "http://0.0.0.0:9997"

# 列出所有在运行的模型
xinference list

# 释放模型资源
xinference terminate --model-uid "qwen2.5-instruct"

6. LLM 本地化部署（六）：安装 Ollama 模型推理平台

Xinference 多运用与企业级部署，而 Ollama 则简化本地部署与交互，提供开箱即用的命令行工具和轻量级 API，支持快速模型加载和交互式调试。

6.1. 安装

在线安装

curl -fsSL https://ollama.com/install.sh | sh

离线安装

curl -L https://ollama.com/download/ollama-linux-amd64.tgz -o ollama-linux-amd64.tgz
sudo tar -C /usr -xzf ollama-linux-amd64.tgz

权限设置

sudo useradd -r -s /bin/false -U -m -d /usr/share/ollama ollama
sudo usermod -a -G ollama $(whoami)

6.2. 配置

https://github.com/ollama/ollama/blob/main/docs/faq.md

# /etc/systemd/system/ollama.service.d/override.conf
sudo systemctl edit ollama

[Service]
Environment="OLLAMA_HOST=172.17.0.1:8888"
Environment="OLLAMA_KEEP_ALIVE=1h"
Environment="OLLAMA_MAX_LOADED_MODELS=2"
Environment="OLLAMA_NUM_PARALLEL=3"

默认位置： /usr/share/ollama/.ollama/models

**特别注意：**修改了默认主机后，运行ollama命令需要增加加前缀 OLLAMA_HOST=172.17.0.1:8888

例如：OLLAMA_HOST=172.17.0.1:8888 ollama ps

6.3. 自启动

sudo vim /etc/systemd/system/ollama.service

[Unit]
Description=Ollama Service
After=network-online.target

[Service]
ExecStart=/usr/bin/ollama serve
User=ollama
Group=ollama
Restart=always
RestartSec=3
Environment="PATH=$PATH"

[Install]
WantedBy=default.target

启动

sudo systemctl daemon-reload
sudo systemctl enable --now ollama

6.4. 卸载

sudo systemctl stop ollama
sudo systemctl disable ollama
sudo rm /etc/systemd/system/ollama.service
sudo rm $(which ollama)
sudo rm -r /usr/share/ollama
sudo userdel ollama
sudo groupdel ollama
sudo rm -rf /usr/local/lib/ollama

6.5. 导入GGUF模型

• https://github.com/ollama/ollama/blob/main/docs/import.md
• https://zhuanlan.zhihu.com/p/21162949288

6.5.1. 创建 Modelfile 文件

vim DeepSeek-R1-Distill-Qwen-7B-GGUF/Modelfile

FROM DeepSeek-R1-Distill-Qwen-7B-Q4_K_M.gguf

TEMPLATE """{{- if .System }}{{ .System }}{{ end }}
{{- range $i, $_ := .Messages }}
{{- $last := eq (len (slice $.Messages $i)) 1}}
{{- if eq .Role "user" }}<｜User｜>{{ .Content }}
{{- else if eq .Role "assistant" }}<｜Assistant｜>{{ .Content }}{{- if not $last }}<｜end▁of▁sentence｜>{{- end }}
{{- end }}
{{- if and $last (ne .Role "assistant") }}<｜Assistant｜>{{- end }}
{{- end }}"""

PARAMETER stop "<｜begin▁of▁sentence｜>"
PARAMETER stop "<｜end▁of▁sentence｜>"
PARAMETER stop "<｜User｜>"
PARAMETER stop "<｜Assistant｜>"

6.5.2. 创建、运行模型

#ollama create <model_name> -f <path_to_Modelfile>
ollama create deepseek-r1-7b
ollama run deepseek-r1-7b
ollama list
ollama ps