Add Deploy DeepSeek R1 on Arm CPU learning path

TianyuLi0 · TianyuLi0 · commit 2348be273385 · 2025-03-20T18:03:08.000+08:00
Signed-off-by: Tianyu Li &lt;tianyu.li@arm.com&gt;
diff --git a/content/learning-paths/servers-and-cloud-computing/deepseek-cpu/_index.md b/content/learning-paths/servers-and-cloud-computing/deepseek-cpu/_index.md
@@ -0,0 +1,57 @@
+---
+title: Deploy DeepSeek R1 on Arm servers
+
+minutes_to_complete: 30
+
+who_is_this_for: This is an introductory topic for developers interested in running DeepSeek-R1 on Arm-based servers. 
+
+learning_objectives:
+    - Download and build llama.cpp on your Arm server.
+    - Download a pre-quantized DeepSeek-R1 model from Hugging Face.
+    - Run the pre-quantized model on your Arm CPU and measure the performance.
+
+prerequisites:
+    - An AWS Graviton4 r8g.16xlarge instance to test Arm performance optimizations, or any [Arm based instance](/learning-paths/servers-and-cloud-computing/csp/) from a cloud service provider or an on-premise Arm server.
+
+author:
+    - Tianyu Li
+
+### Tags
+skilllevels: Introductory
+subjects: ML
+armips:
+    - Neoverse
+operatingsystems:
+    - Linux
+tools_software_languages:
+    - LLM
+    - GenAI
+    - Python
+
+
+further_reading:
+    - resource:
+        title: Getting started with DeepSeek-R1
+        link: https://huggingface.co/deepseek-ai/DeepSeek-R1
+        type: documentation
+    - resource:
+        title: Hugging Face Documentation
+        link: https://huggingface.co/docs
+        type: documentation
+    - resource:
+        title: Democratizing Generative AI with CPU-based inference 
+        link: https://blogs.oracle.com/ai-and-datascience/post/democratizing-generative-ai-with-cpu-based-inference
+        type: blog
+    - resource: 
+        title: DeepSeek-R1-GGUF
+        link: https://huggingface.co/bartowski/DeepSeek-R1-GGUF 
+        type: website
+
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---
diff --git a/content/learning-paths/servers-and-cloud-computing/deepseek-cpu/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/deepseek-cpu/_next-steps.md
@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # Set to always be larger than the content in this path to be at the end of the navigation.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---
diff --git a/content/learning-paths/servers-and-cloud-computing/deepseek-cpu/deepseek-chatbot.md b/content/learning-paths/servers-and-cloud-computing/deepseek-cpu/deepseek-chatbot.md
@@ -0,0 +1,258 @@
+---
+title: Run a DeepSeek R1 chatbot on Arm servers
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Before you begin
+The instructions in this Learning Path are for any Arm server running Ubuntu 24.04 LTS. You need an Arm server instance with at least 64 cores and 512GB of RAM to run this example. Configure disk storage up to at least 400 GB. The instructions have been tested on an AWS Graviton4 r8g.16xlarge instance.
+
+## Overview
+
+Arm CPUs are widely used in traditional ML and AI use cases. In this Learning Path, you learn how to run generative AI inference-based use cases like a LLM chatbot on Arm-based CPUs. You do this by deploying the [DeepSeek-R1 GGUF models](https://huggingface.co/bartowski/DeepSeek-R1-GGUF) on your Arm-based CPU using `llama.cpp`.
+
+[llama.cpp](https://github.com/ggerganov/llama.cpp) is an open source C/C++ project developed by Georgi Gerganov that enables efficient LLM inference on a variety of hardware - both locally, and in the cloud. 
+
+## About the DeepSeek-R1 model and GGUF model format
+
+The [DeepSeek-R1 model](https://huggingface.co/deepseek-ai/DeepSeek-R1) from DeepSeek-AI is free to use for research and commercial purposes. 
+
+The DeepSeek-R1 model has 671 billion parameters, based on Mixture of Experts(MoE) architecture. This improve inference speed and keep good quality result. For this example, the full 671 billion (671B) model is used for retaining quality chatbot capability while also running efficiently on your Arm-based CPU. 
+
+Traditionally, the training and inference of LLMs has been done on GPUs using full-precision 32-bit (FP32) or half-precision 16-bit (FP16) data type formats for the model parameter and weights. Recently, a new binary model format called GGUF was introduced by the `llama.cpp` team. This new GGUF model format uses compression and quantization techniques that remove the dependency on using FP32 and FP16 data type formats. For example, GGUF supports quantization where model weights that are generally stored as FP16 data types are scaled down to 4-bit integers. This significantly reduces the need for computational resources and the amount of RAM required. These advancements made in the model format and the data types used make Arm CPUs a great fit for running LLM inferences.   
+ 
+## Install dependencies 
+
+Install the following packages on your Arm based server instance:
+
+```bash
+sudo apt update
+sudo apt install make cmake -y
+```
+
+You also need to install `gcc` on your machine:
+
+```bash
+sudo apt install gcc g++ -y
+sudo apt install build-essential -y
+```
+
+## Download and build llama.cpp
+
+You are now ready to start building `llama.cpp`. 
+
+Clone the source repository for llama.cpp:
+
+```bash
+git clone https://github.com/ggerganov/llama.cpp
+```
+
+By default, `llama.cpp` builds for CPU only on Linux and Windows. You don't need to provide any extra switches to build it for the Arm CPU that you run it on.
+
+Run `cmake` to build it:
+
+```bash
+cd llama.cpp
+mkdir build
+cd build
+cmake .. -DCMAKE_CXX_FLAGS="-mcpu=native" -DCMAKE_C_FLAGS="-mcpu=native"
+cmake --build . -v --config Release -j `nproc`
+```
+
+`llama.cpp` is now built in the `bin` directory.
+Check that `llama.cpp` has built correctly by running the help command:
+
+```bash
+cd bin
+./llama-cli -h
+```
+
+If `llama.cpp` has built correctly on your machine, you will see the help options being displayed. A snippet of the output is shown below:
+
+```output
+usage: ./llama-cli [options]
+
+general:
+
+  -h,    --help, --usage          print usage and exit
+         --version                show version and build info
+  -v,    --verbose                print verbose information
+         --verbosity N            set specific verbosity level (default: 0)
+         --verbose-prompt         print a verbose prompt before generation (default: false)
+         --no-display-prompt      don't print prompt at generation (default: false)
+  -co,   --color                  colorise output to distinguish prompt and user input from generations (default: false)
+  -s,    --seed SEED              RNG seed (default: -1, use random seed for < 0)
+  -t,    --threads N              number of threads to use during generation (default: 4)
+  -tb,   --threads-batch N        number of threads to use during batch and prompt processing (default: same as --threads)
+  -td,   --threads-draft N        number of threads to use during generation (default: same as --threads)
+  -tbd,  --threads-batch-draft N  number of threads to use during batch and prompt processing (default: same as --threads-draft)
+         --draft N                number of tokens to draft for speculative decoding (default: 5)
+  -ps,   --p-split N              speculative decoding split probability (default: 0.1)
+  -lcs,  --lookup-cache-static FNAME
+                                  path to static lookup cache to use for lookup decoding (not updated by generation)
+  -lcd,  --lookup-cache-dynamic FNAME
+                                  path to dynamic lookup cache to use for lookup decoding (updated by generation)
+  -c,    --ctx-size N             size of the prompt context (default: 0, 0 = loaded from model)
+  -n,    --predict N              number of tokens to predict (default: -1, -1 = infinity, -2 = until context filled)
+  -b,    --batch-size N           logical maximum batch size (default: 2048)
+```
+
+
+## Install Hugging Face Hub
+
+There are a few different ways you can download the DeepSeek-R1 model. In this Learning Path, you download the model from Hugging Face.
+
+[Hugging Face](https://huggingface.co/) is an open source AI community where you can host your own AI models, train them and collaborate with others in the community. You can browse through the thousands of models that are available for a variety of use cases like NLP, audio, and computer vision.
+
+The `huggingface_hub` library provides APIs and tools that let you easily download and fine-tune pre-trained models. You will use `huggingface-cli` to download the [DeepSeek-R1 model](https://huggingface.co/bartowski/DeepSeek-R1-GGUF).
+
+Install the required Python packages:
+
+```bash
+sudo apt install python-is-python3 python3-pip python3-venv -y
+```
+
+Create and activate a Python virtual environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+```
+
+Your terminal prompt now has the `(venv)` prefix indicating the virtual environment is active. Use this virtual environment for the remaining commands.
+
+Install the `huggingface_hub` python library using `pip`:
+
+```bash
+pip install huggingface_hub
+```
+
+You can now download the model using the huggingface cli:
+
+```bash
+huggingface-cli download bartowski/DeepSeek-R1-GGUF --include "*DeepSeek-R1-Q4_0*"  --local-dir DeepSeek-R1-Q4_0
+```
+Before you proceed and run this model, take a quick look at what `Q4_0` in the model name denotes.
+
+## Quantization format
+
+`Q4_0` in the model name refers to the quantization method the model uses. The goal of quantization is to reduce the size of the model (to reduce the memory space required) and faster (to reduce memory bandwidth bottlenecks transferring large amounts of data from memory to a processor). The primary trade-off to keep in mind when reducing a model's size is maintaining quality of performance. Ideally, a model is quantized to meet size and speed requirements while not having a negative impact on performance. 
+
+This model is `DeepSeek-R1-Q4_0-00001-of-00010.gguf`, so what does each component mean in relation to the quantization level? The main thing to note is the number of bits per parameter, which is denoted by 'Q4' in this case or 4-bit integer. As a result, by only using 4 bits per parameter for 671 billion parameters, the model drops to be 354 GB in size.
+
+## Run the pre-quantized DeepSeek-R1 LLM model weights on your Arm-based server
+
+As of [llama.cpp commit 0f1a39f3](https://github.com/ggerganov/llama.cpp/commit/0f1a39f3), Arm has contributed code for performance optimization with three types of GEMV/GEMM kernels corresponding to three processor types:
+
+* AWS Graviton2, where you only have NEON support (you will see less improvement for these GEMV/GEMM kernels),
+* AWS Graviton3, where the GEMV/GEMM kernels exploit both SVE 256 and MATMUL INT8 support, and
+* AWS Graviton4, where the GEMV/GEMM kernels exploit NEON/SVE 128 and MATMUL_INT8 support
+
+With the latest commits in `llama.cpp` you will see improvements for these Arm optimized kernels directly on your Arm-based server. You can run the pre-quantized Q4_0 model as is and do not need to re-quantize the model.
+
+Run the pre-quantized DeepSeek-R1 model exactly as the weights were downloaded from huggingface:
+
+```bash
+./llama-cli -m DeepSeek-R1-Q4_0-00001-of-00010.gguf -no-cnv --temp 0.6 -t 64 --prompt "<|User|>Building a visually appealing website can be done in ten simple steps:<｜Assistant｜>" -n 512
+```
+
+This command will use the downloaded model (`-m` flag), disable conversation mode explicitly (`-no-cnv` flag), adjust the randomness of the generated text (`--temp` flag),  with the specified prompt (`-p` flag), and target a 512 token completion (`-n` flag), using 64 threads (`-t` flag).
+
+You may notice there are many gguf files downloaded, llama.cpp can load all series of files by passing the first one with `-m` flag.
+
+You will see lots of interesting statistics being printed from llama.cpp about the model and the system, followed by the prompt and completion. The tail of the output from running this model on an AWS Graviton4 r8g.16xlarge instance is shown below:
+
+```output
+build: 4879 (f08f4b31) with cc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0 for aarch64-linux-gnu
+...
+load_tensors:   CPU_Mapped model buffer size = 35048.27 MiB
+load_tensors:   CPU_Mapped model buffer size = 22690.15 MiB
+....................................................................................................
+llama_init_from_model: n_seq_max     = 1
+llama_init_from_model: n_ctx         = 4096
+llama_init_from_model: n_ctx_per_seq = 4096
+llama_init_from_model: n_batch       = 2048
+llama_init_from_model: n_ubatch      = 512
+llama_init_from_model: flash_attn    = 0
+llama_init_from_model: freq_base     = 10000.0
+llama_init_from_model: freq_scale    = 0.025
+llama_init_from_model: n_ctx_per_seq (4096) < n_ctx_train (163840) -- the full capacity of the model will not be utilized
+llama_kv_cache_init: kv_size = 4096, offload = 1, type_k = 'f16', type_v = 'f16', n_layer = 61, can_shift = 0
+llama_kv_cache_init:        CPU KV buffer size = 19520.00 MiB
+llama_init_from_model: KV self size  = 19520.00 MiB, K (f16): 11712.00 MiB, V (f16): 7808.00 MiB
+llama_init_from_model:        CPU  output buffer size =     0.49 MiB
+llama_init_from_model:        CPU compute buffer size =  1186.01 MiB
+llama_init_from_model: graph nodes  = 5025
+llama_init_from_model: graph splits = 1
+common_init_from_params: KV cache shifting is not supported for this model, disabling KV cache shifting
+common_init_from_params: setting dry_penalty_last_n to ctx_size = 4096
+common_init_from_params: warming up the model with an empty run - please wait ... (--no-warmup to disable)
+main: llama threadpool init, n_threads = 64
+
+system_info: n_threads = 64 (n_threads_batch = 64) / 64 | CPU : NEON = 1 | ARM_FMA = 1 | FP16_VA = 1 | MATMUL_INT8 = 1 | SVE = 1 | DOTPROD = 1 | SVE_CNT = 16 | OPENMP = 1 | AARCH64_REPACK = 1 |
+
+sampler seed: 3199001937
+sampler params:
+	repeat_last_n = 64, repeat_penalty = 1.000, frequency_penalty = 0.000, presence_penalty = 0.000
+	dry_multiplier = 0.000, dry_base = 1.750, dry_allowed_length = 2, dry_penalty_last_n = 4096
+	top_k = 40, top_p = 0.950, min_p = 0.050, xtc_probability = 0.000, xtc_threshold = 0.100, typical_p = 1.000, top_n_sigma = -1.000, temp = 0.600
+	mirostat = 0, mirostat_lr = 0.100, mirostat_ent = 5.000
+sampler chain: logits -> logit-bias -> penalties -> dry -> top-k -> typical -> top-p -> min-p -> xtc -> temp-ext -> dist
+generate: n_ctx = 4096, n_batch = 2048, n_predict = 512, n_keep = 1
+
+<|User|>Building a visually appealing website can be done in ten simple steps:<think>
+Okay, the user wants to build a visually appealing website in ten simple steps. Let me think about how to break this down. First, I need to outline the key stages of web design without getting too technical. Starting with defining the purpose and audience makes sense because that sets the foundation. Then, choosing the right tools like website builders or coding from scratch. Maybe mention popular platforms like WordPress or Wix as examples.
+
+Next, planning the site structure. Sitemaps and user flow are important here. I should emphasize the importance of clear navigation to avoid confusion. Then, selecting a color scheme and typography. Maybe explain how colors affect user emotions and the importance of readability with fonts. Don't forget accessibility here, like contrast ratios and font sizes.
+
+Responsive design is a must these days, so I need to stress mobile optimization. Maybe mention frameworks like Bootstrap or media queries if coding. Visual hierarchy comes next – using size, spacing, and contrast to guide users. High-quality visuals are crucial, so suggest using stock photos or custom graphics, and optimizing for web to keep load times down.
+
+Whitespace is often overlooked but important for a clean look. Then, call-to-action buttons – their placement and design. Testing across devices and browsers is a key step before launch. Finally, ongoing maintenance and SEO basics. Wait, the user mentioned ten steps. Let me count again.
+
+1. Define purpose and audience
+2. Choose tools
+3. Plan structure
+4. Select colors and fonts
+5. Responsive design
+6. Visual hierarchy
+7. High-quality visuals
+8. Whitespace
+9. CTAs
+10. Test and optimize
+
+That's ten. But maybe step 10 should include maintenance and SEO. Hmm. Maybe combine testing with ongoing SEO as part of the final step. Also, should I mention content creation? Maybe under high-quality visuals. Need to keep each step concise. Also, check if any steps can be merged or rephrased for clarity. Let me make sure each step is actionable and not too vague. Add examples where possible, like suggesting tools or resources. Accessibility should be mentioned in color contrast and typography. Alright, that should cover it without overwhelming the user.
+</think>
+
+Here’s a streamlined 10-step guide to building a visually appealing and functional website:
+
+---
+
+### **1. Define Purpose & Audience**
+- **Goal:** Clarify the site’s objective (e.g., portfolio, e-commerce, blog).
+- **Audience
+
+llama_perf_sampler_print:    sampling time =      38.85 ms /   532 runs   (    0.07 ms per token, 13694.75 tokens per second)
+llama_perf_context_print:        load time = 1061927.81 ms
+llama_perf_context_print: prompt eval time =    6585.21 ms /    20 tokens (  329.26 ms per token,     3.04 tokens per second)
+llama_perf_context_print:        eval time =   47463.45 ms /   511 runs   (   92.88 ms per token,    10.77 tokens per second)
+llama_perf_context_print:       total time =   54172.15 ms /   531 tokens
+```
+
+The `system_info` printed from llama.cpp highlights important architectural features present on your hardware that improve the performance of the model execution. In the output shown above from running on an AWS Graviton4 instance, you will see:
+
+  * NEON = 1 This flag indicates support for Arm's Neon technology which is an implementation of the Advanced SIMD instructions
+  * ARM_FMA = 1 This flag indicates support for Arm Floating-point Multiply and Accumulate instructions 
+  * MATMUL_INT8 = 1 This flag indicates support for Arm int8 matrix multiplication instructions
+  * SVE = 1 This flag indicates support for the Arm Scalable Vector Extension
+
+
+The end of the output shows several model timings:
+
+* load time refers to the time taken to load the model.
+* prompt eval time refers to the time taken to process the prompt before generating the new text. 
+* eval time refers to the time taken to generate the output. Generally anything above 10 tokens per second is faster than what humans can read.
+
+You have successfully run a LLM chatbot with Arm KleidiAI optimizations, all running on your Arm AArch64 CPU on your server. You can continue experimenting and trying out the model with different prompts.
+
diff --git a/content/learning-paths/servers-and-cloud-computing/deepseek-cpu/deepseek-server.md b/content/learning-paths/servers-and-cloud-computing/deepseek-cpu/deepseek-server.md
