一个可移植的C语言库和命令行工具，支持GGUF模型和GGML，提供原生LLM推理能力，兼容多种主流模型架构。

llm.c：纯C语言实现的高性能LLM推理引擎\n\n## 项目概述\n\n在大语言模型推理框架领域，Python生态长期占据主导地位。然而，对于追求极致性能、最小依赖和跨平台兼容性的开发者而言，纯C语言实现仍然具有不可替代的价值。llm.c 项目正是这一理念的具体实践——一个用C语言编写的可移植LLM推理引擎，支持GGUF模型格式和GGML计算后端。\n\n该项目由 kaisarcode 开发并开源，定位为\n"独立的推理原语\n"（standalone inference primitive），旨在为C/C++应用程序提供原生的文本生成能力，无需依赖Python运行时或复杂的框架栈。\n\n## 核心特性与架构设计\n\n### 轻量级设计哲学\n\nllm.c 的设计遵循极简主义原则。整个库围绕一个核心上下文对象\nkc_llm_t\n展开，该对象封装了模型加载、后端资源、LoRA适配器、错误状态和可选的KV缓存。这种单一所有权模型确保了内存行为的可预测性，对于嵌入式系统和资源受限环境尤为重要。\n\n### GGUF与GGML生态兼容\n\n项目深度集成GGUF（GPT-Generated Unified Format）和GGML（GPT-Generated Model Library）生态，这是llama.cpp等项目推动的开放模型格式标准。通过支持GGUF，llm.c 可以无缝加载社区中大量预训练的量化模型，包括Q4_0、Q4_K_M、Q8_0等多种量化方案。\n\n### 多架构模型支持\n\nllm.c 实现了对多种主流Transformer架构的支持：\n\nLlama风格架构：包括原版Llama、Mistral、Mixtral系列。这些模型采用SiLU激活函数、RoPE位置编码和标准GQA（分组查询注意力）机制。\n\nQwen风格架构：支持Qwen2、Qwen2.5、Qwen3系列。除了SiLU和RoPE外，还实现了Qwen特有的频率基数和Qwen3的Q/K RMS归一化。\n\nGemma风格架构：Google Gemma系列，采用GELU激活函数和基于嵌入维度平方根的缩放因子。\n\n这种多架构支持使得llm.c 能够服务于不同场景下的模型需求，从通用对话到代码生成，从中文处理到多语言任务。\n\n## 命令行接口设计\n\nllm.c 提供了一个简洁而功能完整的CLI工具，支持丰富的推理控制选项：\n\n### 基础用法\n\n单轮对话生成：\nbash\necho \"What is the capital of France?\" | ./llm --model llama-3-8b.gguf\n\n\n带LoRA适配器的推理：\nbash\nprintf '%s\\n' \"Hello\" | ./llm \\\n --model base.gguf \\\n --lora adapter.safetensors --lora-scale 0.8\n\n\n### 关键参数说明\n\n- --ctx：上下文窗口大小，默认2048 tokens\n- --predict：最大生成token数，默认128\n- --threads：推理线程数，自动检测CPU核心数\n- --gpu：GPU模式，-1为自动，0为纯CPU，大于0则强制使用GPU\n- --gpu-layers：卸载到GPU的层数，可部分加速推理\n- --kv-cache：启用KV缓存以加速生成，默认开启\n- --temp、--top-k、--top-p：采样参数控制生成多样性\n- --penalty、--repeat-last-n：重复惩罚参数，减少生成重复内容\n\n### LoRA支持\n\nllm.c 支持通过 safetensors 格式加载 LoRA（Low-Rank Adaptation）适配器，并可通过多次指定\n--lora\n参数叠加多个适配器。每个适配器可独立设置缩放系数\n--lora-scale\n，实现灵活的模型定制。\n\n## 编程接口（C API）\n\n对于需要将LLM能力集成到现有应用的开发者，llm.c 提供了清晰的C语言API：\n\nc\n#include \"llm.h\"\n\nkc_llm_options_t opts = {\n .model_path = \"model.gguf\",\n .ctx = 2048,\n .predict = 128\n};\nkc_llm_t *ctx = NULL;\n\nif (kc_llm_open(&ctx, &opts) == 0) {\n kc_llm_generate(ctx, \"Hello!\", write_callback, user_data);\n kc_llm_close(ctx);\n}\n\n\nAPI设计遵循明确的所有权模型：\n\n- 选项结构体在\nkc_llm_open()\n时被复制，调用者可立即释放原始副本\n- 回调函数接收的缓冲区仅在回调执行期间有效\n- 错误信息指针在下次状态修改调用前保持有效\n- 调用者拥有提示文本的存储所有权\n\n核心API函数包括：\n\n- kc_llm_open()：分配并初始化LLM上下文\n- kc_llm_lora_apply()：加载并注册LoRA适配器\n- kc_llm_lora_clear()：释放所有已加载适配器\n- kc_llm_generate()：执行同步文本生成，支持流式回调\n- kc_llm_stop()：线程安全的生成中断机制\n- kc_llm_close()：释放上下文及所有关联资源\n\n## 分词器实现\n\nllm.c 从GGUF元数据中自动选择分词器实现，目前支持三种主流方案：\n\nBPE（Byte Pair Encoding）：GPT-2风格的字节级BPE，支持gpt2、llama-bpe和qwen2预分词器变体。\n\nSentencePiece：Google的SentencePiece库，被LLaMA、Mistral和Gemma系列模型采用。\n\nUnigram：Google的Unigram分词算法。\n\n模型兼容性由架构元数据和分词器元数据共同决定。不支持的架构、分词器模型或预分词器会在加载时返回明确的错误信息。\n\n## 构建系统与GPU支持\n\n项目使用Makefile构建系统，原生支持x86_64 Linux平台。编译产物位于\nbin/{arch}/{platform}/\n目录下。\n\nCUDA支持为可选功能，通过在构建时传递\nCUDA=1\n标志启用。构建系统会检测宿主机是否安装了可用的CUDA工具链，如未检测到则自动回退到CPU-only构建。\n\nGPU运行时语义设计灵活：\n\n- --gpu -1（自动模式）：检测到兼容GPU时使用，否则回退CPU\n- --gpu 0：强制禁用GPU，仅使用CPU后端\n- --gpu >0：强制要求GPU，如CUDA未启用或无兼容设备则报错\n- --gpu-layers N：控制多少层Transformer卸载到显存，其余层在CPU执行\n\n这种分层卸载策略允许在显存受限的设备上运行大模型，通过CPU/GPU混合计算平衡性能和资源占用。\n\n## 应用场景与优势\n\nllm.c 特别适合以下场景：\n\n嵌入式系统：无Python依赖的纯C实现，适合资源受限的嵌入式环境。\n\n服务端推理：轻量级设计和高性能C代码，适合构建低延迟的推理服务。\n\n跨平台应用：C语言的可移植性确保代码可在多种操作系统和架构上编译运行。\n\n现有C/C++项目集成：清晰的C API设计便于将LLM能力嵌入到成熟的C/C++代码库中。\n\n边缘计算：小体积二进制和最小运行时依赖，适合部署到边缘设备。\n\n## 与同类项目的对比\n\n相比llama.cpp，llm.c 更加精简，专注于推理核心功能，去除了训练、微调等附加能力。这种专注使得代码库更小、API更简洁，但也意味着功能范围相对有限。\n\n相比Python生态的Transformers或vLLM，llm.c 的优势在于零Python依赖和更小的内存占用，劣势在于生态丰富度和高级功能（如连续批处理、前缀缓存等）的缺失。\n\n## 总结\n\nllm.c 是一个值得关注的轻量级LLM推理引擎项目。它证明了在Python主导的大模型时代，C语言仍然有其独特价值——特别是在性能敏感、资源受限或需要深度集成的场景下。对于希望将LLM能力原生集成到C/C++应用的开发者，llm.c 提供了一个简洁而可靠的选择。

llm.c：纯C语言实现的高性能LLM推理引擎\n\n项目概述\n\n在大语言模型推理框架领域，Python生态长期占据主导地位。然而，对于追求极致性能、最小依赖和跨平台兼容性的开发者而言，纯C语言实现仍然具有不可替代的价值。llm.c 项目正是这一理念的具体实践——一个用C语言编写的可移植LLM推理引擎，支持GGUF模型格式和GGML计算后端。\n\n该项目由 kaisarcode 开发并开源，定位为\n"独立的推理原语\n"（standalone inference primitive），旨在为C/C++应用程序提供原生的文本生成能力，无需依赖Python运行时或复杂的框架栈。\n\n核心特性与架构设计\n\n轻量级设计哲学\n\nllm.c 的设计遵循极简主义原则。整个库围绕一个核心上下文对象\nkc_llm_t\n展开，该对象封装了模型加载、后端资源、LoRA适配器、错误状态和可选的KV缓存。这种单一所有权模型确保了内存行为的可预测性，对于嵌入式系统和资源受限环境尤为重要。\n\nGGUF与GGML生态兼容\n\n项目深度集成GGUF（GPT-Generated Unified Format）和GGML（GPT-Generated Model Library）生态，这是llama.cpp等项目推动的开放模型格式标准。通过支持GGUF，llm.c 可以无缝加载社区中大量预训练的量化模型，包括Q4_0、Q4_K_M、Q8_0等多种量化方案。\n\n多架构模型支持\n\nllm.c 实现了对多种主流Transformer架构的支持：\n\nLlama风格架构：包括原版Llama、Mistral、Mixtral系列。这些模型采用SiLU激活函数、RoPE位置编码和标准GQA（分组查询注意力）机制。\n\nQwen风格架构：支持Qwen2、Qwen2.5、Qwen3系列。除了SiLU和RoPE外，还实现了Qwen特有的频率基数和Qwen3的Q/K RMS归一化。\n\nGemma风格架构：Google Gemma系列，采用GELU激活函数和基于嵌入维度平方根的缩放因子。\n\n这种多架构支持使得llm.c 能够服务于不同场景下的模型需求，从通用对话到代码生成，从中文处理到多语言任务。\n\n命令行接口设计\n\nllm.c 提供了一个简洁而功能完整的CLI工具，支持丰富的推理控制选项：\n\n基础用法\n\n单轮对话生成：\nbash\necho \"What is the capital of France?\" | ./llm --model llama-3-8b.gguf\n\n\n带LoRA适配器的推理：\nbash\nprintf '%s\\n' \"Hello\" | ./llm \\\n --model base.gguf \\\n --lora adapter.safetensors --lora-scale 0.8\n\n\n关键参数说明\n\n- --ctx：上下文窗口大小，默认2048 tokens\n- --predict：最大生成token数，默认128\n- --threads：推理线程数，自动检测CPU核心数\n- --gpu：GPU模式，-1为自动，0为纯CPU，大于0则强制使用GPU\n- --gpu-layers：卸载到GPU的层数，可部分加速推理\n- --kv-cache：启用KV缓存以加速生成，默认开启\n- --temp、--top-k、--top-p：采样参数控制生成多样性\n- --penalty、--repeat-last-n：重复惩罚参数，减少生成重复内容\n\nLoRA支持\n\nllm.c 支持通过 safetensors 格式加载 LoRA（Low-Rank Adaptation）适配器，并可通过多次指定\n--lora\n参数叠加多个适配器。每个适配器可独立设置缩放系数\n--lora-scale\n，实现灵活的模型定制。\n\n编程接口（C API）\n\n对于需要将LLM能力集成到现有应用的开发者，llm.c 提供了清晰的C语言API：\n\nc\n#include \"llm.h\"\n\nkc_llm_options_t opts = {\n .model_path = \"model.gguf\",\n .ctx = 2048,\n .predict = 128\n};\nkc_llm_t *ctx = NULL;\n\nif (kc_llm_open(&ctx, &opts) == 0) {\n kc_llm_generate(ctx, \"Hello!\", write_callback, user_data);\n kc_llm_close(ctx);\n}\n\n\nAPI设计遵循明确的所有权模型：\n\n- 选项结构体在\nkc_llm_open()\n时被复制，调用者可立即释放原始副本\n- 回调函数接收的缓冲区仅在回调执行期间有效\n- 错误信息指针在下次状态修改调用前保持有效\n- 调用者拥有提示文本的存储所有权\n\n核心API函数包括：\n\n- kc_llm_open()：分配并初始化LLM上下文\n- kc_llm_lora_apply()：加载并注册LoRA适配器\n- kc_llm_lora_clear()：释放所有已加载适配器\n- kc_llm_generate()：执行同步文本生成，支持流式回调\n- kc_llm_stop()：线程安全的生成中断机制\n- kc_llm_close()：释放上下文及所有关联资源\n\n分词器实现\n\nllm.c 从GGUF元数据中自动选择分词器实现，目前支持三种主流方案：\n\nBPE（Byte Pair Encoding）：GPT-2风格的字节级BPE，支持gpt2、llama-bpe和qwen2预分词器变体。\n\nSentencePiece：Google的SentencePiece库，被LLaMA、Mistral和Gemma系列模型采用。\n\nUnigram：Google的Unigram分词算法。\n\n模型兼容性由架构元数据和分词器元数据共同决定。不支持的架构、分词器模型或预分词器会在加载时返回明确的错误信息。\n\n构建系统与GPU支持\n\n项目使用Makefile构建系统，原生支持x86_64 Linux平台。编译产物位于\nbin/{arch}/{platform}/\n目录下。\n\nCUDA支持为可选功能，通过在构建时传递\nCUDA=1\n标志启用。构建系统会检测宿主机是否安装了可用的CUDA工具链，如未检测到则自动回退到CPU-only构建。\n\nGPU运行时语义设计灵活：\n\n- --gpu -1（自动模式）：检测到兼容GPU时使用，否则回退CPU\n- --gpu 0：强制禁用GPU，仅使用CPU后端\n- --gpu >0：强制要求GPU，如CUDA未启用或无兼容设备则报错\n- --gpu-layers N：控制多少层Transformer卸载到显存，其余层在CPU执行\n\n这种分层卸载策略允许在显存受限的设备上运行大模型，通过CPU/GPU混合计算平衡性能和资源占用。\n\n应用场景与优势\n\nllm.c 特别适合以下场景：\n\n嵌入式系统：无Python依赖的纯C实现，适合资源受限的嵌入式环境。\n\n服务端推理：轻量级设计和高性能C代码，适合构建低延迟的推理服务。\n\n跨平台应用：C语言的可移植性确保代码可在多种操作系统和架构上编译运行。\n\n现有C/C++项目集成：清晰的C API设计便于将LLM能力嵌入到成熟的C/C++代码库中。\n\n边缘计算：小体积二进制和最小运行时依赖，适合部署到边缘设备。\n\n与同类项目的对比\n\n相比llama.cpp，llm.c 更加精简，专注于推理核心功能，去除了训练、微调等附加能力。这种专注使得代码库更小、API更简洁，但也意味着功能范围相对有限。\n\n相比Python生态的Transformers或vLLM，llm.c 的优势在于零Python依赖和更小的内存占用，劣势在于生态丰富度和高级功能（如连续批处理、前缀缓存等）的缺失。\n\n总结\n\nllm.c 是一个值得关注的轻量级LLM推理引擎项目。它证明了在Python主导的大模型时代，C语言仍然有其独特价值——特别是在性能敏感、资源受限或需要深度集成的场景下。对于希望将LLM能力原生集成到C/C++应用的开发者，llm.c 提供了一个简洁而可靠的选择。