🚀 Hive-GPU v0.1.0

High-performance GPU acceleration library for vector operations

📦 Installation

Add to your Cargo.toml:

[dependencies]
hive-gpu = "0.1.0"

# Optional: Enable specific GPU backends
hive-gpu = { version = "0.1.0", features = ["metal-native"] }  # macOS
hive-gpu = { version = "0.1.0", features = ["cuda"] }          # Linux/Windows
hive-gpu = { version = "0.1.0", features = ["wgpu"] }          # Cross-platform

🎯 Features

• 🔥 GPU Acceleration: Metal Native, CUDA, and wgpu support
• ⚡ High Performance: VRAM-only storage for maximum speed
• 🧠 HNSW Graphs: GPU-accelerated approximate nearest neighbor search
• 📊 Vector Operations: Cosine similarity, Euclidean distance, dot product
• 🔄 Batch Processing: Efficient batch operations
• 🛡️ Type Safety: Rust's type system for GPU operations
• 📱 Cross-Platform: macOS, Linux, Windows support

🚀 Quick Start

Basic Usage

use hive_gpu::metal::context::MetalNativeContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};
use hive_gpu::types::{GpuVector, GpuDistanceMetric};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create GPU context
    let context = MetalNativeContext::new()?;
    
    // Create vector storage
    let mut storage = context.create_storage(128, GpuDistanceMetric::Cosine)?;
    
    // Prepare vectors
    let vectors = vec![
        GpuVector {
            id: "vector_1".to_string(),
            data: vec![1.0, 2.0, 3.0, 4.0], // 4D vector
            metadata: std::collections::HashMap::new(),
        },
        GpuVector {
            id: "vector_2".to_string(),
            data: vec![2.0, 3.0, 4.0, 5.0],
            metadata: std::collections::HashMap::new(),
        },
    ];
    
    // Add vectors to GPU
    storage.add_vectors(&vectors)?;
    
    // Search for similar vectors
    let query = vec![1.5, 2.5, 3.5, 4.5];
    let results = storage.search(&query, 5)?;
    
    println!("Found {} similar vectors:", results.len());
    for result in results {
        println!("ID: {}, Score: {:.4}", result.id, result.score);
    }
    
    Ok(())
}

Advanced Usage with HNSW

use hive_gpu::metal::context::MetalNativeContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};
use hive_gpu::types::{GpuVector, GpuDistanceMetric, HnswConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create GPU context
    let context = MetalNativeContext::new()?;
    
    // Configure HNSW parameters
    let hnsw_config = HnswConfig {
        m: 16,              // Number of bi-directional links
        ef_construction: 200, // Size of dynamic candidate list
        ef_search: 50,      // Size of dynamic candidate list for search
        seed: 42,           // Random seed
    };
    
    // Create storage with HNSW configuration
    let mut storage = context.create_storage_with_config(
        512, 
        GpuDistanceMetric::Cosine, 
        hnsw_config
    )?;
    
    // Generate random vectors
    let mut vectors = Vec::new();
    for i in 0..1000 {
        let data = (0..512).map(|_| rand::random::<f32>()).collect();
        vectors.push(GpuVector {
            id: format!("vector_{}", i),
            data,
            metadata: std::collections::HashMap::new(),
        });
    }
    
    // Add vectors in batches
    storage.add_vectors(&vectors)?;
    
    // Search with HNSW acceleration
    let query = (0..512).map(|_| rand::random::<f32>()).collect::<Vec<f32>>();
    let results = storage.search(&query, 10)?;
    
    println!("HNSW search results:");
    for (i, result) in results.iter().enumerate() {
        println!("{}. ID: {}, Score: {:.6}", i + 1, result.id, result.score);
    }
    
    Ok(())
}

🔧 GPU Backends

Metal Native (macOS)

use hive_gpu::metal::context::MetalNativeContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};

// Metal Native provides the highest performance on macOS
let context = MetalNativeContext::new()?;
let storage = context.create_storage(128, GpuDistanceMetric::Cosine)?;

CUDA (Linux/Windows)

use hive_gpu::cuda::context::CudaContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};

// CUDA provides excellent performance on NVIDIA GPUs
let context = CudaContext::new()?;
let storage = context.create_storage(128, GpuDistanceMetric::Cosine)?;

wgpu (Cross-platform)

use hive_gpu::wgpu::context::WgpuContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};

// wgpu provides cross-platform GPU acceleration
let context = WgpuContext::new()?;
let storage = context.create_storage(128, GpuDistanceMetric::Cosine)?;

🏗️ Integration with Vectorizer

Using with Hive-Vectorizer

# In your Cargo.toml
[dependencies]
vectorizer = { git = "https://github.com/hivellm/vectorizer.git" }
hive-gpu = "0.1.0"

use vectorizer::VectorStore;
use hive_gpu::metal::context::MetalNativeContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create vectorizer store
    let mut store = VectorStore::new();
    
    // Create collection with GPU acceleration
    let config = vectorizer::models::CollectionConfig {
        dimension: 512,
        metric: vectorizer::models::DistanceMetric::Cosine,
        hnsw_config: vectorizer::models::HnswConfig {
            m: 16,
            ef_construction: 200,
            ef_search: 50,
            seed: 42,
        },
    };
    
    store.create_collection("my_collection", config)?;
    
    // Add vectors
    let vectors = vec![
        vectorizer::models::Vector {
            id: "doc_1".to_string(),
            data: vec![1.0; 512],
            payload: None,
        },
        // ... more vectors
    ];
    
    store.add_vectors("my_collection", vectors)?;
    
    // Search
    let query = vec![0.5; 512];
    let results = store.search("my_collection", &query, 10)?;
    
    println!("Found {} results", results.len());
    
    Ok(())
}

Custom GPU Integration

use hive_gpu::metal::context::MetalNativeContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};
use hive_gpu::types::{GpuVector, GpuDistanceMetric};

struct MyVectorStore {
    gpu_storage: Box<dyn GpuVectorStorage>,
}

impl MyVectorStore {
    async fn new(dimension: usize) -> Result<Self, Box<dyn std::error::Error>> {
        let context = MetalNativeContext::new()?;
        let storage = context.create_storage(dimension, GpuDistanceMetric::Cosine)?;
        
        Ok(Self {
            gpu_storage: storage,
        })
    }
    
    async fn add_vector(&mut self, id: String, data: Vec<f32>) -> Result<(), Box<dyn std::error::Error>> {
        let vector = GpuVector {
            id,
            data,
            metadata: std::collections::HashMap::new(),
        };
        
        self.gpu_storage.add_vectors(&[vector])?;
        Ok(())
    }
    
    async fn search(&self, query: &[f32], limit: usize) -> Result<Vec<(String, f32)>, Box<dyn std::error::Error>> {
        let results = self.gpu_storage.search(query, limit)?;
        Ok(results.into_iter().map(|r| (r.id, r.score)).collect())
    }
}

📊 Performance Benchmarks

Throughput Comparison

Memory Usage

• VRAM Only: All vector data stored in GPU memory
• Zero CPU-GPU Transfer: No overhead during search
• Efficient Buffers: Automatic memory management
• Scalable: Supports millions of vectors

🛠️ Configuration

Cargo Features

[dependencies]
hive-gpu = { version = "0.1.0", features = ["metal-native"] }  # macOS only
hive-gpu = { version = "0.1.0", features = ["cuda"] }          # Linux/Windows
hive-gpu = { version = "0.1.0", features = ["wgpu"] }          # Cross-platform
hive-gpu = { version = "0.1.0", features = ["metal-native", "cuda", "wgpu"] }  # All backends

Environment Variables

# Enable debug logging
export RUST_LOG=debug

# Set GPU memory limit (if supported)
export HIVE_GPU_MEMORY_LIMIT=4GB

# Enable performance monitoring
export HIVE_GPU_PROFILE=true

🔍 Examples

Complete Example: Document Search

use hive_gpu::metal::context::MetalNativeContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};
use hive_gpu::types::{GpuVector, GpuDistanceMetric};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize GPU context
    let context = MetalNativeContext::new()?;
    let mut storage = context.create_storage(384, GpuDistanceMetric::Cosine)?;
    
    // Simulate document embeddings (384-dimensional)
    let documents = vec![
        ("doc_1", "Machine learning and artificial intelligence"),
        ("doc_2", "Deep learning neural networks"),
        ("doc_3", "Natural language processing"),
        ("doc_4", "Computer vision and image recognition"),
        ("doc_5", "Reinforcement learning algorithms"),
    ];
    
    // Add document vectors
    for (id, text) in documents {
        let embedding = generate_embedding(text); // Your embedding function
        let vector = GpuVector {
            id: id.to_string(),
            data: embedding,
            metadata: {
                let mut meta = std::collections::HashMap::new();
                meta.insert("text".to_string(), text.to_string());
                meta
            },
        };
        storage.add_vectors(&[vector])?;
    }
    
    // Search for similar documents
    let query_text = "AI and machine learning";
    let query_embedding = generate_embedding(query_text);
    let results = storage.search(&query_embedding, 3)?;
    
    println!("Search results for: '{}'", query_text);
    for (i, result) in results.iter().enumerate() {
        println!("{}. {} (similarity: {:.4})", 
                 i + 1, result.id, result.score);
    }
    
    Ok(())
}

// Mock embedding function (replace with your actual implementation)
fn generate_embedding(text: &str) -> Vec<f32> {
    // In practice, use a real embedding model like sentence-transformers
    (0..384).map(|i| (i as f32 + text.len() as f32) * 0.01).collect()
}

Batch Processing Example

use hive_gpu::metal::context::MetalNativeContext;
use hive_gpu::traits::{GpuContext, GpuVectorStorage};
use hive_gpu::types::{GpuVector, GpuDistanceMetric};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let context = MetalNativeContext::new()?;
    let mut storage = context.create_storage(128, GpuDistanceMetric::Cosine)?;
    
    // Generate large batch of vectors
    let batch_size = 10000;
    let mut vectors = Vec::with_capacity(batch_size);
    
    for i in 0..batch_size {
        let data = (0..128).map(|_| rand::random::<f32>()).collect();
        vectors.push(GpuVector {
            id: format!("batch_vector_{}", i),
            data,
            metadata: std::collections::HashMap::new(),
        });
    }
    
    // Add vectors in batches for efficiency
    let chunk_size = 1000;
    for chunk in vectors.chunks(chunk_size) {
        storage.add_vectors(chunk)?;
        println!("Added {} vectors", chunk.len());
    }
    
    // Batch search
    let queries = vec![
        (0..128).map(|_| rand::random::<f32>()).collect::<Vec<f32>>(),
        (0..128).map(|_| rand::random::<f32>()).collect::<Vec<f32>>(),
        (0..128).map(|_| rand::random::<f32>()).collect::<Vec<f32>>(),
    ];
    
    for (i, query) in queries.iter().enumerate() {
        let results = storage.search(query, 5)?;
        println!("Query {}: Found {} results", i + 1, results.len());
    }
    
    Ok(())
}

🧪 Testing

Running Tests

# Test all features
cargo test --all-features

# Test specific backend
cargo test --features metal-native
cargo test --features cuda
cargo test --features wgpu

# Run benchmarks
cargo bench

Example Test

#[cfg(test)]
mod tests {
    use super::*;
    use hive_gpu::metal::context::MetalNativeContext;
    use hive_gpu::traits::{GpuContext, GpuVectorStorage};

    #[test]
    fn test_gpu_vector_operations() {
        let context = MetalNativeContext::new().unwrap();
        let mut storage = context.create_storage(4, GpuDistanceMetric::Cosine).unwrap();
        
        let vectors = vec![
            GpuVector {
                id: "test_1".to_string(),
                data: vec![1.0, 0.0, 0.0, 0.0],
                metadata: std::collections::HashMap::new(),
            },
            GpuVector {
                id: "test_2".to_string(),
                data: vec![0.0, 1.0, 0.0, 0.0],
                metadata: std::collections::HashMap::new(),
            },
        ];
        
        storage.add_vectors(&vectors).unwrap();
        
        let query = vec![1.0, 0.0, 0.0, 0.0];
        let results = storage.search(&query, 2).unwrap();
        
        assert_eq!(results.len(), 2);
        assert_eq!(results[0].id, "test_1");
        assert!(results[0].score > results[1].score);
    }
}

📚 API Reference

Core Types

pub struct GpuVector {
    pub id: String,
    pub data: Vec<f32>,
    pub metadata: HashMap<String, String>,
}

pub struct GpuSearchResult {
    pub id: String,
    pub score: f32,
    pub index: usize,
}

pub enum GpuDistanceMetric {
    Cosine,
    Euclidean,
    DotProduct,
}

Traits

pub trait GpuContext {
    fn create_storage(&self, dimension: usize, metric: GpuDistanceMetric) -> Result<Box<dyn GpuVectorStorage>>;
    fn create_storage_with_config(&self, dimension: usize, metric: GpuDistanceMetric, config: HnswConfig) -> Result<Box<dyn GpuVectorStorage>>;
}

pub trait GpuVectorStorage {
    fn add_vectors(&mut self, vectors: &[GpuVector]) -> Result<Vec<usize>>;
    fn search(&self, query: &[f32], limit: usize) -> Result<Vec<GpuSearchResult>>;
    fn remove_vectors(&mut self, ids: &[String]) -> Result<()>;
    fn vector_count(&self) -> usize;
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/hivellm/hive-gpu.git
cd hive-gpu

# Install dependencies
cargo build

# Run tests
cargo test --all-features

# Run benchmarks
cargo bench

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Metal Framework: Apple's GPU compute framework
• CUDA: NVIDIA's parallel computing platform
• wgpu: Cross-platform GPU API
• Rust Community: For the amazing ecosystem

📞 Support

• GitHub Issues: Report bugs and request features
• Discussions: Community discussions
• Documentation: API Documentation

Made with ❤️ by the HiveLLM team