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

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)

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

127 × 43 = **5,461**

What to try next:

• See Installation for local deployment options
• See Core Usage for prompt patterns and the reasoning format
• See Troubleshooting for common API issues

2. Installation

System Requirements

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:

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

Hugging Face Transformers

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

Ollama

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

vLLM (Production Local)

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

Post-Install Verification

API:

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)

Hello! How can I assist you today?

Local (Hugging Face):

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.")

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

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

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.

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

<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).

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

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

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

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

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

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)

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

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

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

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

<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
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 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. Include your model variant, the exact API call (with the key redacted), and the full error response.