Update release note and known issues (#4749)

* remove basekit activate & add OCL_ICD_VENDORS setting

* add python execution example

* update CCL_ROOT setting with multi-gpu usage

* update compile bundle bat branch to release tag

* update example in getting started

* correct version of intel-level-zero-gpu

* remove deprecated api

* set version of accelerate for finetune

* fix model name

* Update deepspeed in requirements.txt

* update release note and known issue

* update ipex.llm.optimize

* update IPEX_LOG

---------

Co-authored-by: Jing Xu <[email protected]>
Co-authored-by: jundu <[email protected]>
Co-authored-by: Ye Ting <[email protected]>
Co-authored-by: zhuyuhua-v <[email protected]>

Author: 5 people

README.md

@@ -23,7 +23,7 @@ The extension can be loaded as a Python module for Python programs or linked as
 
 In the current technological landscape, Generative AI (GenAI) workloads and models have gained widespread attention and popularity. Large Language Models (LLMs) have emerged as the dominant models driving these GenAI applications. Starting from 2.1.0, specific optimizations for certain LLM models are introduced in the Intel® Extension for PyTorch\*. Check [LLM optimizations CPU](./examples/cpu/inference/python/llm) and [LLM optimizations GPU](./examples/gpu/llm) for details.
 
-### Optimized Model List 
+### Validated Model List 
 
 #### LLM Inference
 

csrc/gpu/utils/LogImpl.cpp

@@ -15,7 +15,7 @@ spdlog::level::level_enum get_log_level_from_int(int level) {
     return spdlog::level::critical;
   } else {
     throw std::runtime_error(
-        "USING error log level for IPEX_LOGGING, log level should be -1 to 5, but met " +
+        "USING error log level for IPEX_LOG, log level should be -1 to 5, but met " +
         std::string{level});
   }
 }
@@ -231,7 +231,7 @@ void EventLogger::print_result(int log_level) {
     if (this->message_queue.size() >= 2) {
       auto next_time = this->message_queue.front().timestamp;
       auto next_step = this->message_queue.front().step_id;
-      // inside IPEX_LOGGING we are using nanoseconds, 1ns = 0.001us, cast to us
+      // inside IPEX_LOG we are using nanoseconds, 1ns = 0.001us, cast to us
       // here
       auto time_step = static_cast<float>((next_time - this_time) / 1000);
       log_result_with_args(
@@ -283,3 +283,4 @@ void BasicLogger::update_logger() {
   logger->set_pattern("[%c %z] [%l] [thread %t] %v");
   spdlog::set_default_logger(logger);
 }
+

docs/tutorials/api_doc.rst

@@ -6,66 +6,12 @@ General
 
 .. currentmodule:: intel_extension_for_pytorch
 .. autofunction:: optimize
-.. autofunction:: optimize_transformers
+.. currentmodule:: intel_extension_for_pytorch.llm
+.. autofunction:: optimize
+.. currentmodule:: intel_extension_for_pytorch
 .. autofunction:: get_fp32_math_mode
 .. autofunction:: set_fp32_math_mode
 
-
-Miscellaneous
-=============
-
-.. currentmodule:: intel_extension_for_pytorch.xpu
-.. StreamContext
-.. can_device_access_peer
-.. current_blas_handle
-.. autofunction:: current_device
-.. autofunction:: current_stream
-.. default_stream
-.. autoclass:: device
-.. autofunction:: device_count
-.. autoclass:: device_of
-.. autofunction:: get_device_name
-.. autofunction:: get_device_properties
-.. get_gencode_flags
-.. get_sync_debug_mode
-.. autofunction:: init
-.. ipc_collect
-.. autofunction:: is_available
-.. autofunction:: is_initialized
-.. memory_usage
-.. autofunction:: set_device
-.. set_stream
-.. autofunction:: stream
-.. autofunction:: synchronize
-
-.. currentmodule:: intel_extension_for_pytorch.xpu.fp8.fp8
-.. autofunction:: fp8_autocast
-
-
-Random Number Generator
-=======================
-
-.. currentmodule:: intel_extension_for_pytorch.xpu
-.. autofunction:: get_rng_state
-.. autofunction:: get_rng_state_all
-.. autofunction:: set_rng_state
-.. autofunction:: set_rng_state_all
-.. autofunction:: manual_seed
-.. autofunction:: manual_seed_all
-.. autofunction:: seed
-.. autofunction:: seed_all
-.. autofunction:: initial_seed
-
-Streams and events
-==================
-
-.. currentmodule:: intel_extension_for_pytorch.xpu
-.. autoclass:: Stream
-    :members: 
-.. ExternalStream
-.. autoclass:: Event
-    :members: 
-
 Memory management
 =================
 
@@ -92,9 +38,17 @@ Memory management
 .. autofunction:: memory_stats_as_nested_dict
 .. autofunction:: reset_accumulated_memory_stats
 
+
+Quantization
+============
+
+.. currentmodule:: intel_extension_for_pytorch.quantization.fp8
+.. autofunction:: fp8_autocast
+
+
 C++ API
 =======
 
-.. doxygenenum:: xpu::FP32_MATH_MODE
+.. doxygenenum:: torch_ipex::xpu::FP32_MATH_MODE
 
-.. doxygenfunction:: xpu::set_fp32_math_mode
+.. doxygenfunction:: torch_ipex::xpu::set_fp32_math_mode

docs/tutorials/features.rst

@@ -137,19 +137,6 @@ For more detailed information, check `torch.compile for GPU <features/torch_comp
 
    features/torch_compile_gpu
 
-Simple Trace Tool (Prototype)
------------------------------
-
-Simple Trace is a built-in debugging tool that lets you control printing out the call stack for a piece of code. Once enabled, it can automatically print out verbose messages of called operators in a stack format with indenting to distinguish the context. 
-
-For more detailed information, check `Simple Trace Tool <features/simple_trace.md>`_.
-
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-
-   features/simple_trace
-
 Kineto Supported Profiler Tool (Prototype)
 ------------------------------------------
 
@@ -178,13 +165,13 @@ For more detailed information, check `Compute Engine <features/compute_engine.md
    features/compute_engine
 
 
-``IPEX_LOGGING`` (Prototype feature for debug)
-----------------------------------------------
+``IPEX_LOG`` (Prototype feature for debug)
+------------------------------------------
 
 
-``IPEX_LOGGING`` provides the capability to log verbose information from Intel® Extension for PyTorch\* . Please use ``IPEX_LOGGING`` to get the log information or trace the execution from Intel® Extension for PyTorch\*. Please continue using PyTorch\* macros such as ``TORCH_CHECK``, ``TORCH_ERROR``, etc. to get the log information from PyTorch\*.
+``IPEX_LOG`` provides the capability to log verbose information from Intel® Extension for PyTorch\* . Please use ``IPEX_LOG`` to get the log information or trace the execution from Intel® Extension for PyTorch\*. Please continue using PyTorch\* macros such as ``TORCH_CHECK``, ``TORCH_ERROR``, etc. to get the log information from PyTorch\*.
 
-For more detailed information, check `IPEX_LOGGING <features/ipex_log.md>`_.
+For more detailed information, check `IPEX_LOG <features/ipex_log.md>`_.
 
 .. toctree::
    :hidden:
@@ -193,3 +180,4 @@ For more detailed information, check `IPEX_LOGGING <features/ipex_log.md>`_.
    features/ipex_log
 
 
+

docs/tutorials/features/ipex_log.md

@@ -1,11 +1,11 @@
-`IPEX_LOGGING` (Prototype)
+`IPEX_LOG` (Prototype)
 ==========================
 
 ## Introduction
 
-`IPEX_LOGGING` provides the capability to log verbose information from Intel® Extension for PyTorch\* . Please use `IPEX_LOGGING` to get the log information or trace the execution from Intel® Extension for PyTorch\*. Please continue using PyTorch\* macros such as `TORCH_CHECK`, `TORCH_ERROR`, etc. to get the log information from PyTorch\*.
+`IPEX_LOG` provides the capability to log verbose information from Intel® Extension for PyTorch\* . Please use `IPEX_LOG` to get the log information or trace the execution from Intel® Extension for PyTorch\*. Please continue using PyTorch\* macros such as `TORCH_CHECK`, `TORCH_ERROR`, etc. to get the log information from PyTorch\*.
 
-## `IPEX_LOGGING` Definition
+## `IPEX_LOG` Definition
 ### Log Level
 The supported log levels are defined as follows, default log level is `DISABLED`:
 
@@ -81,3 +81,4 @@ Use `torch.xpu.set_log_level(0)` to get logs to replace the previous usage in `I
 
 ## Replace `IPEX_VERBOSE`
 Use `torch.xpu.set_log_level(1)` to get logs to replace the previous usage in `IPEX_VERBOSE`.
+

docs/tutorials/features/simple_trace.md

@@ -1,5 +1,5 @@
-Simple Trace Tool (Prototype)
-=============================
+Simple Trace Tool (Deprecated)
+==============================
 
 ## Introduction
 

docs/tutorials/getting_started.md

@@ -32,9 +32,9 @@ model = ipex.optimize(model, dtype=dtype)
 ########## FP32 ############
 with torch.no_grad():
 ####### BF16 on CPU ########
-with torch.no_grad(), with torch.cpu.amp.autocast():
+with torch.no_grad(), torch.cpu.amp.autocast():
 ##### BF16/FP16 on GPU #####
-with torch.no_grad(), with torch.xpu.amp.autocast(enabled=True, dtype=dtype, cache_enabled=False):
+with torch.no_grad(), torch.xpu.amp.autocast(enabled=True, dtype=dtype, cache_enabled=False):
 ############################
   ###### Torchscript #######
   model = torch.jit.trace(model, data)
@@ -49,13 +49,14 @@ More examples, including training and usage of low precision data types are avai
 
 ## Execution
 
-Execution requires an active Intel® oneAPI environment. Suppose you have the Intel® oneAPI Base Toolkit installed in `/opt/intel/oneapi` directory, activating the environment is as simple as sourcing its environment activation bash scripts.
-
 There are some environment variables in runtime that can be used to configure executions on GPU. Please check [Advanced Configuration](./features/advanced_configuration.html#runtime-configuration) for more detailed information.
 
+Set `OCL_ICD_VENDORS` with default path `/etc/OpenCL/vendors`.
+Set `CCL_ROOT` if you are using multi-GPU.
+
 ```bash
-source /opt/intel/oneapi/compiler/latest/env/vars.sh
-source /opt/intel/oneapi/mkl/latest/env/vars.sh
+export OCL_ICD_VENDORS=/etc/OpenCL/vendors
+export CCL_ROOT=${CONDA_PREFIX} 
 python <script>
 ```
 

docs/tutorials/known_issues.md

@@ -4,44 +4,40 @@ Troubleshooting
 ## General Usage
 
 - **Problem**: FP64 data type is unsupported on current platform.
-  - **Cause**: FP64 is not natively supported by the [Intel® Data Center GPU Flex Series](https://www.intel.com/content/www/us/en/products/docs/discrete-gpus/data-center-gpu/flex-series/overview.html) and [Intel® Arc™ A-Series Graphics](https://www.intel.com/content/www/us/en/products/details/discrete-gpus/arc.html) platforms. 
+  - **Cause**: FP64 is not natively supported by the [Intel® Data Center GPU Flex Series](https://www.intel.com/content/www/us/en/products/docs/discrete-gpus/data-center-gpu/flex-series/overview.html) and [Intel® Arc™ A-Series Graphics](https://www.intel.com/content/www/us/en/products/details/discrete-gpus/arc.html) platforms.
     If you run any AI workload on that platform and receive this error message, it means a kernel requires FP64 instructions that are not supported and the execution is stopped.
-- **Problem**: Runtime error `invalid device pointer` if `import horovod.torch as hvd` before `import intel_extension_for_pytorch`
+- **Problem**: Runtime error `invalid device pointer` if `import horovod.torch as hvd` before `import intel_extension_for_pytorch`.
   - **Cause**: Intel® Optimization for Horovod\* uses utilities provided by Intel® Extension for PyTorch\*. The improper import order causes Intel® Extension for PyTorch\* to be unloaded before Intel®
     Optimization for Horovod\* at the end of the execution and triggers this error.
   - **Solution**: Do `import intel_extension_for_pytorch` before `import horovod.torch as hvd`.
 - **Problem**: Number of dpcpp devices should be greater than zero.
-  - **Cause**: If you use Intel® Extension for PyTorch* in a conda environment, you might encounter this error. Conda also ships the libstdc++.so dynamic library file that may conflict with the one shipped
-    in the OS. 
+  - **Cause**: If you use Intel® Extension for PyTorch\* in a conda environment, you might encounter this error. Conda also ships the libstdc++.so dynamic library file that may conflict with the one shipped
+    in the OS.
   - **Solution**: Export the `libstdc++.so` file path in the OS to an environment variable `LD_PRELOAD`.
 - **Problem**: Symbol undefined caused by `_GLIBCXX_USE_CXX11_ABI`.
     ```bash
     ImportError: undefined symbol: _ZNK5torch8autograd4Node4nameB5cxx11Ev
     ```
   - **Cause**: DPC++ does not support `_GLIBCXX_USE_CXX11_ABI=0`, Intel® Extension for PyTorch\* is always compiled with `_GLIBCXX_USE_CXX11_ABI=1`. This symbol undefined issue appears when PyTorch\* is
     compiled with `_GLIBCXX_USE_CXX11_ABI=0`.
-  - **Solution**: Pass `export GLIBCXX_USE_CXX11_ABI=1` and compile PyTorch\* with particular compiler which supports `_GLIBCXX_USE_CXX11_ABI=1`. We recommend using prebuilt wheels 
+  - **Solution**: Pass `export GLIBCXX_USE_CXX11_ABI=1` and compile PyTorch\* with particular compiler which supports `_GLIBCXX_USE_CXX11_ABI=1`. We recommend using prebuilt wheels
     in [download server](https:// developer.intel.com/ipex-whl-stable-xpu) to avoid this issue.
-- **Problem**: Bad termination after AI model execution finishes when using Intel MPI.
-  - **Cause**: This is a random issue when the AI model (e.g. RN50 training) execution finishes in an Intel MPI environment. It is not user-friendly as the model execution ends ungracefully. It has been fixed in PyTorch* 2.3 ([#116312](https://github.com/pytorch/pytorch/commit/f657b2b1f8f35aa6ee199c4690d38a2b460387ae)). 
-  - **Solution**: Add `dist.destroy_process_group()` during the cleanup stage in the model script, as described 
-    in [Getting Started with Distributed Data Parallel](https://pytorch.org/tutorials/intermediate/ddp_tutorial.html), before Intel® Extension for PyTorch* supports PyTorch* 2.3.
 - **Problem**: `-997 runtime error` when running some AI models on Intel® Arc™ A-Series GPUs.
-  - **Cause**:  Some of the `-997 runtime error` are actually out-of-memory errors. As Intel® Arc™ A-Series GPUs have less device memory than Intel® Data Center GPU Flex Series 170 and Intel® Data Center GPU 
+  - **Cause**:  Some of the `-997 runtime error` are actually out-of-memory errors. As Intel® Arc™ A-Series GPUs have less device memory than Intel® Data Center GPU Flex Series 170 and Intel® Data Center GPU
     Max  Series, running some AI models on them may trigger out-of-memory errors and cause them to report failure such as `-997 runtime error` most likely. This is expected. Memory usage optimization is a work in progress to allow Intel® Arc™ A-Series GPUs to support more AI models.
 - **Problem**: Building from source for Intel® Arc™ A-Series GPUs fails on WSL2 without any error thrown.
   - **Cause**: Your system probably does not have enough RAM, so Linux kernel's Out-of-memory killer was invoked. You can verify this by running `dmesg` on bash (WSL2 terminal).
-  - **Solution**: If the OOM killer had indeed killed the build process, then you can try increasing the swap-size of WSL2, and/or decreasing the number of parallel build jobs with the environment 
+  - **Solution**: If the OOM killer had indeed killed the build process, then you can try increasing the swap-size of WSL2, and/or decreasing the number of parallel build jobs with the environment
     variable `MAX_JOBS` (by default, it's equal to the number of logical CPU cores. So, setting `MAX_JOBS` to 1 is a very conservative approach that would slow things down a lot).
 - **Problem**: Some workloads terminate with an error `CL_DEVICE_NOT_FOUND` after some time on WSL2.
   - **Cause**:  This issue is due to the [TDR feature](https://learn.microsoft.com/en-us/windows-hardware/drivers/display/tdr-registry-keys#tdrdelay) on Windows.
   - **Solution**: Try increasing TDRDelay in your Windows Registry to a large value, such as 20 (it is 2 seconds, by default), and reboot.
 - **Problem**: Random bad termination after AI model convergence test (>24 hours) finishes.
   - **Cause**: This is a random issue when some AI model convergence test execution finishes. It is not user-friendly as the model execution ends ungracefully.
   - **Solution**: Kill the process after the convergence test finished, or use checkpoints to divide the convergence test into several phases and execute separately.
-- **Problem**: Random instability issues such as page fault or atomic access violation when executing LLM inference workloads on Intel® Data Center GPU Max series cards.
-  - **Cause**:  This issue is reported on LTS driver [803.29](https://dgpu-docs.intel.com/releases/LTS_803.29_20240131.html). The root cause is under investigation.
-  - **Solution**: Use active rolling stable release driver [775.20](https://dgpu-docs.intel.com/releases/stable_775_20_20231219.html) or latest driver version to workaround.
+- **Problem**: Runtime error `munmap_chunk(): invalid pointer` when executing some scaling LLM workloads on Intel® Data Center GPU Max Series platform
+  - **Cause**: Users targeting GPU use, must set the environment variable ‘FI_HMEM=system’ to disable GPU support in underlying libfabric as Intel® MPI Library 2021.13.1 will offload the GPU support instead. This avoids a potential bug in libfabric GPU initialization.
+  - **Solution**: Set the environment variable ‘FI_HMEM=system’ to workaround this issue when encounter.
 
 ## Library Dependencies
 
@@ -54,7 +50,7 @@ Troubleshooting
   /usr/bin/ld: cannot find -lmkl_tbb_thread
   dpcpp: error: linker command failed with exit code 1 (use -v to see invocation)
   ```
-  
+
   - **Cause**: When PyTorch\* is built with oneMKL library and Intel® Extension for PyTorch\* is built without MKL library, this linker issue may occur.
   - **Solution**: Resolve the issue by setting:
 
@@ -66,8 +62,8 @@ Troubleshooting
    Then clean build Intel® Extension for PyTorch\*.
 
 - **Problem**: Undefined symbol: `mkl_lapack_dspevd`. Intel MKL FATAL ERROR: cannot load `libmkl_vml_avx512.so.2` or `libmkl_vml_def.so.2.
-  - **Cause**: This issue may occur when Intel® Extension for PyTorch\* is built with oneMKL library and PyTorch\* is not build with any MKL library. The oneMKL kernel may run into CPU backend incorrectly 
-    and trigger this issue. 
+  - **Cause**: This issue may occur when Intel® Extension for PyTorch\* is built with oneMKL library and PyTorch\* is not build with any MKL library. The oneMKL kernel may run into CPU backend incorrectly
+    and trigger this issue.
   - **Solution**: Resolve the issue by installing the oneMKL library from conda:
 
     ```bash
@@ -87,14 +83,30 @@ Troubleshooting
 
     If you continue seeing similar issues for other shared object files, add the corresponding files under `${MKL_DPCPP_ROOT}/lib/intel64/` by `LD_PRELOAD`. Note that the suffix of the libraries may change (e.g. from .1 to .2), if more than one oneMKL library is installed on the system.
 
+- **Problem**: RuntimeError: could not create an engine.
+  - **Cause**: `OCL_ICD_VENDORS` path is wrongly set when activate a exist conda environment.
+  - **Solution**: `export OCL_ICD_VENDORS=/etc/OpenCL/vendors` after `conda activate`
+
+- **Problem**: If you encounter issues related to CCL environment variable configuration when running distributed tasks.
+  - **Cause**: `CCL_ROOT` path is wrongly set.
+  - **Solution**: `export CCL_ROOT=${CONDA_PREFIX}`
 
-## Performance Issue 
+- **Problem**: If you encounter issues related to MPI environment variable configuration when running distributed tasks.
+  - **Cause**: MPI environment variable configuration not correct.
+  - **Solution**: `conda deactivate` and then `conda activate` to activate the correct MPI environment variable automatically.
+
+    ```
+    conda deactivate
+    conda activate
+    export OCL_ICD_VENDORS=/etc/OpenCL/vendors
+    ```
+
+## Performance Issue
 
 - **Problem**: Extended durations for data transfers from the host system to the device (H2D) and from the device back to the host system (D2H).
   - **Cause**: Absence of certain Dynamic Kernel Module Support (DKMS) packages on Ubuntu 22.04 or earlier versions.
   - **Solution**: For those running Ubuntu 22.04 or below, it's crucial to follow all the recommended installation procedures, including those labeled as [optional](https://dgpu-docs.intel.com/driver/client/overview.html#optional-out-of-tree-kernel-mode-driver-install). These steps are likely necessary to install the missing DKMS packages and ensure your system is functioning optimally. The Kernel Mode Driver (KMD) package that addresses this issue has been integrated into the Linux kernel for Ubuntu 23.04 and subsequent releases.
 
-
 ## Unit Test
 
 - Unit test failures on Intel® Data Center GPU Flex Series 170