Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
338
vendor/ruvector/docs/integration/hub_integration.md
vendored
Normal file
338
vendor/ruvector/docs/integration/hub_integration.md
vendored
Normal file
@@ -0,0 +1,338 @@
|
||||
# HuggingFace Hub Integration for RuvLTRA
|
||||
|
||||
This document describes the HuggingFace Hub integration for publishing and downloading RuvLTRA models.
|
||||
|
||||
## Overview
|
||||
|
||||
The `ruvllm::hub` module provides comprehensive functionality for:
|
||||
|
||||
1. **Model Download**: Pull GGUF files from HuggingFace Hub with progress tracking and resume support
|
||||
2. **Model Upload**: Push models to HuggingFace Hub with automatic model card generation
|
||||
3. **Model Registry**: Pre-configured RuvLTRA model collection with hardware requirements
|
||||
4. **Progress Tracking**: Visual progress bars with ETA and speed indicators
|
||||
5. **Checksum Verification**: SHA256 validation for downloaded files
|
||||
|
||||
## Module Structure
|
||||
|
||||
```
|
||||
crates/ruvllm/src/hub/
|
||||
├── mod.rs # Main module with exports and common types
|
||||
├── download.rs # Model download functionality
|
||||
├── upload.rs # Model upload functionality
|
||||
├── registry.rs # RuvLTRA model registry
|
||||
├── model_card.rs # HuggingFace model card generation
|
||||
└── progress.rs # Progress tracking utilities
|
||||
```
|
||||
|
||||
## Model Registry
|
||||
|
||||
The registry includes pre-configured RuvLTRA models:
|
||||
|
||||
### Base Models
|
||||
|
||||
| Model ID | Size | Params | Quantization | Use Case |
|
||||
|----------|------|--------|--------------|----------|
|
||||
| `ruvltra-small` | 662MB | 0.5B | Q4_K_M | Edge devices, includes SONA weights |
|
||||
| `ruvltra-small-q8` | 1.3GB | 0.5B | Q8_0 | High quality, small model |
|
||||
| `ruvltra-medium` | 2.1GB | 3B | Q4_K_M | General purpose, extended context |
|
||||
| `ruvltra-medium-q8` | 4.2GB | 3B | Q8_0 | High quality, balanced model |
|
||||
|
||||
### LoRA Adapters
|
||||
|
||||
| Adapter ID | Size | Base Model | Purpose |
|
||||
|------------|------|------------|---------|
|
||||
| `ruvltra-small-coder` | 50MB | ruvltra-small | Code completion specialization |
|
||||
|
||||
## Usage
|
||||
|
||||
### 1. Model Download
|
||||
|
||||
#### Using the CLI Example
|
||||
|
||||
```bash
|
||||
# Download RuvLTRA Small
|
||||
cargo run -p ruvllm --example hub_cli -- pull ruvltra-small
|
||||
|
||||
# Download to custom directory
|
||||
cargo run -p ruvllm --example hub_cli -- pull ruvltra-medium --output ./models
|
||||
|
||||
# List all available models
|
||||
cargo run -p ruvllm --example hub_cli -- list
|
||||
|
||||
# Show detailed model info
|
||||
cargo run -p ruvllm --example hub_cli -- info ruvltra-small
|
||||
```
|
||||
|
||||
#### Using the API
|
||||
|
||||
```rust
|
||||
use ruvllm::hub::{ModelDownloader, RuvLtraRegistry};
|
||||
|
||||
// Download by model ID
|
||||
let downloader = ModelDownloader::new();
|
||||
let path = downloader.download_by_id("ruvltra-small")?;
|
||||
|
||||
// Or download with custom config
|
||||
let registry = RuvLtraRegistry::new();
|
||||
let model_info = registry.get("ruvltra-small").unwrap();
|
||||
|
||||
let config = DownloadConfig {
|
||||
cache_dir: PathBuf::from("./models"),
|
||||
resume: true,
|
||||
show_progress: true,
|
||||
verify_checksum: true,
|
||||
..Default::default()
|
||||
};
|
||||
|
||||
let downloader = ModelDownloader::with_config(config);
|
||||
let path = downloader.download(model_info, None)?;
|
||||
```
|
||||
|
||||
### 2. Model Upload
|
||||
|
||||
#### Using the CLI Example
|
||||
|
||||
```bash
|
||||
# Upload a custom model (requires HF_TOKEN)
|
||||
export HF_TOKEN=your_huggingface_token
|
||||
|
||||
cargo run -p ruvllm --example hub_cli -- push \
|
||||
--model ./my-ruvltra-custom.gguf \
|
||||
--repo username/my-ruvltra-custom \
|
||||
--description "My custom RuvLTRA model" \
|
||||
--params 0.5 \
|
||||
--architecture llama \
|
||||
--context 4096 \
|
||||
--quant Q4_K_M
|
||||
```
|
||||
|
||||
#### Using the API
|
||||
|
||||
```rust
|
||||
use ruvllm::hub::{ModelUploader, ModelMetadata, UploadConfig};
|
||||
|
||||
// Create metadata
|
||||
let metadata = ModelMetadata {
|
||||
name: "My RuvLTRA Model".to_string(),
|
||||
description: Some("A custom RuvLTRA variant".to_string()),
|
||||
architecture: "llama".to_string(),
|
||||
params_b: 0.5,
|
||||
context_length: 4096,
|
||||
quantization: Some("Q4_K_M".to_string()),
|
||||
license: Some("MIT".to_string()),
|
||||
datasets: vec!["custom-dataset".to_string()],
|
||||
tags: vec!["ruvltra".to_string(), "custom".to_string()],
|
||||
};
|
||||
|
||||
// Configure uploader
|
||||
let config = UploadConfig::new(hf_token)
|
||||
.private(false)
|
||||
.commit_message("Upload custom RuvLTRA model");
|
||||
|
||||
let uploader = ModelUploader::with_config(config);
|
||||
let url = uploader.upload(
|
||||
"./my-model.gguf",
|
||||
"username/my-ruvltra-custom",
|
||||
Some(metadata),
|
||||
)?;
|
||||
|
||||
println!("Model uploaded to: {}", url);
|
||||
```
|
||||
|
||||
### 3. Model Registry
|
||||
|
||||
```rust
|
||||
use ruvllm::hub::{RuvLtraRegistry, ModelSize};
|
||||
|
||||
let registry = RuvLtraRegistry::new();
|
||||
|
||||
// Get a specific model
|
||||
let model = registry.get("ruvltra-small").unwrap();
|
||||
println!("Model: {}", model.name);
|
||||
println!("Size: {} MB", model.size_bytes / (1024 * 1024));
|
||||
|
||||
// List all models
|
||||
for model in registry.list_all() {
|
||||
println!("{}: {}", model.id, model.description);
|
||||
}
|
||||
|
||||
// List by size category
|
||||
for model in registry.list_by_size(ModelSize::Small) {
|
||||
println!("Small model: {}", model.id);
|
||||
}
|
||||
|
||||
// Get adapters for a base model
|
||||
for adapter in registry.list_adapters("ruvltra-small") {
|
||||
println!("Adapter: {}", adapter.id);
|
||||
}
|
||||
|
||||
// Recommend model based on available RAM
|
||||
let model = registry.recommend_for_ram(4.0).unwrap();
|
||||
println!("Recommended for 4GB RAM: {}", model.id);
|
||||
```
|
||||
|
||||
### 4. Model Card Generation
|
||||
|
||||
```rust
|
||||
use ruvllm::hub::{
|
||||
ModelCardBuilder, TaskType, Framework, License
|
||||
};
|
||||
|
||||
let card = ModelCardBuilder::new("RuvLTRA Custom")
|
||||
.description("A custom RuvLTRA variant")
|
||||
.task(TaskType::TextGeneration)
|
||||
.framework(Framework::Gguf)
|
||||
.architecture("llama")
|
||||
.parameters(500_000_000)
|
||||
.context_length(4096)
|
||||
.license(License::Mit)
|
||||
.add_dataset("training-data", Some("Custom dataset".to_string()))
|
||||
.add_metric("perplexity", 5.2, Some("test-set".to_string()))
|
||||
.add_tag("ruvltra")
|
||||
.add_tag("custom")
|
||||
.build();
|
||||
|
||||
// Generate markdown for HuggingFace
|
||||
let markdown = card.to_markdown();
|
||||
```
|
||||
|
||||
### 5. Progress Tracking
|
||||
|
||||
```rust
|
||||
use ruvllm::hub::{ProgressBar, ProgressStyle};
|
||||
|
||||
let mut pb = ProgressBar::new(total_bytes)
|
||||
.with_style(ProgressStyle::Detailed)
|
||||
.with_width(50);
|
||||
|
||||
// Update progress
|
||||
pb.update(downloaded_bytes);
|
||||
|
||||
// Finish
|
||||
pb.finish();
|
||||
```
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
Each model in the registry includes hardware requirements:
|
||||
|
||||
```rust
|
||||
let model = registry.get("ruvltra-small").unwrap();
|
||||
|
||||
println!("Minimum RAM: {:.1} GB", model.hardware.min_ram_gb);
|
||||
println!("Recommended RAM: {:.1} GB", model.hardware.recommended_ram_gb);
|
||||
println!("Apple Neural Engine: {}", model.hardware.supports_ane);
|
||||
println!("Metal GPU: {}", model.hardware.supports_metal);
|
||||
println!("CUDA: {}", model.hardware.supports_cuda);
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
- `HF_TOKEN`: HuggingFace API token (required for uploads and private repos)
|
||||
- `HUGGING_FACE_HUB_TOKEN`: Alternative name for HF token
|
||||
- `RUVLLM_MODELS_DIR`: Default cache directory for downloaded models
|
||||
|
||||
## Dependencies
|
||||
|
||||
The hub integration requires:
|
||||
|
||||
- `curl` or `wget` for downloads (uses system tools for efficiency)
|
||||
- `huggingface-cli` for uploads (install with `pip install huggingface_hub[cli]`)
|
||||
- SHA256 for checksum verification (built-in via `sha2` crate)
|
||||
|
||||
## Features
|
||||
|
||||
### Download Features
|
||||
|
||||
- ✅ Resume interrupted downloads
|
||||
- ✅ Progress bar with ETA
|
||||
- ✅ SHA256 checksum verification
|
||||
- ✅ Automatic retry on failure
|
||||
- ✅ HuggingFace token authentication
|
||||
- ✅ Cache directory management
|
||||
|
||||
### Upload Features
|
||||
|
||||
- ✅ Automatic repository creation
|
||||
- ✅ Model card generation
|
||||
- ✅ Public/private repository support
|
||||
- ✅ SONA weights upload
|
||||
- ✅ Custom metadata
|
||||
- ✅ Commit message customization
|
||||
|
||||
### Registry Features
|
||||
|
||||
- ✅ Pre-configured model catalog
|
||||
- ✅ Hardware requirement tracking
|
||||
- ✅ Quantization level support
|
||||
- ✅ LoRA adapter registry
|
||||
- ✅ RAM-based recommendations
|
||||
- ✅ Download time estimation
|
||||
|
||||
## Error Handling
|
||||
|
||||
All hub operations return `Result<T, HubError>`:
|
||||
|
||||
```rust
|
||||
use ruvllm::hub::{HubError, ModelDownloader};
|
||||
|
||||
match downloader.download_by_id("ruvltra-small") {
|
||||
Ok(path) => println!("Downloaded to: {}", path.display()),
|
||||
Err(HubError::NotFound(id)) => eprintln!("Model {} not found", id),
|
||||
Err(HubError::ChecksumMismatch { expected, actual }) => {
|
||||
eprintln!("Checksum mismatch: expected {}, got {}", expected, actual);
|
||||
}
|
||||
Err(HubError::Network(msg)) => eprintln!("Network error: {}", msg),
|
||||
Err(e) => eprintln!("Error: {}", e),
|
||||
}
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Run the hub integration tests:
|
||||
|
||||
```bash
|
||||
# Test model registry
|
||||
cargo test -p ruvllm --lib hub::registry
|
||||
|
||||
# Test download (requires network)
|
||||
cargo test -p ruvllm --lib hub::download
|
||||
|
||||
# Test model card generation
|
||||
cargo test -p ruvllm --lib hub::model_card
|
||||
|
||||
# Run all hub tests
|
||||
cargo test -p ruvllm --lib hub
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
See the examples for complete usage:
|
||||
|
||||
1. `examples/download_test_model.rs` - Legacy downloader with hub integration
|
||||
2. `examples/hub_cli.rs` - Full CLI with pull/push/list/info commands
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned improvements:
|
||||
|
||||
- [ ] Direct API uploads (without huggingface-cli dependency)
|
||||
- [ ] Parallel chunk downloads for faster transfers
|
||||
- [ ] Delta updates for model weights
|
||||
- [ ] Model versioning support
|
||||
- [ ] Automatic quantization variant selection
|
||||
- [ ] Multi-repo synchronization
|
||||
- [ ] Offline model registry cache
|
||||
|
||||
## Contributing
|
||||
|
||||
To add a new model to the registry:
|
||||
|
||||
1. Add model definition to `registry.rs` in `RuvLtraRegistry::new()`
|
||||
2. Include hardware requirements
|
||||
3. Set checksum after first upload
|
||||
4. Update this documentation
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See LICENSE file for details
|
||||
Reference in New Issue
Block a user