Text-Generation-Inference项目运行中libcuda.so.1缺失问题的解决方案

2025-05-23 21:25:49作者：段琳惟

问题背景

在使用HuggingFace的Text-Generation-Inference(TGI)项目部署大语言模型服务时，用户可能会遇到一个常见的CUDA相关错误："ImportError: libcuda.so.1: cannot open shared object file: No such file or directory"。这个问题通常出现在使用Docker容器运行TGI服务时，特别是在Ubuntu 22.04系统环境下。

错误分析

这个错误的核心是CUDA运行时库(libcuda.so.1)无法被找到。具体表现为：

当尝试启动TGI容器时，系统提示无法加载libcuda.so.1共享库文件
错误通常发生在容器内部尝试初始化GPU加速组件时
即使宿主机已安装NVIDIA驱动和CUDA工具包，容器内部仍可能无法访问这些资源

根本原因

这个问题主要由以下几个因素导致：

Docker容器未正确配置GPU支持：默认情况下，Docker容器无法直接访问宿主机的GPU资源
CUDA运行时库路径问题：容器内部缺少必要的CUDA库文件或路径配置不正确
NVIDIA容器工具包未安装：宿主系统缺少必要的NVIDIA Docker支持组件

解决方案

1. 确保宿主系统环境正确

首先确认宿主系统已正确安装：

NVIDIA显卡驱动(版本需与CUDA要求匹配)
CUDA工具包
NVIDIA容器工具包

可以通过以下命令验证：

nvidia-smi

2. 安装NVIDIA容器工具包

在Ubuntu系统上执行：

distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
      && curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
      && curl -fsSL https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.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
sudo systemctl restart docker

3. 正确运行Docker容器

运行TGI容器时必须添加--gpus all参数，确保容器可以访问GPU资源：

docker run --gpus all --shm-size 1g -p 8080:80 \
  -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:2.0.4 \
  --model-id codellama/CodeLlama-13b-Instruct-hf \
  --quantize eetq

4. 验证CUDA环境

进入容器内部验证CUDA是否可用：

docker exec -it <container_id> bash
nvcc --version

其他可能遇到的问题

Safetensors反序列化错误：如果遇到模型文件加载问题，可以尝试重新下载模型或检查文件完整性
HF_TRANSFER问题：某些环境下可能需要禁用HF传输加速：
```
docker run --env HF_HUB_ENABLE_HF_TRANSFER=0 ...
```
CUDA版本不匹配：确保宿主CUDA版本与容器要求的版本兼容