# DeepSeek-R1 User Guide

## 1. Quick Start

**DeepSeek-R1** is an open-source reasoning language model series developed by DeepSeek AI. It is designed to solve complex problems in mathematics, coding, and logical reasoning through an extended chain-of-thought process before producing a final answer. The model family includes both a full-scale 671B Mixture-of-Experts model and several distilled dense variants, making it accessible across a range of hardware configurations.

**Key capabilities:**
- Extended reasoning with transparent `<think>` steps before final answers
- Strong performance on mathematics and scientific benchmarks
- Multiple model sizes from 1.5B to 671B parameters
- Open weights (MIT license) available for self-hosting via Hugging Face
- API-compatible interface following OpenAI SDK conventions
- Distilled variants based on Qwen2.5 and Llama-3 architectures

**Prerequisites:** An API key from the DeepSeek platform, or a machine with sufficient VRAM for local inference.

> [!TIP]
> The fastest path to productivity is the DeepSeek API — no local hardware required. Point your existing OpenAI SDK client at `https://api.deepseek.com` and use model `deepseek-reasoner`.

### Minimal API example

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DEEPSEEK_API_KEY",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user", "content": "What is 127 × 43?"}]
)
print(response.choices[0].message.content)
```

```text
<think>
127 × 43 = 127 × 40 + 127 × 3 = 5080 + 381 = 5461
</think>

127 × 43 = **5,461**
```

**What to try next:**
- See [Installation](#2-installation) for local deployment options
- See [Core Usage](#4-core-usage) for prompt patterns and the reasoning format
- See [Troubleshooting](#6-troubleshooting) for common API issues

---

## 2. Installation

### System Requirements

| Deployment Method | RAM | GPU VRAM | Disk |
|---|---|---|---|
| API (cloud) | Any | None | None |
| DeepSeek-R1-Distill-Qwen-1.5B | 4 GB | 4 GB (FP16) | ~3 GB |
| DeepSeek-R1-Distill-Qwen-7B | 16 GB | 8 GB (FP16) | ~14 GB |
| DeepSeek-R1-Distill-Llama-8B | 16 GB | 10 GB (FP16) | ~16 GB |
| DeepSeek-R1-Distill-Qwen-14B | 32 GB | 16 GB (FP16) | ~28 GB |
| DeepSeek-R1-Distill-Qwen-32B | 64 GB | 40 GB (FP16) | ~65 GB |
| DeepSeek-R1-Distill-Llama-70B | 140 GB | 80 GB+ (FP16) | ~140 GB |
| DeepSeek-R1 (full, 671B MoE) | Cluster | Multi-node A100/H100 | ~1.3 TB |

> [!IMPORTANT]
> The full 671B DeepSeek-R1 uses a Mixture-of-Experts (MoE) architecture requiring multi-GPU cluster infrastructure. For individuals and most organizations, the distilled variants (1.5B–70B) deliver strong reasoning performance at practical resource levels.

=== "API (Recommended)"

    No software to install beyond the OpenAI SDK:

    ```bash
    pip install openai
    export DEEPSEEK_API_KEY="sk-..."
    ```

=== "Hugging Face Transformers"

    ```bash
    pip install transformers torch accelerate
    huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-7B
    ```

=== "Ollama"

    ```bash
    # Install Ollama from ollama.com for your platform, then:
    ollama pull deepseek-r1:7b
    ollama run deepseek-r1:7b
    ```

=== "vLLM (Production Local)"

    ```bash
    pip install vllm
    vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-7B --host 0.0.0.0 --port 8000
    ```

### Post-Install Verification

**API:**

```python
from openai import OpenAI
client = OpenAI(api_key="sk-...", base_url="https://api.deepseek.com")
r = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user", "content": "Say hello."}],
    max_tokens=50
)
print(r.choices[0].message.content)
```

```text
Hello! How can I assist you today?
```

**Local (Hugging Face):**

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("deepseek-ai/DeepSeek-R1-Distill-Qwen-7B")
model = AutoModelForCausalLM.from_pretrained(
    "deepseek-ai/DeepSeek-R1-Distill-Qwen-7B", device_map="auto"
)
print("Model loaded successfully.")
```

```text
Model loaded successfully.
```

> [!WARNING]
> Model downloads range from 3 GB to over 140 GB depending on variant. Ensure sufficient disk space and a stable connection. For VRAM-constrained setups, load with `load_in_4bit=True` to reduce memory usage at a small quality cost.

---

## 3. Configuration

The `deepseek-ai/DeepSeek-R1` repository contains no application source code or configuration files — it is a model release artifact (research paper, README, benchmark figure, license). All configuration is done through API call parameters or your chosen inference framework.

### API Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `model` | string | — | `deepseek-reasoner` for R1 via API |
| `messages` | array | — | Chat history in OpenAI message format |
| `max_tokens` | integer | varies | Cap on total response tokens (reasoning + answer) |
| `temperature` | float | 1.0 | Sampling temperature; 0.5–0.7 recommended for reasoning tasks |
| `top_p` | float | 1.0 | Nucleus sampling threshold |
| `stream` | boolean | false | Enable token-by-token streaming |

> [!NOTE]
> The `logprobs` parameter is not supported for the R1 model on the DeepSeek API (GitHub issue #815). If you need token-level probabilities, run a distilled model locally with vLLM, which supports `logprobs` natively.

### Environment Variables

| Variable | Description |
|---|---|
| `DEEPSEEK_API_KEY` | Your API key from platform.deepseek.com |

For local deployment configuration (vLLM server flags, Ollama options), see the Admin Guide.

---

## 4. Core Usage

### Understanding the Reasoning Format

DeepSeek-R1 produces a two-part response: a reasoning trace inside `<think>...</think>` tags, followed by a concise final answer. The thinking block is the model's internal scratchpad — visible in the raw API response but sometimes hidden by chat interfaces.

```python
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user", "content": "What is the derivative of x³?"}]
)
print(response.choices[0].message.content)
```

```text
<think>
Using the power rule: d/dx(x^n) = n·x^(n-1)
For x³: n = 3, so d/dx(x³) = 3x²
</think>

The derivative of x³ is **3x²**.
```

> [!TIP]
> For math and coding tasks, keep `temperature` between 0.5 and 0.7. For creative or open-ended writing, 1.0 works well. Very low temperatures (< 0.3) can cause repetitive or prematurely cut-off reasoning chains.

### Multi-Turn Conversations

The API is stateless — you must include the full conversation history in every request. There is no server-side session storage (GitHub issue #797).

```python
messages = [
    {"role": "user", "content": "I have a list: [3, 1, 4, 1, 5]. Sort it."}
]

response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=messages
)
answer = response.choices[0].message.content
messages.append({"role": "assistant", "content": answer})

# Follow-up turn
messages.append({"role": "user", "content": "Now remove duplicates."})
response2 = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=messages
)
print(response2.choices[0].message.content)
```

> [!WARNING]
> There is no built-in session persistence. If you need memory across restarts, serialize your `messages` list to disk after each exchange and reload it at the start of the next session.

### Streaming Responses

```python
stream = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user", "content": "Explain recursion step by step."}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
```

### System Prompts

```python
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant. Limit answers to 100 words."},
        {"role": "user", "content": "What is a binary tree?"}
    ]
)
```

> [!NOTE]
> System prompts are not persisted between API calls. Include your system instruction in every request. Feature requests for persistent system instructions have been filed (GitHub issue #812). Third-party wrappers can handle automatic injection.

---

## 5. Common Tasks

### Task 1 — Solve a Math Problem Step by Step

```python
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{"role": "user", "content": "Find all prime numbers less than 50, showing your work."}]
)
print(response.choices[0].message.content)
```

**Verify:** The response should include a `<think>` block with a sieve or enumeration, then list: 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47.

### Task 2 — Generate a Python Function

```python
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{
        "role": "user",
        "content": "Write a Python function to check if a string is a palindrome, with tests."
    }]
)
print(response.choices[0].message.content)
```

### Task 3 — Code Review

```python
code = """
def find_max(lst):
    max_val = lst[0]
    for x in lst:
        if x > max_val:
            max_val = x
    return max_val
"""
response = client.chat.completions.create(
    model="deepseek-reasoner",
    messages=[{
        "role": "user",
        "content": f"Review this function and suggest improvements:\n\n```python\n{code}\n```"
    }]
)
```

### Task 4 — Run a Distilled Model Locally (Offline)

```python
from transformers import pipeline

pipe = pipeline(
    "text-generation",
    model="deepseek-ai/DeepSeek-R1-Distill-Qwen-7B",
    device_map="auto"
)
result = pipe(
    "What is 15 factorial? Show your work.",
    max_new_tokens=512
)
print(result[0]["generated_text"])
```

### Task 5 — Batch Async API Calls

```python
import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(api_key="sk-...", base_url="https://api.deepseek.com")

async def ask(prompt):
    r = await client.chat.completions.create(
        model="deepseek-reasoner",
        messages=[{"role": "user", "content": prompt}]
    )
    return r.choices[0].message.content

async def main():
    prompts = ["What is 2+2?", "What is the capital of France?", "Explain gravity."]
    results = await asyncio.gather(*[ask(p) for p in prompts])
    for p, r in zip(prompts, results):
        print(f"Q: {p}\nA: {r}\n")

asyncio.run(main())
```

### Task 6 — Integrate with LangChain

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="deepseek-reasoner",
    openai_api_key="sk-...",
    openai_api_base="https://api.deepseek.com"
)
result = llm.invoke("Explain gradient descent in simple terms.")
print(result.content)
```

### Task 7 — Run via Ollama CLI

```bash
ollama pull deepseek-r1:7b
ollama run deepseek-r1:7b "What is the Pythagorean theorem?"
```

```text
<think>
The Pythagorean theorem relates the sides of a right triangle...
</think>

In a right triangle: a² + b² = c², where c is the hypotenuse.
```

---

## 6. Troubleshooting

**Diagnostic checklist:**
- [ ] API key valid and not expired?
- [ ] `base_url` set to `https://api.deepseek.com`?
- [ ] Model name is exactly `deepseek-reasoner`?
- [ ] For local: VRAM is sufficient for the chosen model size?

---

### Error: `401 Unauthorized`

**Cause:** API key missing, invalid, or not passed correctly.

**Solution:**
1. Verify your key at [platform.deepseek.com](https://platform.deepseek.com)
2. Pass it explicitly: `OpenAI(api_key="sk-...", base_url="https://api.deepseek.com")`
3. Check for accidental whitespace in the key string

**Prevention:** Load from environment: `api_key=os.environ["DEEPSEEK_API_KEY"]`

---

### Error: `404 Model not found`

**Cause:** Incorrect model identifier.

**Solution:**
1. Use `deepseek-reasoner` (not `deepseek-r1` or `r1`) for the API
2. For Hugging Face, use the full path: `deepseek-ai/DeepSeek-R1-Distill-Qwen-7B`

---

### Error: Response truncates mid-reasoning

**Cause:** `max_tokens` too low to contain the full reasoning chain plus answer.

**Solution:**
1. Reasoning models produce more tokens than standard chat models
2. Set `max_tokens=4096` as a baseline; use `max_tokens=8192` for proofs and complex code
3. Check the `finish_reason` field: `length` means truncation occurred

---

### Error: `tool_choice` parameter rejected

**Cause:** The R1 model via the DeepSeek API does not support the `tool_choice` field (GitHub issue #813).

**Solution:**
1. Remove `tool_choice` from your request
2. Use prompt engineering to direct tool-use behavior instead
3. For production tool-calling, self-host a distilled model with a framework that supports it

> [!WARNING]
> Do not assume OpenAI-compatible endpoints support every OpenAI parameter. The DeepSeek API subset differs; test each parameter before relying on it in production.

---

### Error: `logprobs` not returned

**Cause:** Not supported on the DeepSeek API for R1 (GitHub issue #815).

**Solution:** Run a distilled model locally with vLLM (`--enable-logprobs`) if token probabilities are required.

---

### Local — Out of VRAM

**Cause:** Model is larger than available GPU memory.

**Solution:**
1. Choose a smaller distilled variant
2. Load with 4-bit quantization: `from_pretrained(..., load_in_4bit=True)`
3. Use `device_map="auto"` to split across CPU and GPU

> [!CAUTION]
> Running without quantization on insufficient VRAM will crash the Python process. Always check `nvidia-smi` before loading a model.

---

### Local — Extremely Slow Inference

**Cause:** Model falling back to CPU, or no batching optimization.

**Solution:**
1. Confirm GPU is available: `python -c "import torch; print(torch.cuda.is_available())"`
2. Use `device_map="auto"` so Transformers assigns layers to GPU
3. Switch to vLLM for high-throughput workloads

> [!TIP]
> vLLM's PagedAttention and continuous batching provide 2–4× higher throughput than Hugging Face's `generate()` for concurrent requests.

---

### Chat history disappeared

**Cause:** API is stateless — no server-side session storage (GitHub issue #805).

**Solution:**
1. Serialize `messages` to a JSON file after each exchange
2. Reload the file at the start of each session and append to the list
3. Trim early turns when approaching the context window limit

---

## 7. FAQ

**Q: What is the difference between DeepSeek-R1 and the distilled models?**

DeepSeek-R1 is the full 671B MoE model, accessible via the API. The distilled variants (1.5B–70B) are smaller dense models trained to replicate R1's reasoning behavior and are practical for local deployment.

**Q: Is DeepSeek-R1 free to use?**

The model weights are MIT-licensed and free to download. API usage is subject to DeepSeek platform pricing. See [platform.deepseek.com](https://platform.deepseek.com) for current rates.

**Q: Can I use the OpenAI Python SDK with DeepSeek-R1?**

Yes. Set `base_url="https://api.deepseek.com"` and provide your DeepSeek API key. Most parameters work; exceptions are `tool_choice` and `logprobs` (see Troubleshooting).

**Q: What model name do I use in the API?**

Use `deepseek-reasoner` for the R1 reasoning model.

**Q: Does the model remember my previous conversations?**

No. The API is stateless. Send the full conversation history in every request. GitHub issue #797 tracks persistent memory requests.

**Q: Can I fine-tune DeepSeek-R1?**

The MIT license permits fine-tuning. Use the distilled model weights on Hugging Face as your starting checkpoint. Refer to Hugging Face Transformers documentation for fine-tuning procedures.

**Q: What context window does DeepSeek-R1 support?**

The full DeepSeek-R1 model supports up to 128K tokens. Distilled variants inherit context limits from their base architectures (Qwen2.5 or Llama-3). Check the Hugging Face model card for the specific variant you are using.

**Q: Why does the response include `<think>` tags?**

That block is the model's reasoning trace — the chain-of-thought scratchpad. Chat interfaces often hide it. The raw API always returns it in `response.choices[0].message.content`.

**Q: Is voice chat supported?**

Voice chat is not part of the R1 model or API (GitHub issue #155). Combine third-party speech-to-text and text-to-speech services with the API if you need voice interaction.

**Q: How do I file a bug report?**

Open an issue at [github.com/deepseek-ai/DeepSeek-R1](https://github.com/deepseek-ai/DeepSeek-R1). Include your model variant, the exact API call (with the key redacted), and the full error response.

---

_Generated May 2026 from deepseek-ai/DeepSeek-R1 at 0cf7856. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._