2. 环境准备

在开始编写FastAPI服务代码之前，必须先构建一个干净、可复现且与硬件算力匹配的Python运行环境。环境准备的质量直接决定了后续开发调试的效率、模型推理的稳定性以及部署上线的可维护性。本章将围绕“虚拟环境隔离”、“CUDA/CPU运行时选择”、“依赖锁定与安装”三个核心环节展开，帮助你从零搭建一个既适合本地开发、又能平滑迁移到生产服务器的环境底座。

上图展示了从硬件驱动到Python依赖的完整准备链路。核心思想是：先确认硬件能力，再选择运行时，最后锁定依赖版本。下面我们将逐一拆解每个环节的具体操作与判断标准。

2.1 Python虚拟环境：为什么必须隔离，以及如何选择工具

核心原理：Python项目之间常常存在依赖冲突，例如项目A需要numpy==1.21，而项目B需要numpy==1.24。如果全局安装，后安装的版本会覆盖先前的版本，导致项目A无法运行。虚拟环境为每个项目创建独立的Python解释器副本和site-packages目录，实现依赖的完全隔离。对于大模型部署项目，由于涉及torch、transformers、fastapi等重量级库，隔离更是避免“环境地狱”的第一道防线。

判断方法与操作流程：当前主流方案有两种——venv（Python内置）和conda（Anaconda/Miniconda附带）。选择标准如下表：

对于大多数FastAPI部署场景，推荐使用venv，因为它更轻量、与系统Python绑定紧密，且在生产服务器上无需额外安装conda。操作流程如下：

# 创建项目目录并进入
mkdir llm-fastapi-service && cd llm-fastapi-service

# 创建虚拟环境（指定Python版本，需提前安装）
python3.10 -m venv .venv

# 激活虚拟环境（Linux/macOS）
source .venv/bin/activate

# Windows下激活命令
# .venv\Scripts\activate

# 验证当前Python路径
which python  # 应指向 .venv/bin/python

2.2 CUDA/CPU环境配置：从硬件探测到运行时安装

核心原理：大模型推理的算力瓶颈主要在GPU的矩阵乘法单元。CUDA是NVIDIA GPU的并行计算平台，PyTorch等框架通过CUDA调用GPU加速。若机器无NVIDIA GPU，则退化为CPU推理，此时需安装CPU版本的PyTorch，其底层使用MKL或OpenBLAS优化。配置的关键在于驱动版本、CUDA Toolkit版本、PyTorch CUDA版本三者必须兼容。

判断方法：三步探测法

1. 检查GPU硬件：运行nvidia-smi，若无此命令或提示“No devices found”，则走CPU路线。
2. 查看驱动支持的CUDA版本：nvidia-smi右上角会显示“CUDA Version: 12.2”，这是驱动支持的最高CUDA版本，而非已安装的Toolkit版本。
3. 确认PyTorch匹配版本：访问PyTorch官网（pytorch.org），选择对应的CUDA版本（如cu118、cu121），复制安装命令。

案例拆解：一台双GPU服务器的环境配置

某算法团队需要部署一个7B参数的LLM，服务器配置为2张NVIDIA A100（40GB），驱动版本为535.104.05，nvidia-smi显示CUDA Version: 12.2。初始现象是：直接执行pip install torch后，torch.cuda.is_available()返回False。分析过程：默认pip源安装的是CPU版PyTorch（因为PyPI上的默认包为CPU版）。解决步骤：

# 1. 确认驱动支持CUDA 12.x
nvidia-smi | grep "CUDA Version"

# 2. 安装CUDA 12.1对应的PyTorch（使用官方源）
pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121

# 3. 验证GPU可用性
python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.device_count())"

结果对比：安装后torch.cuda.is_available()返回True，且device_count为2。风险与代价：若直接安装cu122（驱动不支持），会报错“CUDA driver version is insufficient”。复盘经验：永远先看驱动版本，再选CUDA Toolkit，最后定PyTorch版本，顺序不可颠倒。

2.3 依赖安装与版本管理：从requirements到锁定文件

核心原理：大模型项目依赖复杂，直接pip install容易引入未预期版本更新，导致行为变化。版本管理的目标是可复现性——即今天安装的环境，三个月后依然能原样重建。实现手段是使用requirements.txt配合精确版本号，或使用pip-tools/uv生成锁定文件。

操作流程：推荐使用pip-tools工作流

# 1. 在requirements.in中声明顶层依赖（不写版本或写宽松范围）
echo "fastapi==0.115.0" > requirements.in
echo "uvicorn[standard]==0.30.6" >> requirements.in
echo "torch==2.1.2" >> requirements.in
echo "transformers==4.44.2" >> requirements.in

# 2. 编译生成锁定文件（包含所有传递依赖的精确版本）
pip install pip-tools
pip-compile requirements.in -o requirements.txt

# 3. 安装锁定版本
pip install -r requirements.txt

案例拆解：一次依赖升级引发的推理精度异常

某团队在部署GPTQ量化模型时，发现推理结果偶尔出现NaN。初始现象：模型在开发机（Python 3.9）上正常，但在生产服务器（Python 3.11）上异常。关键输入数据：transformers版本从4.40.0升级到4.44.0，torch从2.0.1升级到2.1.2。分析判断：transformers 4.44.0对量化算子的实现有调整，且与torch 2.1.2的某些CUDA内核存在兼容性问题。实际操作：回退transformers到4.41.2，并锁定torch==2.1.2，问题解决。结果对比：推理精度恢复，且速度无下降。复盘经验：对于大模型推理，任何依赖升级都必须跑一遍完整的精度回归测试，不能只看“能跑通”就上线。