Modul thinking în API-ul DeepSeek: thinking și reasoning_effort în DeepSeek (V4 & R1): explicație și exemple

Ambele modele din API (deepseek-flash și deepseek-v4-pro) sunt hibride: același model răspunde în mod thinking sau non-thinking. Modul thinking este activ implicit, cu effort high. În formatul OpenAI, comutatorul este {"thinking": {"type": "enabled"}} sau "disabled"; cu SDK-ul OpenAI pentru Python se trimite prin extra_body. Nivelul se dă cu reasoning_effort: low, high sau max, iar none oprește modul thinking. DeepSeek recomandă low pentru sarcini simple, high pentru sarcinile zilnice de agent și max pentru cele complexe.

Pentru compatibilitate, API-ul acceptă și alte niveluri și le mapează: minimal devine low, medium și xhigh devin high, ultra devine max. În formatul Anthropic, comutatorul este tot thinking (budget_tokens este ignorat), iar nivelul se dă în output_config.effort. În Responses API, reasoning.effort primește none, low, high sau max.

Raționamentul vine în reasoning_content, la același nivel cu content. Dacă cererea nu are tools, raționamentul turelor anterioare nu intră în context, chiar dacă îl trimiți înapoi. Dacă cererea are tools, trebuie să trimiți înapoi reasoning_content din toate turele anterioare, inclusiv din cele fără apel de unealtă; altfel API-ul întoarce eroarea 400 (vezi tool calls). În thinking, temperature, presence_penalty și frequency_penalty nu au efect și nu produc eroare.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
`thinking.type`	`enabled` (implicit) sau `disabled`, în formatele OpenAI și Anthropic.
`reasoning_effort`	`none`, `low`, `high` (implicit), `max`, în Chat Completions.
`output_config.effort`	`low`, `high`, `max`, în formatul Anthropic.
`reasoning.effort`	`none`, `low`, `high`, `max`, în Responses API; `none` oprește thinking.
`message.reasoning_content`	Lanțul de raționament; în streaming vine în `delta.reasoning_content`.
`usage.completion_tokens_details.reasoning_tokens`	Tokenii generați pentru raționament.
`max_tokens`	Implicit 64K în thinking și 128K cu `max`; maximum 384K.
`top_p`	`deepseek-flash`: are efect doar în thinking, între 0,95 și 1,0 (valorile mai mici devin 0,95). `deepseek-v4-pro`: ignorat în thinking (0,95 cu `tools`, altfel 1,0), aplicat în non-thinking.
`tool_choice`	În thinking, `required` sau o unealtă anume dau eroarea 400; rămân `none` și `auto`.

Exemple practice și scenarii reale

Exemplul 1: Raționamentul și răspunsul, separat

După exemplul oficial. În tura a doua, fără tools, raționamentul anterior nu intră în context.

import os
from openai import OpenAI

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

messages = [{"role": "user", "content": "Care număr e mai mare: 9.11 sau 9.8?"}]
r = client.chat.completions.create(
    model="deepseek-flash",
    messages=messages,
    reasoning_effort="high",
    extra_body={"thinking": {"type": "enabled"}},
)
print(r.choices[0].message.reasoning_content)   # raționamentul
print(r.choices[0].message.content)             # răspunsul final

messages.append({"role": "assistant", "content": r.choices[0].message.content})
messages.append({"role": "user", "content": "Câte litere r are cuvântul strawberry?"})

Exemplul 2: Streaming cu raționament

stream = client.chat.completions.create(
    model="deepseek-flash",
    messages=messages,
    stream=True,
    extra_body={"thinking": {"type": "enabled"}},
)
gandire, raspuns = "", ""
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.reasoning_content:
        gandire += delta.reasoning_content
    elif delta.content:
        raspuns += delta.content

Exemplul 3: Non-thinking pentru o sarcină simplă

temperature are efect doar în non-thinking. Ghidul de parametri recomandă 1.3 pentru traduceri (valoarea implicită este 1.0).

r = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Tradu în engleză: Bună dimineața!"}],
    temperature=1.3,
    reasoning_effort="none",          # echivalent cu thinking disabled
)

Exemplul 4: Effort maxim cu curl

curl https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  -d '{
        "model": "deepseek-v4-pro",
        "messages": [{"role": "user", "content": "Demonstrează că radical din 2 este irațional."}],
        "thinking": {"type": "enabled"},
        "reasoning_effort": "max"
      }'

Greșeli frecvente și capcane

Setezi temperature în thinking și te aștepți la alt comportament. Parametrul este ignorat fără eroare; la fel presence_penalty și frequency_penalty, care sunt depreciate și în non-thinking.
În bucla cu unelte pierzi reasoning_content din istoric. API-ul răspunde cu 400; adaugă în messages obiectul response.choices[0].message întreg.
Folosești tool_choice="required" cu thinking activ. Primești 400; dezactivează thinking pentru o unealtă forțată.
Pui max peste tot. Crește consumul de tokeni și max_tokens implicit (128K); alege nivelul după complexitatea sarcinii.

`Modul thinking în API-ul DeepSeek: thinking și reasoning_effort` în DeepSeek (V4 & R1)