DeepSeek is a Chinese AI company known for MIT-licensed open weights and very low API prices. This guide covers using the 1M-token-context V4.1-Flash and V4-Pro through the OpenAI-compatible API, the rules for thinking mode and tool calls, cutting cost with automatic context caching, and running R1 distills locally โ in the order you would use them.
DeepSeek Practical Examples
Examples of a Think-tag parser, math problem solving, a code-debugging agent and a reasoning API.
View practical examples โDeepSeek showed with V3 and the R1 reasoning model that top-tier performance does not need top-tier cost. It now releases the V4 family as MIT-licensed open weights and offers the same models through a very cheap OpenAI-compatible API.
| When | What changed |
|---|---|
| Aug-Dec 2025 | V3.1, V3.2 โ deepseek-chat/deepseek-reasoner became the normal and thinking modes of one model; tool calls supported in thinking mode |
| April 2026 | V4 (Pro, Flash) announced with 1M-token context; retirement of the old model names announced |
| July-August 2026 | V4-Flash and V4-Pro generally available; deepseek-chat and deepseek-reasoner retired (July 24) |
| September 2026 | V4.1-Flash โ native image understanding; API name deepseek-flash |
To build an agent that puts long logs and runbooks into a 1M-token context, cuts cost with caching and analyzes incidents, see the DeepSeek incident log-analysis agent tutorial.
| Model | API name | Context / max output | Input | License | Best for |
|---|---|---|---|---|---|
| DeepSeek-V4.1-Flash | deepseek-flash | 1M / 384K | Text + image | MIT | The default โ fast and cheapest; JSON, tools and FIM |
| DeepSeek-V4-Pro | deepseek-v4-pro | 1M / 384K | Text | MIT | Hard reasoning, coding and agent work |
| DeepSeek-R1 distills | โ (local) | Varies | Text | MIT | Running a reasoning model on a PC (Ollama deepseek-r1) |
| DeepSeek-OCR | โ (local) | โ | Image | MIT | Document images โ text (Ollama deepseek-ocr, 3B) |
The V4 family are MoE (mixture-of-experts) models with hundreds of billions to over a trillion parameters, computing only some experts per token. That keeps API prices low, but serving them yourself needs GPU server nodes.
deepseek-chat and deepseek-reasoner were retired on July 24, 2026. Now there is one model (deepseek-flash) and you turn thinking mode on or off per request.
| Old code | New code |
|---|---|
model="deepseek-chat" | model="deepseek-flash" + extra_body={"thinking": {"type": "disabled"}} |
model="deepseek-reasoner" | model="deepseek-flash" + extra_body={"thinking": {"type": "enabled"}} |
| When you need stronger reasoning | model="deepseek-v4-pro" + reasoning_effort="high" |
Thinking mode is on by default. If you expected the fast responses of the old deepseek-chat, always set "disabled"; otherwise responses get slower and output token costs rise.
| Model (per 1M tokens, peak) | Input โ cache hit | Input โ cache miss | Output |
|---|---|---|---|
deepseek-flash | $0.006 | $0.30 | $1.20 |
deepseek-v4-pro | $0.044 | $1.32 | $3.96 |
Off-peak hours cost half of the above. Peak hours are weekdays 01:00-04:00 and 06:00-10:00 UTC. Prices are from the official pricing page as of October 2026 and may change.
Context caching applies to every request automatically. When the beginning of a request exactly matches an earlier one, that part is billed at the cache-hit price (about 1/50 of a miss), so keep system prompts and long documents at the front and append only the changing question.
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")
runbook = open("runbook.md", encoding="utf-8").read() # long document โ keep it unchanged at the front of every request
for question in ["What is the disk alert procedure?", "What is the DB failover order?"]:
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "Answer only from the following runbook.\n\n" + runbook},
{"role": "user", "content": question},
],
extra_body={"thinking": {"type": "disabled"}},
)
u = resp.usage
# From the second request on, the runbook part hits the cache
print(question, "| cache hit", getattr(u, "prompt_cache_hit_tokens", 0), "/ miss", getattr(u, "prompt_cache_miss_tokens", 0))The DeepSeek API is OpenAI-compatible, so use the OpenAI Python SDK with a different base_url. Get a key from the DeepSeek Platform.
uv add openai
export DEEPSEEK_API_KEY="your_key"import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[
{"role": "system", "content": "You are an SRE who answers concisely."},
{"role": "user", "content": "Explain the difference between 502 and 504 errors"},
],
extra_body={"thinking": {"type": "disabled"}}, # fast normal response
stream=True,
)
for chunk in resp:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
print()With thinking on, the model generates its reasoning before answering, returned separately in a reasoning_content field at the same level as content. Choose the depth with reasoning_effort: low, high or max (default high).
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "How should I tune autovacuum for PostgreSQL taking 3,000 writes per second?"}],
reasoning_effort="high",
extra_body={"thinking": {"type": "enabled"}},
)
msg = resp.choices[0].message
reasoning = getattr(msg, "reasoning_content", None) # a DeepSeek extension field, not part of the OpenAI SDK
print("[reasoning]", (reasoning or "")[:300], "...")
print("[answer]", msg.content)
print("output tokens:", resp.usage.completion_tokens)Thinking mode ignores temperature, presence_penalty and frequency_penalty. In conversations without tools, you do not need to send earlier turnsโ reasoning_content back (it is ignored if you do).
Tools work in thinking mode too. But in conversations that use tools, you must send back the reasoning_content of every previous turn, including turns without a tool call. Storing the whole response message with model_dump() keeps that field.
import json
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")
def get_error_rate(service: str, minutes: int = 15) -> dict:
"""Recent error rate for a service (query Prometheus in a real implementation)"""
return {"service": service, "minutes": minutes, "error_rate": 0.083, "p95_ms": 1840}
TOOLS = {"get_error_rate": get_error_rate}
TOOL_SCHEMAS = [{"type": "function", "function": {
"name": "get_error_rate",
"description": "Get a service's recent error rate and p95 latency",
"parameters": {"type": "object", "properties": {
"service": {"type": "string"}, "minutes": {"type": "integer"}}, "required": ["service"]},
}}]
messages = [{"role": "user", "content": "Is the checkout service healthy right now?"}]
for _ in range(5):
resp = client.chat.completions.create(
model="deepseek-flash", messages=messages, tools=TOOL_SCHEMAS,
extra_body={"thinking": {"type": "enabled"}},
)
msg = resp.choices[0].message
messages.append(msg.model_dump(exclude_none=True)) # keeps reasoning_content as well
if not msg.tool_calls:
print(msg.content)
break
for tc in msg.tool_calls:
result = TOOLS[tc.function.name](**json.loads(tc.function.arguments))
messages.append({"role": "tool", "tool_call_id": tc.id, "content": json.dumps(result)})If you store only some fields, as in messages.append({"role": "assistant", "content": msg.content}), reasoning_content and tool_calls are lost and the next request fails or the reasoning breaks.
Use response_format={"type": "json_object"}, and always include the word "json" and an example of the format in the prompt.
import json
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")
SYSTEM = """Extract details from an incident report and answer only in json.
Example format: {"service": "checkout", "symptom": "rising 5xx", "started_at": "2026-10-04 09:12", "suspected_cause": "deploy"}"""
resp = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "system", "content": SYSTEM},
{"role": "user", "content": "500 errors on checkout started rising right after the 09:12 deploy"}],
response_format={"type": "json_object"},
max_tokens=500, # enough that the JSON is not cut off
extra_body={"thinking": {"type": "disabled"}},
)
content = resp.choices[0].message.content
data = json.loads(content) if content else {} # empty responses happen occasionally โ retry
print(data)V4 is too large for a personal PC, so locally use deepseek-r1, which distills R1โs reasoning into smaller Qwen- and Llama-family models. It helps when sensitive logs cannot leave your machine.
ollama pull deepseek-r1:8b # 8 GB GPU class
ollama pull deepseek-r1:14b # 16 GB GPU class
ollama pull deepseek-r1:32b # 24 GB GPU classfrom ollama import chat
resp = chat(
model="deepseek-r1:8b",
messages=[{"role": "user", "content": "Guess the cause of this stack trace: NullPointerException at OrderService.java:118"}],
think=True,
)
print("[thinking]", (resp.message.thinking or "")[:300], "...")
print("[answer]", resp.message.content)Distills have less knowledge and weaker reasoning than V4. A practical setup is first-pass analysis with the local model, sending only summaries that are allowed to leave to the large API model.
Companies that cannot send data to an external API can serve the MIT-licensed weights themselves. V4.1-Flash lists vLLM and SGLang as recommended engines, and the official model card recommends a single node of 4ร GB300 for V4-Pro.
vllm serve deepseek-ai/DeepSeek-V4.1-Flash # add tensor/expert parallel options for your GPU setupSelf-hosting costs a lot in GPUs and operations staff. With API prices this low for the same model, start with the API and check your usage first, unless data policy forbids it.
| Symptom | Cause | Fix |
|---|---|---|
| Model Not Exist / 400 error | Using the retired deepseek-chat or deepseek-reasoner | deepseek-flash + set thinking |
| Slower and more expensive than before | Thinking mode is on by default | Use {"type": "disabled"} for simple requests |
| Tool conversations fail midway | Earlier turnsโ reasoning_content is missing | Store the whole response message with model_dump() |
| Empty JSON response | A known intermittent issue, or too few max_tokens | Retry on empty content; give max_tokens room |
| Few cache hits | The start of each request changes (time, request ID, etc.) | Move changing values toward the end of the prompt |
| Changing temperature changes nothing | Thinking mode does not support temperature | Adjust with reasoning_effort |
deepseek-chat and deepseek-reasoner were retired on July 24, 2026. Replace deepseek-chat with deepseek-flash with thinking disabled, and deepseek-reasoner with deepseek-flash with thinking enabled. Set thinking with extra_body={"thinking": {"type": "enabled"}} or "disabled".
As of October 2026, deepseek-flash at peak hours costs $0.30 per million input tokens ($0.006 on a cache hit) and $1.20 per million output tokens, and off-peak hours are half price. Prices change often, so check the official pricing page before calculating real costs.
No. Disk-based context caching is on by default for every user, with no code changes. Keep the same system prompt and documents at the front and change only the question at the end, and that prefix hits the cache and cuts input cost sharply; check the hit volume in usage.prompt_cache_hit_tokens.
V4.1-Flash and V4-Pro weights are public under the MIT license, but they are MoE models with hundreds of billions to over a trillion parameters and need GPU server nodes. On a personal PC, the realistic option is deepseek-r1 (1.5B-70B) via Ollama, which distills R1โs reasoning into smaller models.
Thinking mode does not support temperature, presence_penalty or frequency_penalty. Sending them causes no error, but they have no effect. To adjust depth, choose reasoning_effort low, high or max.