diff --git a/docs/install.md b/docs/install.md index 4c9382d..b86869e 100644 --- a/docs/install.md +++ b/docs/install.md @@ -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 @@ -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 @@ -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: @@ -90,28 +84,13 @@ cd groqflow/examples/ 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)!