Agent-Lightning 环境部署

本文档基于 Ubuntu 22.04 / NVIDIA A800 80GB / Python 3.12 conda 环境 实际安装并验证成功。
flash-attn 无需本地编译（用官方预编译 wheel），CUDA 版本用 torch 自带 cu128 即可，并修复了 3 个会导致环境装好后 import 崩溃的隐藏坑。

0. 硬件配置

项目	要求	本机实测
操作系统	Ubuntu 22.04 LTS (x86_64)	✅ 22.04.5
GPU	NVIDIA Ampere（A800/A100，sm_80）	✅ A800 80GB（sm_80）
NVIDIA 驱动	≥ 550	✅ 580.159.03（最高支持 CUDA 13.0）
Python	3.12	✅ 3.12.13（conda env agent_lighting）

1. CUDA 版本

• CUDA 12.8（与 torch 2.8.0 的 +cu128 构建匹配）。不单独安装系统级 CUDA 12.8 toolkit。torch 2.8.0 从 PyPI 安装即自带 cu128 运行库；flash-attn 用官方预编译 wheel，全程零编译，所以本机 /usr/local/cuda 是 12.9 也无任何影响。驱动 580 完全兼容 12.8。

2. conda 环境创建

conda create --name agent_lighting python=3.12 -y
conda activate agent_lighting

3. 安装步骤

3.1 核心框架

pip install --upgrade agentlightning
pip install openai

# torch 2.8.0（PyPI 默认就是 cu128 构建，无需 --index-url）
pip install torch==2.8.0 torchvision==0.23.0

# ★ 关键：先固定 numpy，verl 0.5.0 要求 numpy<2.0
pip install numpy==1.26.4

pip install vllm==0.10.2
pip install verl==0.5.0

安装后检查关键版本是否一致：

python -c "import torch; print(torch.__version__, torch.version.cuda)"   # 2.8.0+cu128 12.8
python -c "import numpy; print(numpy.__version__)"                       # 1.26.4
python -c "import vllm; print(vllm.__version__)"                         # 0.10.2
python -c "import verl; print(verl.__version__)"                         # 0.5.0
python -c "import agentlightning as agl; print(hasattr(agl,'VERL'), hasattr(agl,'Trainer'))"  # True True

3.2 flash-attn构建

• 不要从源码编译！ flash-attn 官方在每个版本发布时提供与 torch/Python 精确匹配的预编译 wheel（GitHub Releases），pip install flash-attn 直接装即可。

1. 先确认 torch 的 ABI（决定选 cxx11abiTRUE 还是 cxx11abiFALSE 的 wheel）：

python -c "import torch; print(torch._C._GLIBCXX_USE_CXX11_ABI)"   # 本机 pip 安装的 torch 输出 True

2. 下载对应 wheel（本机：torch 2.8 / Python 3.12 / x86_64 / cxx11abiTRUE）：

# 若上面输出 True → 用 cxx11abiTRUE；输出 False → 换 cxx11abiFALSE
curl -sSL -o /tmp/flash_attn.whl \
  "https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.3.post1/flash_attn-2.8.3.post1%2Bcu12torch2.8cxx11abiTRUE-cp312-cp312-linux_x86_64.whl"
pip install /tmp/flash_attn.whl

3. 验证（在空闲 GPU 上跑一次前向）：

python -c "
import torch, flash_attn
from flash_attn import flash_attn_func
q = torch.randn(1, 4, 64, 32, dtype=torch.float16, device='cuda')
out = flash_attn_func(q, q, q)
print('flash_attn', flash_attn.__version__, 'forward OK', tuple(out.shape))
"

wheel 匹配关系速查（torch 2.8.0 + cp312 + linux_x86_64）：

torch._C._GLIBCXX_USE_CXX11_ABI	wheel 文件名
True（pip 装的 torch 通常如此）	flash_attn-2.8.3.post1+cu12torch2.8cxx11abiTRUE-cp312-cp312-linux_x86_64.whl
False	flash_attn-2.8.3.post1+cu12torch2.8cxx11abiFALSE-cp312-cp312-linux_x86_64.whl

3.3 SQL-Agent 基础库

pip install "langgraph<1.0" "langchain[openai]<1.0" "langchain-community" "langchain-text-splitters<1.0" sqlparse nltk
pip install modelscope wandb

4. 三个必踩的坑（已在本环境修复）

• 环境装完后直接跑 sql_agent.py 会 import 崩溃，根源都不是缺包，而是版本/链接问题：

坑 1：libstdc++.so.6: version 'CXXABI_1.3.15' not found

• 现象：import sqlite3（或 langchain/langgraph 链路上的任意 C 扩展）报错。
• 原因：agentlightning→litellm 等某个 pip 装的 manylinux C 扩展会先加载系统 libstdc++（GCC 11，只有 CXXABI_1.3.13），随后 _sqlite3 依赖的 conda ICU 库需要 CXXABI_1.3.15 就崩了。conda 默认 RPATH 管不到 pip 装的 wheel。
• 修复：把 conda 环境的 lib 放到 LD_LIBRARY_PATH 最前。本环境已固化到 conda 激活脚本，conda activate agent_lighting 后自动生效，无需手动 export：

# 已写入 $CONDA_PREFIX/etc/conda/activate.d/env_vars.sh：
# export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:${LD_LIBRARY_PATH}"

若重建环境，记得再执行一次上面的写入。

坑 2：litellm proxy 与 fastapi 不兼容

• 现象：from litellm.proxy.proxy_server import app 报
  ImportError: cannot import name 'get_flat_dependant' from 'fastapi.dependencies.utils'。
• 原因：agentlightning 会 import litellm proxy；litellm 代码用了 get_flat_dependant，该符号在 fastapi ≥ 0.140 被移除，而 pip 默认装了最新 fastapi 0.141.1。
• 修复（已执行）：pip install fastapi==0.136.3（litellm 声明 >=0.136.3，vllm 声明 >=0.115，0.136.3 同时满足且带该符号）。

坑 3：transformers 5.x 与老栈不兼容

• 现象：pip install vllm 会顺带装最新 transformers（5.14.x），但 vllm 0.10.2 / verl 0.5.0 / agentlightning 0.3.0 都是 4.x 时代开发的。
• 修复（已执行）：pip install "transformers>=4.55.2,<5"（本机最终为 4.57.6）。

5. 项目目录与运行准备

5.1 目录结构

SQL-Agent-RL/
├── data/      # train_spider.parquet(7000), test_dev_500.parquet(500), test_dev.parquet(100), database/, test_database/
├── model/     # 放置 Qwen2.5-Coder 模型权重（空目录，待下载）
└── spider/    # sql_agent.py, train_sql_agent.py, spider_eval/

5.2 下载模型

conda activate agent_lighting
pip install modelscope
mkdir -p ./models/Qwen3-1.7B
modelscope download --model Qwen/Qwen3-1.7B --local_dir ./models/Qwen3-1.7B

5.3 环境变量 / .env

export OPENAI_API_KEY=sk-xxx              # 任意占位（vLLM 服务用）
export OPENAI_API_BASE=http://127.0.0.1:8000/v1
export VERL_SPIDER_DATA_DIR=../data       # 若在 spider/ 目录下运行时需要

5.4 运行

# ① 启动 vLLM 服务（在 model 目录，或传本地模型路径）
vllm serve SQL-Agent-RL/model/Qwen3-1.7B --host 0.0.0.0 --port 8000 --max-model-len 4096 --dtype bfloat16

# ② 调试 SQL Agent（OpenAI 兼容接口）
cd SQL-Agent-RL/spider && python sql_agent.py

# ③ 训练（注意：数据路径相对 CWD，请在 SQL-Agent-RL 根目录运行）
cd SQL-Agent-RL && python spider/train_sql_agent.py qwen

GPU 提示：训练前可用 CUDA_VISIBLE_DEVICES=x 指定空闲卡。

6. 环境验证清单

conda activate agent_lighting
cd SQL-Agent-RL/spider
python -c "import sql_agent"                       # LangGraph SQLAgent + LitSQLAgent 定义成功
python -c "import torch,vllm,verl,flash_attn,agentlightning as agl; print('stack OK', hasattr(agl,'VERL'))"
python -c "import pandas as pd; df=pd.read_parquet('data/train_spider.parquet'); print(len(df), list(df.columns))"
CUDA_VISIBLE_DEVICES=4 python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_capability(0))"

7. 最终安装的版本快照（agent_lighting 环境）

包	版本	说明
python	3.12.13	conda
torch / torchvision / torchaudio	2.8.0+cu128 / 0.23.0 / 2.8.0	PyPI 默认 cu128
flash-attn	2.8.3.post1	官方预编译 wheel（cu12torch2.8 cxx11abiTRUE）
vllm	0.10.2	文档指定版本
verl	0.5.0	文档指定版本
agentlightning	0.3.0	最新版
transformers	4.57.6	必须 <5
fastapi	0.136.3	必须 ≤0.136.x（litellm 兼容）
numpy	1.26.4	verl 要求 <2.0
langchain / langgraph	0.3.30 / 0.6.11	<1.0
modelscope	1.39.0	模型下载