DeepSeek Models Guide

TL;DR

• DeepSeek is a Chinese AI lab producing open-weight models that disrupted the market with strong reasoning at dramatically lower cost than OpenAI o-series.

• Hosted API default in mid-August 2026 is DeepSeek V4 — pin deepseek-v4-pro (V4-Pro-0813 GA) / deepseek-v4-flash (Flash-0731) with 1M context and thinking effort low / high / max. Experimental multimodal: deepseek-v4-flash-vision-exp. See the model page for DeepSeek V4.

• DeepSeek-V3 is a 671B MoE open checkpoint (~37B active) — still important for self-host and comparisons; do not assume live API aliases still serve V3 weights.

• DeepSeek-R1 is a reasoning model trained with reinforcement learning to produce chain-of-thought - competitive with closed reasoning tiers on math and coding. See DeepSeek R1.

• Open weights enable self-hosting - but the full V3-class models require datacenter-class GPU clusters; distilled smaller versions run locally.

• DeepSeek is not without tradeoffs - geopolitical considerations, variable API availability, and less mature ecosystem than OpenAI or Anthropic.

Quick Decision Guide

Who this guide is for

• Best for: AI engineers · ML engineers · platform/infra engineers · architects
• Difficulty: Intermediate
• Estimated time: 55 min

Learning Path

Large Language Models → Transformers → DeepSeek Models → Fine-tuning → LoRA → Cost Optimization

On this page

• Why This Matters
• The Problem DeepSeek Models Solve
• How We Got Here
• What Is the DeepSeek Model Family?
• How DeepSeek Models Work
• Architecture
• Step-by-Step Flow
• Real Production Example
• Design Decisions
• Comparisons
• Common Mistakes
• Where It Breaks Down
• When NOT to Use DeepSeek
• Running in Production
• Production Checklist
• Related Guides
• Interview Questions
• FAQs
• References
• Further Reading

Why This Matters

In early 2025, DeepSeek-R1's release sent shockwaves through the AI industry. An open-weight reasoning model matching OpenAI o1 on math and code benchmarks - trained for a reported fraction of the cost - challenged assumptions about who can build frontier models and what they should cost.

For engineers, DeepSeek matters because it expands the viable options for reasoning-heavy workloads. If your application needs multi-step math, competitive programming, or scientific analysis, DeepSeek-R1 offers an alternative to expensive o-series API calls - either via their low-cost API or self-hosted distilled models.

But hype obscures nuance. DeepSeek models excel on benchmarks that reward chain-of-thought reasoning. They may not outperform frontier closed APIs (OpenAI's and Anthropic's current flagship models) on creative writing, nuanced instruction following, or production agent workflows. Understanding where DeepSeek actually wins - and where it does not - prevents costly mis-routing.

Engineering Insight

A strong price/reasoning ratio wins routes only when tool reliability holds up. Validate agent behavior on your workloads — cheap tokens do not offset failed tool calls.

The Problem DeepSeek Models Solve

Reasoning models (frontier closed reasoning tiers, Claude with thinking) deliver strong results on hard problems but at high cost and latency. A single frontier reasoning query can cost on the order of $0.50+ (approximate — verify) and take 30–60 seconds. For applications that need reasoning at scale - tutoring platforms, code review, financial modeling - this pricing is prohibitive.

DeepSeek addresses the cost-efficiency gap:

1. DeepSeek-V3 - frontier-class general model at a large (approximate — verify current rates) API cost advantage over peer closed APIs (OpenAI's and Anthropic's current flagship models).

2. DeepSeek-R1 - reasoning model at a substantial (approximate — verify) cost advantage over comparable closed reasoning tiers.

3. Distilled R1 models (1.5B–70B) - smaller models trained on R1 outputs, runnable locally with surprisingly strong reasoning.

4. Open weights - full model weights published for self-hosting (with hardware requirements).

The tradeoff is ecosystem maturity, geopolitical risk for US/EU enterprises, and variable service availability during high demand.

How We Got Here

DeepSeek's model history explains why two different stories coexist: a widely deployed open-weight baseline and a faster-moving hosted API. DeepSeek Coder established code specialization. DeepSeek-V2 demonstrated economical sparse MoE inference. DeepSeek-V3 scaled that design to 671B total parameters with about 37B active per token, Multi-head Latent Attention, and multi-token prediction. In January 2025, R1 applied reinforcement learning to extended reasoning and released full and distilled weights under permissive terms.

V3 and R1 remain important self-hosting, research, and comparison baselines. The hosted service moved beyond those original endpoints: by July 21, 2026, DeepSeek's official documentation lists V4 Flash and V4 Pro, with thinking and non-thinking modes. The legacy deepseek-chat and deepseek-reasoner aliases pointed to V4 Flash and retired on July 24, 2026. On July 31, 2026, DeepSeek published V4-Flash-0731 as the official Flash release (MIT weights on Hugging Face). On August 13, 2026, V4-Pro-0813 left preview as the GA Pro build, with thinking effort low / high / max on both Pro and Flash and native OpenAI Responses API support. Peak/off-peak API prices take effect at 16:00 UTC on August 16, 2026. On August 21, 2026, DeepSeek launched experimental deepseek-v4-flash-vision-exp for image+text API work (Flash rates; no open vision weights yet) plus a free Files API for image reuse. Production code must separate the open checkpoint name from the hosted API ID.

Diagram: DeepSeek's open-weight and API evolution

timeline
    title From code models to unified V4 API tiers
    2023 : DeepSeek Coder
    2024 : DeepSeek-V2 sparse MoE
         : DeepSeek-V3 671B / 37B active
    2025 : DeepSeek-R1 reasoning
         : R1 distilled variants
         : V3.1 and V3.2 API upgrades
    2026 : V4 Flash and V4 Pro API
         : Legacy chat/reasoner aliases retire
         : V4-Flash-0731 official agent upgrade
         : V4-Pro-0813 GA + peak/off-peak prices
         : V4-Flash-Vision-Exp multimodal API

V3 and R1 define the open-weight architecture story, while hosted integrations must follow the current API lifecycle.

This distinction prevents a subtle production error: saying “we use R1” can mean the original MIT-licensed R1 weights, an R1 distill built on Qwen or Llama, a third-party hosted snapshot, or a compatibility alias that now serves another model. Record provider, model ID, snapshot, mode, tokenizer, and serving engine in every evaluation result.

What Is the DeepSeek Model Family?

DeepSeek (深度求索) is an AI research lab backed by High-Flyer, a Chinese quantitative hedge fund. They release both API access and open-weight models.

Core Models

The table describes the foundational open releases requested most often by self-hosting teams. For DeepSeek's first-party API, use deepseek-v4-flash or deepseek-v4-pro as documented in August 2026 rather than assuming the historic V3/R1 names still identify the served weights.

Distilled Models (from R1)

Distilled models inherit R1's reasoning patterns at sizes that run on consumer hardware.

How DeepSeek Models Work

DeepSeek-V3 Architecture

V3 uses a Mixture-of-Experts (MoE) architecture with innovations:

• Multi-head Latent Attention (MLA) - compresses KV-cache, reducing memory for long contexts.

• Auxiliary-loss-free load balancing - routes tokens to experts without auxiliary loss terms that degrade quality.

• 671B total parameters, ~37B activated per token - similar efficiency philosophy to Mixtral but at larger scale.

DeepSeek-R1 Reasoning

R1 was trained in two stages:

1. Cold-start SFT - fine-tune on chain-of-thought examples to bootstrap reasoning format.

2. Large-scale RL - reinforcement learning reward model on math, code, and logic tasks. The model learns to generate extended reasoning traces before producing answers.

At inference time, R1 generates ... blocks (internal reasoning) before the visible response. Reasoning tokens are billed but can be discarded from the output shown to users.

The original Transformer uses stacked encoder and decoder blocks. Each block combines multi-head self-attention with position-wise feed-forward layers, residual connections, and layer normalization.

Source: Google Research

Multi-Token Prediction (MTP)

V3 trains on predicting multiple future tokens simultaneously - improving training efficiency and inference speed.

Architecture: Model Tiers and Capabilities

A reliable DeepSeek system puts a policy gateway in front of both hosted and self-hosted endpoints. The gateway must know whether a request can cross jurisdictions, whether extended thinking is useful, and whether the workflow can tolerate weaker function-call adherence. It also needs an independent fallback; an OpenAI-compatible wire format does not imply behavioral equivalence.

Diagram: Compliance-aware DeepSeek routing architecture

flowchart LR
    A[Application] --> G[Model gateway]
    G --> P{Policy check}
    P -->|Restricted data| S[Self-hosted V3/R1]
    P -->|API allowed| D[DeepSeek V4 API]
    G --> C{Task class}
    C -->|Math or code| T[Thinking mode]
    C -->|Extract or chat| N[Non-thinking mode]
    D --> T
    D --> N
    S --> E[Output evaluator]
    T --> E
    N --> E
    E -->|Agent failure| F[Closed frontier fallback]
    E --> O[Response]

Policy chooses the eligible deployment boundary before task routing chooses a model and thinking mode.

API Model Comparison

All prices are approximate snapshots and change frequently. V3/R1 rows are historical launch-era rates; V4 rows reflect DeepSeek's official page on August 13, 2026. From 16:00 UTC August 16, 2026, V4 uses peak/off-peak billing (off-peak = half of peak; peak hours 01:00–04:00 and 06:00–10:00 UTC). Peak Pro output is $3.96 / 1M tokens. Verify the current pricing page before budgeting.

Capability Comparison

DeepSeek vs Open Models

Step-by-Step Flow: Choosing and Deploying DeepSeek

1. API vs self-host

2. V3 vs R1 routing

General tasks, chat, extraction  → DeepSeek-V3
Math, code, logic, proofs        → DeepSeek-R1
Simple high-volume               → V3 (R1 is slower and more verbose)

3. API integration

DeepSeek API is OpenAI-compatible - change base_url and api_key.

4. Self-host distilled models

For local deployment, use distilled R1 models (7B–70B) via Ollama or vLLM.

5. Handle reasoning output

Strip `` blocks before showing to users. Log them for debugging.

6. Implement fallback

DeepSeek API experiences congestion during peak demand. Route to GPT/Claude on failure.

Diagram: A DeepSeek request with validation and fallback

sequenceDiagram
    participant App
    participant Router
    participant DS as DeepSeek endpoint
    participant Judge as Evaluator
    participant Alt as Closed API
    App->>Router: task + data class
    Router->>DS: selected model and mode
    DS-->>Router: answer + reasoning metadata
    Router->>Judge: validate answer/tool calls
    alt accepted
        Judge-->>App: approved answer
    else failed or unavailable
        Judge->>Alt: retry with normalized prompt
        Alt-->>App: fallback answer
    end

Treat reasoning output, tool arguments, and endpoint health as signals to evaluate, not guarantees of correctness.

Real Production Example

OpenAI-compatible API with model routing:

from openai import OpenAI
import os
import re

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

def route_query(prompt: str) -> tuple[str, dict]:
    """Choose a current endpoint and thinking mode by workload."""
    reasoning_keywords = ["prove", "calculate", "solve", "debug", "implement"]
    needs_reasoning = any(kw in prompt.lower() for kw in reasoning_keywords)
    model = "deepseek-v4-pro" if needs_reasoning else "deepseek-v4-flash"
    thinking = {"type": "enabled" if needs_reasoning else "disabled"}
    return model, thinking

def query_deepseek(prompt: str) -> str:
    model, thinking = route_query(prompt)
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        max_tokens=4096,
        extra_body={"thinking": thinking},
        timeout=45.0,
    )
    return response.choices[0].message.content

# General query → V3
print(query_deepseek("Summarize the history of transformer architectures."))

# Reasoning query → R1
print(query_deepseek("Prove that the square root of 2 is irrational."))

Self-hosted distilled model with Ollama:

ollama pull deepseek-r1:7b
ollama run deepseek-r1:7b "Solve: If x^2 + 5x + 6 = 0, what are the roots?"

Production serving with vLLM (distilled 32B):

python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/DeepSeek-R1-Distill-Qwen-32B \
  --max-model-len 32768 \
  --tensor-parallel-size 2

Design Decisions: When to Pick DeepSeek

Choose DeepSeek when:

• Cost is the primary constraint for reasoning workloads - R1 is typically far cheaper per query than frontier closed reasoning tiers (multiples are approximate — verify current rates).
• You need strong math and code performance without frontier closed-API pricing.
• You want open weights for distillation, research, or self-hosting distilled models.
• You are building in markets where DeepSeek is readily accessible and compliance permits.

Choose GPT/Claude when:

• Agent and tool use reliability is critical - DeepSeek trails on multi-step agent workflows.

• Enterprise compliance requires US/EU providers with established SOC2/HIPAA.

• Ecosystem integration matters - most frameworks optimize for OpenAI and Anthropic first.

• Consistent availability and SLAs are non-negotiable.

Choose Llama/Mistral when:

• You need full self-hosting of a capable model on 1–2 GPUs without distillation.

• Apache 2.0 / Llama license clarity is important for your legal team.

Comparisons

DeepSeek should win routes because of measured utility, not because a benchmark leaderboard or low token price appears decisive. Math and code test sets often underrepresent malformed tool arguments, recovery from tool errors, permission boundaries, ambiguous business instructions, and long-running state.

Approximate list prices change frequently. Verify current DeepSeek, OpenAI, Anthropic, and Google pages before budgeting. Pricing is not normalized for caching, reasoning-token volume, long context, tools, regions, or retries.

The practical metric is cost per accepted task, not token price:

accepted-task cost = (tokens + tool charges + retries + verifier calls) / accepted outputs

A model that is ten times cheaper per token can be more expensive if agent loops fail, outputs need human repair, or verbose reasoning multiplies output tokens. Conversely, a well-bounded code-analysis job may realize DeepSeek's price advantage with no meaningful quality loss.

Common Mistakes

1. Using R1 for everything. R1 is slower, more verbose, and more expensive than V3. Route selectively.

2. Showing or depending on reasoning traces. Use the API's documented reasoning metadata and visible answer fields. Do not scrape invented tag formats or treat hidden reasoning as an audit log.

3. Ignoring availability issues. DeepSeek API has experienced outages and rate limiting during peak demand. Always have fallbacks.

4. Assuming benchmark scores transfer to your tasks. R1 excels on math contests; your customer support bot may not benefit.

5. Underestimating self-hosting V3/R1. Full 671B models need 16+ H100 GPUs. Use distilled models for realistic self-hosting.

6. Skipping compliance review. US and EU enterprises should evaluate data handling, geopolitical risk, and regulatory requirements.

Where It Breaks Down

• Agent workflows - tool use and multi-step agent reliability trail frontier closed APIs (OpenAI's and Anthropic's current flagship models).

• Creative and nuanced tasks - R1 is tuned for reasoning, not creative writing or subtle instruction following.

• API stability - congestion, rate limits, and service interruptions during high demand.

• Geopolitical risk - US government restrictions, enterprise procurement policies, and data sovereignty concerns.

• Ecosystem immaturity - fewer fine-tunes, integrations, and production tooling than Llama or OpenAI.

• Verbose outputs - R1 generates long reasoning traces. Token costs add up even at low per-token rates.

• Full model self-hosting - 671B parameters is datacenter-scale. Not practical for most teams.

When NOT to Use DeepSeek

Avoid DeepSeek as the primary route when the workload demands consistently strong autonomous tool use and your evaluation shows material failure against OpenAI's, Anthropic's, or Google's current flagship tiers. Low token prices do not compensate for unsafe actions or repeated retries.

Do not use the first-party API for regulated or confidential data until legal and security teams approve its data-processing location, retention, subprocessors, contractual terms, and incident controls. DeepSeek is based in China; enterprise procurement may impose additional restrictions, and some public-sector environments prohibit its use. Self-hosted weights can change the data path, but they do not remove model-license, supply-chain, or governance obligations.

Other reasons not to choose it:

• You require a mature enterprise SLA, regional endpoint, or certification not offered for the selected service.
• The full open weights exceed your memory, interconnect, and operations budget; a weak distill would not meet quality targets.
• Your application is predominantly creative, realtime, or customer-facing and another family wins representative evals. For multimodal, treat deepseek-v4-flash-vision-exp as experimental API-only—open Flash/Pro weights remain text-first.
• Your team cannot track API deprecations. The July 2026 alias retirement shows why compatibility names are not a stable model contract.
• You have no fallback provider. API compatibility makes fallback implementation easier, but prompts, tool schemas, safety behavior, and output fields still require normalization.

Never make DeepSeek—or any provider—a permanent global default. Define workload routes, reevaluate them on model changes, and keep at least one operationally independent fallback.

Running in Production

Best Practice

✅ Best Practices - Instrument every stage, version embedding models, enforce access control at retrieval time, and evaluate on a fixed golden set before shipping changes.

Ecosystem

• API: DeepSeek Platform (OpenAI-compatible endpoint).

• Open weights: Hugging Face (V3, R1, distilled variants).

• Local inference: Ollama, vLLM, llama.cpp (GGUF quantized).

• Frameworks: LangChain, LlamaIndex - via OpenAI-compatible client.

• Distillation: Community fine-tunes based on R1 outputs on smaller bases.

Continue Learning

• Next guide: Llama Models
• Then: Mistral Models

Production Checklist

• Model ID / checkpoint pinned (API alias retirement risk acknowledged)
• General vs reasoning tier routing policy defined and logged
• Reasoning-token cost and latency budgets set for thinking routes
• Data-handling / residency policy reviewed for regulated workloads
• Tool-use reliability evaluated on agent golden sets before agent routes
• Cache behavior and retry-adjusted cost measured
• Self-host vs API decision documented (weights, distill, or hosted)
• Golden-set evaluation completed for V3 / reasoning / distill paths
• Cross-provider fallback (GPT / Claude / Gemini class) load-tested
• Circuit-breaker and deprecation monitoring configured
• Rollback path for ID or checkpoint changes documented

Related Guides

Prerequisites

• Large Language Models — Understand MoE and autoregressive inference.

Core Concepts

• Mistral Models — MoE architecture comparison.
• Llama Models — Self-hosting open models.
• GPT Models — o-series reasoning comparison.

Implementation

• Fine-tuning · LoRA — Adapt open checkpoints efficiently.

Optimization

• Cost Optimization — Model routing strategies.

Advanced Topics

• LLM Evaluation — Measuring reasoning quality.
• Evaluation — Measure accepted-task quality and agent reliability.

Diagram: Learning path for DeepSeek deployment

flowchart LR
    LLM[LLM basics] --> DS[DeepSeek family]
    DS --> Eval[Evaluation]
    Eval --> Route[Model routing]
    DS --> FT[Fine-tuning]
    FT --> LoRA[LoRA]
    Route --> Cost[Cost opt]

Start with architecture and evaluation, then optimize routing, adapters, and cost.

Interview Questions

Why is DeepSeek-V3 called a 671B model if about 37B parameters are active?

The total counts all experts and shared parameters stored in the model. A sparse router selects only a subset of experts for each token, so forward-pass compute is closer to the active count while memory and distribution requirements reflect much more of the total.

What is the operational difference between R1 and an R1 distill?

R1 is the full reasoning model. Distills are smaller Qwen- or Llama-based models trained to imitate outputs or reasoning behavior. They are easier to serve but are separate models with different capacity, failure modes, licenses inherited from components, and evaluation results.

Why can benchmark parity fail in an agent?

Static benchmarks score final answers in controlled prompts. Agents must choose tools, emit valid arguments, recover from errors, preserve state, obey permissions, and stop correctly. Reliability compounds across steps, so a small per-step gap becomes a large workflow gap.

How should an enterprise evaluate China-hosting risk?

Map data classes and jurisdictions, inspect provider terms and retention, identify subprocessors and government-access obligations, review sector restrictions, and test a self-hosted or alternate-provider path. This is a legal and security decision, not a benchmark decision.

What does API compatibility guarantee?

Mostly request and response shape. It does not guarantee identical tool semantics, streaming events, reasoning fields, safety policy, tokenizer, rate limits, retries, or output quality.

FAQs

What is DeepSeek-R1?

A reasoning model trained with reinforcement learning to generate chain-of-thought before answering. Competitive with OpenAI o1 on math and coding benchmarks. Available via API and as open weights.

How does DeepSeek-V3 compare to the frontier closed models?

V3 is competitive on many benchmarks at a large (approximate — verify) API cost advantage. Frontier closed APIs (OpenAI's and Anthropic's current flagship models) lead on some instruction following, tool use, and multimodal tasks. Benchmark on your specific workloads.

Is DeepSeek really that much cheaper?

DeepSeek API pricing has historically been much lower than frontier closed providers - roughly $0.27/$1.10 per million input/output tokens for V3 (approximate). Compare against current frontier-tier pricing on each provider's page, since both DeepSeek and closed-API rates change frequently.

Can I self-host DeepSeek models?

Distilled R1 models (1.5B–70B) run on consumer to server GPUs. Full V3/R1 (671B) requires datacenter-class infrastructure (16+ H100 GPUs). Most teams use the API or distilled models.

What are distilled R1 models?

Smaller models (based on Qwen or Llama) trained on outputs from the full R1 model. They inherit reasoning capabilities at sizes runnable on local hardware. Quality scales with size.

Should I use V3 or R1?

V3 for general tasks - chat, summarization, extraction, coding. R1 for math, proofs, complex debugging, and logic puzzles. R1 is slower and more expensive than V3.

Is DeepSeek safe for enterprise use?

Evaluate carefully. Consider data handling policies, geopolitical factors, API stability, and regulatory requirements. US government agencies have restricted DeepSeek on official devices. Consult your compliance team.

How do I handle reasoning output?

Use the selected endpoint's documented response fields and thinking controls. Return only the intended answer field, apply normal data-retention policy to reasoning metadata, and never depend on regex removal of presumed tags.

Does DeepSeek support function calling?

V3 has basic tool use support, but reliability trails frontier closed APIs (OpenAI's and Anthropic's current flagship models) for agent workflows. Test thoroughly before deploying agent architectures on DeepSeek.

How does DeepSeek-R1 compare to frontier reasoning tiers?

R1 is competitive on math and code benchmarks at significantly lower cost. Frontier closed reasoning tiers may lead on the hardest problems and have better ecosystem integration. R1 is the cost-effective alternative for most reasoning tasks (verify current pricing and capability before committing).

What license do DeepSeek models use?

DeepSeek publishes its own license for model weights. It permits commercial use with conditions. Read the specific license for each model on Hugging Face.

Can I use DeepSeek with LangChain?

Yes. Use the OpenAI-compatible endpoint - set base_url to https://api.deepseek.com and use your DeepSeek API key.

What happens when DeepSeek API is down?

Congestion and outages have occurred during peak demand. Implement circuit breakers, fallback to GPT/Claude, and cache deterministic responses.

References

• DeepSeek-V4-Pro GA Release
• DeepSeek-V4-Flash-Vision-Exp Release
• DeepSeek Models and Pricing
• DeepSeek API Change Log
• DeepSeek-V3 Technical Report and Weights
• DeepSeek-R1 Technical Report and Weights
• Hugging Face Transformers Documentation
• LangChain Documentation
• OpenAI API Documentation

Further Reading

• Anthropic Documentation
• Google AI for Developers
• LlamaIndex Documentation
• Pinecone Learning Center

Summary

• DeepSeek disrupted pricing for reasoning models - R1 at a fraction of o-series cost. - Route V3 for general tasks, R1 for math/code/logic - never use R1 for everything. - Distilled models (7B–70B) bring reasoning to local hardware. - Full V3/R1 self-hosting requires datacenter GPUs - use API or distilled models instead. - Agent and tool use trails frontier closed models - test before deploying agents.

• Evaluate geopolitical and compliance risks for enterprise deployments. - Always implement API fallbacks - availability is not guaranteed at OpenAI/Anthropic levels.