Ir para o conteúdo

llama-crab

Bindings Rust seguros, ergonômicos e completos para llama.cpp.

Crates.io docs.rs MSRV: 1.88 License: MIT llama.cpp pinned

O que é o llama-crab?

llama-crab é um crate Rust (na verdade um workspace de dois crates) que oferece uma API 100% segura em Rust sobre o llama.cpp. Você pode carregar qualquer modelo GGUF, executar completions de texto e chat, calcular embeddings, restringir a geração com uma gramática GBNF, acionar modelos visão-linguagem através do mtmd, ou expor tudo via HTTP — tudo isso sem tocar em um único bloco unsafe no nível da aplicação.

  • Comece em 5 minutos

    Carregue um modelo e gere uma completion com poucas linhas.

    Instalação Seu primeiro programa

  • Execute em qualquer hardware

    CPU, Metal, CUDA, Vulkan, ROCm, OpenCL e KleidiAI — escolha seu backend em tempo de compilação e descarregue quantas camadas couberem na VRAM.

    Backends & offload de GPU

  • Distribua em celulares e tablets

    Perfis release-size e release-perf, OpenCL + KleidiAI para Android, Metal para iOS, e MobilePreset para padrões sensatos.

    Distribuição mobile

  • Visão e áudio

    Combine um GGUF de texto com um projetor mmproj e alimente imagens ou áudio no mesmo contexto.

    Multimodal

  • Embeddings e reranking

    Extraia vetores com pooling configurável, faça busca semântica ou use um cross-encoder para ranqueamento de alta qualidade.

    Embeddings

  • Servidor HTTP pronto

    llama-crab-server expõe a API de alto nível através de uma interface HTTP compatível com OpenAI, com streaming SSE.

    Servidor

Um gostinho da API

use llama_crab::{Llama, LlamaParams};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut llama = Llama::load(
        LlamaParams::new("models/qwen2.5-0.5b-instruct-q4_k_m.gguf")
            .with_n_ctx(2048)
            .with_n_gpu_layers(99),
    )?;

    let response = llama.create_completion("The capital of France is", 32)?;
    println!("{}", response.text);
    Ok(())
}

use llama_crab::chat::BuiltinTemplate;
use llama_crab::high_level::chat_completion::{create_chat_completion_with, ChatMessage};
use llama_crab::{Llama, LlamaParams, Role};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut llama = Llama::load(
        LlamaParams::new("models/instruct.gguf").with_n_ctx(4096),
    )?;

    let messages = vec![
        ChatMessage::new(Role::System, "You are a concise assistant."),
        ChatMessage::new(Role::User, "Explain Rust ownership in one paragraph."),
    ];

    let response = create_chat_completion_with(
        &mut llama,
        &messages,
        BuiltinTemplate::ChatMl,
        &[],
        128,
    )?;

    println!("{}", response.content);
    Ok(())
}

use llama_crab::{Llama, LlamaParams};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut llama = Llama::load(
        LlamaParams::new("models/bge-small-en-v1.5-q4_k_m.gguf")
            .with_n_ctx(512)
            .with_embeddings(true),
    )?;

    let embedding = llama.embed("Rust is memory-safe.", true)?;
    println!("dim = {}", embedding.len());
    Ok(())
}

Por que llama-crab?

llama-crab foi desenhado para aplicações que precisam acessar o llama.cpp diretamente sem abrir mão da segurança, do empacotamento e da disciplina de deploy do Rust.

  • Seguro por padrão

    A API de alto nível não expõe superfície unsafe. As fronteiras FFI ficam atrás de wrappers tipados, e o acesso bruto continua opt-in para os casos que realmente precisam dele.

  • Superfície de recursos completa

    Amostragem, formatos de chat, pipelines de visão, gramáticas por JSON-Schema, decodificação especulativa, embeddings, reranking e fluxos de cache KV ficam disponíveis por APIs seguras em Rust.

  • Builds reproduzíveis

    O llama.cpp fica fixado em um commit conhecido, o build explicita os backends habilitados, e a CI mantém visíveis as combinações CPU / CUDA / Vulkan / Metal / ROCm suportadas.

  • Performance em primeiro lugar

    Offload de camadas, flash attention, presets mobile, cadeias de amostragem, decodificação especulativa e parsers de tool-call ficam expostos sem exigir kernels customizados no código da aplicação.

Crates neste workspace

Crate Propósito Quando usar
llama-crab API 100% segura em Rust: carregamento de modelo, amostragem, chat, embeddings, cola do servidor. Maioria das aplicações. Este é o crate do qual você depende.
llama-crab-sys FFI bruta gerada via bindgen sobre wrapper.h + CMake. Quando você precisa de acesso direto a símbolos do llama.cpp que o crate seguro ainda não encapsula.
llama-crab-server Binário HTTP construído sobre llama-crab. Quando você quer um endpoint compatível com OpenAI sem escrever um.

Licença

llama-crab é distribuído sob a Licença MIT. Veja LICENSE-MIT para o texto completo.

Por onde começar?