Dippy Studio Bittensor Miner

A specialized Bittensor subnet miner (subnet 231 on testnet) for high-performance FLUX.1-dev inference with TensorRT acceleration and LoRA refitting.

Prerequisites

You will need access to a H100 GPU PCIe with the following configuration:

NVIDIA-SMI 570.172.08             Driver Version: 570.172.08     CUDA Version: 12.8

For managing python installation, we recommend uv and only officially support this configuration.

Before running this miner, you must:

1. Set up a HuggingFace account and token:

   • Create an account at HuggingFace
   • Generate an access token at HuggingFace Settings
   • The token must have write permissions to create and upload models

2. Accept FLUX.1-dev model license:

   • Visit the FLUX.1-dev model page
   • Read and accept the license agreement
   • Without accepting the license, the model download will fail

Quick Start

Choose Your Deployment Mode

The miner can run in two modes:

• Inference Mode: Serves pre-trained models with TensorRT acceleration
• Kontext Editing Mode: Enable deterministic FLUX.1-Kontext-dev editing

# 1. Clone the repository
git clone https://github.com/dippy-ai/dippy-studio-bittensor-miner
cd dippy-studio-bittensor-miner

# 2. Create .env file with your credentials
cp .env.example .env
# Edit .env and add your HF_TOKEN

# 3. Choose your deployment mode:

# For INFERENCE only (requires TRT engines)
make setup-inference

# 4. Check logs
make logs

The miner server will be available at http://localhost:8091.

Image Editing with FLUX.1-Kontext-dev

The miner now supports deterministic image editing using FLUX.1-Kontext-dev.

Enable Kontext Editing

# Quick setup
make setup-kontext

# Or manually
echo "ENABLE_KONTEXT_EDIT=true" >> .env
make restart

Usage Example

# Edit an image
curl -X POST http://localhost:8091/edit \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add a red hat to the person",
    "image_b64": "base64_encoded_image_data",
    "seed": 42,
    "guidance_scale": 2.5,
    "num_inference_steps": 28
  }'

# Check status
curl http://localhost:8091/edit/status/{job_id}

# Download result
curl http://localhost:8091/edit/result/{job_id} -o edited.png

Determinism Testing

# Run E2E tests (local miner)
export ENABLE_KONTEXT_EDIT=true
pytest tests/e2e/kontext_determinism/ -v -m e2e

# Or use make command
make test-kontext-determinism

For Docker-based testing, see tests/e2e/kontext_determinism/README.md for network configuration.

See docs/kontext-editing.md for full API documentation including async callbacks.

Available Make Commands

# Deployment Modes
make setup-inference  # Deploy inference-only server (auto-builds TRT if needed)
make setup-kontext    # Deploy with FLUX.1-Kontext-dev editing enabled

# Building & Management
make build            # Build Docker images
make trt-build        # Build TRT engine (20-30 min)
make trt-rebuild      # Force rebuild TRT engine
make up               # Start miner service
make down             # Stop miner service
make logs             # Follow miner logs
make restart          # Restart miner service

# Testing
make test-kontext-determinism  # Run Kontext determinism E2E tests
make test-kontext-unit         # Run Kontext unit tests

# Maintenance
make clean-cache      # Remove all cached TRT engines
make help             # Show all available commands

Architecture

The system consists of three main components:

1. Reverse Proxy (Public Entrypoint)

The reverse proxy handles Bittensor authentication and routes requests to internal services.

Setup:

1. Register on testnet: btcli s register --netuid 231 --subtensor.network test
2. Transfer 0.01 testnet TAO to 5FU2csPXS5CZfMVd2Ahdis9DNaYmpTCX4rsN11UW7ghdx24A for mining permit
3. Configure environment variables in reverse_proxy/.env
4. Install and run:

   cd reverse_proxy
   uv pip install -e .[dev]
   python server.py

2. Miner Server

A FastAPI server (miner_server.py) that can run inference

Features:

• Inference Mode: TensorRT-accelerated image generation with LoRA support and automatic engine preloading
• Static file serving: Direct image URL access

Endpoints:

• POST /inference - Generate image (with optional LoRA and callback support)
• POST /edit - Edit image with FLUX.1-Kontext-dev (with callback support)
• GET /inference/status/{job_id} - Check inference status
• GET /edit/status/{job_id} - Check edit job status
• GET /inference/result/{job_id} - Download generated image
• GET /edit/result/{job_id} - Download edited image
• GET /health - Health check

3. TensorRT Engine

High-performance inference engine for FLUX.1-dev model.

Building the Engine:

# Using make (recommended)
make trt-build     # Build if not exists
make trt-rebuild   # Force rebuild

# Or Docker directly
docker compose run --rm trt-builder

Async Inference E2E Test

Follow docs/async_inference_e2e.md for a walkthrough of the new async inference test harness, including how to launch the reference callback server and run checks via pytest or python -m tests.e2e.async_inference.cli run.

Quick start (host execution)

pip install -r requirements_test_async.txt
export ASYNC_MINER_URL=http://localhost:8091
export ASYNC_CALLBACK_BASE_URL=http://127.0.0.1:8092
pytest tests/e2e/async_inference/test_async_inference.py -s

Running against a miner in Docker

The container cannot reach 127.0.0.1 on the host. Use an address the container can see (for example the docker0 gateway on Linux):

pip install -r requirements_test_async.txt
export ASYNC_MINER_URL=http://localhost:8091
export ASYNC_CALLBACK_BASE_URL=http://172.17.0.1:8092
export ASYNC_CALLBACK_BIND_HOST=0.0.0.0                 # ensure the mock callback server listens externally
pytest tests/e2e/async_inference/test_async_inference.py -s

Run ip addr show docker0 and use the inet value (typically 172.17.0.1) for ASYNC_CALLBACK_BASE_URL.

Expose the same ASYNC_CALLBACK_BASE_URL (and optionally ASYNC_CALLBACK_BIND_HOST) to the miner service via your .env or compose file, then restart the container so it picks up the new settings.

Configuration

Environment Variables

Create a .env file in the project root:

# Required
HF_TOKEN=your_huggingface_token_here        # HuggingFace token with write permissions

# Mode Configuration (set based on deployment choice)
ENABLE_INFERENCE=true                       
MODEL_PATH=black-forest-labs/FLUX.1-dev    # Base model path
OUTPUT_DIR=/app/output                      # Output directory in container (mapped to ./output on host)
MINER_SERVER_PORT=8091                      # Server port
MINER_SERVER_HOST=0.0.0.0                   # Server host
SERVICE_URL=http://localhost:8091           # Public URL for image serving

For the reverse proxy, create reverse_proxy/.env:

# Required
MINER_HOTKEY=your_miner_hotkey_here         # Bittensor miner hotkey

# Service endpoints (internal)
INFERENCE_SERVER_URL=http://localhost:8091  # Miner server for inference

How It Works

The miner provides two main services:

Inference Service

1. Receives generation requests via POST to /inference:

   • prompt: Text description for image generation
   • lora_path: Optional path to LoRA weights
   • width/height: Image dimensions
   • num_inference_steps: Quality control
   • guidance_scale: Prompt adherence strength
   • seed: For reproducibility

2. Generates images using TensorRT:

   • Uses pre-built TRT engine for fast inference
   • Supports dynamic LoRA switching via refitting
   • Returns image URL immediately after generation

3. Serves generated images via static file server:

   • Images accessible at /images/{job_id}.png
   • Direct URL access for validator retrieval

API Examples

Generate Image with Base Model

curl -X POST http://localhost:8091/inference \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains",
    "width": 1024,
    "height": 1024,
    "num_inference_steps": 28,
    "guidance_scale": 7.5,
    "seed": 42
  }'

Generate Image with LoRA

curl -X POST http://localhost:8091/inference \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A portrait in anime style",
    "lora_path": "/app/models/anime_lora.safetensors",
    "width": 1024,
    "height": 1024
  }'

Check Job Status

# Inference status
curl http://localhost:8091/inference/status/{job_id}

System Requirements

• H100 PCIe with the following specific nvidia-smi configuration. See below for reference:

NVIDIA-SMI 570.172.08             Driver Version: 570.172.08     CUDA Version: 12.8

• GPU: NVIDIA H100 GPU PCIe (80GB VRAM supports both FLUX.1-dev + Kontext simultaneously)
• CUDA: Version 12.8 Specifically
• RAM: 32GB minimum
• Storage: 100GB+ for model weights (FLUX.1-dev + Kontext models)
• Docker: Latest version with nvidia-container-toolkit

Monitoring and Logs

• API logs: Check docker compose logs -f
• GPU usage: Use nvidia-smi to monitor GPU utilization

Troubleshooting

TensorRT Engine Issues

If inference fails with TRT errors:

1. Rebuild the engine: docker compose --profile build up trt-builder --force-recreate
2. Check GPU compatibility (requires compute capability 7.0+)
3. Ensure sufficient GPU memory (24GB+ recommended)

LoRA Loading Issues

If LoRA weights don't apply correctly:

1. Verify LoRA was trained for FLUX.1-dev (not SDXL or other models)
2. Check file path is accessible within container
3. Ensure LoRA file is in .safetensors format

Model Download Issues

If you encounter permission errors downloading FLUX.1-dev:

1. Ensure you've accepted the model license on HuggingFace
2. Verify your HF_TOKEN is correctly set
3. Check that your token has read permissions

Docker Issues

If container fails to start:

1. Check nvidia-docker is installed: docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
2. Verify Docker has GPU access
3. Check port 8091 is not in use: lsof -i :8091

Connection Issues

If the miner can't connect to validators:

1. Check firewall settings for port 8091
2. Ensure Docker networking is properly configured
3. Verify validator endpoints are accessible
4. Check SERVICE_URL environment variable for production

Additional Resources

• Bittensor Documentation
• FLUX.1 Model Card

Support

For issues and questions:

• Check existing issues in the repository
• Join the Bittensor Discord community
• Review validator documentation for integration details