Tool calls în API-ul DeepSeek: apeluri de funcții și modul strict în DeepSeek (V4 & R1)

tools=[{"type": "function", "function": {"name": "...", "parameters": {...}}}]
tool_choice="auto"    # none | auto | required | {"type": "function", "function": {"name": "..."}}

Uneltele se declară în tools, în formatul OpenAI; singurul tip acceptat este function. Numele funcției poate conține litere, cifre, _ și -, are cel mult 128 de caractere și trebuie să fie unic. Când modelul vrea o unealtă, răspunsul are tool_calls (cu id, function.name și function.arguments ca șir JSON) și finish_reason egal cu tool_calls. Modelul nu execută nimic: aplicația rulează funcția, adaugă un mesaj {"role": "tool", "tool_call_id": ..., "content": ...} și face o cerere nouă.

Din DeepSeek-V3.2, uneltele merg și în modul thinking: modelul poate alterna raționament și apeluri de unelte înainte de răspunsul final. În acest caz trebuie să trimiți înapoi reasoning_content din toate turele, altfel primești eroarea 400; cel mai simplu este să adaugi în messages obiectul response.choices[0].message întreg. În thinking, tool_choice poate fi doar none sau auto (vezi modul thinking).

Modul strict (Beta) face ca argumentele să respecte schema JSON a funcției. Cere base_url="https://api.deepseek.com/beta" și "strict": true la fiecare funcție; serverul validează schema și întoarce eroare dacă ea folosește tipuri neacceptate. Fiecare obiect trebuie să aibă toate proprietățile în required și "additionalProperties": false. Chat Completions nu permite inserarea în istoric a unor apeluri de unelte pe care modelul nu le-a generat; pentru asta, documentația recomandă formatul Anthropic sau Responses API (vezi formatele API).

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
tools	Lista de funcții: name, description, parameters (schemă JSON; lipsa ei înseamnă funcție fără parametri), opțional strict.
tool_choice	none (implicit fără unelte), auto (implicit cu unelte), required sau o funcție anume.
message.tool_calls	Apelurile cerute; arguments este un șir JSON care trebuie validat.
role: tool	Mesajul cu rezultatul; tool_call_id îl leagă de apel. Conținutul poate fi text sau, pentru deepseek-flash, și imagini.
strict (Beta)	Tipuri acceptate: object, string, number, integer, boolean, array, enum, anyOf, plus $ref / $def.
string în modul strict	Acceptă pattern și format (email, hostname, ipv4, ipv6, uuid); nu acceptă minLength / maxLength.
number / integer în modul strict	Acceptă const, default, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.
array în modul strict	Nu acceptă minItems / maxItems.

Exemple practice și scenarii reale

Exemplul 1: Un apel de unealtă în modul non-thinking

După exemplul oficial. Funcția vremea întoarce date de test; în aplicație ar apela un serviciu real.

import json, os
from openai import OpenAI

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

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Întoarce vremea pentru un oraș. Utilizatorul trebuie să dea orașul.",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Orașul, de exemplu Cluj-Napoca"}},
            "required": ["location"],
        },
    },
}]

def vremea(location):
    return "18°C, senin"   # date de test

def cere(messages):
    return client.chat.completions.create(
        model="deepseek-flash", messages=messages, tools=tools,
        extra_body={"thinking": {"type": "disabled"}},
    ).choices[0].message

messages = [{"role": "user", "content": "Cum e vremea în Cluj-Napoca?"}]
msg = cere(messages)
messages.append(msg)
for call in msg.tool_calls or []:
    args = json.loads(call.function.arguments)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": vremea(**args)})

print(cere(messages).content)

Exemplul 2: Bucla de unelte în modul thinking

Mesajul adăugat întreg păstrează reasoning_content și tool_calls, cum cere documentația.

UNELTE = {"get_weather": vremea}

def ruleaza_tura(messages):
    while True:
        r = client.chat.completions.create(
            model="deepseek-flash",
            messages=messages,
            tools=tools,
            reasoning_effort="high",
            extra_body={"thinking": {"type": "enabled"}},
        )
        msg = r.choices[0].message
        messages.append(msg)
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            rezultat = UNELTE[call.function.name](**json.loads(call.function.arguments))
            messages.append({"role": "tool", "tool_call_id": call.id, "content": rezultat})

Exemplul 3: Funcție în modul strict (Beta)

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

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "strict": True,
        "description": "Întoarce vremea pentru un oraș.",
        "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string", "description": "Orașul"}},
            "required": ["location"],
            "additionalProperties": False,
        },
    },
}]

Greșeli frecvente și capcane

• Execuți direct arguments. Referința API spune că modelul nu generează mereu JSON valid și poate inventa parametri; validează argumentele înainte de apel.
• În modul thinking construiești manual mesajul asistentului fără reasoning_content. Primești 400 la cererea următoare.
• Folosești modul strict fără /beta în base_url sau cu minLength, maxItems și alte cuvinte-cheie neacceptate. Serverul respinge schema.
• Inserezi în istoricul Chat Completions apeluri de unelte negenerate de model. Pentru acest scenariu folosește formatul Anthropic sau Responses API.

Noțiuni și module înrudite

• deepseek-thinking-mode
• deepseek-json-output
• deepseek-api-integration
• deepseek-context-caching