Integração mistral.rs

Execute LLMs localmente com inferência nativa em Rust - sem servidores externos, sem chaves de API.

---

O que é mistral.rs?

mistral.rs é um motor de inferência Rust de alta performance que executa LLMs diretamente no seu hardware. O adk-rust o integra através da crate adk-mistralrs.

Principais destaques:

• 🦀 Native Rust - Sem Python, sem servidores externos
• 🔒 Totalmente offline - Sem chaves de API ou internet necessária
• ⚡ Aceleração de hardware - otimizações para CUDA, Metal, CPU
• 📦 Quantization - Execute modelos grandes em hardware limitado
• 🔧 LoRA adapters - Suporte a modelos ajustados com troca dinâmica
• 👁️ Vision models - Capacidades de compreensão de imagens
• 🎯 Multi-model - Serve múltiplos modelos a partir de uma única instância

---

Passo 1: Adicionar Dependências

Como adk-mistralrs depende de repositórios git, ele não pode ser publicado no crates.io. Adicione-o via git:

[package]
name = "my-local-agent"
version = "0.1.0"
edition = "2024"

[dependencies]
adk-mistralrs = { git = "https://github.com/zavora-ai/adk-rust" }
adk-agent = { git = "https://github.com/zavora-ai/adk-rust" }
adk-rust = { git = "https://github.com/zavora-ai/adk-rust" }
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"

Para aceleração de hardware, adicione os feature flags:

# macOS com Apple Silicon
adk-mistralrs = { git = "https://github.com/zavora-ai/adk-rust", features = ["metal"] }

# GPU NVIDIA (requer o CUDA toolkit)
adk-mistralrs = { git = "https://github.com/zavora-ai/adk-rust", features = ["cuda"] }

---

Passo 2: Exemplo Básico

Carregue um modelo do HuggingFace e execute-o localmente:

use adk_agent::LlmAgentBuilder;
use adk_mistralrs::{Llm, MistralRsConfig, MistralRsModel, ModelSource};
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load model from HuggingFace (downloads on first run)
    let config = MistralRsConfig::builder()
        .model_source(ModelSource::huggingface("microsoft/Phi-3.5-mini-instruct"))
        .build();

    println!("Loading model (this may take a while on first run)...");
    let model = MistralRsModel::new(config).await?;
    println!("Model loaded: {}", model.name());

    // Create agent
    let agent = LlmAgentBuilder::new("local_assistant")
        .description("Local AI assistant powered by mistral.rs")
        .instruction("You are a helpful assistant running locally. Be concise.")
        .model(Arc::new(model))
        .build()?;

    // Run interactive chat
    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

O que acontece:

1. A primeira execução baixa o modelo do HuggingFace (~2-8GB dependendo do modelo)
2. O modelo é armazenado em cache localmente em ~/.cache/huggingface/
3. As execuções subsequentes carregam do cache instantaneamente

---

Passo 3: Reduzir Memória com Quantização

Modelos grandes exigem muita RAM. Use ISQ (Quantização In-Situ) para reduzir a memória:

use adk_agent::LlmAgentBuilder;
use adk_mistralrs::{Llm, MistralRsConfig, MistralRsModel, ModelSource, QuantizationLevel};
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load model with 4-bit quantization for reduced memory
    let config = MistralRsConfig::builder()
        .model_source(ModelSource::huggingface("microsoft/Phi-3.5-mini-instruct"))
        .isq(QuantizationLevel::Q4_0) // 4-bit quantization
        .paged_attention(true) // Memory-efficient attention
        .build();

    println!("Loading quantized model...");
    let model = MistralRsModel::new(config).await?;
    println!("Model loaded: {}", model.name());

    let agent = LlmAgentBuilder::new("quantized_assistant")
        .instruction("You are a helpful assistant. Be concise.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Níveis de quantização:

---

Passo 4: LoRA Adapters (Modelos Ajustados)

Carregue modelos com LoRA adapters para tarefas especializadas:

use adk_agent::LlmAgentBuilder;
use adk_mistralrs::{AdapterConfig, Llm, MistralRsAdapterModel, MistralRsConfig, ModelSource};
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load base model with LoRA adapter
    let config = MistralRsConfig::builder()
        .model_source(ModelSource::huggingface("meta-llama/Llama-3.2-3B-Instruct"))
        .adapter(AdapterConfig::lora("username/my-lora-adapter"))
        .build();

    println!("Loading model with LoRA adapter...");
    let model = MistralRsAdapterModel::new(config).await?;
    println!("Model loaded: {}", model.name());
    println!("Available adapters: {:?}", model.available_adapters());

    let agent = LlmAgentBuilder::new("lora_assistant")
        .instruction("You are a helpful assistant with specialized knowledge.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Troque adapters em tempo de execução:

model.swap_adapter("another-adapter").await?;

---

Passo 5: Modelos de Visão (Compreensão de Imagens)

Processe imagens com modelos de visão-linguagem:

use adk_mistralrs::{Llm, MistralRsConfig, MistralRsVisionModel, ModelSource};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = MistralRsConfig::builder()
        .model_source(ModelSource::huggingface("microsoft/Phi-3.5-vision-instruct"))
        .build();

    println!("Loading vision model...");
    let model = MistralRsVisionModel::new(config).await?;
    println!("Model loaded: {}", model.name());

    // Analisar uma imagem
    let image = image::open("photo.jpg")?;
    let response = model.generate_with_image("Describe this image.", vec![image]).await?;

    Ok(())
}

Passo 6: Servindo Múltiplos Modelos

Sirva múltiplos modelos a partir de uma única instância:

use adk_mistralrs::{MistralRsConfig, MistralRsMultiModel, ModelSource};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let multi = MistralRsMultiModel::new();

    // Add models
    let phi_config = MistralRsConfig::builder()
        .model_source(ModelSource::huggingface("microsoft/Phi-3.5-mini-instruct"))
        .build();
    multi.add_model("phi", phi_config).await?;

    let gemma_config = MistralRsConfig::builder()
        .model_source(ModelSource::huggingface("google/gemma-2-2b-it"))
        .build();
    multi.add_model("gemma", gemma_config).await?;

    // Set default and route requests
    multi.set_default("phi").await?;
    println!("Available models: {:?}", multi.model_names().await);

    // Route to specific model
    // multi.generate_with_model(Some("gemma"), request, false).await?;

    Ok(())
}

---

Fontes de Modelo

HuggingFace Hub (Padrão)

ModelSource::huggingface("microsoft/Phi-3.5-mini-instruct")

Diretório Local

ModelSource::local("/path/to/model")

GGUF Pré-Quantizado

ModelSource::gguf("/path/to/model.Q4_K_M.gguf")

---

Modelos Recomendados

---

Aceleração de Hardware

macOS (Apple Silicon)

adk-mistralrs = { git = "https://github.com/zavora-ai/adk-rust", features = ["metal"] }

A aceleração Metal é automática em Macs M1/M2/M3.

GPU NVIDIA

adk-mistralrs = { git = "https://github.com/zavora-ai/adk-rust", features = ["cuda"] }

Requer CUDA toolkit 11.8+.

Apenas CPU

Nenhum recurso necessário - CPU é o padrão.

---

Exemplos de Execução

# Uso básico
cargo run --bin basic

# Com quantização
cargo run --bin quantized

# Adaptadores LoRA
cargo run --bin lora

# Configuração multi-modelo
cargo run --bin multimodel

# Modelos de visão
cargo run --bin vision

---

Solução de Problemas

Sem Memória

// Habilitar quantização
.isq(QuantizationLevel::Q4_0)
// Habilitar atenção paginada
.paged_attention(true)

Primeiro Carregamento Lento

• A primeira execução baixa o modelo (~2-8GB)
• As execuções subsequentes usam o modelo em cache

Modelo Não Encontrado

• Verifique se o ID do modelo HuggingFace está correto
• Garanta conexão com a internet para o primeiro download

---

Relacionado

• Provedores de Modelo - Provedores de LLM na nuvem
• Ollama - Servidor de modelo local alternativo
• LlmAgent - Usando modelos com agentes

---

Anterior: ← Ollama (Local) | Próximo: Ferramentas de Função →