Учебник по DeepSeek V4.1 Flash API: создаём визуального агента для исправления багов

Создайте визуального агента на Python с DeepSeek V4.1 Flash, Responses API, скриншотами Playwright, apply_patch, pytest, кэшированием контекста и учётом стоимости.

Обновлено 22 сент. 2026 г.

Изучить с помощью AI

ChatGPT Claude Perplexity

Когда дашборд выходит с багом, цикл отладки всегда один и тот же. Вы смотрите на экран, находите нужный файл, правите его, снова запускаете тесты, перезагружаете страницу и проверяете ещё раз. Это утомительно, и половина улик живёт в скриншотах, а не в трассировках стека.

Этот эксперимент начался сразу после релиза DeepSeek V4.1 Flash. Это самая компактная модель нового семейства архитектур с поддержкой ввода изображений. Хотелось понять, сможет ли она исследовать сломанное веб‑приложение, внести правки в код и понять, когда работа завершена.

Здесь мы сосредоточимся на одном проекте: небольшом Flask‑дашборде Nimbus Analytics Launch Metrics с тремя багами, которые агент должен найти и исправить через реализацию DeepSeek формата Responses API. Записанный прогон также показывает пробел в инструментах агента.

Мы разберём, как:

Сделать первый вызов DeepSeek V4.1 Flash через Responses API
Передать модели эталонный скриншот, а затем подставлять свежие скриншоты Playwright как вывод инструмента
Дать агенту инструменты для перечисления и чтения файлов, запуска pytest и правки кода сразу в нескольких файлах одним вызовом через apply_patch
Хранить и пересылать историю диалога, поскольку API не хранит состояние
Вернуть структурированный JSON‑отчёт об исправлениях
Посчитать стоимость с учётом кэшированных входных, рассуждений и выходных токенов

Итоги вкратце

Responses API у DeepSeek V4.1 Flash не хранит состояние, поэтому Python‑код хранит переписку и пересылает её на каждом шаге. В том же цикле используются: зрение — для эталонного изображения и скриншотов инструментов, режим рассуждения — для инспекции нескольких файлов, и apply_patch — для правок. Четыре наблюдения из прогона повлияли на то, как стоило бы строить следующую версию.

Один патч исправил все три бага сразу: один вызов apply_patch по очереди затронул CSS, JavaScript и Python‑файлы, уложившись в лимит из четырнадцати шагов.
Кэширование контекста покрыло большую часть входных токенов: 137 088 из 156 724 входных токенов были кэшированы, 87% попаданий.
Верный диагноз не гарантировал полной проверки: агент корректно выявил «залежавшийся» процесс Flask, но у него не было инструмента для перезапуска, поэтому он не смог сам подтвердить визуальное совпадение.
Измеренная стоимость API составила около $0,0103: четырнадцать шагов в цикле исправлений плюс финальный запрос на JSON‑отчёт.

Эти цифры — один прогон на одном небольшом дашборде, а не бенчмарк. Количество шагов, попадания кэша и стоимость изменятся для более крупного приложения или иного набора багов.

Что такое DeepSeek V4.1 Flash?

DeepSeek предоставляет V4.1 Flash через API под идентификатором модели deepseek-flash. Модель принимает изображения, поддерживает режимы с рассуждением и без, имеет контекстное окно на 1 млн токенов и может возвращать до 384 тыс. токенов через Chat Completions и Responses API.

Наша обзорная статья о DeepSeek V4.1 Flash охватывает запуск, архитектуру и бенчмарки.

Как работает DeepSeek V4.1 Flash?

DeepSeek описывает V4.1 Flash как MoE‑бэкбон на 552B параметров, тогда как Hugging Face сообщает 763B параметров для опубликованного чекпойнта. Разница в основном приходится на условную память Engram на 196B параметров, плюс vision‑энкодер и «проектор» — все это входит в чекпойнт, но находится вне MoE‑бэкбона.

Дизайн Causal Encoder‑Decoder переиспользует кэшированные состояния энкодера: 8B активных параметров на токен при обработке входа и 16B — при генерации выхода.

Что нового в DeepSeek V4.1 Flash?

V4.1 Flash — первая модель в новом семействе V4.1 с нативно встроенным зрением. Визуальные и текстовые эмбеддинги обучаются совместно с самого начала пре‑тренировки, а не добавляются потом, как в экспериментальной V4‑Flash‑Vision‑Exp.

Responses API появился до V4.1 Flash; DeepSeek добавил родную поддержку во время более раннего релиза V4. Устаревшие имена моделей deepseek-v4-flash и deepseek-v4-flash-vision-exp теперь перенаправляются на V4.1 Flash.

Сколько стоит DeepSeek V4.1 Flash?

Цены DeepSeek зависят от пиковых часов, а внепиковые тарифы — 50% от пиковых. Когда проводился прогон агента, кэшированный вход стоил $0,003 за миллион токенов вне пика и $0,006 в пике, некэшированный вход — $0,15 вне пика и $0,30 в пике, а выход — $0,60 вне пика и $1,20 в пике, согласно странице с ценами DeepSeek.

Пиковые часы — с 01:00 до 04:00 и с 06:00 до 10:00 UTC, с понедельника по пятницу, за исключением государственных праздников Китая. Все остальные часы — вне пика, а в китайские гос.праздники весь день считается внепиковым.

Что будем строить: агент визуального ремонта Launch Metrics

Nimbus Analytics Launch Metrics — это Flask‑дашборд по общим посетителям, регистрациям, конверсии, выручке и ежедневным регистрациям. Я разместил три бага в трёх файлах и не сообщил агенту, какие именно. Код и сломанный дашборд — в этом репозитории на GitHub.

Сломанный дашборд рядом с эталоном. Изображение автора.

Три бага требуют разной доказательной базы. Один виден на скриншоте, один влияет на поведение браузера, а один валит pytest. Агент не получает список багов.

Перед тем как отдать это агенту, я определил критерии «исправлено»: набор pytest должен проходить, а свежий скриншот — визуально совпадать с эталоном. Мнения модели недостаточно, поэтому раннер проверяет оба вида улик.

Как работает цикл исправления

Цикл чередует запрос к модели и выполнение локальных инструментов. V4.1 Flash возвращает рассуждения, сообщение или вызовы инструментов; Python запускает запрошенные инструменты и добавляет результаты в историю. Цикл останавливается, когда модель отвечает без следующего вызова инструмента или достигает лимита в четырнадцать шагов.

Цикл ремонта, соединяющий модель, инструменты и браузер. Изображение автора.

Как настроить DeepSeek V4.1 Flash API

Понадобится Python 3.10 или новее и API‑ключ DeepSeek с балансом. API DeepSeek следует формату запросов OpenAI, поэтому в проекте используется пакет openai с base_url на DeepSeek.

Создайте виртуальное окружение и установите зависимости проекта.

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

Тестировалось с openai 3.14.1, flask 3.1.3 и playwright 1.63.0. Сохраните ключ в файле .env в корне проекта как DEEPSEEK_API_KEY=sk-... и загрузите его через python-dotenv. Если ваш ключ уже работает с Responses API, пропустите следующий блок кода; иначе запрос проверит ключ и базовый 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)

Если вы увидите короткое приветствие, ключ и базовый URL настроены верно.

Шаг 1: Покажите модели, как выглядит «исправлено»

Первый ввод для агента содержит эталонный скриншот, краткую задачу и живой URL. Это единственное изображение, отправляемое в сообщении пользователя. Все последующие скриншоты приходят как результат инструмента.

Раннер отправляет эталонное изображение как base64 data URL в каждом запросе. DeepSeek рекомендует Files API, если изображение переиспользуется. file_id избавляет от повторной передачи одних и тех же данных.

Получение первой реакции до разрешения на изменения

В приложенном изображении я спросил, что модель станет проверять сначала, но инструменты были отключены. Так можно было изучить план, прежде чем она сможет что‑то править. В ответе предлагалось перечислить файлы проекта, проследить CSS‑переменные и сделать скриншот; использовалась настройка reasoning: {"effort": "high"} — уровень рассуждения по умолчанию у DeepSeek.

Шаг 2: Дайте агенту полезные инструменты

Агент получает четыре функциональных инструмента и один кастомный инструмент.

list_files и read_file исследуют проект, оба ограничены директориями dashboard/ и tests/.
run_tests запускает pytest.
capture_dashboard_screenshot запускает безголовый Chromium через Playwright.

Кастомный инструмент — apply_patch, объявлен как {"type": "custom", "name": "apply_patch"} и поддерживается «для совместимости с Codex». Любое другое имя кастомного инструмента вернёт ошибку 400, тогда как встроенные типы, вроде веб‑поиска и управления компьютером, просто игнорируются.

Аргументы функций приходят как JSON‑текст и проверяются до выполнения в Python. apply_patch приходит как ввод кастомного инструмента, поэтому код обрабатывает его отдельно и валидирует патч перед записью файлов. Ошибки инструментов возвращаются модели, не останавливая цикл.

Возврат скриншотов Playwright как вывода инструмента

Когда capture_dashboard_screenshot отрабатывает, результат не сохраняется на диск. Python возвращает его как часть input_image внутри function_call_output. Тогда DeepSeek читает скриншот как изображение, а не как текстовое описание.

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

Агент может поправить CSS, сделать новый скриншот и проверить, читаются ли цифры.

Шаг 3: Постройте цикл агента и сами управляйте историей

История хранится в списке Python, так как API не поддерживает previous_response_id или серверные диалоги. Режим рассуждения также требует все элементы reasoning из предыдущих шагов с инструментами.

Важно: если вывод инструмента вставлен между двумя вызовами из одного и того же шага, следующий запрос вернёт ошибку 400. Добавляйте каждый элемент из response.output по порядку, затем запускайте инструменты и добавляйте их результаты.

Раннер ограничивает агента четырнадцатью шагами и директориями dashboard/ и tests/. Доступ к shell не предоставляется, аргументы инструментов проверяются, а для верификации используется pytest.

Поддерживает ли DeepSeek V4.1 Flash структурированный вывод?

Да, через Responses API DeepSeek V4.1 Flash принимает JSON Schema через text.format. В Chat Completions response_format поддерживает режим JSON, но не схемы. После остановки цикла финальный запрос фиксирует баги, исправления, результаты тестов, результаты скриншотов и метод проверки.

В проект также входит приложение на Streamlit в app_streamlit.py. Тот же агент запускается как генератор с stream=True, поэтому страница показывает текст рассуждений и вызовы инструментов по мере поступления. В сайдбаре можно менять усилие рассуждения и детализацию изображения.

Интерфейс Streamlit показывает ход работы агента в потоке. Видео автора.

Шаг 4: Запустите агента для визуального исправления багов

Казалось, всё завершилось после одного патча, но живая страница была не согласна.

Поиск и исправление багов

Агент потратил первые два шага на осмотр до правок: на первом — перечислил файлы и сделал базовый скриншот, на втором прочитал app.py, index.html, style.css и файл тестов.

На третьем шаге запустил pytest, затем на четвёртом применил один патч: исправил формулу конверсии, изменил цвет метрики и сопоставил поиск элемента в JavaScript с ID канваса.

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

Запуск тестов на пятом шаге показал, что все пять проходят. На этом аккуратность прогона закончилась. Каждый новый скриншот всё ещё показывал конверсию 15% и пустой график.

Обнаружение «залежалого» состояния системы и исправление

Агент подтвердил, что файлы на диске содержат правки, повторил скриншот и проверил, грузит ли сервер изменённые Python‑ и шаблонные файлы. Две временные проверки свежести также не отобразились на живой странице.

К четырнадцатому шагу цикл достиг лимита и определил причину: run_tests проверяет код на диске, а скриншот — работающий процесс с устаревшим состоянием. Flask запущен с debug=False, поэтому перезагрузчик не подхватил изменённый модуль Python, а автообновление шаблонов не было включено.

Изменение CSS проявилось, тогда как значение из Python и график на шаблоне оставались старыми. Pytest импортировал app.py с диска, поэтому зелёные тесты не гарантировали свежесть страницы.

После перезапуска Flask дашборд совпал с эталонным изображением. Не хватало инструмента restart_server, а не ещё одного патча в код.

Перезапуск делает видимыми изменения в исправленном дашборде. Изображение автора.

Исправил ли агент дашборд?

Да, агент исправил дашборд на диске. Он изменил только три проблемных файла, и pytest прошёл с четырёх падений до пяти успешных тестов. После перезапуска Flask все исправления появились и на живой странице.

Шаг 5: Измерьте использование, кэш и стоимость

Поскольку агент пересылает свою историю, последующие запросы повторяют значительную часть ввода из предыдущих шагов. DeepSeek сравнивает этот повторяющийся префикс со своим автоматическим кэшем. Кэш работает по принципу best‑effort, поэтому эти цифры относятся только к данному прогону.

За четырнадцать шагов ремонта и финальный запрос на JSON‑отчёт API сообщил о 156 724 входных токенах, включая 137 088 кэшированных (87% попаданий). Выход составил 11 497 токенов, из них 9 362 — токены рассуждений. Прогон пришёлся на внепиковые часы, поэтому все пятнадцать запросов стоили примерно $0,0103.

Вывод рассуждений — крупнейшая статья расходов. Изображение автора.

Более крупная кодовая база, больше скриншотов или меньше попаданий кэша изменят как число токенов, так и стоимость.

Ограничения DeepSeek V4.1 Flash API, о которых стоит знать

Три ограничения API имеют значение, прежде чем расширять этот раннер за рамки демо.

Фоновые ответы не поддерживаются, поэтому длинные шаги блокируют до завершения.
parallel_tool_calls и max_tool_calls игнорируются; параллельные вызовы инструментов остаются включёнными.
Автоматическая усечка не поддерживается, поэтому запросы сверх лимита контекста возвращают ошибку 400.

Чек-лист развертывания агента на DeepSeek V4.1 Flash

Перед использованием этого паттерна в продакшене перенесите контроли в код приложения, а не в инструкции модели.

Ограничивайте количество шагов и стоимость, оповещайте при достижении лимитов
Ограничьте доступ к файлам и проверяйте каждый аргумент инструмента
добавьте инструменты для перезапуска и проверки сервиса, чтобы верификация шла по текущему коду
Логируйте использование токенов, вызовы инструментов, результаты тестов и финальный статус

Когда использовать apply_patch, а когда — обычные функции?

Используйте apply_patch, когда одно изменение должно затронуть несколько файлов — как в этом примере. После патча запускайте тесты, потому что один неудачный вызов может повредить сразу несколько файлов.

Используйте read_file и write_file когда каждую правку нужно проверять или утверждать отдельно. Это требует больше шагов, но неудачное изменение повлияет лишь на один файл.

Заключение

Цикл визуального ремонта исправил все три бага одним патчем, но прогон нельзя назвать безупречным. Pytest прошёл, тогда как Flask продолжал отдавать старые Python‑данные и шаблоны, поэтому агент не смог подтвердить финальную страницу, пока я не перезапустил сервер.

Перед тестированием более крупного приложения стоило бы добавить инструмент restart_server и пиксельное сравнение. Я бы сохранил границы по файлам и лимит шагов, а pytest и сравнение скриншотов рассматривал как отдельные проверки. Прохождение одной не должно подменять другую.