mistral.rs 統合

外部サーバーや API キーを使用せず、ネイティブ Rust 推論で LLMs をローカルで実行します。

---

mistral.rs とは？

mistral.rs は、LLMs をハードウェア上で直接実行する、高性能な Rust 推論エンジンです。ADK-Rust は adk-mistralrs crate を通じてこれを統合しており、v0.8.0 に固定され、Gemma 4 をサポートしています。

主な特徴:

• 🦀 ネイティブ Rust - Python や外部サーバーは不要
• 🔒 完全オフライン - API キーやインターネット接続は不要
• ⚡ ハードウェアアクセラレーション - CUDA、Metal（3.1 bfloat16）、CPU 最適化
• 📦 量子化 - 限られたハードウェアで大規模モデルを実行するための ISQ、MXFP4、GGUF、UQFF
• 🔧 LoRA アダプター - ホットスワッピングに対応したファインチューニング済みモデル
• 👁️ マルチモーダル - 画像、音声、動画の理解（Gemma 4、Qwen 3 VL）
• 🎤 音声 - Voxtral によるリアルタイム音声認識
• 🎯 マルチモデル - 1 つのインスタンスから複数のモデルを提供

---

ステップ 1: 依存関係を追加する

adk-mistralrs はワークスペースメンバーとして crates.io に公開されています。標準の依存関係として追加します。

[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"

ハードウェアアクセラレーションを使用するには、feature flags を追加します。

# 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"] }

---

ステップ 2: 基本的な例

HuggingFace からモデルを読み込み、ローカルで実行します。

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

実行時の動作:

1. 初回実行時に、モデルが HuggingFace からダウンロードされます（モデルによって約 2～8GB）
2. モデルはローカルの ~/.cache/huggingface/ にキャッシュされます
3. 2 回目以降の実行では、キャッシュから即座に読み込まれます

---

ステップ 3: 量子化でメモリを削減する

大規模モデルには大量の RAM が必要です。ISQ（In-Situ Quantization）を使用してメモリ使用量を削減します。

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

量子化レベル:

---

ステップ 4: LoRA アダプター（ファインチューニング済みモデル）

特殊なタスク向けに LoRA アダプターを使用してモデルを読み込みます。

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

実行時にアダプターをホットスワップ:

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

---

ステップ 5: ビジョンモデル（画像理解）

ビジョン・ランゲージモデルを使用して画像を処理します。

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

---

ステップ 6: 複数モデルのサービング

1つのインスタンスから複数のモデルを提供します。

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

---

モデルソース

HuggingFace ハブ（デフォルト）

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

ローカルディレクトリ

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

量子化済み GGUF

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

---

推奨モデル

---

ハードウェアアクセラレーション

macOS（Apple Silicon）

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

M1/M2/M3 Mac では Metal アクセラレーションが自動的に有効になります。

NVIDIA GPU

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

CUDA toolkit 11.8 以降が必要です。

CPU のみ

特別な機能は必要ありません。CPU がデフォルトです。

---

Crate の検証

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

---

トラブルシューティング

メモリ不足

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

初回読み込みが遅い

• 初回実行時にモデル（約 2～8GB）がダウンロードされます
• 2 回目以降の実行ではキャッシュされたモデルが使用されます

モデルが見つからない

• HuggingFace モデル ID が正しいことを確認してください
• 初回ダウンロード時にインターネット接続が確立されていることを確認してください

---

関連項目

• モデルプロバイダー - クラウド LLM プロバイダー
• Ollama - 代替のローカルモデルサーバー
• LlmAgent - エージェントでモデルを使用する

---

前へ: ← Ollama（ローカル） | 次へ: Function Tools →