安装前先弄清适用场景

TensorRT-LLM 是面向大语言模型推理优化的工具链。

它适合在 NVIDIA 显卡环境中部署和测试 LLM 推理性能。

这个工具更偏工程化，常用于模型转换、引擎构建、推理服务验证和性能调优。

如果只是想简单体验对话模型，未必需要一开始就安装它。

如果你已经有本地显卡，需要提升推理速度，或者降低显存占用，TensorRT-LLM 才更能体现价值。

如果你准备把模型接入业务服务，安装它也是值得的。

新手踩坑，往往不在命令本身，而是版本组合。

显卡驱动、CUDA、Python、PyTorch、TensorRT-LLM 之间存在兼容关系。

建议优先使用官方文档标注的版本，不要随意混装。

本文以 Linux 环境为主要说明对象。

Windows 用户建议使用 WSL2 或容器方案。

在原生 Windows 中直接安装，往往会遇到更多编译与依赖问题。

准备工作：确认硬件与基础环境

确认硬件与驱动

安装前，先执行 nvidia-smi。

确认系统能识别显卡，并记录驱动版本和 CUDA 运行时提示。

注意：nvidia-smi 显示的 CUDA Version 代表驱动支持的最高运行时版本。

这并不等于系统已经安装了对应 CUDA Toolkit。

确认 Python 环境

接着执行 python3 --version。

建议选择 Python 3.10 或官方当前推荐版本。

版本过新或过旧，都可能导致包无法安装。

安装基础工具

还需要准备基础工具：git、python3-venv、pip、build-essential 等。

Ubuntu 系统可先执行 sudo apt update，再安装缺失组件。

生产机器上不建议直接使用 root 安装 Python 包，避免污染系统环境。

更稳妥的方式是建立独立虚拟环境，并把项目、模型、缓存目录分开管理。

创建 Python 虚拟环境

选择一个空间充足的工作目录，例如 /data/ai/tensorrt-llm。

执行 mkdir -p /data/ai/tensorrt-llm 后进入目录。

再运行 python3 -m venv .venv 创建虚拟环境。

启用环境使用 source .venv/bin/activate，看到命令行前出现 (.venv) 说明已生效。

进入虚拟环境后，先升级基础安装工具：python -m pip install -U pip setuptools wheel。

如果下载速度不稳定，可临时使用可信镜像源。

但不要从来历不明的页面复制安装包。

AI 工具链依赖体积大，安装中断后建议清理缓存再重试。

残留损坏文件会造成后续异常。

安装 PyTorch 与相关依赖

安装 PyTorch

TensorRT-LLM 通常需要与 PyTorch、CUDA 组件配合使用。

安装 PyTorch 时，一定要选择与 CUDA 匹配的版本。

例如官方页面会提供类似 pip install torch torchvision torchaudio --index-url ... 的命令。

应以官方生成命令为准。

验证 GPU 可用性

安装后，执行 python -c "import torch; print(torch.cuda.is_available()); print(torch.version.cuda)" 检查 PyTorch 是否能调用 GPU。

如果输出为 False，不要急着安装 TensorRT-LLM。

应先排查驱动、CUDA、PyTorch 版本和环境变量。

常见原因包括：

• 装成了 CPU 版 PyTorch
• 驱动版本过低
• 虚拟环境未启用
• 多个 CUDA 路径互相干扰

此时继续安装只会把问题复杂化。

安装 TensorRT-LLM

安装包

新手建议优先使用预编译包或官方推荐的安装方式。

可先尝试 pip install tensorrt_llm。

如果提示没有匹配版本，说明当前 Python、系统平台或 CUDA 组合不被该包支持。

需要回到官方版本表重新选择环境。

部分版本还可能要求额外安装 TensorRT、mpi4py、ninja、cmake 等组件。

验证安装

安装完成后，执行 python -c "import tensorrt_llm; print(tensorrt_llm.__version__)" 验证。

若能正常输出版本号，说明 Python 包层面安装成功。

接下来，再运行示例脚本或最小模型转换流程，验证构建引擎和推理链路是否可用。

不要只看 pip 安装成功，因为真正的问题常出现在编译插件、加载权重、构建 engine 阶段。

推荐的目录结构

为了后期维护，建议把程序、模型、缓存、构建结果分开。

例如：

• /data/ai/tensorrt-llm/project 放项目代码
• /data/ai/models 放模型权重
• /data/ai/cache 放下载缓存
• /data/ai/engines 放构建后的引擎文件
• /data/ai/logs 放日志

这样做的好处是：升级工具时不影响模型文件，清理缓存时不误删引擎，迁移机器时也更清楚哪些目录必须保留。

如果使用 Hugging Face 生态，可设置环境变量：

• export HF_HOME=/data/ai/cache/huggingface
• export TRANSFORMERS_CACHE=/data/ai/cache/transformers

为了每次进入环境自动生效，可把这些变量写入虚拟环境的 .venv/bin/activate 尾部，或写入当前用户的 shell 配置文件。

多人共用机器时，不建议把缓存放到个人主目录下，容易占满系统盘。

数据目录迁移方法

安全迁移步骤

当系统盘空间不足时，可以把模型缓存和构建产物迁移到大容量磁盘。

安全做法是：先停止正在运行的推理任务，确认没有进程占用目录。

然后创建新目录，例如 mkdir -p /data/ai/cache /data/ai/models /data/ai/engines。

接着使用 rsync -a v 原目录/ 新目录/ 复制数据。

确认文件数量和大小无误后，再修改环境变量指向新路径。

使用软链接过渡

如果已有程序写死了旧路径，可使用软链接过渡。

例如把旧的 ~/.cache/huggingface 迁移到 /data/ai/cache/huggingface 后，执行 ln -s /data/ai/cache/huggingface ~/.cache/huggingface。

注意：创建软链接前，旧目录应先改名备份，避免链接失败。

确认运行正常一段时间后，再删除旧备份。

迁移引擎文件时要特别注意：TensorRT 构建出的 engine 通常与显卡型号、TensorRT 版本、精度配置相关，换机器后不一定可复用。

常见问题与处理思路

• 问题一：安装时提示找不到匹配版本
  通常是 Python 版本、系统架构或 CUDA 组合不符合要求。处理方式是新建一个符合官方推荐版本的虚拟环境，不要在旧环境中反复覆盖安装。
• 问题二：导入包成功，但运行示例时报 CUDA 错误
  先检查 torch.cuda.is_available()，再检查 LD_LIBRARY_PATH 是否包含错误路径。如果机器上装过多个 CUDA，建议整理环境变量，避免优先加载旧库。
• 问题三：构建引擎耗时很长或显存不足
  可以降低 batch size、减少最大序列长度、选择更合适的精度配置，或先用较小模型验证流程。不要一开始就用超大模型排错，否则很难判断是资源不足还是安装异常。
• 问题四：升级后旧项目不能运行
  TensorRT-LLM 更新较快，接口和示例可能变化。升级前应记录当前版本：pip freeze > requirements-lock.txt，并备份虚拟环境或保留安装清单。需要回退时，重新创建虚拟环境并按锁定文件安装，比在原环境里降级更可靠。

安全边界与实用建议

安全建议

安装 AI 工具链时，不要执行来源不明的一键脚本，尤其是需要高权限的脚本。

下载模型和依赖时，应选择官方仓库或可信来源，避免把未知文件放入生产环境。

对于企业或团队环境，建议：固定版本、记录安装过程、保留校验信息，并将模型文件、配置文件和日志纳入统一管理。

新手推荐路线

新手最稳的路线是：

• 先确认显卡驱动正常
• 再建虚拟环境
• 先装 PyTorch 并验证 GPU
• 再装 TensorRT-LLM
• 先跑官方小示例
• 再接入自己的模型
• 先迁移缓存目录
• 再进行大规模下载和引擎构建

只要把版本、路径和权限三件事管好，大多数安装问题都能快速定位，后续升级和迁移也会轻松很多。