rig — biblioteca para integração de LLM em Rust

No mundo do desenvolvimento Rust, trabalhar com grandes modelos de linguagem (LLMs) sempre foi um desafio. A maioria dos SDKs era escrita em Python ou JavaScript, e o ecossistema Rust oferecia apenas clientes HTTP desconexos. A biblioteca rig (Rust Integration with GGUF/LLM) resolve esse problema, fornecendo uma interface unificada, ergonômica e segura para interagir com dezenas de provedores de LLM: OpenAI, Anthropic, Cohere, Google Gemini, Llama.cpp, Ollama e outros.

Por que usar rig? Primeiro, ela oferece uma API type-safe: todas as requisições e respostas são estritamente tipadas, eliminando uma classe inteira de erros em tempo de execução. Segundo, a rig implementa pipelines — cadeias de chamadas LLM componíveis com suporte a streaming, janelas de contexto e chamadas de ferramentas (tool calling). Terceiro, a biblioteca foi projetada com foco em desempenho: assincronicidade nativa, alocações mínimas e suporte a batching.

Este artigo é um guia extremamente detalhado sobre rig. Vamos abordar a instalação, os principais métodos, escrever um exemplo real e dar dicas de otimização. Ao final, você será capaz de criar aplicações Rust prontas para produção que utilizam LLMs.

Instalação

Adicione a rig ao seu projeto Cargo:

cargo add rig-core --features openai,anthropic,cohere,gemini,ollama,llama-cpp

Se você precisar apenas de um provedor, como OpenAI:

cargo add rig-core --features openai

Para trabalhar com modelos locais via llama.cpp, você precisará instalar o próprio llama.cpp (baixe do GitHub) e compilá-lo com suporte a CUDA/Metal. Em seguida, adicione a feature llama-cpp.

Versão mínima do Rust: 1.75.0. Verifique:

rustc --version

Início Rápido

Crie um arquivo src/main.rs e escreva uma requisição simples para a OpenAI:

use rig::providers::openai;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Inicializa o cliente através da variável de ambiente OPENAI_API_KEY
    let client = openai::Client::from_env();
    
    // Cria o modelo
    let model = client.model("gpt-4o-mini").build();
    
    // Envia a requisição
    let response = model.prompt("Conte uma piada sobre programadores").await?;
    
    println!("{}", response);
    Ok(())
}

Execute:

export OPENAI_API_KEY="sk-..."
cargo run

Você verá uma piada gerada. Parabéns — você acabou de integrar um LLM em Rust!

Principais Métodos e Funções

Vamos analisar os métodos-chave da rig. Para cada um, forneceremos a assinatura, descrição e um exemplo funcional.

1. Client::from_env()

Assinatura: pub fn from_env() -> Self

O que faz: Cria um cliente para um provedor específico, lendo a chave da API de uma variável de ambiente (ex: OPENAI_API_KEY).

use rig::providers::openai;
let client = openai::Client::from_env();

2. Client::model(name)

Assinatura: pub fn model(&self, model_name: &str) -> ModelBuilder

O que faz: Retorna um builder para configurar o modelo. Permite definir temperatura, max_tokens, stop words e outros parâmetros.

let model = client.model("gpt-4o")
    .temperature(0.7)
    .max_tokens(200)
    .build();

3. Model::prompt(text)

Assinatura: pub async fn prompt(&self, prompt: impl Into<String>) -> Result<String, ModelError>

O que faz: Envia