Integración de mistral.rs

Ejecuta LLMs localmente con inferencia nativa de Rust: sin servidores externos ni claves de API.

---

¿Qué es mistral.rs?

mistral.rs es un motor de inferencia de Rust de alto rendimiento que ejecuta LLMs directamente en tu hardware. ADK-Rust lo integra mediante el crate adk-mistralrs, fijado en v0.8.0 con compatibilidad con Gemma 4.

Aspectos destacados:

• 🦀 Rust nativo: sin Python ni servidores externos
• 🔒 Totalmente offline: no se necesitan claves de API ni conexión a Internet
• ⚡ Aceleración de hardware: CUDA, Metal (bfloat16 3.1), optimizaciones de CPU
• 📦 Cuantización: ISQ, MXFP4, GGUF, UQFF para ejecutar modelos grandes en hardware limitado
• 🔧 Adaptadores LoRA: compatibilidad con modelos ajustados y cambio en caliente
• 👁️ Multimodal: comprensión de imágenes, audio y vídeo (Gemma 4, Qwen 3 VL)
• 🎤 Voz: reconocimiento de voz en tiempo real con Voxtral
• 🎯 Varios modelos: sirve varios modelos desde una única instancia

---

Paso 1: Añadir dependencias

adk-mistralrs se publica en crates.io como miembro del espacio de trabajo. Añádelo como una dependencia estándar:

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

[dependencies]
adk-mistralrs = "2.1.0"
adk-agent = "2.1.0"
adk-rust = "2.1.0"
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"

Para la aceleración de hardware, añade indicadores de características:

# macOS with Apple Silicon
adk-mistralrs = { version = "2.1.0", features = ["metal"] }

# NVIDIA GPU (requires CUDA toolkit)
adk-mistralrs = { version = "2.1.0", features = ["cuda"] }

---

Paso 2: Ejemplo básico

Carga un modelo desde HuggingFace y ejecútalo 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(())
}

Qué sucede:

1. La primera ejecución descarga el modelo desde HuggingFace (aproximadamente 2-8 GB, según el modelo)
2. El modelo se almacena en caché localmente en ~/.cache/huggingface/
3. Las ejecuciones posteriores cargan el modelo de la caché al instante

---

Paso 3: Reducir la memoria con cuantización

Los modelos grandes necesitan mucha RAM. Usa ISQ (cuantización en el propio lugar) para reducir el consumo de memoria:

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(())
}

Niveles de cuantización:

---

Paso 4: LoRA Adaptadores (Modelos ajustados)

Carga modelos con adaptadores LoRA para tareas 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(())
}

Cambia adaptadores en caliente durante el tiempo de ejecución:

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

---

Paso 5: Modelos de visión (Comprensión de imágenes)

Procesa imágenes con modelos de visión-lenguaje:

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());

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

    Ok(())
}

---

Paso 6: Servicio de múltiples modelos

Sirve varios modelos desde una única instancia:

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(())
}

---

Fuentes de modelos

HuggingFace Hub (Predeterminado)

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

Directorio local

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

GGUF pre-cuantizado

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

---

Modelos recomendados

---

Aceleración de hardware

macOS (Apple Silicon)

adk-mistralrs = { version = "2.1.0", features = ["metal"] }

La aceleración de Metal es automática en los Mac con M1/M2/M3.

GPU NVIDIA

adk-mistralrs = { version = "2.1.0", features = ["cuda"] }

Requiere el kit de herramientas CUDA 11.8 o posterior.

Solo CPU

No se necesitan funciones: la CPU es la opción predeterminada.

---

Validar el crate

cargo build -p adk-mistralrs
cargo build -p adk-mistralrs --features metal

---

Solución de problemas

Memoria insuficiente

// Enable quantization
.isq(QuantizationLevel::Q4_0)
// Enable paged attention
.paged_attention(true)

Primera carga lenta

• La primera ejecución descarga el modelo (~2-8GB)
• Las ejecuciones posteriores utilizan el modelo en caché

Modelo no encontrado

• Comprueba que el ID de modelo HuggingFace sea correcto
• Asegúrate de tener conexión a Internet para la primera descarga

---

Relacionado

• Proveedores de modelos - proveedores de modelos LLM en la nube
• Ollama - servidor de modelos local alternativo
• LlmAgent - Uso de modelos con agentes

---

Anterior: ← Ollama (local) | Siguiente: Herramientas de función →