Skip to content

Commit

Permalink
Update install.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@hozen-groq
hozen-groq authored Dec 3, 2023
1 parent 5f5c5c2 commit a55ae79
Showing 1 changed file with 39 additions and 60 deletions.
99 changes: 39 additions & 60 deletions docs/install.md
View file
Original file line number Diff line number Diff line change
@@ -1,40 +1,29 @@
# GroqFlow™ Installation Guide

The following describes how to install GroqFlow. These instructions enable users to build models for Groq hardware, as well as execute those builds in systems that have GroqCard™ accelerators physically installed.

## Prerequisites

### Check your versions

- Ensure that you are using one of the following Linux distributions: Ubuntu 22.04 or Rocky 8.4.
- Download and install the GroqWare™ Suite version >=0.9.2.1.
- For more information, see the GroqWare Quick Start Guide at [support.groq.com](https://support.groq.com).
- To compile your model for Groq hardware, GroqFlow requires the Groq Developer Tools Package (groq-devtools). To run your compiled model on hardware, GroqFlow requires the Groq Runtime Package (groq-runtime).
The following includes the instructions for installation of GroqFlow.

## Step 1. Confirm Versions
Make sure that your combination of GroqWare™ Suite version, OS version, and Python version are compatible. Our supported matrix of versions is:

| GroqWare | OS | Python Version |
|-----------|--------------|----------------|
| 0.9.2.1 | Ubuntu 22.04 | 3.10 |
| 0.9.3 | Ubuntu 18.04 | 3.8 |
| 0.9.3 | Ubuntu 22.04 | 3.8 |
| 0.9.3 | Rocky 8.4 | 3.8 |
| 0.10.0 | Ubuntu 22.04 | 3.10 |
| 0.10.0 | Rocky 8.4 | 3.8 |
| GroqWare Version | OS Version | Python Version |
|------------------|--------------|----------------|
| 0.10.0 | Ubuntu 22.04 | 3.10 |
| 0.10.0 | Rocky 8.4 | 3.8 |
| 0.9.3 | Ubuntu 22.04 | 3.8 |
| 0.9.3 | Rocky 8.4 | 3.8 |
| 0.9.3 | Ubuntu 18.04 | 3.8 |
| 0.9.2.1 | Ubuntu 22.04 | 3.10 |

### Install GroqWare
## Step 2. Download and install the GroqWare Suite version >=0.9.2.1
Create an account or log in on our [portal](https://support.groq.com) to see the [GroqWare Quick Start Guide](https://support.groq.com/#/downloads/view/groqware-qsg) for installation instructions.

Download and install the GroqWare Suite version >=0.9.2.1.
- For more information, see the GroqWare Quick Start Guide at [support.groq.com](https://support.groq.com).
- To compile your model for Groq hardware, GroqFlow requires the Groq Developer Tools Package (groq-devtools). To run your compiled model on hardware, GroqFlow requires the Groq Runtime Package (groq-runtime).
If you have Groq hardware, install both the Groq Developer Tools Package (groq-devtools) and the Groq Runtime Package (groq-runtime) to both build and run models on hardware.

## Trying out GroqFlow
If you do not have Groq hardware, install the Groq Developer Tools Package (groq-devtools) to build and compile models to estimate performance.

If you want to try out GroqFlow by running the [examples](https://github.com/groq/groqflow/tree/main/examples) and [proof points](https://github.com/groq/groqflow/tree/main/proof_points), we recommend that you take the following steps. If you want to use GroqFlow with your own environment and model, we suggest skipping ahead to [Developing with GroqFlow](#developing-with-groqflow).
## Step 3. Create and activate a virtual Conda environment

### Step 1: Create and activate a virtual environment

First, download, install, and create a Miniconda virtual environment.
Download, install, and create a Miniconda virtual environment by copying and pasting the following commands into your terminal:

```
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
Expand All @@ -44,13 +33,12 @@ conda deactivate
conda activate groqflow
```

Where `$GF_PYTHON_VERSION` is the version of Python corresponding to your OS and GroqWare version in the [compatibility chart](#check-your-versions) above.

> _Note_: it is important to deactivate your base conda environment when first setting up a new groqflow environment. This helps to prevent conda from making unwanted changes in the PATHs of your environments.
Where `$GF_PYTHON_VERSION` is the version of Python corresponding to your OS and GroqWare version in the [compatibility chart](#step-1-confirm-versions) above.

### Step 2: Pip install GroqFlow
> _Note_: It is important to deactivate your base Conda environment when first setting up a new GroqFlow environment. This helps to prevent Conda from making unwanted changes in the PATHs of your environments.
Install the `groqflow` package into your virtual environment:
## Step 4. Pip install GroqFlow
If you are developing a **Pytorch, ONNX,** or **Hummingbird** model, install the `groqflow` package into your virtual environment by copying and pasting the following commands into your terminal:

```
git clone https://github.com/groq/groqflow.git
Expand All @@ -59,29 +47,35 @@ cd groqflow
pip install .
```

where `groqflow` is the directory where you cloned the GroqFlow repo in the [prerequisites](#prerequisites).

_Optional_: if you want to use GroqFlow with TensorFlow, use this install command instead of `pip install .`:
If you are developing a **Keras** model, use the following command instead of `pip install .`:

```
pip install .[tensorflow]
```

### Step 3: Add GroqWare Suite to Python Path
**Note:** Use separate Conda environments for PyTorch/ONNX/Hummingbird development vs. TensorFlow development. Do not `pip install groqflow[tensorflow]` into an environment where you already did `pip install groqflow`, as this will cause errors.

## Step 5. Add GroqWare Suite to Python Path

This adds the Groq tools to your path:
Copy and paste the following into your terminal to add GroqWare Suite to your PATH:

```
conda env config vars set PYTHONPATH="/opt/groq/runtime/site-packages:$PYTHONPATH"
```

**Note:** you will need to reactivate your conda environment for this to take effect.

**Note:** if you encounter errors later that say GroqFlow is unable to find a tool from the GroqWare suite (Groq API, Groq Runtime, Groq DevTools, Groq Compiler, etc.) it usually means either:
**Note:** If you encounter errors later that say GroqFlow is unable to find a tool from GroqWare Suite (Groq API, Groq Runtime, Groq DevTools, Groq Compiler, etc.), it usually means either:
- You forgot to complete this step.
- Your GroqWare Suite installation failed and you should attempt to re-install the GroqWare Suite.
- Your GroqWare Suite installation failed and you should reinstall GroqWare Suite following all the required steps outlined in the [GroqWare Quick Start Guide](https://support.groq.com/#/downloads/view/groqware-qsg).

### Step 4: Rock-It with groqit()
## Step 6. Reactivate your Conda environment
Copy and paste the following into your terminal for the PATH modification in the previous step to take effect:

```
conda deactivate
conda activate groqflow
```

## Step 7. Rock it 🚀 with `groqit()`

To confirm that you're setup correctly, navigate to the examples folder at `groqflow/examples/` and run the `hello_world.py` example that can be found in the `keras`, `onnx`, and `pytorch` folder depending on your preferred framework:

Expand All @@ -90,28 +84,13 @@ cd groqflow/examples/<framework>
python hello_world.py
```

### Step 5: Take-off with a Proof Point
## Step 8. (Recommended) Take off 🚀 with a Proof Point

Included in the directory: `groqflow/proof_points`, are multiple examples of various machine learning and linear algebra workloads. To run these proof points, the `groqflow/demo_helpers` must be installed in your groqflow environment.
Included in the `groqflow/proof_points` directory are various machine learning models and linear algebra workloads. To run these proof points, install `groqflow/demo_helpers` in your `groqflow` environment:

```
cd groqflow/demo_helpers/
pip install -e .
```

Then you can learn about how to run proof points [here](https://github.com/groq/groqflow/tree/main/proof_points).

## Developing with GroqFlow

When you are ready to try out your own model with GroqFlow, we recommend taking the following steps:

1. Activate the conda virtual environment where you are able to run your model
1. Install the GroqFlow package from PyPI:
- If you are developing a PyTorch, ONNX, or Hummingbird model, use `pip install groqflow`
- If you are developing a Keras model, use `pip install groqflow[tensorflow]`
1. Follow steps 3 and 4 in [Testing Out GroqFlow](#testing-out-groqflow) to complete setup
1. Import `groqflow` into the script where you are running your model and call `groqit(model, inputs)` to build your model (see the [examples](https://github.com/groq/groqflow/tree/main/examples) to learn more about calling `groqit()`)

**Note:** The supported Python/OS combinations in [Check your Versions](#check-your-versions) apply here as well.

**Note:** We recommend using separate conda environments for PyTorch/ONNX/Hummingbird development vs. TensorFlow development. The reason we make TensorFlow support optional in GroqFlow is to help you avoid dependency conflicts between the TensorFlow package and the other Groq/GroqFlow dependencies. Do not `pip install groqflow[tensorflow]` into an environment where you already did `pip install groqflow`, as this will cause errors.
You can learn more about how to run proof points [here](https://github.com/groq/groqflow/tree/main/proof_points)!

0 comments on commit a55ae79

Please sign in to comment.