ipex-llm/docs/mddocs/Quickstart/install_linux_gpu.zh-CN.md
Yuwen Hu 633d1c72e7
Add PyTorch 2.6 QuickStart for Intel GPU (#13024)
* Add quickstart for install IPEX-LLM with PyTorch 2.6 on Intel GPUs

* Add jump links

* Rename

* Small fix

* Small fix

* Update based on comments

* Small fix
2025-04-01 10:21:38 +08:00

471 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 在带有 Intel GPU 的Linux系统上安装 IPEX-LLM
<p>
< <a href='./install_linux_gpu.md'>English</a> | <b>中文</b> >
</p>
本指南将引导你如何在带有 Intel GPU 的 Linux 系统上安装 IPEX-LLM。适用于 Intel 数据中心的 GPU Flex 和 Max 系列,以及 Intel Arc 系列 GPU 和 Intel iGPU。
> [!NOTE]
> 如果需要安装 IPEX-LLM PyTorch 2.6 版本,请参阅本[指南](./install_pytorch26_gpu.md#linux-quickstart)获取详细信息。
> [!NOTE]
> 如果是在 Intel Arc B 系列 GPU 上安装(例,**B580**),请参阅本[指南](./bmg_quickstart.md)。
> [!NOTE]
> 如果是在 Windows 系统上安装,请参阅本[指南](./install_windows_gpu.zh-CN.md)。
我们建议使用带有 Linux 内核 6.2 或 6.5 的 Ubuntu 22.04 操作系统上使用 IPEX-LLM。本页演示了如何在 PyTorch 2.1 中使用 IPEX-LLM。你可以查看[完整安装页面](../Overview/install_gpu.md#linux)了解更多详细信息。
## 目录
- [系统环境安装](./install_linux_gpu.zh-CN.md#系统环境安装)
- [安装 GPU 驱动程序](./install_linux_gpu.zh-CN.md#安装-GPU-驱动程序)
- [适用于处理器编号为 1xxH/U/HL/UL 的第一代 Intel Core™ Ultra Processors代号 Meteor Lake](./install_linux_gpu.zh-CN.md#适用于处理器编号为-1xxhuhlul-的第一代-intel-core-ultra-processors代号-meteor-lake)
- [适用于其他 Intel iGPU 和 dGPU](./install_linux_gpu.zh-CN.md#适用于其他-intel-igpu-和-dgpu)
- [安装 oneAPI](./install_linux_gpu.zh-CN.md#安装-oneapi)
- [设置 Python 环境](./install_linux_gpu.zh-CN.md#设置-python-环境)
- [安装 ipex-llm](./install_linux_gpu.zh-CN.md#安装-ipex-llm)
- [验证安装](./install_linux_gpu.zh-CN.md#验证安装)
- [运行时配置](./install_linux_gpu.zh-CN.md#运行时配置)
- [快速示例](./install_linux_gpu.zh-CN.md#快速示例)
- [故障排除和提示](./install_linux_gpu.zh-CN.md#故障排除和提示)
## 系统环境安装
### 安装 GPU 驱动程序
#### 适用于处理器编号为 1xxH/U/HL/UL 的第一代 Intel Core™ Ultra Processors代号 Meteor Lake
> [!NOTE]
> 我们目前已在具有内核 `6.5.0-35-generic` 的 Ubuntu 22.04 系统中验证过 IPEX-LLM 在 Meteor Lake iGPU 上的运行和使用。
##### 1. 查看当前内核版本
你可以通过以下方式查看当前的内核版本:
```bash
uname -r
```
如果显示的版本不是 `6.5.0-35-generic`,可以通过以下方式将内核降级或升级至推荐版本。
##### 2. (可选) 降级 / 升级到内核 6.5.0-35
如果当前的内核版本不是 `6.5.0-35-generic`,你可以通过以下方式降级或升级它:
```bash
export VERSION="6.5.0-35"
sudo apt-get install -y linux-headers-$VERSION-generic linux-image-$VERSION-generic linux-modules-extra-$VERSION-generic
sudo sed -i "s/GRUB_DEFAULT=.*/GRUB_DEFAULT=\"1> $(echo $(($(awk -F\' '/menuentry / {print $2}' /boot/grub/grub.cfg \
| grep -no $VERSION | sed 's/:/\n/g' | head -n 1)-2)))\"/" /etc/default/grub
sudo update-grub
```
然后重新启动机器:
```bash
sudo reboot
```
重启之后,再次使用 `uname -r` 查看,内核版本已经修改为 `6.5.0-35-generic`
##### 3. 通过 `force_probe` flag 启用 GPU 驱动程序支持
接下来,你需要通过设置 `force_probe` 参数在内核 `6.5.0-35-generic` 上启用 GPU 驱动程序支持:
```bash
export FORCE_PROBE_VALUE=$(sudo dmesg | grep i915 | grep -o 'i915\.force_probe=[a-zA-Z0-9]\{4\}')
sudo sed -i "/^GRUB_CMDLINE_LINUX_DEFAULT=/ s/\"\(.*\)\"/\"\1 $FORCE_PROBE_VALUE\"/" /etc/default/grub
```
> [!TIP]
> 除了使用上述命令之外,你还可以通过以下方式手动查看 `force_probe` flag 的值:
>
> ```bash
> sudo dmesg | grep i915
> ```
>
> 你可能会获得类似 `Your graphics device 7d55 is not properly supported by i915 in this kernel version. To force driver probe anyway, use i915.force_probe=7d55` 的输出,其中 `7d55` 是 PCI ID它取决于你的 GPU 型号。
>
> 然后,直接修改 `/etc/default/grub` 文件。确保在 `GRUB_CMDLINE_LINUX_DEFAULT` 的值中添加 `i915.force_probe=xxxx`。例如,修改之前,`/etc/default/grub` 文件中有 `GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"`。你需要将其修改为 `GRUB_CMDLINE_LINUX_DEFAULT="quiet splash i915.force_probe=7d55"`。
然后通过以下方式更新 grub
```bash
sudo update-grub
```
需要重启机器使配置生效:
```bash
sudo reboot
```
##### 4. 安装 computer packages
通过以下命令在 Ubuntu 22.04 上为 Intel GPU 安装需要的 computer packages
```bash
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | \
sudo gpg --yes --dearmor --output /usr/share/keyrings/intel-graphics.gpg
echo "deb [arch=amd64,i386 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy client" | \
sudo tee /etc/apt/sources.list.d/intel-gpu-jammy.list
sudo apt update
sudo apt-get install -y libze1 intel-level-zero-gpu intel-opencl-icd clinfo
```
##### 5. 配置权限并验证 GPU 驱动程序设置
要完成 GPU 驱动程序设置,需要确保你的用户在 render 群组中:
```bash
sudo gpasswd -a ${USER} render
newgrp render
```
然后,你可以使用以下命令验证 GPU 驱动程序是否正常运行:
```bash
clinfo | grep "Device Name"
```
基于你的 GPU 型号,上述命令的输出应包含 `Intel(R) Arc(TM) Graphics``Intel(R) Graphics`
> [!TIP]
> 请参阅[客户端 GPU 驱动程序的 Intel 官方安装指南](https://dgpu-docs.intel.com/driver/client/overview.html#installing-client-gpus-on-ubuntu-desktop-22-04-lts)以获取更多详情。
#### 适用于其他 Intel iGPU 和 dGPU
##### Linux 内核 6.2
* 根据你的 CPU 类型选择以下其中一个选项进行设置:
1. **选项 1**:对于配备多个 A770 Arc GPU 的 `Intel Core CPU`,使用以下 repository
```bash
sudo apt-get install -y gpg-agent wget
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | \
sudo gpg --dearmor --output /usr/share/keyrings/intel-graphics.gpg
echo "deb [arch=amd64,i386 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy client" | \
sudo tee /etc/apt/sources.list.d/intel-gpu-jammy.list
```
3. **选项 2** 对于配备多个 A770 Arc GPU 的 `Intel Xeon-W/SP CPU`,使用以下 repository 可获得更好的性能:
```bash
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | \
sudo gpg --yes --dearmor --output /usr/share/keyrings/intel-graphics.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy/lts/2350 unified" | \
sudo tee /etc/apt/sources.list.d/intel-gpu-jammy.list
sudo apt update
```
<img src="https://llm-assets.readthedocs.io/en/latest/_images/wget.png" width=100%; />
* 安装驱动程序
```bash
sudo apt-get update
# Install out-of-tree driver
sudo apt-get -y install \
gawk \
dkms \
linux-headers-$(uname -r) \
libc6-dev
sudo apt install intel-i915-dkms intel-fw-gpu
# Install Compute Runtime
sudo apt-get install -y udev \
intel-opencl-icd intel-level-zero-gpu level-zero \
intel-media-va-driver-non-free libmfx1 libmfxgen1 libvpl2 \
libegl-mesa0 libegl1-mesa libegl1-mesa-dev libgbm1 libgl1-mesa-dev libgl1-mesa-dri \
libglapi-mesa libgles2-mesa-dev libglx-mesa0 libigdgmm12 libxatracker2 mesa-va-drivers \
mesa-vdpau-drivers mesa-vulkan-drivers va-driver-all vainfo
sudo reboot
```
<img src="https://llm-assets.readthedocs.io/en/latest/_images/i915.png" width=100%; />
<img src="https://llm-assets.readthedocs.io/en/latest/_images/gawk.png" width=100%; />
* 配置权限
```bash
sudo gpasswd -a ${USER} render
newgrp render
# Verify the device is working with i915 driver
sudo apt-get install -y hwinfo
hwinfo --display
```
##### Linux 内核 6.5
* 根据你的 CPU 类型选择以下其中一个选项安装:
1. **选项 1**: 对于配备多个 A770 Arc GPU 的 `Intel Core CPU`,使用以下 repository
```bash
sudo apt-get install -y gpg-agent wget
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | \
sudo gpg --dearmor --output /usr/share/keyrings/intel-graphics.gpg
echo "deb [arch=amd64,i386 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy client" | \
sudo tee /etc/apt/sources.list.d/intel-gpu-jammy.list
```
2. **选项 2**: 对于配备多个 A770 Arc GPU 的 `Intel Xeon-W/SP CPU`,使用以下 repository 可获得更好的性能:
```bash
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | \
sudo gpg --yes --dearmor --output /usr/share/keyrings/intel-graphics.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy/lts/2350 unified" | \
sudo tee /etc/apt/sources.list.d/intel-gpu-jammy.list
sudo apt update
```
<img src="https://llm-assets.readthedocs.io/en/latest/_images/wget.png" width=100%; />
* 安装驱动程序
```bash
sudo apt-get update
# Install out-of-tree driver
sudo apt-get -y install \
gawk \
dkms \
linux-headers-$(uname -r) \
libc6-dev
sudo apt install -y intel-i915-dkms intel-fw-gpu
# Install Compute Runtime
sudo apt-get install -y udev \
intel-opencl-icd intel-level-zero-gpu level-zero \
intel-media-va-driver-non-free libmfx1 libmfxgen1 libvpl2 \
libegl-mesa0 libegl1-mesa libegl1-mesa-dev libgbm1 libgl1-mesa-dev libgl1-mesa-dri \
libglapi-mesa libgles2-mesa-dev libglx-mesa0 libigdgmm12 libxatracker2 mesa-va-drivers \
mesa-vdpau-drivers mesa-vulkan-drivers va-driver-all vainfo
sudo reboot
```
<img src="https://llm-assets.readthedocs.io/en/latest/_images/gawk.png" width=100%; />
* 配置权限
```bash
sudo gpasswd -a ${USER} render
newgrp render
# Verify the device is working with i915 driver
sudo apt-get install -y hwinfo
hwinfo --display
```
### 安装 oneAPI
IPEX-LLM 需要在 Linux 上安装适用于 Intel GPU 的 oneAPI 2024.0。
```bash
wget -O- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB | gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] https://apt.repos.intel.com/oneapi all main" | sudo tee /etc/apt/sources.list.d/oneAPI.list
sudo apt update
sudo apt install intel-oneapi-common-vars=2024.0.0-49406 \
intel-oneapi-common-oneapi-vars=2024.0.0-49406 \
intel-oneapi-diagnostics-utility=2024.0.0-49093 \
intel-oneapi-compiler-dpcpp-cpp=2024.0.2-49895 \
intel-oneapi-dpcpp-ct=2024.0.0-49381 \
intel-oneapi-mkl=2024.0.0-49656 \
intel-oneapi-mkl-devel=2024.0.0-49656 \
intel-oneapi-mpi=2021.11.0-49493 \
intel-oneapi-mpi-devel=2021.11.0-49493 \
intel-oneapi-dal=2024.0.1-25 \
intel-oneapi-dal-devel=2024.0.1-25 \
intel-oneapi-ippcp=2021.9.1-5 \
intel-oneapi-ippcp-devel=2021.9.1-5 \
intel-oneapi-ipp=2021.10.1-13 \
intel-oneapi-ipp-devel=2021.10.1-13 \
intel-oneapi-tlt=2024.0.0-352 \
intel-oneapi-ccl=2021.11.2-5 \
intel-oneapi-ccl-devel=2021.11.2-5 \
intel-oneapi-dnnl-devel=2024.0.0-49521 \
intel-oneapi-dnnl=2024.0.0-49521 \
intel-oneapi-tcm-1.0=1.0.0-435
```
<img src="https://llm-assets.readthedocs.io/en/latest/_images/oneapi.png" alt="image-20240221102252565" width=100%; />
<img src="https://llm-assets.readthedocs.io/en/latest/_images/basekit.png" alt="image-20240221102252565" width=100%; />
>[!IMPORTANT]
> 请务必在 GPU 驱动程序和 oneAPI 安装完成后重新启动机器:
>
> ```bash
> sudo reboot
> ```
### 设置 Python 环境
如果你的机器上没有安装 conda请按如下方式下载并安装 Miniforge
```bash
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh
source ~/.bashrc
```
你可以使用 `conda --version` 来确认 conda 已安装成功。
conda 安装完成后,创建一个新的 Python 环境 `llm`
```bash
conda create -n llm python=3.11
```
激活新创建的 `llm` 环境:
```bash
conda activate llm
```
## 安装 `ipex-llm`
在已激活的 `llm` 环境,使用 `pip` 安装适用于 GPU 的 `ipex-llm`。可根据区域选择不同的 `extra-index-url`,提供 US 和 CN 两个选项:
- **US**:
```bash
pip install --pre --upgrade ipex-llm[xpu] --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/
```
- **CN**:
```bash
pip install --pre --upgrade ipex-llm[xpu] --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/cn/
```
> [!NOTE]
> 如果在安装 IPEX 时遇到网络问题,请参阅[本指南](../Overview/install_gpu.md#install-ipex-llm-from-wheel-1)获取故障排除建议。
## 验证安装
- 你可以通过从库中导入一些类来验证 `ipex-llm` 是否安装成功。例如,在终端中执行以下导入命令:
```bash
source /opt/intel/oneapi/setvars.sh
python
> from ipex_llm.transformers import AutoModel, AutoModelForCausalLM
```
## 运行时配置
要在 Linux 上使用 GPU 加速,需要和推荐设置多个环境变量。根据你的 GPU 设备选择相应的配置:
- **Intel Arc™ A 系列和 Intel 数据中心 Flex 系列 GPU**:
对于 Intel Arc™ A 系列和 Intel 数据中心 Flex 系列 GPU推荐使用
```bash
# Configure oneAPI environment variables.
source /opt/intel/oneapi/setvars.sh
# Recommended Environment Variables for optimal performance
export USE_XETLA=OFF
export SYCL_CACHE_PERSISTENT=1
# [optional] under most circumstances, the following environment variable may improve performance, but sometimes this may also cause performance degradation
export SYCL_PI_LEVEL_ZERO_USE_IMMEDIATE_COMMANDLISTS=1
```
- **Intel 数据中心 Max 系列 GPU**:
我们建议使用如下环境变量:
```bash
# Configure oneAPI environment variables.
source /opt/intel/oneapi/setvars.sh
# Recommended Environment Variables for optimal performance
export LD_PRELOAD=${LD_PRELOAD}:${CONDA_PREFIX}/lib/libtcmalloc.so
export SYCL_CACHE_PERSISTENT=1
export ENABLE_SDP_FUSION=1
# [optional] under most circumstances, the following environment variable may improve performance, but sometimes this may also cause performance degradation
export SYCL_PI_LEVEL_ZERO_USE_IMMEDIATE_COMMANDLISTS=1
```
请注意 `libtcmalloc.so` 可以通过 `conda install -c conda-forge -y gperftools=2.10` 安装。
- **Intel iGPU**:
```bash
# Configure oneAPI environment variables.
source /opt/intel/oneapi/setvars.sh
export SYCL_CACHE_PERSISTENT=1
```
> [!NOTE]
> 有关运行时配置的更多详细信息,请参阅[本指南](../Overview/install_gpu.md#runtime-configuration-1)。
> [!NOTE]
> 环境变量 `SYCL_PI_LEVEL_ZERO_USE_IMMEDIATE_COMMANDLISTS` 用于控制是否使用即时命令列表将任务提交到 GPU。启动此变量通常可以提高性能但也有例外情况。因此建议你在启用和禁用该环境变量的情况下进行测试以找到最佳的性能设置。更多相关细节请参考[此处文档](https://www.intel.com/content/www/us/en/developer/articles/guide/level-zero-immediate-command-lists.html)。
## 快速示例
现在让我们体验一下真实的大型语言模型LLM。本示例将使用 [phi-1.5](https://huggingface.co/microsoft/phi-1_5) 模型一个具有13亿个参数的 LLM。请按照以下步骤设置和运行模型并观察它如何对提示 "What is AI?" 做出响应。
- 步骤 1激活之前创建的 `llm` Python 环境:
```bash
conda activate llm
```
- 步骤 2按照上述[运行时配置](#运行时配置)章节,准备运行时环境。
- 步骤 3创建一个名为 `demo.py` 新文件,并将如下代码复制进其中:
```python
# Copy/Paste the contents to a new file demo.py
import torch
from ipex_llm.transformers import AutoModelForCausalLM
from transformers import AutoTokenizer, GenerationConfig
generation_config = GenerationConfig(use_cache = True)
tokenizer = AutoTokenizer.from_pretrained("tiiuae/falcon-7b", trust_remote_code=True)
# load Model using ipex-llm and load it to GPU
model = AutoModelForCausalLM.from_pretrained(
"tiiuae/falcon-7b", load_in_4bit=True, cpu_embedding=True, trust_remote_code=True)
model = model.to('xpu')
# Format the prompt
question = "What is AI?"
prompt = " Question:{prompt}\n\n Answer:".format(prompt=question)
# Generate predicted tokens
with torch.inference_mode():
input_ids = tokenizer.encode(prompt, return_tensors="pt").to('xpu')
# warm up one more time before the actual generation task for the first run, see details in `Tips & Troubleshooting`
# output = model.generate(input_ids, do_sample=False, max_new_tokens=32, generation_config = generation_config)
output = model.generate(input_ids, do_sample=False, max_new_tokens=32, generation_config = generation_config).cpu()
output_str = tokenizer.decode(output[0], skip_special_tokens=True)
print(output_str)
```
> **提示**:
>
> 在内存有限的 Intel iGPU 上运行大语言模型时,我们建议在 `from_pretrained` 函数中设置 `cpu_embedding=True`。这将使内存占用较大的 embedding 层使用 CPU 而非 GPU。
- 步骤 4在已激活的 Python 环境中使用以下命令运行 `demo.py`
```bash
python demo.py
```
### 示例输出
以下是在一个配备第 11 代 Intel Core i7 CPU 和 Iris Xe Graphics iGPU 的系统上的示例输出:
```
Question:What is AI?
Answer: AI stands for Artificial Intelligence, which is the simulation of human intelligence in machines.
```
## 提示和故障排除
### 首次运行时进行 Warm-up 以获得最佳性能
首次在 GPU 上运行大语言模型时,你可能会注意到性能低于预期,在生成第一个 token 之前可能会有长达几分钟的延迟。发生这种延迟是因为 GPU 内核需要编译和初始化,这在不同类型的 GPU 之间会有所差异。为获得最佳稳定的性能,我们推荐在正式生成任务开始之前,额外运行一次 `model.generate(...)` 做为 warm-up。如果你正在开发应用程序你可以将此 warm-up 步骤集成到启动或加载流程中以加强用户体验。