⚙️ Heurist Miner Setup Guide

Introduction

Welcome to the Heurist Miner, the entrance to decentralized generative AI. Whether you have a high-end gaming PC with NVIDIA GPU or you're a datacenter owner ready to explore the world of AI and cryptocurrency, this guide will help you get started on an exciting journey!

What is Heurist Miner?

Heurist Miner allows you to contribute your GPU to perform AI inference tasks on the Heurist network. By running this miner, you'll earn rewards by hosting AI models and supporting various applications in Heurist ecosystem.

Key Features ✨

🖼️ Dual Mining Capabilities: Support for both image generation models and Large Language Models.
🖥️ Flexible Setup: Run on Windows or Linux, with support for multiple GPUs.
🔐 Secure Rewards: Utilizes a dual-wallet system for enhanced security.
🌐 Open Source: The code is fully open and transparent. Download and run with ease.

System Requirements

Before you begin, ensure your system meets the following requirements:

Hardware 🖥️

GPU: NVIDIA GPU with at least 12GB VRAM (24GB+ recommended for optimal performance)
CPU: Multi-core processor (4+ cores recommended)
RAM: 16GB+ system RAM
Storage: At least 50GB free space (NVMe recommended for faster model loading)

Software 💾

Operating System:
- Windows 10/11 (64-bit)
- Linux (Ubuntu 20.04 LTS or later recommended)
CUDA: Version 12.1, or 12.2
Python: Version 3.10 or 3.11
Git: For cloning the repository

Network 🌐

Stable internet connection (100 Mbps+ recommended)
Ability to access HuggingFace and GitHub repositories

Additional Notes ℹ️

Some models (especially larger LLMs) may require more VRAM. Check the model-specific requirements in the detailed setup sections.
Ensure your system is up-to-date with the latest NVIDIA GPU drivers.
Stable Diffusion models need at least 8-10GB VRAM, while LLMs can require 16GB to 40GB+ depending on the model size.

Quick Start Guide

Local Setup

For experienced users, here's a quick overview to get you mining:

Clone the Repository

git clone https://github.com/heurist-network/miner-release.git
cd miner-release

Set Up Environment

Install Miniconda (if not already installed)
Create and activate a new conda environment:

conda create --name heurist-miner python=3.11
conda activate heurist-miner

Install Dependencies

pip install -r requirements.txt

Configure Miner ID

Create a .env file in the root directory
Add your Ethereum wallet address:

MINER_ID_0=0xYourWalletAddressHere

Follow "Multiple GPU Configuration" section if you have multiple GPUs.

Choose Your Miner

For Stable Diffusion:

python sd-miner.py

For LLM:

./llm-miner-starter.sh <model_id>

For detailed instructions, troubleshooting, and advanced configuration, please refer to the sections below.

Docker Setup

(current version only supports Flux model)

For users who prefer using Docker, follow these steps:

Build the Docker Image

docker build -t heurist-miner:latest .

Run the Docker Container

Single GPU:

sudo docker run -d --gpus all \
  -e MINER_ID_0=0xWalletAddressHere \
  -e LOG_LEVEL=INFO \
  -v $HOME/.cache/heurist:/app/.cache/heurist \
  heurist-miner:latest

Replace 0xYourWalletAddressHere with your wallet address to receive rewards.

Multiple GPUs:

sudo docker run -d --gpus all \
  -e MINER_ID_0=0xYourFirstWalletAddressHere \
  -e MINER_ID_1=0xYourSecondWalletAddressHere \
  -e MINER_ID_2=0xYourThirdWalletAddressHere \
  -e LOG_LEVEL=INFO \
  -v $HOME/.cache/heurist:/app/.cache/heurist \
  heurist-miner:latest

Replace 0xYourFirstWalletAddressHere, 0xYourSecondWalletAddressHere, and 0xYourThirdWalletAddressHere with your actual wallet addresses.

This command:

Runs the container in detached mode (-d)
Allows access to all GPUs (--gpus all)
Sets environment variables for miner IDs and log level
Mounts a volume for persistent cache storage
Uses the image we just built (heurist-miner:latest)

Note: Ensure you have the NVIDIA Container Toolkit installed for GPU support in Docker.

Detailed Setup Instructions

Configuring Miner ID and Identity Wallet

Heurist Miner uses a dual-wallet system for security and reward distribution:

Identity Wallet: Used for authentication, stored locally. Do not store funds here.
Reward Wallet (Miner ID): Receives points, Heurist Token rewards, potential ecosystem benefits.

Setting Up Your Wallets

Create a .env file in the root directory of your miner installation.

Add your Ethereum wallet address(es) as Miner ID(s):

MINER_ID_0=0xYourFirstWalletAddressHere
MINER_ID_1=0xYourSecondWalletAddressHere

(Optional) Add custom tags for tracking:

MINER_ID_0=0xYourFirstWalletAddressHere-GamingPC4090
MINER_ID_1=0xYourSecondWalletAddressHere-GoogleCloudT4

Generate or import identity wallets:
```
python3 ./auth/generator.py
```
Follow the prompts to create new wallets or import existing ones.

Stable Diffusion Miner Detailed Setup

Windows Setup

Install Miniconda:
- Download from Miniconda website
- Choose the latest Windows 64-bit version for Python 3.11

Create Conda Environment:

conda create --name heurist-miner python=3.11
conda activate heurist-miner

Install CUDA Toolkit:
- Download CUDA 12.1 from NVIDIA website
- Follow the installation prompts

Install PyTorch with GPU Support:

conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

Clone Miner Repository and Install Dependencies:

git clone https://github.com/heurist-network/miner-release
cd miner-release
pip install -r requirements.txt

Run the Miner:
```
python3 sd-miner.py
```

Linux Setup

Update GPU Drivers (if necessary):

sudo apt update
sudo ubuntu-drivers autoinstall

Install Miniconda:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

Create Conda Environment:

conda create --name heurist-miner python=3.11
conda activate heurist-miner

Install CUDA Toolkit:

Follow instructions on NVIDIA CUDA Installation Guide

Install PyTorch with GPU Support:

conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia

Clone Miner Repository and Install Dependencies:

git clone https://github.com/heurist-network/miner-release
cd miner-release
pip install -r requirements.txt

Run the Miner:
```
python3 sd-miner.py
```

Large Language Model Miner Detailed Setup

Setup Process

Ensure CUDA Driver is Installed:
- Check with nvidia-smi
Select a Model ID:
- Choose based on your GPU's VRAM capacity
- Example models:
  - dolphin-2.9-llama3-8b (24GB VRAM)
  - openhermes-mixtral-8x7b-gptq (40GB VRAM)

Run the Setup Script:

chmod +x llm-miner-starter.sh
./llm-miner-starter.sh <model_id> --miner-id-index 0 --port 8000 --gpu-ids 0

Options:

--miner-id-index: Index of miner_id in .env (default: 0)
--port: Port for vLLM process (default: 8000)
--gpu-ids: GPU ID to use (default: 0)

Wait for Model Download:

First run will download the model (can take time)
Models are saved in $HOME/.cache/huggingface

Note: 8x7b, 34b, and 70b models may take up to an hour to load on some devices.

Advanced Configuration for Heurist Miners

Command Line Interface (CLI) Options

Stable Diffusion Miner

When running the SD miner, you can use various CLI options to customize its behavior. You can combine multiple flags.

Log Level
- Set the verbosity of log messages:
```
python3 sd-miner.py --log-level DEBUG
```
- Options: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)
Auto-Confirm
- Automatically confirm model downloads:
```
python3 sd-miner.py --auto-confirm yes
```
- Options: yes, no (default: no)
Exclude SDXL
- Exclude SDXL models to reduce VRAM usage:
```
python3 sd-miner.py --exclude-sdxl
```

Specify Model ID

Run the miner with a specific model:

python3 sd-miner.py --model-id <model_id>

For example, run FLUX.1-dev model with:

python3 sd-miner.py --model-id FLUX.1-dev --skip-checksum

CUDA Device ID
- Specify which GPU to use:
```
python3 sd-miner.py --cuda-device-id 0
```
Skip checksum to speed up miner start-up time
- This skips checking the validity of model files. However, if incompleted files are present on the disk, the miner process will crash without this check.
```
python3 sd-miner.py --skip-checksum
```

Large Language Model Miner

For LLM miner, use the following CLI options to customize its behavior:

Specify Model ID
- Run the miner with a specific model (mandatory):
```
./llm-miner-starter.sh <model_id>
```
- Example: dolphin-2.9-llama3-8b (requires 24GB VRAM)
Miner ID Index
- Specify which miner ID from the .env file to use:
```
./llm-miner-starter.sh <model_id> --miner-id-index 1
```
- Default: 0 (uses the first address configured)
Port
- Set the port for communication with the vLLM process:
```
./llm-miner-starter.sh <model_id> --port 8001
```
- Default: 8000

GPU IDs

Specify which GPU(s) to use:

./llm-miner-starter.sh <model_id> --gpu-ids 1

Default: 0

Example combining multiple options:

./llm-miner-starter.sh dolphin-2.9-llama3-8b --miner-id-index 1 --port 8001 --gpu-ids 1

Advanced usage: To deploy large models using multiple GPUs on the same machine.

./llm-miner-starter.sh openhermes-mixtral-8x7b-gptq --miner-id-index 0 --port 8000 --gpu-ids 0,1

Multiple GPU Configuration

To utilize multiple GPUs:

Assign unique Miner IDs in your .env file:

MINER_ID_0=0xWalletAddress1
MINER_ID_1=0xWalletAddress2

Set num_cuda_devices in config.toml:
```
[system]
num_cuda_devices = 2
```
Run the miner without specifying a CUDA device ID to use all available GPUs.

Troubleshooting

Running into issues? Don't worry, we've got you covered! Here are some common problems and their solutions:

Installation Issues

🚨 CUDA not found
- Ensure CUDA is properly installed
- Check if the CUDA version matches PyTorch requirements
  ✅ Solution: Reinstall CUDA or update PyTorch to match your CUDA version
🚨 Dependencies installation fails
- Check your Python version (should be 3.10 or 3.11)
- Ensure you're in the correct Conda environment
  ✅ Solution: Create a new Conda environment and reinstall dependencies

Runtime Issues

🚨 CUDA out of memory error
- Check available GPU memory using nvidia-smi
- Stop other programs occupying VRAM, or use a smaller model
  ✅ Solution: Add --exclude-sdxl flag for SD miner or choose a smaller LLM
🚨 Miner not receiving tasks
- Check your internet connection
- Verify your Miner ID is correctly set in the .env file
  ✅ Solution: Restart the miner and check logs for connection issues
🚨 Model loading takes too long
- This is normal for large models, especially on first run
- Check disk space and internet speed
  ✅ Solution: Be patient (grab a coffee! ☕), or choose a smaller model

Additional Tips

🔍 Always check the console output for specific error messages
🔄 Ensure you're using the latest version of the miner software
💬 If problems persist, don't hesitate to ask for help in our Discord community!

FAQ

Got questions? We've got answers!

1️⃣ Can I run both SD and LLM miners simultaneously? 🖥️🖥️
🅰️ Absolutely! Just make sure you have enough GPU memory and use different CUDA device IDs.

2️⃣ How do I know if I'm earning rewards? 💰
🅰️ Keep an eye on your miner logs for successful task completions. We're tracking your rewards behind the scenes, and updates should be reflected on https://heurist.ai/portal within minutes.

3️⃣ What's the difference between Identity Wallet and Reward Wallet? 🎭💼
🅰️ Think of the Identity Wallet as your miner's passport (for authentication), and the Reward Wallet (Miner ID) as its piggy bank (for receiving points and rewards).

4️⃣ Can I use my gaming PC for mining when I'm not gaming? 🎮➡️💻
🅰️ Yes! Just remember to pause mining before starting the games. Your GPU can't be in two places at once!

5️⃣ How often should I update the miner software? 🔄
🅰️ Stay tuned to our Discord miner-announcement channel and GitHub for the latest updates. We recommend updating whenever a new version drops.

Support and Community

Discord Channel

Join our lively community on Discord - it's where all the cool miners hang out! 🔗 Heurist Discord #dev-chat channel

Reporting Issues

📚 Check our Troubleshooting guide and FAQ - you might find a quick fix!
🆘 Still stuck? Head over to our GitHub Issues page: 🔗 Heurist Miner Issues
📝 When reporting, remember to include:
- Miner version
- Model
- Operating System
- Console error messages and log files
- Steps to reproduce

Stay in the Loop

Keep up with the latest Heurist happenings:

📖 Medium: Heurist Blogs
📣 Discord: Tune into our #miner-announcements channel
🐦 X/Twitter: Follow Heurist for the latest updates

Name		Name	Last commit message	Last commit date
Latest commit History 174 Commits
auth		auth
llm_mining_core		llm_mining_core
sd_mining_core		sd_mining_core
vendor		vendor
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
config.toml		config.toml
llm-miner-starter.sh		llm-miner-starter.sh
llm-miner.py		llm-miner.py
requirements.txt		requirements.txt
sd-miner-starter.sh		sd-miner-starter.sh
sd-miner.py		sd-miner.py

License

heurist-network/miner-release

Folders and files

Latest commit

History

Repository files navigation