Tutorial API DeepSeek V4.1 Flash: construiește un agent vizual de reparare a bug-urilor

Ce este DeepSeek V4.1 Flash?

DeepSeek oferă V4.1 Flash prin API sub ID-ul modelului deepseek-flash. Acceptă input de tip imagine, suportă moduri cu gândire și fără gândire, are o fereastră de context de 1M tokeni și poate returna până la 384K tokeni prin Chat Completions și Responses API.

Review-ul nostru pentru DeepSeek V4.1 Flash acoperă lansarea, arhitectura și benchmark-urile. 

Cum funcționează DeepSeek V4.1 Flash?

DeepSeek descrie V4.1 Flash ca un backbone MoE cu 552B de parametri, în timp ce Hugging Face raportează 763B de parametri pentru checkpoint-ul publicat. Diferența vine în mare parte din memoria condițională Engram de 196B parametri, plus encoderul și proiectorul vizual, componente care sunt incluse în checkpoint dar stau în afara backbone-ului MoE.

Designul Causal Encoder-Decoder reutilizează stări de encoder cache-uite, cu 8B parametri activi per token în timpul procesării inputului și 16B în timpul outputului.

Ce e nou în DeepSeek V4.1 Flash?

V4.1 Flash este primul model din noua familie de arhitecturi V4.1, cu înțelegerea imaginilor integrată nativ. Înglobările vizuale și de text sunt antrenate împreună încă de la începutul pre-antrenării, nu adăugate ulterior ca în experimentul V4-Flash-Vision-Exp.

Responses API precede V4.1 Flash; DeepSeek a adăugat suport nativ în timpul lansării anterioare a V4. Denumirile de model retrase deepseek-v4-flash și deepseek-v4-flash-vision-exp sunt acum redirecționate către V4.1 Flash.

Cât costă DeepSeek V4.1 Flash?

Prețurile DeepSeek se bazează pe ore de vârf, cu tarifele din afara orelor de vârf setate la 50% din cele de vârf. Când am rulat agentul, inputul cache-uit costa 0,003 $ pe milion de tokeni în afara orelor de vârf și 0,006 $ în orele de vârf, inputul necached costa 0,15 $ în afara orelor de vârf și 0,30 $ în orele de vârf, iar outputul costa 0,60 $ în afara orelor de vârf și 1,20 $ în orele de vârf, conform paginii de prețuri DeepSeek. 

Orele de vârf sunt 01:00–04:00 și 06:00–10:00 UTC, de luni până vineri, excluzând sărbătorile legale din China. Toate celelalte ore sunt în afara orelor de vârf, iar sărbătorile legale din China sunt integral în afara orelor de vârf.

Ce vom construi: Agentul vizual de reparare Launch Metrics

Nimbus Analytics Launch Metrics este un dashboard Flask pentru vizitatori total, înscrieri, rată de conversie, venit și înscrieri zilnice. Am plasat trei bug-uri în trei fișiere și nu i-am spus agentului care sunt. Codul și dashboardul defect sunt în acest repository GitHub.

Dashboardul defect lângă designul de referință. Imagine de autor.

Cele trei bug-uri cer dovezi diferite. Unul apare în captura de ecran, unul afectează comportamentul browserului, iar unul eșuează la pytest. Agentul nu primește nicio listă de bug-uri.

Înainte de a încredința asta agentului, definesc ce înseamnă „reparat”: suita pytest trebuie să treacă, iar o captură proaspătă trebuie să se potrivească vizual cu o imagine de referință. Doar opinia modelului nu este suficientă, așa că runnerul verifică ambele forme de dovezi.

Cum funcționează bucla de reparare

Bucla alternează între o cerere la model și execuția locală a uneltelor. V4.1 Flash returnează raționament, un mesaj sau apeluri de unelte; Python rulează uneltele cerute și adaugă rezultatele în istoric. Bucla se oprește când modelul răspunde fără un nou apel de unealtă sau ajunge la limita de paisprezece pași.

Buclă de reparare care leagă modelul, uneltele și browserul. Imagine de autor.

Cum să configurezi DeepSeek V4.1 Flash API

Ai nevoie de Python 3.10 sau mai nou și de o cheie DeepSeek API cu credit. API-ul DeepSeek urmează formatul de cerere OpenAI, așa că acest proiect folosește pachetul openai pentru Python cu base_url setat către DeepSeek.

Creează un mediu virtual și instalează ce are nevoie proiectul.

python3 -m venv .venv
source .venv/bin/activate
pip install openai flask playwright pytest python-dotenv requests streamlit
playwright install chromium

Am testat asta cu openai 3.14.1, flask 3.1.3 și playwright 1.63.0. Salvează cheia în fișierul .env de la rădăcina proiectului ca DEEPSEEK_API_KEY=sk-... și încarc-o cu python-dotenv. Dacă cheia ta deja funcționează cu Responses API, sari peste următorul bloc de cod; altfel, cererea verifică cheia și baza URL.

from openai import OpenAI
import os
from dotenv import load_dotenv

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

response = client.responses.create(model="deepseek-flash", input="Say hi in five words.")
print(response.output_text)

Dacă afișează un salut scurt, cheia și baza URL funcționează.

Pasul 1: Arată modelului cum arată „reparat”

Primul input al agentului conține o captură de ecran de referință, o sarcină scurtă și URL-ul live. Aceasta este singura imagine trimisă într-un mesaj de utilizator. Toate capturile ulterioare vin dintr-o unealtă.

Runnerul trimite imaginea de referință ca un URL de date base64 la fiecare cerere. DeepSeek recomandă Files API când o imagine este reutilizată. Un file_id evită trimiterea repetată a aceleiași imagini.

Obținerea unei reacții inițiale înainte de a permite orice schimbări

În imaginea atașată, am întrebat ce ar verifica modelul mai întâi, dar nu existau unelte. Asta mi-a permis să-i văd planul înainte să poată edita ceva. Răspunsul a propus listarea fișierelor proiectului, urmărirea variabilelor CSS și realizarea unei capturi; am folosit reasoning: {"effort": "high"}, nivelul implicit de gândire al DeepSeek.

Pasul 2: Oferă agentului unelte pe care le poate folosi

Agentul primește patru unelte de funcție și o unealtă personalizată. 

• list_files și read_file inspectează proiectul, ambele restricționate la dashboard/ și tests/. 

• run_tests rulează pytest.

• capture_dashboard_screenshot pornește Chromium headless prin Playwright.

Unealta personalizată este apply_patch, declarată ca {"type": "custom", "name": "apply_patch"} și acceptată „pentru compatibilitate cu Codex.” Orice alt nume de unealtă personalizată returnează o eroare 400, în timp ce tipuri integrate precum căutare web și utilizare computer sunt ignorate în tăcere.

Argumentele funcțiilor ajung ca text JSON și sunt verificate înainte ca Python să le ruleze. apply_patch ajunge ca input de unealtă personalizată, așa că codul îl tratează separat și verifică patch-ul înainte de a scrie fișiere. Erorile uneltelor sunt returnate modelului în loc să oprească bucla.

Trimiterea capturilor Playwright înapoi ca output de unealtă

Când capture_dashboard_screenshot rulează, rezultatul nu este salvat pe disc. Python îl returnează ca o parte input_image în interiorul function_call_output. DeepSeek citește apoi captura ca imagine, nu ca descriere text.

history.append({
    "type": "function_call_output",
    "call_id": item.call_id,
    "output": [{"type": "input_image", "image_url": f"data:image/png;base64,{png_b64}"}],
})

Agentul poate modifica CSS-ul, face o altă captură și verifica dacă numerele sunt lizibile.

Pasul 3: Construiește bucla agentului și gestionează singur istoricul

Istoricul trăiește într-o listă Python pentru că API-ul nu suportă previous_response_id sau conversații pe server. Modul de gândire cere, de asemenea, fiecare element de raționament din pașii anteriori ai uneltelor.

Important: Dacă outputul uneltei este inserat între două apeluri din același pas, următoarea cerere returnează o eroare 400. Adaugă fiecare element din response.output în ordine, apoi rulează uneltele și adaugă rezultatele lor.

Runnerul limitează agentul la paisprezece pași și la directoarele dashboard/ și tests/ . Nu oferă acces la shell, verifică argumentele uneltelor și folosește pytest pentru verificare.

Acceptă DeepSeek V4.1 Flash output structurat?

Da, prin Responses API, DeepSeek V4.1 Flash acceptă un JSON Schema prin text.format. Chat Completions response_format suportă modul JSON dar nu scheme. După ce bucla se oprește, cererea finală înregistrează bug-urile, remedierile, rezultatele testelor, rezultatele capturilor și metoda de verificare.

Proiectul include și o aplicație Streamlit în app_streamlit.py. Același agent rulează ca generator cu stream=True, astfel încât pagina afișează textul de raționament și apelurile de unelte pe măsură ce sosesc. Bara laterală schimbă efortul de raționament și nivelul de detaliu al imaginii.

Interfața Streamlit redă în flux rularea agentului. Video de autor.

Pasul 4: Rulează agentul vizual de reparare a bug-urilor

Rularea părea încheiată după un patch, dar pagina live nu a fost de acord.

Găsirea și repararea bug-urilor

Agentul și-a folosit primii doi pași ca să observe înainte să atingă ceva: pasul unu a listat fișierele și a făcut o captură de referință, pasul doi a citit app.py, index.html, style.css și fișierul de teste. 

Pasul trei a rulat pytest, apoi pasul patru a aplicat un patch care a corectat formula conversiei, a schimbat culoarea metricii și a potrivit căutarea JavaScript cu ID-ul canvasului.

-    conversion_rate = data["conversions"] / data["signups"] * 100
+    conversion_rate = data["conversions"] / data["total_visitors"] * 100

Rularea testelor la pasul cinci a arătat că toate cele cinci trec. Aici rularea a încetat să mai fie curată. Fiecare nouă captură afișa în continuare o rată de conversie de 15% și un grafic gol.

Descoperirea stării învechite a sistemului și remedierea

Agentul a confirmat că fișierele de pe disc conțineau corecțiile, a reluat captura și a verificat dacă serverul încărca fișierele Python și template-urile modificate. Două verificări temporare de prospețime nu au apărut nici ele în pagina live.

Până la pasul paisprezece, bucla își consumase bugetul și identificase cauza: run_tests verifică codul de pe disc, în timp ce captura verifică un proces care rulează, cu stare învechită. Flask a pornit cu debug=False, astfel încât niciun reloader nu a încărcat modulul Python schimbat, iar reîncărcarea automată a template-urilor nu a fost activată.

Schimbarea de CSS a apărut, în timp ce valoarea derivată din Python și graficul bazat pe template au rămas învechite. Pytest a importat app.py de pe disc, așa că testele verzi nu au garantat o pagină proaspătă.

După ce am repornit Flask, dashboardul s-a potrivit cu imaginea de referință. Piesa lipsă a fost o unealtă restart_server, nu încă un patch de cod.

Repornirea face vizibile schimbările patch-uite în dashboard. Imagine de autor.

A reparat agentul dashboardul?

Da, agentul a reparat dashboardul pe disc. A schimbat doar cele trei fișiere defecte, iar pytest a trecut de la patru eșecuri la cinci teste trecute. Pagina live a afișat fiecare corecție după repornirea Flask.

Pasul 5: Măsoară utilizarea, cache-ul și costul

Pentru că agentul retrimite istoricul, cererile ulterioare repetă mult din inputul din pașii anteriori. DeepSeek verifică acest prefix repetat față de cache-ul automat. Cache-ul funcționează pe bază de efort optim, așa că aceste cifre se aplică doar acestei rulări.

Pe parcursul celor paisprezece pași de reparare și al cererii finale a raportului JSON, API-ul a raportat 156.724 tokeni de input, inclusiv 137.088 tokeni cache-uiți, o rată de 87%. Outputul a însumat 11.497 tokeni, inclusiv 9.362 tokeni de raționament. Rularea a avut loc în afara orelor de vârf, așa că toate cele cincisprezece cereri au costat aproximativ 0,0103 $.

Outputul de raționament este cea mai mare categorie de cost. Imagine de autor.

Un cod de bază mai mare, mai multe capturi sau mai puține hit-uri de cache ar schimba atât numărul de tokeni, cât și costul.

Limitări de știut pentru DeepSeek V4.1 Flash API

Trei limite ale API-ului contează înainte ca acest runner să crească dincolo de demo.

• Răspunsurile în fundal nu sunt suportate, așa că pașii lungi blochează până se finalizează.

• parallel_tool_calls și max_tool_calls sunt ignorate; apelarea paralelă a uneltelor rămâne activată.

• Trunchierea automată nu este suportată, așa că cererile care depășesc limita de context returnează o eroare 400.

Listă de verificare pentru implementarea agentului DeepSeek V4.1 Flash

Înainte de a folosi acest tipar într-un serviciu live, pune controalele în codul aplicației, nu în instrucțiunile modelului.

• Impune limite de pași și cost, și alertează când oricare este atinsă
• Restricționează accesul la fișiere și verifică fiecare argument de unealtă
• unelte pentru a reporni și verifica serviciul, astfel încât verificarea să folosească codul curent
• Înregistrează utilizarea de tokeni, apelurile uneltelor, rezultatele testelor și statusul final

Când ar trebui să folosești apply_patch vs unelte de funcție simple?

Folosește apply_patch când o singură schimbare trebuie să actualizeze mai multe fișiere, cum s-a întâmplat aici. Rulează testele după patch, deoarece un singur apel greșit poate strica mai multe fișiere.

Folosește read_file și write_file când fiecare editare are nevoie de o verificare sau aprobare separată. Iau mai mulți pași, dar o editare greșită afectează câte un singur fișier.

Gânduri finale

Bucla de reparare vizuală a fixat toate cele trei bug-uri într-un singur patch, dar rularea nu a fost un succes curat. Pytest a trecut în timp ce Flask încă servea outputul vechi din Python și template, astfel încât agentul nu a putut confirma pagina finală până când am repornit serverul.

Aș adăuga o unealtă restart_server și o comparație la nivel de pixeli înainte de a testa o aplicație mai mare. Aș păstra limita pe fișiere și pe pași, apoi aș trata pytest și comparația capturilor ca verificări separate. Trecerea uneia nu ar trebui niciodată să o înlocuiască pe cealaltă.