Add more info, installation details, to the README (#30)

* Improve readme

* Update README.md

Co-authored-by: Daniël de Kok <me@danieldk.eu>

---------

Co-authored-by: Daniël de Kok <me@danieldk.eu>
This commit is contained in:
Lysandre Debut
2025-02-25 09:47:23 +01:00
committed by GitHub
parent 9426e7e290
commit af7fdf9202

View File

@ -1,6 +1,22 @@
# hf-kernels
Make sure you have `torch==2.5.1+cu124` installed.
The Kernel Hub allows Python libraries and applications to load compute
kernels directly from the [Hub](https://hf.co/). To support this kind
of dynamic loading, Hub kernels differ from traditional Python kernel
packages in that they are made to be:
- Portable: a kernel can be loaded from paths outside `PYTHONPATH`.
- Unique: multiple versions of the same kernel can be loaded in the
same Python process.
- Compatible: kernels must support all recent versions of Python and
the different PyTorch build configurations (various CUDA versions
and C++ ABIs). Furthermore, older C library versions must be supported.
## Usage
Kernels depends on `torch>=2.5` and CUDA for now.
Here is how you would use the [activation](https://huggingface.co/kernels-community/activation) kernels from the Hugging Face Hub:
```python
import torch
@ -20,6 +36,25 @@ activation.gelu_fast(y, x)
print(y)
```
These kernels can be built from the [kernel-builder library](https://github.com/huggingface/kernel-builder).
If you're looking to better understand how these kernels are structured, or looking to build your own kernels,
please take a look at the following guide:
[writing kernels](https://github.com/huggingface/kernel-builder/blob/main/docs/writing-kernels.md).
## Installation
To install `hf-kernels`, we recommend installing from the pypi package:
```bash
pip install hf-kernels
```
You should then be able to run the script above (also in [examples/basic.py](examples/basic.py)):
```bash
python examples/basic.py
```
## Docker Reference
build and run the reference [examples/basic.py](examples/basic.py) in a Docker container with the following commands:
@ -68,9 +103,8 @@ The pre-downloaded kernels are used by the `get_locked_kernel` function.
want kernel loading to error when a kernel is not pre-downloaded, you can use
the `load_kernel` function instead:
````python
```python
from hf_kernels import load_kernel
activation = load_kernel("kernels-community/activation")
````
```