Programming on kenji.blog

Casos de Uso da API Recente e Códigos de Exemplo do Microsoft.Windows.AI

Fri, 11 Sep 2026 18:00:00 +0900

Casos de Uso da API Recente e Códigos de Exemplo do Microsoft.Windows.AI: Explorando as Profundezas do Windows Copilot Runtime

1. Introdução: A Nova Era do Windows com IA Integrada Nativamente

Nos últimos anos, a evolução da tecnologia de IA tem sido notável, com uma rápida mudança de paradigma do uso de Grandes Modelos de Linguagem (LLM) na nuvem para a inferência de IA em dispositivos edge (PCs locais). O núcleo disso é o “Windows Copilot Runtime” fornecido pela Microsoft para o Windows 11 e a API “Microsoft.Windows.AI” para controlá-lo.

O desenvolvimento de aplicativos usando APIs em nuvem (como OpenAI ou Azure OpenAI) é fácil, mas traz desafios como latência, privacidade e custos contínuos. Por outro lado, a execução de modelos de IA localmente permite obter aplicativos de latência ultrabaixa que funcionam offline sem enviar dados confidenciais para fora do dispositivo.

Neste artigo, explicaremos detalhadamente e de forma abrangente, da arquitetura ao ajuste de desempenho, os métodos de implementação de recursos de IA local, que serão essenciais no desenvolvimento de aplicativos para Windows, juntamente com exemplos de código prático em C# e C++. Além de simplesmente chamar a API, nos aprofundaremos em detalhes técnicos avançados, como a utilização de hardware subjacente (NPU e GPU) e a integração com o DirectML.

2. Windows Copilot Runtime e a Visão Geral da Arquitetura

O Windows Copilot Runtime é uma pilha de IA projetada para permitir que os desenvolvedores integrem facilmente modelos de IA no Windows e extraiam o melhor desempenho. Este runtime abstrai a aceleração de hardware no nível do sistema operacional e fornece uma interface unificada para os desenvolvedores.

graph TD App["Aplicativo Windows (C# / C++)"] --> API["APIs Microsoft.Windows.AI"] App --> ORT["ONNX Runtime"] API --> WCR["Windows Copilot Runtime (Camada do SO)"] WCR --> SLM["Modelos Locais (Phi-Silica, etc.)"] ORT --> DML["Provedor de Execução DirectML"] SLM --> DML DML --> DXCore["DXCore / DirectX 12"] DXCore --> NPU["NPU (Unidade de Processamento Neural)"] DXCore --> GPU["GPU (Unidade de Processamento Gráfico)"] DXCore --> CPU["CPU"]

Como o diagrama de arquitetura acima mostra, ao usar a API de alto nível Microsoft.Windows.AI, o aplicativo pode acessar diretamente Pequenos Modelos de Linguagem (SLM: como o Phi-Silica) integrados ao sistema operacional. Além disso, ao usar um modelo personalizado, a aceleração de hardware pode ser explicitamente utilizada via ONNX Runtime e DirectML. Como a camada do sistema operacional otimiza a distribuição da carga de trabalho para CPU, GPU e NPU, os desenvolvedores podem construir aplicativos de IA de alto desempenho sem se preocupar profundamente com as diferenças de hardware.

3. Aceleração de Hardware e Avaliação Matemática da NPU

Os mais recentes Copilot+ PCs são equipados com a NPU (Unidade de Processamento Neural), um processador especializado em processamento de IA. O desempenho da NPU é geralmente avaliado em TOPS (Tera Operations Per Second).

Na inferência de modelos de IA, a capacidade de cálculo, especialmente de multiplicação de matrizes (GEMM: General Matrix Multiply), determina a taxa de transferência (throughput). O desempenho máximo teórico do hardware $P_{\text{peak}}$ é estimado pela seguinte fórmula:

$$ P_{\text{peak}} = f \times N_{\text{cores}} \times N_{\text{MACs/core}} \times 2 $$

Onde:

$f$ é a frequência de clock da NPU (Hz)
$N_{\text{cores}}$ é o número de núcleos dentro da NPU
$N_{\text{MACs/core}}$ é o número de unidades MAC (Multiply-Accumulate) por núcleo
O último $2$ ocorre porque uma única operação MAC é contada como duas operações (FLOPs/OPs) de multiplicação e adição.

Por exemplo, para uma NPU com frequência de 1,5 GHz, 4 núcleos e cada núcleo tendo 4096 MACs:

$$ P_{\text{peak}} = 1.5 \times 10^9 \times 4 \times 4096 \times 2 \approx 49.15 \text{ TOPS} $$

Isso demonstra matematicamente que atende ao requisito de 40 TOPS para os Copilot+ PCs com Windows 11.

Além disso, a inferência (fase de decodificação) de modelos de IA, especialmente LLMs, tende a ser limitada pela memória (Memory-Bound). A largura de banda teórica $BW$ da memória do sistema é calculada da seguinte forma:

$$ BW = f_{\text{mem}} \times W_{\text{bus}} \times \frac{2}{8} $$

Para memória LPDDR5x-8533 ($f_{\text{mem}} = 8533 \text{ MT/s}$) e um barramento de 128 bits ($W_{\text{bus}} = 128$), a largura de banda é de aproximadamente $136 \text{ GB/s}$. Na otimização de aplicativos de IA, a forma de economizar essa largura de banda é muito importante, tornando a quantização (Quantization) de modelos, que será discutida mais adiante, essencial.

4. Configuração do Ambiente de Desenvolvimento

Para usar a API de IA mais recente do Windows, é necessário configurar o seguinte ambiente e conjunto de ferramentas:

SO: Windows 11 Versão 24H2 ou posterior (Altamente recomendado um dispositivo equipado com NPU que atenda aos requisitos do Copilot+ PC)
SDK: Windows App SDK (versão compatível com a extensão de IA, v1.5 ou posterior)
Ambiente de Desenvolvimento: Visual Studio 2022 (v17.10 ou posterior), carga de trabalho de desenvolvimento nativo com C++ e carga de trabalho de desenvolvimento para desktop .NET
Pacotes: Instalar Microsoft.Windows.AI e Microsoft.ML.OnnxRuntime.DirectML via NuGet

1
2
3
4
5
6


<!-- Exemplo de configuração do .csproj -->
<ItemGroup>
 <PackageReference Include="Microsoft.Windows.AI" Version="1.0.0-preview1" />
 <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.5.240311000" />
 <PackageReference Include="Microsoft.ML.OnnxRuntime.DirectML" Version="1.17.1" />
</ItemGroup>

5. [Deep Dive 1] Utilizando o Modelo de Linguagem Local (Phi-Silica) com C#

O Windows Copilot Runtime inclui o “Phi-Silica”, um modelo de linguagem de pequena escala e alta eficiência desenvolvido pela Microsoft, como um componente padrão do sistema operacional. Isso permite o processamento avançado de linguagem natural (resumo de textos, geração de código, chatbots) em um ambiente offline, sem precisar baixar modelos do tamanho de GB pela rede.

Abaixo está um exemplo de código avançado para construir uma IA de bate-papo em C# usando o namespace Microsoft.Windows.AI.Generative. Ele suporta respostas em streaming e gera texto em tempo real sem bloquear a thread da UI.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84


using System;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Windows.AI.Generative;

namespace WindowsAI.Sample
{
 public class LocalLanguageModelService
 {
 private LanguageModel _languageModel;
 private bool _isInitialized = false;

 /// <summary>
 /// Inicializa o modelo de linguagem. Verifica a disponibilidade da NPU e carrega o modelo no dispositivo ideal.
 /// </summary>
 public async Task InitializeAsync()
 {
 if (_isInitialized) return;

 Console.WriteLine("Verificando os requisitos do sistema e a disponibilidade do modelo de IA local (Phi-Silica)...");

 // Verifica se o modelo está disponível no sistema (pode solicitar o download caso não seja suportado)
 var availability = await LanguageModel.CheckAvailabilityAsync();
 if (availability != LanguageModelAvailability.Available)
 {
 throw new InvalidOperationException($"O modelo de IA local não está disponível no momento. Estado: {availability}");
 }

 // Cria a instância do modelo (neste momento, o mapeamento para o espaço de memória e a inicialização da NPU ocorrem)
 _languageModel = await LanguageModel.CreateAsync();
 _isInitialized = true;

 Console.WriteLine("Inicialização do modelo de linguagem concluída. A aceleração de hardware via DirectML está ativa.");
 }

 /// <summary>
 /// Recebe o prompt do usuário e gera uma resposta em streaming.
 /// </summary>
 public async Task GenerateResponseStreamAsync(string prompt, CancellationToken cancellationToken)
 {
 if (!_isInitialized) await InitializeAsync();

 Console.WriteLine($"\n[Entrada do Usuário]: {prompt}\n[Assistente de IA]: ");

 // Configura os hiperparâmetros de geração
 var options = new LanguageModelOptions
 {
 Temperature = 0.7f,
 TopP = 0.9f,
 MaxTokens = 2048,
 RepetitionPenalty = 1.1f
 };

 // Constrói o contexto da conversa
 var context = new LanguageModelContext();
 context.AddSystemMessage("Você é um assistente de IA avançado que funciona diretamente na NPU local do Windows. Pense logicamente passo a passo e responda de forma concisa.");
 context.AddUserMessage(prompt);

 try
 {
 // Chama a API de inferência em streaming
 var responseStream = _languageModel.GenerateResponseStreamAsync(context, options);

 // Itera de forma assíncrona sobre os fragmentos (chunks) retornados como IAsyncEnumerable
 await foreach (var chunk in responseStream.WithCancellation(cancellationToken))
 {
 // Exibe os tokens gerados (chunks) no console em tempo real
 // Em um aplicativo de UI, o DispatcherQueue seria usado aqui para refletir em um TextBox, etc.
 Console.Write(chunk.Text);
 }
 Console.WriteLine();
 }
 catch (OperationCanceledException)
 {
 Console.WriteLine("\n[A geração foi cancelada pelo usuário ou pelo sistema]");
 }
 catch (Exception ex)
 {
 Console.WriteLine($"\n[Ocorreu um erro fatal: {ex.Message}]");
 }
 }
 }
}

5.1 Explicação da Arquitetura na Implementação em C#

O núcleo deste código é a validação pré-execução usando LanguageModel.CheckAvailabilityAsync() e o streaming assíncrono através do GenerateResponseStreamAsync. Quando o Copilot Runtime operando em segundo plano no sistema operacional recebe essa chamada de API, ele invoca internamente o ONNX Runtime e seleciona o Provedor de Execução ideal (DirectML + NPU em muitos dos PCs mais recentes) dependendo da configuração do sistema.

Os desenvolvedores podem integrar pipelines de inferência de IA de última geração em seus aplicativos com apenas algumas linhas de código em C#, sem a necessidade de se preocuparem com o formato dos tensores do modelo, a implementação do tokenizador ou a gestão da memória de cache KV.

6. [Deep Dive 2] Inferência de Alta Velocidade de Modelos Personalizados com C++ e DirectML

Ao lidar com domínios específicos (segmentação de imagens própria, reconhecimento de fala, modelos personalizados de detecção de objetos, etc.) que não podem ser cobertos apenas pelo modelo de linguagem padrão do sistema operacional, os desenvolvedores precisarão manipular diretamente o ONNX Runtime e o DirectML, que estão nas camadas inferiores do Microsoft.Windows.AI.

O uso de C++ permite otimizar a alocação de memória ao máximo e extrair o pico de desempenho da NPU/GPU. Abaixo está a implementação principal de um pipeline avançado de inicialização e inferência para executar um modelo personalizado no formato ONNX (ex: YOLOv8) em C++ usando DirectML.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99


#include <iostream>
#include <vector>
#include <string>
#include <stdexcept>
#include <onnxruntime_cxx_api.h>
#include <dml_provider_factory.h>

class CustomVisionAIProcessor {
private:
 Ort::Env env;
 Ort::Session session{nullptr};
 Ort::AllocatorWithDefaultOptions allocator;

public:
 CustomVisionAIProcessor(const std::wstring& modelPath)
 : env(ORT_LOGGING_LEVEL_WARNING, "VisionAIProcessor") {

 Ort::SessionOptions sessionOptions;
 // Otimização do número de threads
 sessionOptions.SetIntraOpNumThreads(1);
 // Define o nível de otimização do gráfico para o máximo
 sessionOptions.SetGraphOptimizationLevel(GraphOptimizationLevel::ORT_ENABLE_ALL);

 // 1. Adição do Provedor de Execução DirectML (DML EP)
 // device_id = 0 é o adaptador padrão recomendado pelo sistema (NPU ou GPU de alto desempenho)
 const OrtApi& ortApi = Ort::GetApi();
 OrtDmlApi* dmlApi = nullptr;
 OrtStatus* status = ortApi.GetExecutionProviderApi("DML", ORT_API_VERSION, reinterpret_cast<void**>(&dmlApi));

 if (status == nullptr && dmlApi != nullptr) {
 Ort::ThrowOnError(dmlApi->SessionOptionsAppendExecutionProvider_DML(sessionOptions, 0));
 std::cout << "[Info] O Provedor de Execução DirectML foi anexado com sucesso." << std::endl;
 } else {
 std::cerr << "[Warning] Falha ao obter a API do DirectML. Executando no modo de fallback da CPU." << std::endl;
 if (status != nullptr) ortApi.ReleaseStatus(status);
 }

 // 2. Carregamento do modelo e criação da sessão
 try {
 session = Ort::Session(env, modelPath.c_str(), sessionOptions);
 std::cout << "[Info] Modelo ONNX carregado com sucesso e o gráfico de computação foi compilado." << std::endl;
 } catch (const Ort::Exception& e) {
 std::cerr << "[Error] Falha ao carregar o modelo: " << e.what() << std::endl;
 throw;
 }
 }

 void RunInference(const std::vector<float>& imageTensor, const std::vector<int64_t>& inputShape) {
 // 3. Criação do buffer para o tensor de entrada
 Ort::MemoryInfo memoryInfo = Ort::MemoryInfo::CreateCpu(OrtArenaAllocator, OrtMemTypeDefault);
 Ort::Value inputTensor = Ort::Value::CreateTensor<float>(
 memoryInfo,
 const_cast<float*>(imageTensor.data()),
 imageTensor.size(),
 inputShape.data(),
 inputShape.size()
 );

 // 4. Obtenção dinâmica dos nomes dos nós de entrada e saída
 auto inputNamePtr = session.GetInputNameAllocated(0, allocator);
 auto outputNamePtr = session.GetOutputNameAllocated(0, allocator);
 const char* inputNames[] = { inputNamePtr.get() };
 const char* outputNames[] = { outputNamePtr.get() };

 // 5. Execução da inferência (descarregada para NPU/GPU via DirectML)
 std::cout << "[Info] Iniciando a execução do motor de inferência..." << std::endl;
 auto startTime = std::chrono::high_resolution_clock::now();

 auto outputTensors = session.Run(Ort::RunOptions{nullptr}, inputNames, &inputTensor, 1, outputNames, 1);

 auto endTime = std::chrono::high_resolution_clock::now();
 auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(endTime - startTime);

 // 6. Recuperação e análise dos tensores de resultado
 float* outputData = outputTensors.front().GetTensorMutableData<float>();
 size_t outputSize = outputTensors.front().GetTensorTypeAndShapeInfo().GetElementCount();

 std::cout << "[Result] Inferência concluída: " << duration.count() << " ms" << std::endl;
 std::cout << "[Result] Número de elementos no tensor de saída: " << outputSize << std::endl;
 // *Após isso, a implementação do processamento NMS (Non-Maximum Suppression) e o desenho das caixas delimitadoras (bounding boxes) devem ser feitos no tensor de saída
 }
};

int main() {
 try {
 // Caminho do modelo ONNX a ser executado
 CustomVisionAIProcessor processor(L"models/yolov8n_quantized.onnx");

 // Dados de imagem fictícios para inferência (Tamanho do lote 1 x 3 canais x 640 x 640)
 std::vector<int64_t> inputShape = {1, 3, 640, 640};
 std::vector<float> dummyImage(1 * 3 * 640 * 640, 0.5f);

 processor.RunInference(dummyImage, inputShape);
 } catch (const std::exception& e) {
 std::cerr << "O programa foi encerrado de forma anormal: " << e.what() << std::endl;
 return -1;
 }
 return 0;
}

6.1 A Importância da Gestão de Memória e Inferência Zero-Copy em C++

A maior vantagem de usar o DirectML com C++ é a forte integração com o DirectX 12 (DX12) que isso possibilita. O código acima inclui a cópia de dados da memória da CPU padrão por uma questão didática, mas em aplicações de processamento de vídeo e motores de jogos reais, muitas vezes já existem imagens (texturas) mantidas no espaço de memória da GPU ou NPU via DX12.

Neste caso, usando as características avançadas de vinculação da API OrtDmlApi, você pode alcançar a “Inferência Zero-Copy (Zero-Copy Inference)”, onde recursos DX12 são mapeados diretamente como tensores para o ONNX Runtime. Com isso, o custo indireto de transferência de dados do barramento PCIe (o consumo da largura de banda $BW$ descrito acima) desaparece completamente, resultando em uma melhoria drástica nas taxas de quadros para o processamento de vídeo em tempo real.

7. Otimização de Desempenho e Melhores Práticas

Abaixo estão as estratégias de otimização essenciais para o desenvolvimento de aplicativos de IA de ponta usando a API de IA do Windows e o DirectML.

7.1 Quantização de Modelos (Quantization) e Toolkit Olive

Para extrair o verdadeiro poder da NPU, é uma condição absoluta quantizar (Quantization) os pesos e ativações do modelo de IA de FP32 (ponto flutuante de precisão simples) para INT8 ou INT4. A arquitetura da NPU é especializada em operações com inteiros, o que permite atingir taxas de transferência teoricamente quatro vezes maiores e reduzir drasticamente o consumo de energia em INT8 em comparação com o FP32.

Ao usar a cadeia de ferramentas Olive (ONNX Live) oferecida pela Microsoft, os modelos de IA, como os do PyTorch, podem ser automaticamente otimizados para ambientes Windows. A ferramenta Olive fornece forte suporte para otimizações de atenção especializadas para modelos baseados em Transformers e compilação de gráficos por hardware.

7.2 Trade-off Entre Processamento em Lote e Streaming Interativo

Nas chamadas de API, a utilização da NPU (Compute Utilization) pode ser aumentada combinando múltiplas solicitações de inferência num processamento em lote. No entanto, no caso de IUs interativas, como chatbots, não é a taxa de transferência, mas sim o tempo até que o primeiro token seja gerado (TTFT: Time To First Token) que determina a experiência do usuário (UX). Portanto, as melhores práticas ditam projetar o tamanho de lote (batch size) como 1 em IUs interativas, priorizando a geração de streaming.

7.3 Tarefas em Segundo Plano e Integração com o SO

A inferência de IA consome localmente grandes quantidades de energia e recursos do sistema. Ao cooperar com a App Lifecycle API do Windows, há a necessidade de uma implementação que suspenda (Suspend) as tarefas de inferência de baixa prioridade ou restrinja o consumo de recursos quando o aplicativo for movido para o segundo plano.

sequenceDiagram participant User as "Usuário" participant App as "Aplicativo Windows (C#)" participant API as "Microsoft.Windows.AI" participant OS as "Windows Copilot Runtime" participant ORT as "ONNX Runtime (DML)" participant NPU as "Hardware NPU" User->>App: "Insere o prompt" App->>API: "GenerateResponseStreamAsync()" API->>OS: "Despacha o trabalho de inferência" OS->>ORT: "Solicitação de execução do gráfico" ORT->>NPU: "Execução da lista de comandos via DirectML" NPU-->>ORT: "Cálculo concluído (Geração de 1 token)" ORT-->>OS: "Resultado em tensor" OS-->>API: "Texto decodificado" API-->>App: "Fragmento IAsyncEnumerable" App-->>User: "Desenho em tempo real do texto na UI" Note over ORT,NPU: "Repete esse loop em alta velocidade até ser concluído"

Este diagrama de sequência ilustra a beleza do processamento assíncrono, através do qual os dados fluem em streaming da camada de hardware mais profunda da NPU para a camada de apresentação do aplicativo de forma contínua, sem bloquear a thread de UI de forma alguma.

8. Perspectivas Futuras e a Evolução da IA do Windows

As APIs Microsoft.Windows.AI e o Copilot Runtime estão passando por uma rápida evolução neste exato momento. Nas futuras atualizações para os desenvolvedores, são esperadas as seguintes mudanças de paradigma:

Integração Nativa da API Multimodal no SO: Em vez de apenas texto, a capacidade de processar simultaneamente e de forma contínua áudio, imagens e até transmissões de vídeo ao vivo, fornecendo inferência transversal de IA como um padrão ao nível do SO.
RAG (Retrieval-Augmented Generation) a Nível de Sistema: Uma IA pessoal super avançada construída através da colaboração de um modelo de IA com grupos de documentos pessoais locais e o índice do Windows Search, operando dentro de uma sandbox segura do SO e protegendo completamente a privacidade do usuário.
Dimensionamento Dinâmico de Recursos da NPU: Quando vários aplicativos de IA funcionam simultaneamente (por exemplo, cancelamento de ruído em segundo plano e geração de código em primeiro plano), o escalonador do kernel do Windows alterna os contextos de execução da NPU de forma dinâmica para garantir a Qualidade de Serviço (QoS).

9. Conclusão: O Futuro dos Aplicativos Transformados pela IA Local

O Copilot Runtime do Windows 11 e a API Microsoft.Windows.AI trouxeram uma arma extremamente poderosa chamada “IA Local” para todos os desenvolvedores do Windows. Não há mais a necessidade de depender completamente de APIs em nuvem. É possível eliminar a latência e oferecer uma experiência de IA de última geração que funciona totalmente offline aos usuários, protegendo rigorosamente a sua privacidade.

Pedimos que você utilize os conhecimentos abordados neste artigo sobre a integração do modelo de linguagem padrão do sistema via C#, a avaliação matemática de desempenho e a otimização extrema de hardware usando C++ e DirectML, para criar, com as suas próprias mãos, os próximos aplicativos de Windows “Nativos de IA”. As possibilidades infinitas que a IA traz estão à sua espera, através do código que você escrever.

Aviso Legal: Note que este artigo foi escrito com base nas versões de pré-lançamento da API e especificações mais recentes disponíveis em Setembro de 2026. Como as especificações da API e os requisitos de hardware podem mudar devido às atualizações do Windows, certifique-se de consultar as documentações oficiais da Microsoft Learn ao implementar.

Adeus Python! Construindo um Motor de Inferência de IA apenas com C++

Fri, 11 Sep 2026 17:00:00 +0900

1. Introdução: Por que abandonar o Python e criar um motor de inferência de IA em C++?

No desenvolvimento moderno de IA, o Python é o padrão de fato. Graças a frameworks poderosos como PyTorch e TensorFlow, é possível construir, treinar e inferir redes neurais complexas com apenas algumas linhas de código. No entanto, por trás desses frameworks, linguagens de baixo nível como C++ e CUDA estão lidando com o processamento pesado de cálculos. O Python atua apenas como uma “cola” (glue).

Então, por que se dar ao trabalho de eliminar o Python e construir um motor de inferência de IA exclusivamente em C++? Existem várias razões fortes para isso.

Desempenho extremo e baixa latência: Você pode eliminar completamente o overhead causado pelo GIL (Global Interpreter Lock) e pela tipagem dinâmica do Python. Especialmente em sistemas que exigem tempo real, atrasos de milissegundos podem ser fatal.
Facilidade de implantação: Configurar um ambiente Python (enormes bibliotecas, inferno de dependências) no ambiente do usuário final é extremamente difícil. Com o C++, basta distribuir um único binário executável (.exe ou binário ELF) vinculado estaticamente.
Suporte a dispositivos de borda: Em ambientes com severas restrições de recursos, como smartphones, dispositivos embarcados e Raspberry Pi, não há margem para executar um runtime Python que consome vários gigabytes de memória.
Controle direto de hardware: O controle de baixo nível, como o tempo de alocação de memória, uso explícito de instruções SIMD e otimização de transferências de memória com a GPU, é possível em C++.

Neste artigo, inspirando-nos muito na arquitetura da biblioteca “GGML” desenvolvida por Georgi Gerganov, explicaremos profundamente o processo de construir do zero um motor de inferência para executar Modelos de Linguagem de Grande Escala (LLMs) apenas com C++, mergulhando nas profundezas técnicas.

2. Visão geral da arquitetura do motor de inferência

O processamento de inferência de IA é, essencialmente, uma “série contínua de cálculos de matrizes gigantes”. Para executar isso de forma eficiente, o motor de inferência precisa ser composto pelos seguintes componentes.

graph TD A["Dados de Entrada (Tokens/Imagens)"] --> B["Gerenciamento de Tensores"] B --> C["Grafo de Computação (DAG)"] C --> D["Arena de Memória & Alocador"] C --> E["Agendador & Pool de Threads"] E --> F["Backend de CPU (AVX2/ARM NEON)"] E --> G["Backend de GPU (CUDA/Metal)"] F --> H["Resultados de Saída"] G --> H

Gerenciamento de Tensores (Tensor): Gerencia a estrutura de dados de arrays multidimensionais e o passo (Stride) de cada dimensão.
Grafo de Computação (Computation Graph): Representa as operações de cada camada da rede neural como um Grafo Acíclico Dirigido (DAG).
Arena de Memória (Memory Arena): Um mecanismo de gerenciamento de memória pré-alocada para evitar o overhead de alocação dinâmica de memória (malloc ou new).
Backend: A implementação de operações otimizadas para hardwares específicos, como CPU ou GPU (Kernels).

Vamos montar tudo isso usando os poderosos recursos do C++ (templates, aritmética de ponteiros, RAII, etc.).

3. Os segredos do gerenciamento de memória: Arena de Memória e Alinhamento SIMD

O gerenciamento de memória em um motor de inferência é um dos fatores mais importantes que afeta diretamente o desempenho. Durante a inferência, um número colossal de tensores intermediários é gerado, especialmente ao passar por cada camada de um modelo Transformer. Se alocarmos e liberarmos isso a cada vez com o malloc padrão, a fragmentação do heap e as trocas de contexto do SO causarão uma lentidão fatal.

Portanto, adotamos a abordagem da “Arena de Memória (Memory Arena)”. Trata-se de uma técnica em que calculamos (ou fixamos) a quantidade máxima de memória necessária no início da inferência, alocamos tudo de uma vez e separamos a memória apenas incrementando um ponteiro.

3.1 A importância do alinhamento

As CPUs modernas suportam instruções SIMD (Single Instruction, Multiple Data). Exemplos incluem AVX2/AVX-512 da Intel/AMD e NEON da ARM. Essas instruções processam 256 bits (32 bytes) ou 512 bits (64 bytes) de dados de uma só vez, mas a memória de dados a ser processada deve estar alinhada a um limite específico de bytes (geralmente 32 ou 64 bytes).

Abaixo, um exemplo de implementação em C++ de uma arena de memória considerando o alinhamento:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


#include <cstdint>
#include <cstddef>
#include <stdexcept>
#include <iostream>

struct MemoryArena {
 size_t size;
 size_t offset;
 uint8_t* data;

 MemoryArena(size_t size) : size(size), offset(0) {
 // POSIX系なら posix_memalign、Windowsなら _aligned_malloc を使用
#ifdef _WIN32
 data = static_cast<uint8_t*>(_aligned_malloc(size, 64));
#else
 if (posix_memalign(reinterpret_cast<void**>(&data), 64, size) != 0) {
 throw std::bad_alloc();
 }
#endif
 }

 ~MemoryArena() {
#ifdef _WIN32
 _aligned_free(data);
#else
 free(data);
#endif
 }

 void* allocate(size_t bytes, size_t alignment = 64) {
 // アライメントの計算（パディングを求める）
 size_t pad = (alignment - (offset % alignment)) % alignment;
 if (offset + pad + bytes > size) {
 throw std::runtime_error("OOM: MemoryArena out of memory");
 }
 offset += pad;
 void* ptr = data + offset;
 offset += bytes;
 return ptr;
 }

 void reset() {
 offset = 0; // メモリの解放はポインタを戻すだけ（O(1)）
 }
};

Dessa forma, sempre obteremos memória através desta arena ao criar tensores. Simplesmente chamando reset() ao final de cada etapa da inferência (como a cada geração de token), podemos reutilizar a memória instantaneamente.

4. Estrutura de dados do Tensor e a magia do Stride

O tensor é uma generalização dos conceitos de escalar, vetor e matriz. O importante na implementação é que, embora os dados reais estejam organizados na memória como um array contíguo unidimensional, eles possuem o conceito de “passo” (Stride) para interpretá-los como multidimensionais.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


enum class DataType {
 FP32,
 FP16,
 INT8, // 量子化用
 INT4 // 量子化用
};

struct Tensor {
 int n_dims; // 次元の数
 int64_t ne[4]; // 各次元の要素数 (Number of Elements)
 size_t nb[4]; // 各次元のストライド (Number of Bytes)
 DataType type; // データ型
 void* data; // ペイロードへのポインタ

 // 計算グラフ用
 enum OpType op;
 Tensor* src0;
 Tensor* src1;
};

O stride nb[i] representa a distância em bytes na memória entre elementos adjacentes na dimensão i. Por exemplo, se uma matriz com elementos $M \times N$ (FP32, 4 bytes por elemento) for armazenada em Row-Major (ordem de linha principal), os strides serão os seguintes:

nb[0] = 4 (bytes): movimento na direção da coluna
nb[1] = $N \times 4$ (bytes): movimento na direção da linha

Ao utilizar isso, operações como “Transposição (Transpose)” e “Visão (View)” podem ser realizadas apenas trocando os valores de stride, sem envolver cópias de memória. É extremamente elegante e rápido.

5. Construção do Grafo de Computação (DAG) e Avaliação Preguiçosa

Assim como no PyTorch, nosso motor de inferência também adota uma avaliação preguiçosa (Lazy Evaluation) semelhante ao “Define-by-Run”. Ou seja, no momento em que a função de operação é chamada, o cálculo não é realizado; constrói-se apenas o grafo (as dependências entre os nós).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


Tensor* tensor_add(MemoryArena& arena, Tensor* a, Tensor* b) {
 Tensor* out = create_tensor(arena, a->type, a->n_dims, a->ne);
 out->op = OpType::ADD;
 out->src0 = a;
 out->src1 = b;
 return out;
}

Tensor* tensor_mul_mat(MemoryArena& arena, Tensor* a, Tensor* b) {
 // bは転置されていることが多い
 int64_t ne[2] = { a->ne[0], b->ne[1] };
 Tensor* out = create_tensor(arena, a->type, 2, ne);
 out->op = OpType::MUL_MAT;
 out->src0 = a;
 out->src1 = b;
 return out;
}

O fluxo de processamento da inferência será o seguinte:

graph LR A["Definir Tensores"] --> B["Construir Grafo via Operações"] B --> C["Ordenação Topológica"] C --> D["Alocar Memória para Saídas"] D --> E["Executar Nós em Ordem"]

Ao avaliar o grafo (forward pass), utilizamos a ordenação topológica para executar o processamento em ordem a partir dos nós sem dependências. Se for apenas para inferência, não há necessidade de reter gradientes para retropropagação (backpropagation), o que torna o gerenciamento de memória extremamente simples.

6. O núcleo da matemática e otimização: Produto de Matrizes (GEMM)

Mais de 90% da quantidade de cálculos de inferência de IA é gasta em multiplicação de matrizes (GEMM: General Matrix Multiply). O mecanismo de atenção (Attention), núcleo do modelo Transformer, bem como as redes feed-forward (FFN), resumem-se, em última análise, a produtos gigantes de matrizes.

O produto $C = A B$ (tamanho $M \times N$) de duas matrizes $A$ (tamanho $M \times K$) e $B$ (tamanho $K \times N$) pode ser expresso através da seguinte fórmula:

$$ C_{i,j} = \sum_{k=0}^{K-1} A_{i,k} \cdot B_{k,j} $$

Se isso for implementado com um loop triplo ingênuo, os erros de cache (cache misses) ocorrerão com frequência, e não haverá nenhum desempenho.

6.1 Bloqueio de Cache (Cache Blocking) e Otimização SIMD na CPU

A estratégia básica para acelerar o GEMM na CPU é a seguinte:

Loop Tiling (Bloqueio de Cache): A matriz é dividida em blocos menores que cabem no cache L1/L2 e calculados.
Empacotamento de Dados (Data Packing): Os dados são reorganizados internamente para que o padrão de acesso à memória seja contíguo.
Aproveitamento de SIMD: Utilizamos instruções FMA (Fused Multiply-Add) como _mm512_fmadd_ps no AVX-512 para executar várias operações de multiplicar-adicionar em um único ciclo de clock.

Aqui está um exemplo simplificado do produto escalar (Dot Product) de vetores utilizando C++ e SIMD Intrinsics:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#include <immintrin.h> // AVX命令用

// AVX2を用いたFP32の高速内積
float dot_product_avx2(const float* a, const float* b, int n) {
 __m256 sum256 = _mm256_setzero_ps();
 int i = 0;

 // 8要素ずつ一度に処理（256ビット = 32バイト = 8 * 4バイト）
 for (; i <= n - 8; i += 8) {
 __m256 va = _mm256_loadu_ps(a + i);
 __m256 vb = _mm256_loadu_ps(b + i);
 // FMA命令: sum256 = va * vb + sum256
 sum256 = _mm256_fmadd_ps(va, vb, sum256);
 }

 // SIMDレジスタ内の値を水平加算
 float result[8];
 _mm256_storeu_ps(result, sum256);
 float dot = result[0] + result[1] + result[2] + result[3] +
 result[4] + result[5] + result[6] + result[7];

 // 余りの処理
 for (; i < n; ++i) {
 dot += a[i] * b[i];
 }
 return dot;
}

Apenas com esse pequeno esforço, podemos obter uma melhoria de velocidade de várias a dezenas de vezes em comparação com uma implementação ingênua.

7. Ultrapassando a barreira do hardware: Integração dos backends CUDA e Metal

Embora uma implementação puramente em C++ já funcione consideravelmente bem na CPU, o poder de computação paralela das GPUs é indispensável para executar modelos gigantes como LLMs a velocidades práticas (ex.: gerar 20 tokens ou mais por segundo). Por isso, introduziremos uma camada de abstração de backend em nosso motor.

7.1 Abstração de Backend

Usando o polimorfismo do C++, permitiremos a troca do executor das operações (Executor).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


class Backend {
public:
 virtual ~Backend() = default;
 virtual void alloc_buffer(Tensor* t) = 0;
 virtual void free_buffer(Tensor* t) = 0;
 virtual void copy_to_device(Tensor* t) = 0;
 virtual void copy_to_host(Tensor* t) = 0;

 // 各種演算の実行
 virtual void compute_add(Tensor* src0, Tensor* src1, Tensor* dst) = 0;
 virtual void compute_mul_mat(Tensor* src0, Tensor* src1, Tensor* dst) = 0;
};

7.2 Implementação do Backend NVIDIA CUDA

Para utilizar as GPUs da NVIDIA, implementaremos o backend usando a extensão CUDA C++. Embora seja possível escrever nossos próprios kernels, a melhor abordagem em relação à multiplicação de matrizes é aproveitar a “cuBLAS”, a biblioteca de ponta fornecida pela NVIDIA.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <cublas_v2.h>
#include <cuda_runtime.h>

class CUDABackend : public Backend {
private:
 cublasHandle_t handle;

public:
 CUDABackend() {
 cublasCreate(&handle);
 }

 ~CUDABackend() {
 cublasDestroy(handle);
 }

 void compute_mul_mat(Tensor* src0, Tensor* src1, Tensor* dst) override {
 // CUDAではデフォルトがColumn-Majorのため、パラメータに注意が必要
 const float alpha = 1.0f;
 const float beta = 0.0f;

 int m = src0->ne[0];
 int k = src0->ne[1];
 int n = src1->ne[1]; // src1は転置されている前提

 cublasSgemm(handle, CUBLAS_OP_T, CUBLAS_OP_N,
 m, n, k,
 &alpha,
 (const float*)src0->data, k,
 (const float*)src1->data, k,
 &beta,
 (float*)dst->data, m);
 cudaDeviceSynchronize();
 }
};

Como a transferência de dados (cudaMemcpy) entre a memória CUDA e a memória host (CPU) é muito pesada, é importante projetar para manter ao máximo todos os pesos (tensores de peso) e tensores intermediários na VRAM durante a inferência.

7.3 Backend Apple Silicon (Metal)

Nos últimos anos, os chips M1/M2/M3 do Mac (Apple Silicon) têm se mostrado excelentes como máquinas de inferência de IA. A razão para isso está na “memória unificada” (Unified Memory). Como a CPU e a GPU compartilham a mesma área de memória, elimina-se totalmente a necessidade de transferências de memória onerosas entre host e dispositivo através do barramento PCIe, como acontece com CUDA.

Para chamar o Metal a partir do C++, usamos Objective-C++ (arquivos .mm) como ponte ou utilizamos a biblioteca metal-cpp. Escrevemos o kernel utilizando o Compute Shader do Metal (escrito em arquivos .metal de forma semelhante ao C++).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// Metalシェーダ (kernel.metal)
#include <metal_stdlib>
using namespace metal;

kernel void mul_mat_kernel(
 device const float* A [[buffer(0)]],
 device const float* B [[buffer(1)]],
 device float* C [[buffer(2)]],
 constant uint3& dims [[buffer(3)]],
 uint2 gid [[thread_position_in_grid]]
) {
 uint m = dims.x; uint k = dims.y; uint n = dims.z;
 uint row = gid.y; uint col = gid.x;

 if (row < m && col < n) {
 float sum = 0.0;
 for (uint i = 0; i < k; ++i) {
 sum += A[row * k + i] * B[i * n + col]; // 簡略化
 }
 C[row * n + col] = sum;
 }
}

Em ambientes Apple Silicon, uma biblioteca de otimização chamada MPS (Metal Performance Shaders) voltada para o produto de matrizes também é fornecida, e sua utilização na prática pode alcançar velocidades de inferência surpreendentes.

8. Processamento específico para modelos Transformer: Attention e Cache KV

Os LLMs de ponta, como LLaMA 2/3 e GPT, são baseados na arquitetura Transformer. Para implementar isso em C++, é indispensável construir o “Scaled Dot-Product Attention”, expresso pela seguinte fórmula:

$$ \text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V $$

Além disso, na geração de tokens autorregressiva (Autoregressive), é necessário manter os resultados de cálculo (Key e Value) de tokens passados. A isso damos o nome de “Cache KV (Key-Value Cache)”.

graph TD T["Token Atual"] --> Q["Consulta (Query)"] T --> K["Chave (Key)"] T --> V["Valor (Value)"] K --> KCache["Adicionar ao Cache KV"] V --> VCache["Adicionar ao Cache KV"] Q --> Dot1["Q * K_Cache^T"] KCache --> Dot1 Dot1 --> Scale["Escala (1/sqrt(d))"] Scale --> Softmax["Softmax"] Softmax --> Dot2["Saída Softmax * V_Cache"] VCache --> Dot2 Dot2 --> Out["Vetor de Contexto"]

A alocação de memória para o Cache KV também deve operar como um buffer circular (ring buffer), garantindo antecipadamente na arena um espaço de memória equivalente ao comprimento máximo de contexto (por exemplo, 4096 ou 8192 tokens). Isso evita a necessidade de realocar memória a cada etapa de geração.

Além disso, para a Codificação Posicional (Positional Encoding), implementaremos o “RoPE (Rotary Position Embedding)”, que tem se tornado a norma nos últimos anos. Esta técnica embute a informação de posição como um vetor de rotação num espaço complexo, e a otimização de chamadas de funções sin e cos em C++ (por exemplo, uso de tabelas de consulta / look-up tables) é a chave para a performance.

9. Otimização extrema por meio da Quantização (Quantization) de modelos

Se carregarmos um modelo de grande escala (por exemplo, o modelo LLaMA com 7 bilhões de parâmetros) em FP32 (ponto flutuante de 32 bits), ele consumirá cerca de 28 GB de memória (VRAM) apenas para os pesos. Ao incluir o cache KV e os buffers de inferência, ultrapassará facilmente os 30 GB, tornando-se inexequível em GPUs de uso comum para consumidores.

Aí entra a necessidade indispensável da “Quantização (Quantization)”. Esse é, inclusive, o verdadeiro ponto forte do formato GGML.

A quantização é a técnica de reduzir intencionalmente a precisão dos pesos.

FP16 (16 bits): Tamanho reduzido pela metade. Quase nenhuma degradação de precisão.
INT8 (8 bits): 1/4 do tamanho. Leve degradação.
INT4 (4 bits): 1/8 do tamanho. Utilizando bloqueios e fatores de escala próprios, a inferência prática torna-se possível.

No lado do motor de inferência, lemos os pesos comprimidos em INT4 (ou INT8) da memória e, imediatamente após carregá-los nos registradores da CPU ou GPU, expandimos (Desquantização/Dequantize) para FP16 ou FP32 para realizar os cálculos.

Surpreendentemente, mesmo que o volume de cálculos aumente, reduzir a quantidade de dados lidos da memória torna o processo mais rápido. Isso ocorre porque o gargalo nas tarefas de inferência no hardware moderno não é o “Poder de Computação (Compute Bound)”, mas sim a “Largura de Banda da Memória (Memory Bandwidth Bound)”. Com um motor implementado em C++ utilizando quantização INT4, é possível executar LLMs locais suavemente até mesmo em um MacBook Air com 8 GB de RAM unificada.

10. Ajuste de desempenho (Performance Tuning): Arquitetura NUMA e Pool de Threads

Ao realizar inferência utilizando CPU, a implementação de multi-threading é obrigatória. No entanto, não podemos dizer que é o ideal simplesmente inicializar um grande número de std::thread.

Em servidores multi-soquete modernos ou CPUs de ponta como o Ryzen Threadripper, adota-se a arquitetura NUMA (Non-Uniform Memory Access). O acesso de um núcleo de CPU para a memória fisicamente mais próxima (memória local) é rápido, mas o acesso à memória vinculada a outro processador será extremamente lento.

Em um motor de inferência C++ avançado, fazemos pleno uso das seguintes técnicas:

Fixação de Threads (Thread Pinning): Fixa cada thread a um núcleo de CPU específico (definindo Afinidade/Affinity) para evitar a invalidação de cache causada por trocas de contexto.
Alocação ciente de NUMA (NUMA-aware allocation): Garante a alocação de memória no mesmo nó NUMA que a thread que está processando os dados.
Pool de threads do tipo Work-Stealing: Divide cada nó do grafo de computação em pequenas tarefas e implementa um agendador eficiente onde threads ociosas capturam (roubam) tarefas automaticamente para execução.

Fazendo uso dessas técnicas, é possível manter a taxa de uso da CPU muito próxima de 100%, atingindo um rendimento (throughput) que se aproxima do valor teórico.

11. Conclusão: A alegria de conduzir a IA com os “músculos” do C++

É certo que o Python é conveniente. Não há linguagem que se iguale à sua produtividade na fase de pesquisa, desenvolvimento e prototipagem. Contudo, no instante em que passamos para a fase de “executar o modelo concluído no mundo real, de forma eficiente e em todos os dispositivos”, chega o momento de usar o C++.

Manipular a sequência de bytes na memória de forma direta, forçar os registradores ao limite com instruções SIMD e lutar contra a largura de banda da VRAM da GPU para construir um motor de inferência que vai gerando textos (tokens) em japonês natural (ou qualquer outro idioma) sequencialmente no console… A sensação de realização ao ver isso acontecer proporciona uma “alegria genuína de engenheiro”, a qual nunca se obterá simplesmente chamando model.generate() em um framework Python.

Embora a tecnologia de IA tenda a se tornar uma “Caixa Preta (Black Box)”, escrever tudo à mão em C++, desde as operações de tensores até a alocação de memória, permite a você entender profundamente o verdadeiro mecanismo de como um LLM “pensa”.

Se você tem conhecimentos básicos de C++ e possui um forte interesse nas atuais tecnologias de IA, experimente o desafio de desenvolver seu próprio motor de inferência. Os códigos-fonte do GGML ou llama.cpp servirão, sem dúvida, como os melhores livros didáticos vivos disponíveis.

Vamos lá, jogue fora os pesados runtimes do Python e faça a IA de ponta rodar com os músculos do C++!

Guia de Desenvolvimento de Modelos de IA em Pequena Escala (como TinyLLaMA) com C++

Fri, 11 Sep 2026 14:00:00 +0900

Guia de Desenvolvimento de Modelos de IA em Pequena Escala (como TinyLLaMA) com C++

Recentemente, o interesse na execução de Grandes Modelos de Linguagem (LLMs) em ambientes locais aumentou rapidamente. Em particular, modelos de pequena escala como o TinyLLaMA (1.1B parâmetros) são capazes de inferir a uma velocidade prática mesmo em dispositivos de borda com recursos limitados ou notebooks comuns (incluindo ambientes Windows). Enquanto o desenvolvimento usando Python e PyTorch é a tendência principal, a combinação de C++ e “ggml”, uma biblioteca de tensores baseada em C, tornou-se o padrão de fato quando se busca o máximo de desempenho e eficiência de memória.

Neste artigo, explicaremos o procedimento de desenvolvimento muito detalhado para construir um motor de inferência do zero (ou compreender profundamente a estrutura interna do llama.cpp existente) para carregar o TinyLLaMA e gerar texto usando C++.

1. Por que C++ e ggml?

Na fase de treinamento da IA, o Python, com sua flexibilidade e ecossistema rico, é esmagadoramente vantajoso. No entanto, nas fases de implantação e “Inferência”, o C++ torna-se uma escolha poderosa pelas seguintes razões:

Redução de Sobrecarga: Pode eliminar completamente a sobrecarga do Global Interpreter Lock (GIL) e do tempo de execução do Python.
Eficiência de Memória e Alocação de Arena: Como a alocação e liberação de memória podem ser controladas manualmente, é possível evitar picos imprevisíveis causados pela coleta de lixo.
Acesso Direto ao Hardware: É possível chamar diretamente funções intrínsecas (Intrinsics) SIMD, como AVX-512, AVX2 e ARM NEON, para maximizar o poder de computação da CPU.
Eliminação de Dependências: O ggml é uma biblioteca C/C++ sem dependências (Zero dependencies) que pode ser facilmente compilada em um ambiente MSVC no Windows, desde que haja um compilador.

2. Visão Geral da Arquitetura

O fluxo completo do pipeline de inferência é mostrado no diagrama Mermaid abaixo. É um processo em série que começa com o texto de entrada do usuário até a geração final do próximo token.

graph TD A["Texto de Entrada do Usuário"] --> B["Tokenizador BPE"] B --> C["Matriz de IDs de Tokens"] C --> D["Busca na Camada de Embedding"] D --> E["Blocos Transformer"] E --> F["RMSNorm"] F --> G["Camada Head LM"] G --> H["Matriz de Logits"] H --> I["Módulo Amostrador"] I --> J["Próximo ID de Token"] J --> K["Detokenizador"] K --> L["Pedaço de Texto de Saída"] J -.-> |"Adicionar ao Contexto"| C

Por ser um modelo autorregressivo, o token de saída é adicionado novamente ao contexto e circula como entrada para a previsão do próximo token (parte tracejada do diagrama).

3. Formato do Modelo e Mapeamento de Memória (mmap)

O maior obstáculo ao lidar com os pesos de uma rede neural gigantesca é a E/S de disco e o consumo de memória. Na implementação em C++, isso é resolvido com o mapeamento de memória (mmap).

3.1 Mecanismo de Mapeamento de Memória e Implementação no Windows

O mmap permite mapear o conteúdo de um arquivo diretamente para o espaço de memória virtual do processo.

Zero-copy: Os dados são lidos diretamente do disco para o cache de página do kernel, sem causar cópias extras para o espaço do usuário.
Carregamento sob Demanda (Page Fault): No exato momento em que a CPU acessa aquele endereço de memória, ocorre uma falha de página, e apenas o pedaço necessário (geralmente 4KB) é carregado na memória física.

No ambiente Windows, usa-se as APIs Win32 CreateFileMapping e MapViewOfFile em vez do mmap POSIX.

sequenceDiagram participant OS["Sistema Operacional Windows"] participant RAM["Memória Física"] participant App["Aplicativo C++"] App->>OS: "CreateFileMapping / MapViewOfFile" OS-->>App: "Ponteiro de Endereço de Memória Virtual" App->>App: "Ler Dados do Tensor no Ponteiro" OS->>RAM: "Page Fault / Carregar página do Disco" RAM-->>App: "Dados prontos para Computação SIMD"

3.2 Estrutura Binária do Formato GGUF

O GGUF (GPT-Generated Unified Format), convertido a partir de formatos como .safetensors do Hugging Face, é o formato definitivo para inferência. Ele possui o seguinte layout binário estrito:

Magic Bytes: 0x46554747 (GGUF).
Version: Número da versão do formato.
Tensor Count & Metadata Count: Número de tensores e número de pares chave-valor de metadados.
Metadata (Key-Value Pairs): Chaves com prefixo de comprimento de string e valores tipados.
Tensor Info: Nome de cada tensor, número de dimensões, tipo de dados (FP16, Q4_K, etc.) e a posição de deslocamento no arquivo.
Padding: Preenchimento inserido para garantir que os dados do tensor sejam alinhados a um limite específico (geralmente 32 bytes ou 64 bytes). Isso é essencial para acessos rápidos à memória em instruções SIMD (especialmente AVX).
Tensor Data: A matriz real de dados de peso alinhados.

4. Base Matemática do TinyLLaMA e Algoritmo C++

O TinyLLaMA incorpora várias inovações arquitetônicas avançadas para maior eficiência. Explicaremos as representações matemáticas para implementá-las corretamente em C++.

4.1 RMSNorm (Root Mean Square Normalization)

Reduz o custo de cálculo ao omitir a centralização da média do LayerNorm e realizar apenas o dimensionamento da variância.

$$ \text{RMSNorm}(x) = \frac{x}{\sqrt{\frac{1}{d}\sum_{i=1}^{d} x_i^2 + \epsilon}} \odot \gamma $$

$d$ é o número de dimensões, e $\gamma$ é o tensor de escalonamento aprendido. Ao implementar em C++, ele é otimizado primeiramente calculando rapidamente a soma dos quadrados da matriz com _mm256_fmadd_ps do AVX2, e multiplicando pela raiz quadrada inversa (como a instrução _mm256_rsqrt_ps).

4.2 RoPE (Rotary Position Embedding)

Esta é uma técnica para aplicar informações de posição de tokens como uma rotação no espaço tensorial. Pode ser vista como uma rotação no plano complexo, e aplica a seguinte rotação a pares de dimensões adjacentes $(x_1, x_2)$ do vetor $x$:

$$ \text{RoPE}(x, m) = \begin{pmatrix} x_{1} \cos(m\theta) - x_{2} \sin(m\theta) \\ x_{1} \sin(m\theta) + x_{2} \cos(m\theta) \end{pmatrix} $$

Aqui, $m$ é o índice absoluto de posição do token e $\theta$ é a frequência fundamental pré-calculada. No ggml, a execução paralela é feita simplesmente adicionando o operador ggml_rope durante a construção do grafo de inferência.

4.3 Grouped-Query Attention (GQA)

Na Multi-Head Attention (MHA) comum, há o mesmo número de cabeças para Query, Key e Value. No entanto, o TinyLLaMA adota o Grouped-Query Attention (GQA) para reduzir drasticamente o consumo de largura de banda de memória e cache KV.

$$ \text{Attention}(Q, K, V) = \text{softmax}\left(\frac{Q K^T}{\sqrt{d_k}}\right) V $$

No GQA, várias cabeças de Query compartilham uma única cabeça de Key/Value. Na implementação C++, antes de executar o produto de matrizes ggml_mul_mat, é necessária uma operação para transmitir (broadcast) os tensores KV para corresponder ao número de Queries.

4.4 Função de Ativação SwiGLU

Na camada Feed-Forward Network (FFN), SwiGLU é usado em vez de GELU.

$$ \text{SwiGLU}(x) = \text{Swish}(x W_{\text{gate}}) \otimes (x W_{\text{up}}) $$ $$ \text{Swish}(z) = z \cdot \sigma(z) = z \cdot \frac{1}{1 + e^{-z}} $$

No grafo computacional, isso é expresso pela combinação do operador ggml_silu com ggml_mul.

5. Construção de Grafo Computacional e Gerenciamento de Memória com ggml

O ggml adota uma abordagem “Define-and-Run”, onde um grafo computacional estático para inferência é construído e então avaliado posteriormente.

5.1 ggml_context e Alocador de Arena

A característica mais singular do ggml é a “alocação de arena”, que evita qualquer alocação dinâmica de memória (malloc ou new) dentro do loop de inferência. Uma região contígua e gigante de memória (arena) é alocada no momento da inicialização, e toda vez que ggml_new_tensor é chamado, o ponteiro dessa região é incrementado. Quando uma etapa de inferência é concluída, simplesmente redefinir o ponteiro de alocação para a posição inicial conclui instantaneamente a alocação de memória para a próxima etapa de inferência.

5.2 Exemplo Concreto de Construção de Grafo

Para cada etapa de inferência, o seguinte grafo computacional é montado na memória.

graph TD A["ID de Entrada de Tokens"] --> B["Busca de Embedding"] B --> C["ggml_rms_norm"] C --> D["Projeções Q / K / V"] D --> E["Posicional ggml_rope"] E --> F["Armazenar em Cache KV"] E --> G["Carregar Cache KV"] G --> H["Self Attention"] H --> I["Escalar & Softmax"] I --> J["Saída da Atenção"] J --> K["Projeção de Saída"] K --> L["Adicionar Residual"]

6. Quantização (Quantization) e Otimização para Windows / SIMD

Lidar com o TinyLLaMA (1.1B) em FP16 requer cerca de 2.2GB de memória, mas por meio da quantização de 4 bits (como Q4_K), pode ser comprimido drasticamente para cerca de 600MB.

6.1 Arquitetura de Quantização em Bloco

O ggml não quantiza o tensor inteiro de maneira uniforme, mas o faz em unidades de “blocos”. No formato Q4_0, 32 valores FP16 são agrupados em um bloco.

Fator de escala: 1 valor FP16 (2 bytes)
Dados quantizados: 32 valores de 4 bits (16 bytes) Isso minimiza a influência de outliers locais.

6.2 Aceleração de Produto Escalar com AVX2

Ao compilar para a CPU x86 mais recente no ambiente Windows, sinalizadores de compilador como /arch:AVX2 são utilizados, e o processamento SIMD é realizado no fluxo abaixo.

Carregar: Dados quantizados de 4 bits são carregados da memória em registradores AVX de 256 bits.
Expansão e Desempacotamento: Os valores de 4 bits são expandidos para Int8 ou Int16 com máscaras de bits e operações de deslocamento.
Desquantização: O fator de escala é multiplicado para converter em ponto flutuante.
Operação FMA: Executa o cálculo paralelo de multiplicar e somar usando o valor de ativação e _mm256_fmadd_ps (Fused Multiply-Add).

7. Detalhes de Implementação do Cache KV

Na geração autorregressiva, o “cache KV” é um recurso indispensável para pular o cálculo de Key e Value dos tokens anteriores.

Os pontos da implementação em C++ são os seguintes:

Alocação Prévia do Tensor: Um tensor gigante para o tamanho máximo do contexto (ex: 2048 tokens) é inicializado para o cache KV (recomenda-se FP16).
Cópia com Deslocamento: Quando o cálculo para a posição $N$ do token for realizado, os vetores K e V obtidos nessa etapa são armazenados na $N$-ésima linha do tensor de cache KV usando ggml_cpy ou similares.
Criação de Visualização na Atenção: Ao calcular a atenção, uma “visualização” apontando apenas para a parte dos tokens de 0 a $N$ é criada e passada para a multiplicação de matrizes.

8. Tokenizador BPE e Decodificação

Trata as strings de entrada como sequências de bytes UTF-8 e as combina com um vocabulário pré-definido. Em C++, algoritmos utilizando Árvore Trie (árvore de prefixo) ou filas de prioridade são implementados para acelerar a busca no vocabulário.

A partir dos logits emitidos pelo LM Head, as probabilidades são escalonadas usando o parâmetro Temperature, os candidatos são reduzidos por meio da extração Top-K ou Top-P (Nucleus Sampling), e o próximo token final é determinado por meio de números aleatórios.

9. Configuração do Projeto C++ (Ambiente Windows / PowerShell)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


cmake_minimum_required(VERSION 3.14)
project(TinyLLaMACpp)

set(CMAKE_CXX_STANDARD 17)

# Otimização e definição do sinalizador AVX2 para Windows (MSVC)
if(MSVC)
 add_compile_options(/O2 /arch:AVX2 /fp:fast)
 add_link_options(/STACK:8388608)
else()
 add_compile_options(-O3 -march=native -ffast-math)
endif()

add_library(ggml OBJECT ggml/ggml.c ggml/ggml-alloc.c)
target_compile_definitions(ggml PRIVATE GGML_USE_AVX2 GGML_USE_F16C GGML_USE_FMA)

add_executable(main main.cpp)
target_link_libraries(main ggml)

Exemplo de comando de build no PowerShell:

1
2
3
4


mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release

10. Resumo

Implementar o motor de inferência de um modelo de IA em pequena escala como o TinyLLaMA do zero usando C++ e ggml é uma excelente oportunidade para descobrir a caixa preta do deep learning e aprender a beleza do controle de hardware de baixo nível. Vamos abrir o futuro da IA de borda (Edge AI) aproveitando a essência da programação de sistemas, como o carregamento de zero cópia usando mapeamento de memória, otimização SIMD e construção de cache KV.

Como usar o llama.cpp e uma introdução à customização em C++

Fri, 11 Sep 2026 11:00:00 +0900

Nos últimos anos, a evolução dos Grandes Modelos de Linguagem (LLM) tem sido impressionante, e sua área de aplicação se expande dia após dia. No entanto, para executar modelos com bilhões ou dezenas de bilhões de parâmetros em um ambiente local, normalmente é necessária uma GPU de ponta com uma quantidade enorme de VRAM. O llama.cpp é o que quebrou essa “barreira de hardware” e tornou possível a inferência prática de LLM em PCs comuns, Macs e até dispositivos como o Raspberry Pi.

Neste artigo, explicaremos de forma extremamente detalhada para engenheiros, indo além do simples uso de ferramentas de linha de comando, para cobrir a arquitetura de sua tecnologia base ggml, a base matemática do Transformer e a quantização, e até mesmo métodos para incorporar e customizar LLMs em suas próprias aplicações usando a API C++.

1. Visão geral do llama.cpp e ggml

O llama.cpp é um motor de inferência de LLM leve escrito em C/C++, desenvolvido por Georgi Gerganov. Inicialmente criado com o propósito de rodar o modelo LLaMA da Meta rapidamente no Apple Silicon (Macs M1/M2), agora ele suporta várias arquiteturas e modelos.

Sua principal característica é ser uma implementação pura em C/C++ sem dependências externas. Ele não requer grandes ecossistemas como Python ou PyTorch e pode ser compilado como um único arquivo executável, o que torna o deploy extremamente fácil.

No coração deste llama.cpp está a biblioteca de operações tensoriais ggml. A ggml foi projetada do zero para otimizar operações de matriz em aprendizado de máquina no CPU (e algumas GPUs) ao limite absoluto.

1.1 Por que o llama.cpp é tão rápido?

Utilização de mapeamento de memória (mmap): Ao carregar os pesos do modelo na memória, ele usa o mmap do SO, evitando um carregamento completo na RAM, alcançando assim uma inicialização rápida e economia de memória.
Otimização exaustiva de instruções SIMD: Ele utiliza conjuntos de instruções específicos do CPU, como AVX2, AVX-512, ARM NEON e Apple AMX para acelerar enormemente a multiplicação de matrizes.
Quantização (Quantization): Ele comprime pesos de ponto flutuante de 16 bits (FP16) em inteiros de 4 bits, 5 bits ou 8 bits, eliminando o gargalo na largura de banda da memória (mais detalhes abaixo).

2. Base Matemática: Transformer e Quantização (Quantization)

Para entender profundamente o llama.cpp, você precisa saber quais fórmulas matemáticas ele está calculando e como ele aproxima esses cálculos.

2.1 O Processo de Inferência do Transformer

Modelos como o LLaMA adotam uma arquitetura de decodificador Transformer auto-regressiva (Auto-regressive). O núcleo da geração de texto é o mecanismo de Self-Attention.

Para uma matriz de estado oculto de entrada $X \in \mathbb{R}^{N \times d}$, as queries $Q$, keys $K$ e values $V$ são calculadas por produtos com matrizes de pesos.

$$ Q = X W_Q, \quad K = X W_K, \quad V = X W_V $$

Aqui, a saída da Attention é definida como a seguir.

$$ \text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V $$

No loop de inferência do llama.cpp, o gargalo é o produto dessas enormes matrizes $W_Q, W_K, W_V$ ou das matrizes de pesos da rede feed-forward (FFN) com o vetor $X$ (já que processa um token por vez na fase de geração, $N=1$), isto é, GEMV (General Matrix-Vector Multiplication).

2.2 Base Matemática da Quantização (Quantization)

Na inferência, onde a largura de banda de acesso à memória se torna um gargalo, a quantização, que expressa parâmetros de peso em um número menor de bits, é essencial. Explicaremos o princípio básico da quantização em blocos amplamente utilizada no llama.cpp (por exemplo, Q4_K e Q4_0).

Por exemplo, considere um bloco $w = [w_1, w_2, \dots, w_B]$ de comprimento $B$ (geralmente 32 ou 64) que é parte da matriz de pesos FP16 $W$. Nós aproximamos este bloco para um inteiro de 4 bits $q_i \in [-8, 7]$ e um único fator de escala $\Delta$ (FP16 ou FP32).

$$ w_i \approx \Delta \times q_i $$

O $\Delta$ é determinado com base no valor absoluto máximo dentro do bloco.

$$ \Delta = \frac{\max_i |w_i|}{7} $$

Ao calcular o produto escalar $y = w \cdot x$ usando os pesos quantizados, se o vetor de entrada $x$ for similarmente quantizado de modo que $x_i \approx \Delta_x \times q_{x, i}$, então

$$ y = \sum_{i=1}^{B} w_i x_i \approx \Delta \Delta_x \sum_{i=1}^{B} q_i q_{x, i} $$

Esta parte de $\sum q_i q_{x, i}$ se torna uma operação inteira pura, a qual pode ser calculada em paralelo em altíssima velocidade usando instruções SIMD. Este é o truque matemático de como o llama.cpp alcança sua velocidade incrível em CPUs.

3. Arquitetura e Fluxo de Inferência

Para entender o funcionamento interno do llama.cpp, o diagrama Mermaid a seguir mostra a arquitetura de todo o sistema e o fluxo de dados.

graph TD A["Entrada do Usuário (String)"] --> B["Tokenizer llama.cpp"] B --> C["IDs de Tokens (array int32)"] C --> D["Buffer de Contexto (KV Cache)"] D --> E["Grafo de Computação ggml"] E --> F["Camadas do Transformer"] subgraph "Motor ggml" F --> G["Self-Attention (RoPE)"] G --> H["Rede Feed Forward"] H --> F end F --> I["Logits (Tamanho do Vocabulário)"] I --> J["Sampler (Temperature, Top-K, Top-P)"] J --> K["ID do Token Selecionado"] K --> L["Detokenizer llama.cpp"] L --> M["String de Saída"] K -. "Loop auto-regressivo" .-> D

A geração de texto é um loop auto-regressivo onde cada vez que um token é emitido, ele é adicionado ao KV Cache como a próxima entrada e passa novamente pelo grafo de computação.

4. Configuração do Ambiente e Métodos de Build

Antes de incorporar o llama.cpp ao seu projeto em C++, vamos primeiro tentar compilar o código-fonte.

4.1 Clonando o Repositório

1
2


git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

4.2 Compilando Usando CMake

Para integrá-lo em outros aplicativos como um projeto C++, usar o CMake é a abordagem mais padrão. Ativar o acelerador (backend) para cada plataforma pode aumentar a velocidade de computação.

Apenas CPU (Build básico):

1
2
3


mkdir build && cd build
cmake ..
cmake --build . --config Release -j 8

Ao usar NVIDIA GPU (CUDA):

1
2
3


mkdir build && cd build
cmake .. -DGGML_CUDA=ON
cmake --build . --config Release -j 8

Ao usar Apple Silicon (Metal):

1
2
3


mkdir build && cd build
cmake .. -DGGML_METAL=ON
cmake --build . --config Release -j 8

Uma vez que a compilação for bem-sucedida, arquivos executáveis como o llama-cli, bem como a biblioteca llama (e a biblioteca ggml) para vinculação com a API C++ descrita mais adiante, serão gerados no diretório build/bin/.

5. Introdução à Customização em C++: Usando a API do llama.cpp

A partir daqui, discutiremos o tema principal: controlar o llama.cpp a partir de código C++. Para não apenas usar a ferramenta de linha de comando, mas também incorporar o LLM em sua própria aplicação (como motores de jogos, aplicativos de desktop, sistemas embarcados, etc.), você precisa chamar a API C++ diretamente.

O llama.cpp fornece uma interface de linguagem C principalmente através de um arquivo de cabeçalho chamado llama.h. Quando você o chama do C++, você também utilizará esta interface.

5.1 Includes e Configurações Mínimas Necessárias

Ao usar o llama.cpp em seu próprio projeto, você incluirá o seguinte.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


#include "llama.h"
#include <iostream>
#include <vector>
#include <string>
#include <stdexcept>

// Macro para tratamento de erros
#define LLAMA_ASSERT(x) \
 do { \
 if (!(x)) { \
 std::cerr << "Assertion failed: " << #x << std::endl; \
 std::terminate(); \
 } \
 } while (0)

5.2 Carregando o Modelo e Inicializando o Contexto

Primeiro, carregamos um arquivo de modelo no formato .gguf e alocamos um contexto (espaço de memória e KV cache) para inferência.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


int main(int argc, char ** argv) {
 if (argc < 2) {
 std::cerr << "Usage: " << argv[0] << " <model.gguf>" << std::endl;
 return 1;
 }
 std::string model_path = argv[1];

 // 1. Inicialização do backend (configuração do ambiente como CPU/GPU, etc.)
 llama_backend_init();

 // 2. Obter configurações padrão de parâmetros do modelo
 llama_model_params model_params = llama_model_default_params();
 model_params.n_gpu_layers = 35; // Número de camadas a descarregar para a GPU

 // 3. Carregando o modelo
 llama_model * model = llama_load_model_from_file(model_path.c_str(), model_params);
 if (model == nullptr) {
 std::cerr << "Failed to load model" << std::endl;
 return 1;
 }

 // 4. Configuração dos parâmetros de contexto
 llama_context_params ctx_params = llama_context_default_params();
 ctx_params.n_ctx = 2048; // Tamanho máximo de contexto (em tokens)
 ctx_params.n_threads = 8; // Número de threads da CPU para inferência

 // 5. Criação do contexto
 llama_context * ctx = llama_new_context_with_model(model, ctx_params);
 if (ctx == nullptr) {
 std::cerr << "Failed to create context" << std::endl;
 llama_free_model(model);
 return 1;
 }

 std::cout << "Model and context loaded successfully!" << std::endl;
 // ... Processamento subsequente

5.3 Tokenização do Prompt (Tokenization)

Um LLM não entende textos diretamente, mas sim os processa como uma sequência de IDs inteiros (tokens). A string de entrada deve ser convertida em tokens.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


 std::string prompt = "Q: Qual é a capital do Japão?\nA:";
 std::vector<llama_token> tokens_list;
 tokens_list.resize(prompt.length() + 4); // Tamanho de buffer com margem

 // Adicionar um token especial (como BOS: Begin of Sequence) ao início
 bool add_special = true;
 // Converter a string para um array de IDs de tokens
 int n_tokens = llama_tokenize(
 model,
 prompt.c_str(),
 prompt.length(),
 tokens_list.data(),
 tokens_list.size(),
 add_special,
 false // parse_special
 );

 if (n_tokens < 0) {
 // Se o buffer for insuficiente, é necessário realocar e tentar novamente (omitido por simplificação)
 std::cerr << "Failed to tokenize prompt" << std::endl;
 return 1;
 }
 tokens_list.resize(n_tokens);

5.4 Loop de Inferência e Amostragem (Sampling)

Construímos um loop onde os tokens são inseridos no modelo, obtemos a distribuição de probabilidade (Logits) do próximo token e realizamos amostragem a partir dela para determinar o próximo token.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72


 // Número máximo de tokens a gerar
 const int max_gen_tokens = 100;

 // Inicializar a estrutura para avaliação em lote (batch)
 llama_batch batch = llama_batch_init(512, 0, 1);

 // Adicionar tokens de prompt ao batch
 for (size_t i = 0; i < tokens_list.size(); i++) {
 llama_batch_add(batch, tokens_list[i], i, { 0 }, false);
 }
 // Configurar para produzir logits (resultados previstos) apenas para o último token do prompt
 batch.logits[batch.n_tokens - 1] = true;

 // Avaliação inicial (alimentando o modelo com o prompt)
 if (llama_decode(ctx, batch) != 0) {
 std::cerr << "llama_decode() failed" << std::endl;
 return 1;
 }

 int n_cur = batch.n_tokens; // Tamanho atual do contexto
 int n_decode = 0;

 std::cout << "\nOutput: ";

 // Inicialização do contexto do sampler (configurações como Temperature, Top-K, Top-P, etc.)
 llama_sampler * smpl = llama_sampler_chain_init(llama_sampler_chain_default_params());
 llama_sampler_chain_add_top_k(smpl, 40);
 llama_sampler_chain_add_top_p(smpl, 0.9f, 1);
 llama_sampler_chain_add_temp(smpl, 0.7f);
 llama_sampler_chain_add_dist(smpl, 1234); // Valor da semente (Seed)

 while (n_decode < max_gen_tokens) {
 // 1. Amostragem: Prever o próximo token com base no contexto atual
 llama_token new_token_id = llama_sampler_sample(smpl, ctx, -1);

 // 2. Se o token for EOS (End of Sequence), encerrar o loop
 if (llama_token_is_eog(model, new_token_id)) {
 break;
 }

 // 3. Decodificar o token para uma string (texto) e exibir
 char buf[128];
 int n_chars = llama_token_to_piece(model, new_token_id, buf, sizeof(buf), 0, false);
 if (n_chars > 0) {
 std::cout << std::string(buf, n_chars) << std::flush;
 }

 // 4. Preparar o token recém-gerado para o próximo batch
 llama_batch_clear(batch);
 llama_batch_add(batch, new_token_id, n_cur, { 0 }, true);

 // 5. Avaliação do modelo (atualiza a KV cache e prevê a seguir)
 if (llama_decode(ctx, batch) != 0) {
 std::cerr << "Failed to evaluate" << std::endl;
 break;
 }

 n_cur += 1;
 n_decode += 1;
 }

 std::cout << std::endl;

 // Cleanup (Limpeza)
 llama_sampler_free(smpl);
 llama_batch_free(batch);
 llama_free(ctx);
 llama_free_model(model);
 llama_backend_free();

 return 0;
}

Este código implementa um loop de inferência customizado usando a API básica do llama.cpp. Ele usa a estrutura llama_batch para gerenciar grupos de tokens e executa um forward pass (propagação para frente) na rede neural com llama_decode.

6. Exemplo de Customização Avançada: Manipulação de Logits e Controle de Penalidade com C++

Se além da simples geração de texto você deseja forçar a saída de um formato específico (por exemplo, apenas JSON) ou quer controlar para evitar a geração de palavras proibidas específicas, você manipula diretamente os Logits antes da amostragem no lado do C++.

Você pode obter o array de pontuações brutas (valores antes de serem convertidos para probabilidades) de cada token imediatamente antes que o modelo o emita.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Logo após a inferência e antes de realizar a amostragem, obter o array bruto de logits
float * logits = llama_get_logits_ith(ctx, batch.n_tokens - 1);
int n_vocab = llama_n_vocab(model);

// Lista de IDs de tokens proibidos (por exemplo, 1234, 5678)
std::vector<llama_token> forbidden_tokens = { 1234, 5678 };

// Define a probabilidade de um token proibido como 0 (o Logit vai para menos infinito)
for (llama_token bad_tok : forbidden_tokens) {
 logits[bad_tok] = -INFINITY;
}

Dessa forma, usando a API C++ diretamente, uma “intervenção em nível de microssegundo por ciclo de inferência” se torna possível, a qual pode ser muito difícil ou acarretar uma alta sobrecarga se feita via LangChain ou Python.

7. Segredos para Ajuste de Desempenho

Após concluir sua implementação em C++, apresentaremos alguns pontos de verificação para aumentar a velocidade ao limite para uma operação no mundo real.

Otimização de processamento em lote (Batching): Ao processar requisições de vários usuários simultaneamente, adicione múltiplas sequências no llama_batch e chame llama_decode de uma só vez (Continuous Batching). Isso permite compartilhar os acessos de memória, melhorando dramaticamente o throughput.
Ativando a Flash Attention: Configurando ctx_params.flash_attn = true; nos parâmetros de contexto, você pode acelerar os cálculos da Attention enquanto reduz o uso de memória. Esta é uma configuração obrigatória quando lidando com contextos longos (dezenas de milhares de tokens).
Suporte NUMA: Em um ambiente de servidor multi-socket, você pode reduzir a latência de acesso à memória configurando corretamente as configurações NUMA antes do llama_backend_init().

8. Conclusão

Neste artigo, explicamos em detalhe desde a base matemática do llama.cpp até a explicação de sua arquitetura, e como construir um motor de inferência customizado fazendo total uso da API em C++.

O ecossistema Python é extremamente útil para prototipagem, mas em ambientes de produção que exigem implantações em dispositivos de borda, integração em jogos e processamento em tempo real, o controle direto do llama.cpp baseado em C/C++ mostra um poder esmagador.

Nós encorajamos fortemente que você tente escrever seu próprio código em C++ e experiencie a alegria de controlar e operar os LLMs livremente em seu ambiente local.

Lista de Links de Referência

llama.cpp Official Repository

ggml - Tensor Library

Attention Is All You Need (Vaswani et al., 2017)