r200_8f_xtrt_llm/examples/llama/README_CN.md

# LLaMA

本文档介绍了如何使用昆仑芯XTRT-LLM在单XPU和单节点多XPU上构建和运行LLaMA模型。

## 概述

XTRT-LLM LLMa示例代码位于 [`examples/llama`](./). 此文件夹中有以下几个主要文件：

 * [`build.py`](./build.py)  构建运行LLaMa模型所需的XTRT引擎
 * [`run.py`](./run.py)  基于输入的文字进行推理

## 支持的矩阵

  * FP16
  * INT8 Weight-Only
  * Tensor Parallel

## 使用说明

XTRT-LLM LLaMa示例代码位于[examples/llama](./)。它使用HF权重作为输入，并且构建对应的XTRT引擎。XTRT引擎的数量取决于为了运行推理而是用的XPU个数。

### 构建XTRT引擎

需要先按照下面的指南准备HF LLaMA checkpoint：https://huggingface.co/docs/transformers/main/en/model_doc/llama。

XTRT-LLM LLaMA从HF checkpoint构建XTRT引擎。如果未指定checkpoint目录，XTRT-LLM将使用伪权重构建引擎。

通常 `build.py`只需要单个XPU，但如果您已经获得了推理所需的所有XPU，则可以通过添加 `--parallel_build` 参数来启用并行构建，从而加快引擎构建过程。请注意，目前`parallel_build`仅支持单个节点XPU。

以下是一些示例：

```bash
# Build a single-XPU float16 engine from HF weights.
# use_gpt_attention_plugin is necessary in LLaMA.
# It is recommend to use --use_gpt_attention_plugin for better performance

# Build the LLaMA 7B model using a single XPU and FP16.
python build.py --model_dir ./downloads/llama-7b-hf/ \
                --dtype float16 \
                --use_gpt_attention_plugin float16 \
                --output_dir ./downloads/llama-7b-hf/trt_engines/fp16/1-XPU/


# Build the LLaMA 7B model using a single XPU and apply INT8 weight-only quantization.
python build.py --model_dir ./downloads/llama-7b-hf/ \
                --dtype float16 \
                --use_gpt_attention_plugin float16 \
                --use_weight_only \
                --output_dir ./downloads/llama-7b-hf/trt_engines/weight_only/1-XPU/

# Build LLaMA 7B using 2-way tensor parallelism.
python build.py --model_dir ./downloads/llama-7b-hf/ \
                --dtype float16 \
                --use_gpt_attention_plugin float16 \
                --output_dir ./downloads/llama-7b-hf/trt_engines/fp16/2-XPU/ \
                --world_size 2 \
                --tp_size 2 \
                --parallel_build


# Build LLaMA 13B using 2-way tensor parallelism.
python build.py --model_dir ./downloads/llama13b/ \
                --dtype float16 \
                --use_gpt_attention_plugin float16 \
                --output_dir ./downloads/llama13b/trt_engines/fp16/2-XPU/ \
                --world_size 2 \
                --tp_size 2 \
                --parallel_build
```

#### LLaMA v2 更新

LLaMA v2-7B和13B模型与 LLaMA v1的实现是兼容的，以上命令仍然有效。

对于LLaMA v2 70B，张量并行性有一个限制，即KV heads的数量必须可以被XPU的数量整除。例如，由于70B模型有8个KV heads，您可以使用2、4或8个XPU运行它。


```bash
# Build LLaMA 70B using 8-way tensor parallelism.
python build.py --model_dir ./downloads/llama2-70b/ \
                --dtype float16 \
                --use_gpt_attention_plugin float16 \
                --output_dir ./downloads/llama2-70b/trt_engines/fp16/8-XPU/ \
                --world_size 8 \
                --tp_size 8 \
                --parallel_build
```

相同的指令可以应用于LLaMA v2模型的微调版本（例如7Bf或LLaMA-2-7b-chat）。

使用`summarize.py`进行测试：`pip install nltk rouge_score`

```bash
python summarize.py --test_trt_llm \
                    --hf_model_location ./downloads/llama-7b-hf \
                    --data_type fp16 \
                    --engine_dir ./downloads/llama-7b-hf/trt_engines/fp16/1-XPU
```

#### SmoothQuant

SmoothQuant同时支持LLaMA v1和v2。与FP16的HF权重可以直接被处理并加载到XTRT-LLM不同，SmoothQuant需要加载INT8权重，而INT8权重在构建引擎之前需要进行预处理。

示例:
```bash
python3 hf_llama_convert.py -i ./downloads/llama-7b-hf -o ./downloads/smooth_llama_7B/sq0.8/ -sq 0.8 --tensor-parallelism 1 --storage-type fp16
```

注意：使用PyTorch运行`hf_llama_convert.py`，并且
1. 'torch-cpu' 通常比XPyTorch精度更高
2. XPyTorch 通常使用超过32GB的GM，因此需要更多的XPU来完成它。
3. 使用XPyTorch运行时，请添加`-p=1`。

为SmoothQuant 0.6的LLaMa 7B模型，我们提供这些[转换数据](https://fsh.bcebos.com/v1/klx-llm/pretrained_models/quantization/smooth_llama_7B.tar.gz)：

`build.py`增加了新的选项来支持SmoothQuant模型的INT8推理。

`--use_smooth_quant` 是INT8推理的起点。默认情况下，它将以`--per-token`模式运行模型。
`--per-token`和`--per-channel`目前还不支持。

构建调用实例：

```bash
# Build model for SmoothQuant in the _per_tensor_ mode.
python3 build.py --ft_model_dir=./downloads/smooth_llama_7B/sq0.8/1-XPU/ \
                 --use_smooth_quant \
                 --output_dir ./downloads/smooth_llama_7B/sq0.8/trt_engines/fp16/1-XPU/
```

注意：我们使用`--ft_model_dir`而不是`--model_dir`和`--meta_ckpt_dir`，因为SmoothQuant模型需要INT8权重和二进制文件中的各种scales。

### 运行

在运行示例之前，请确保设置环境变量：

```
export PYTORCH_NO_XPU_MEMORY_CACHING=0 # disable XPytorch cache XPU memory.
export XMLIR_D_XPU_L3_SIZE=0           # disable XPytorch use L3.
```

如果使用多个XPU且没有L3空间运行，则可以通过设置`BKCL_CCIX_BUFFER_GM=1`以禁用L3。

使用`build.py`生成的引擎运行XTRT-LLM LLaMA模型：

```bash
# With fp16 inference
python3 run.py --max_output_len=50 \
               --tokenizer_dir ./downloads/llama-7b-hf/ \
               --engine_dir=./downloads/llama-7b-hf/trt_engines/fp16/1-XPU/

# With fp16 inference, SmoothQuant
python3 run.py --max_output_len=50 \
               --tokenizer_dir ./downloads/llama-7b-hf/ \
               --engine_dir=./downloads/smooth_llama_7B/sq0.8/trt_engines/fp16/1-XPU/

```

### 使用LLaMA模型进行总结

```bash
# Run summarization using the LLaMA 7B model in FP16.
python summarize.py --test_trt_llm \
                    --hf_model_location ./downloads/llama-7b-hf/ \
                    --data_type fp16 \
                    --engine_dir ./downloads/llama-7b-hf/trt_engines/fp16/1-XPU/

# Run summarization using the LLaMA 7B model quantized to INT8.
python summarize.py --test_trt_llm \
                    --hf_model_location ./downloads/llama-7b-hf/ \
                    --data_type fp16 \
                    --engine_dir ./downloads/llama-7b-hf/trt_engines/weight_only/1-XPU/

# Run summarization using the LLaMA 7B model in FP16 using two XPUs.
mpirun -n 2 --allow-run-as-root \
    python summarize.py --test_trt_llm \
                        --hf_model_location ./downloads/llama-7b-hf/ \
                        --data_type fp16 \
                        --engine_dir ./downloads/llama-7b-hf/trt_engines/fp16/2-XPU/
```