JSON Output în API-ul DeepSeek: response_format json_object în DeepSeek (V4 & R1)

response_format={"type": "json_object"}

JSON Output face ca modelul să întoarcă un șir JSON valid, ușor de parsat. Se activează cu response_format={"type": "json_object"}; singurele valori acceptate pentru type sunt text (implicit) și json_object. Funcția este disponibilă la deepseek-flash și la deepseek-v4-pro.

Documentația cere trei lucruri: cuvântul „json” în mesajul de sistem sau în cel al utilizatorului, un exemplu de format dorit și un max_tokens suficient. Fără instrucțiunea explicită, modelul poate genera spații albe până la limita de tokeni, iar cererea pare blocată. Dacă finish_reason este length, JSON-ul poate fi tăiat.

JSON Output garantează sintaxa, nu o schemă anume: response_format nu are tipul json_schema. Pentru câmpuri și tipuri impuse, documentația oferă modul strict (Beta) al apelurilor de unelte, în care serverul validează schema JSON. Documentația avertizează și că API-ul poate întoarce ocazional conținut gol în modul JSON; reformularea promptului poate ajuta.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
response_format.type	text (implicit) sau json_object.
cuvântul json în prompt	Necesar: fără el, modelul poate produce spații albe până la max_tokens.
exemplu de format	Un obiect JSON model în mesajul de sistem ajută modelul să păstreze cheile.
max_tokens	Destul de mare ca obiectul să nu fie tăiat.
finish_reason	stop la final normal, length la tăiere (limită de tokeni sau de context).
tools[].function.strict	Alternativa pentru o schemă impusă (Beta, cu base_url terminat în /beta).

Exemple practice și scenarii reale

Exemplul 1: Extragere întrebare / răspuns în JSON

După exemplul oficial, cu textele traduse.

import json, os
from openai import OpenAI

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

system_prompt = """
Utilizatorul trimite o întrebare de examen urmată de răspuns.
Extrage "question" și "answer" și răspunde în format JSON.

EXEMPLU DE INTRARE:
Care este cel mai înalt munte din lume? Everest.

EXEMPLU DE IEȘIRE JSON:
{"question": "Care este cel mai înalt munte din lume?", "answer": "Everest"}
"""

r = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "Care este cel mai lung râu din lume? Nilul."},
    ],
    response_format={"type": "json_object"},
    max_tokens=1000,
)
date = json.loads(r.choices[0].message.content)

Exemplul 2: Parsare defensivă

choice = r.choices[0]
if choice.finish_reason == "length":
    raise RuntimeError("JSON tăiat: mărește max_tokens")
continut = choice.message.content or ""
if not continut.strip():
    raise RuntimeError("Răspuns gol: reformulează promptul și reîncearcă")
date = json.loads(continut)

Greșeli frecvente și capcane

• Activezi json_object fără să ceri JSON în prompt. Cererea poate rula până la limita de tokeni, cu spații albe.
• Copiezi response_format={"type": "json_schema", ...} din alt API. DeepSeek acceptă doar text și json_object; pentru schemă folosește tool calls în modul strict.
• Tratezi JSON-ul valid ca date corecte. Verifică cheile și tipurile (de exemplu cu Pydantic) înainte să le folosești.

Noțiuni și module înrudite

• deepseek-tool-calls
• deepseek-api-integration
• deepseek-fim-prefix-completion