|
| 1 | +<!--Copyright 2025 The HuggingFace Team. All rights reserved. |
| 2 | +
|
| 3 | +Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with |
| 4 | +the License. You may obtain a copy of the License at |
| 5 | +
|
| 6 | +http://www.apache.org/licenses/LICENSE-2.0 |
| 7 | +
|
| 8 | +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on |
| 9 | +an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the |
| 10 | +specific language governing permissions and limitations under the License. |
| 11 | +
|
| 12 | +⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be |
| 13 | +rendered properly in your Markdown viewer. |
| 14 | +
|
| 15 | +--> |
| 16 | + |
| 17 | +# DeepSeek-V3 |
| 18 | + |
| 19 | +## Overview |
| 20 | + |
| 21 | +The DeepSeek-V3 model was proposed in [DeepSeek-V3 Technical Report](https://arxiv.org/abs/2412.19437) by DeepSeek-AI Team. |
| 22 | + |
| 23 | +The abstract from the paper is the following: |
| 24 | +We present DeepSeek-V3, a strong Mixture-of-Experts (MoE) language model with 671B total parameters with 37B activated for each token. To achieve efficient inference and cost-effective training, DeepSeek-V3 adopts Multi-head Latent Attention (MLA) and DeepSeekMoE architectures, which were thoroughly validated in DeepSeek-V2. Furthermore, DeepSeek-V3 pioneers an auxiliary-loss-free strategy for load balancing and sets a multi-token prediction training objective for stronger performance. We pre-train DeepSeek-V3 on 14.8 trillion diverse and high-quality tokens, followed by Supervised Fine-Tuning and Reinforcement Learning stages to fully harness its capabilities. Comprehensive evaluations reveal that DeepSeek-V3 outperforms other open-source models and achieves performance comparable to leading closed-source models. Despite its excellent performance, DeepSeek-V3 requires only 2.788M H800 GPU hours for its full training. In addition, its training process is remarkably stable. Throughout the entire training process, we did not experience any irrecoverable loss spikes or perform any rollbacks. The model checkpoints are available at https://github.com/deepseek-ai/DeepSeek-V3. |
| 25 | + |
| 26 | +## Limitations and call for contribution! |
| 27 | + |
| 28 | +We are super happy to make this code community-powered, and would love to see how you can best optimize the following: |
| 29 | + |
| 30 | +- current implementation uses the "naive" attention compution (so not really MLA) |
| 31 | +- current implementation loops through the experts. This should be replaced. Pointers to use `get_packed_weights` from `intetrations/tensor_parallel`. |
| 32 | +- current implementation uses the eleuther formula for ROPE, using the orginal one would be more efficient! (should still follow our API) |
| 33 | +- static cache is not supported (this should be just a generation config issue / config shape issues) |
| 34 | + |
| 35 | +### Usage tips |
| 36 | +The model uses Multi-head Latent Attention (MLA) and DeepSeekMoE architectures for efficient inference and cost-effective training. It employs an auxiliary-loss-free strategy for load balancing and multi-token prediction training objective. The model can be used for various language tasks after being pre-trained on 14.8 trillion tokens and going through Supervised Fine-Tuning and Reinforcement Learning stages. |
| 37 | + |
| 38 | +You can run the model in `FP8` automatically, using 2 nodes of 8 H100 should be more than enough! |
| 39 | + |
| 40 | +```python |
| 41 | +# `run_deepseek_v1.py` |
| 42 | +from transformers import AutoModelForCausalLM, AutoTokenizer |
| 43 | +import torch |
| 44 | +torch.manual_seed(30) |
| 45 | + |
| 46 | +tokenizer = AutoTokenizer.from_pretrained("deepseek-r1") |
| 47 | + |
| 48 | +chat = [ |
| 49 | + {"role": "user", "content": "Hello, how are you?"}, |
| 50 | + {"role": "assistant", "content": "I'm doing great. How can I help you today?"}, |
| 51 | + {"role": "user", "content": "I'd like to show off how chat templating works!"}, |
| 52 | +] |
| 53 | + |
| 54 | + |
| 55 | +model = AutoModelForCausalLM.from_pretrained("deepseek-r1", device_map="auto", torch_dtype=torch.bfloat16) |
| 56 | +inputs = tokenizer.apply_chat_template(chat, tokenize=True, add_generation_prompt=True, return_tensors="pt").to(model.device) |
| 57 | +import time |
| 58 | +start = time.time() |
| 59 | +outputs = model.generate(inputs, max_new_tokens=50) |
| 60 | +print(tokenizer.batch_decode(outputs)) |
| 61 | +print(time.time()-start) |
| 62 | +``` |
| 63 | +This generated: |
| 64 | + |
| 65 | +`````` |
| 66 | +<｜Assistant｜><think> |
| 67 | +Okay, the user wants to demonstrate how chat templating works. Let me break down what that means. Chat templating is about structuring the conversation data, especially for models that need specific input formats. Maybe they're referring to something like how messages are formatted with roles (user, assistant, system) in APIs like OpenAI. |
| 68 | +
|
| 69 | +First, I should explain what chat templating is. It's the process of formatting conversation data into a structured format that the model can understand. This usually includes roles and content. For example, user messages, assistant responses, and system messages each have their own role tags. |
| 70 | +
|
| 71 | +They might want an example. Let me think of a simple conversation. The user says "Hello, how are you?" and the assistant responds "I'm doing great. How can I help you today?" Then the user follows up with wanting to show off chat templating. So the example should include the history and the new message. |
| 72 | +
|
| 73 | +In some frameworks, like Hugging Face's Transformers, chat templates are applied using Jinja2 templates. The template might look something like combining system messages, then looping through user and assistant messages with appropriate tags. For instance, using {% for message in messages %} and assigning roles like <|user|>, <|assistant|>, etc. |
| 74 | +
|
| 75 | +I should structure the example with the messages array, showing each role and content. Then apply a hypothetical template to convert that into a formatted string the model uses. Also, mention that different models have different templating requirements, like using special tokens or varying role labels. |
| 76 | +
|
| 77 | +Wait, the user mentioned "chat templating" in the context of showing off. Maybe they want a practical example they can present. So providing a code snippet or a structured data example would be helpful. Let me outline a typical messages array and then the templated output. |
| 78 | +
|
| 79 | +Also, it's important to note that proper templating ensures the model knows the conversation flow, which is crucial for generating coherent responses. Maybe include a note about why it's important, like maintaining context and role-specific processing. |
| 80 | +
|
| 81 | +Let me check if there are any common mistakes or things to avoid. For example, not closing tags properly, or mismatching roles. But maybe that's too detailed unless the user asks. Focus on the positive example first. |
| 82 | +
|
| 83 | +Putting it all together, the response should have an example messages array, the applied template, and the final formatted string. Maybe use angle brackets or special tokens as placeholders. Also, mention that this helps in training or fine-tuning models with structured data. |
| 84 | +
|
| 85 | +I think that's a solid approach. Let me structure it step by step to make it clear. |
| 86 | +</think> |
| 87 | +
|
| 88 | +Chat templating is a way to structure conversation data (e.g., user/assistant interactions) into a format that language models understand. This is especially important for models trained to handle multi-turn dialogues, where the input must explicitly separate roles (user, assistant, system, etc.) and messages. Let’s break this down with an example! |
| 89 | +
|
| 90 | +--- |
| 91 | +
|
| 92 | +### **Step 1: Raw Conversation History** |
| 93 | +Suppose we have this conversation: |
| 94 | +- **User**: "Hello, how are you?" |
| 95 | +- **Assistant**: "I'm doing great. How can I help you today?" |
| 96 | +- **User**: "I'd like to show off how chat templating works!" |
| 97 | +
|
| 98 | +--- |
| 99 | +
|
| 100 | +### **Step 2: Structured Messages** |
| 101 | +In frameworks like Hugging Face Transformers or OpenAI, conversations are often formatted as a list of dictionaries with `role` and `content`: |
| 102 | +```python |
| 103 | +messages = [ |
| 104 | + {"role": "user", "content": "Hello, how are you?"}, |
| 105 | + {"role": "assistant", "content": "I'm doing great. How can I help you today?"}, |
| 106 | + {"role": "user", "content": "I'd like to show off how chat templating works!"}, |
| 107 | +] |
| 108 | +``` |
| 109 | +
|
| 110 | +--- |
| 111 | +
|
| 112 | +### **Step 3: Apply a Chat Template** |
| 113 | +A **chat template** converts this structured data into a single string formatted for the model. For example, using a Jinja-style template (common in Hugging Face): |
| 114 | +
|
| 115 | +```jinja |
| 116 | +{% for message in messages %} |
| 117 | + {% if message['role'] == 'user' %} |
| 118 | + <|user|>{{ message['content'] }}<|end|> |
| 119 | + {% elif message['role'] == 'assistant' %} |
| 120 | + <|assistant|>{{ message['content'] }}<|end|> |
| 121 | + {% endif %} |
| 122 | +{% endfor %} |
| 123 | +<|assistant|> |
| 124 | +``` |
| 125 | +
|
| 126 | +--- |
| 127 | +
|
| 128 | +### **Step 4: Final Templated Output** |
| 129 | +Applying the template to our `messages` list would produce: |
| 130 | +```text |
| 131 | +<|user|>Hello, how are you?<|end|> |
| 132 | +<|assistant|>I'm doing great. How can I help you today?<|end|> |
| 133 | +<|user|>I'd like to show off how chat templating works!<|end|> |
| 134 | +<|assistant|> |
| 135 | +``` |
| 136 | +
|
| 137 | +This tells the model: |
| 138 | +1. The conversation history (user/assistant turns). |
| 139 | +2. The model’s turn to generate a response (`<|assistant|>` at the end). |
| 140 | +
|
| 141 | +--- |
| 142 | +
|
| 143 | +### **Key Notes**: |
| 144 | +- **Role Separation**: Tags like `<|user|>` and `<|assistant|>` help the model distinguish speakers. |
| 145 | +- **Special Tokens**: Models often use unique tokens (e.g., `<|end|>`) to mark message boundaries. |
| 146 | +- **Flexibility**: Templates vary by model (e.g., OpenAI uses `{"role": "user", "content": "..."}` instead of tags). |
| 147 | +
|
| 148 | +--- |
| 149 | +
|
| 150 | +### **Why This Matters**: |
| 151 | +- **Consistency**: Ensures the model understands dialogue structure. |
| 152 | +- **Context Preservation**: Maintains the flow of multi-turn conversations. |
| 153 | +- **Alignment**: Matches the format the model was trained on for better performance. |
| 154 | +
|
| 155 | +Want to dive deeper or see a specific framework’s implementation (e.g., OpenAI, Llama, Mistral)? Let me know! 😊<｜end▁of▁sentence｜> |
| 156 | +`````` |
| 157 | + |
| 158 | +Use the following to run it |
| 159 | +```bash |
| 160 | +torchrun --nproc_per_node=8 --nnodes=2 --node_rank=0|1 --rdzv-id an_id --rdzv-backend c10d --rdzv-endpoint master_addr:master_port run_deepseek_r1.py |
| 161 | +``` |
| 162 | + |
| 163 | +If you have: |
| 164 | +```bash |
| 165 | +[rank0]: ncclInternalError: Internal check failed. |
| 166 | +[rank0]: Last error: |
| 167 | +[rank0]: Bootstrap : no socket interface found |
| 168 | +``` |
| 169 | +error, it means NCCL was probably not loaded. |
| 170 | + |
| 171 | + |
| 172 | +## DeepseekV3Config |
| 173 | + |
| 174 | +[[autodoc]] DeepseekV3Config |
| 175 | + |
| 176 | +## DeepseekV3Model |
| 177 | + |
| 178 | +[[autodoc]] DeepseekV3Model |
| 179 | + - forward |
| 180 | + |
| 181 | +## DeepseekV3ForCausalLM |
| 182 | + |
| 183 | +[[autodoc]] DeepseekV3ForCausalLM |
| 184 | + - forward |
0 commit comments