DeepSeek V4.1 Flash API 教程：构建可视化修复缺陷的智能体

什么是 DeepSeek V4.1 Flash？

DeepSeek 通过模型 ID deepseek-flash 在 API 中提供 V4.1 Flash。它支持图像输入，具备思维与非思维两种模式，拥有 100 万 token 的上下文窗口，并可通过 Chat Completions 与 Responses API 返回最多 384K tokens。

我们的 DeepSeek V4.1 Flash 概览 涵盖了发布情况、架构与基准成绩。 

DeepSeek V4.1 Flash 如何工作？

DeepSeek 将 V4.1 Flash 描述为一款 552B 参数的 MoE 主干，而 Hugging Face 对已发布检查点报告为 763B 参数。差异主要来自 196B 参数的 Engram 条件记忆，再加上视觉编码器与投影器，这些组件打包在检查点中，但位于 MoE 主干之外。

其 Causal Encoder-Decoder 设计会复用缓存的编码器状态，输入处理阶段每个 token 激活 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 的定价基于高峰时段，非高峰价格为高峰的一半。当我运行智能体时，按 DeepSeek 的定价页面，缓存输入在非高峰每百万 tokens $0.003、高峰 $0.006；非缓存输入非高峰 $0.15、高峰 $0.30；输出非高峰 $0.60、高峰 $1.20。

高峰时段为周一至周五 UTC 01:00–04:00 和 06:00–10:00，法定节假日除外。其余均为非高峰，中国法定节假日全天非高峰。

我们要构建什么：Launch Metrics 可视化修复智能体

Nimbus Analytics Launch Metrics 是一个 Flask 仪表盘，展示总访客数、注册量、转化率、营收与每日注册量。我在三个文件中安置了三个缺陷，且未告知智能体具体内容。代码与损坏的仪表盘见此 GitHub 仓库。

损坏的仪表盘与参考设计并列。图片来源：作者。

三个缺陷需要不同的证据：一个体现在截图中，一个影响浏览器行为，另一个会导致 pytest 失败。智能体不会收到缺陷清单。

在交给智能体前，我先定义“修好”的标准：pytest 测试需通过，且最新截图需在视觉上匹配参考图。仅凭模型的主观看法不够，因此运行器会同时检查这两类证据。

修复循环的工作方式

循环在模型请求与本地工具执行之间交替。V4.1 Flash 会返回推理、消息或工具调用；Python 运行所需工具并将结果加入历史。若模型在响应时不再发出工具调用，或到达 14 轮上限，循环即停止。

连接模型、工具与浏览器的修复循环。图片来源：作者。

如何设置 DeepSeek V4.1 Flash API

您需要 Python 3.10 或更高版本，以及有余额的 DeepSeek API 密钥。DeepSeek 的 API 遵循 OpenAI 的请求格式，因此本项目使用 openai Python 包，并将 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，可跳过下一段代码；否则，该请求会校验密钥与 base 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)

若打印出简短问候语，说明密钥与 base URL 可用。

步骤 1：先告诉模型“修好”是什么样

智能体的首次输入包含一张参考截图、一段简短任务说明和在线地址。这是唯一一张以用户消息发送的图片。之后的每张截图都来自工具。

运行器在每次请求中都以 base64 数据 URL 形式发送参考图。DeepSeek 建议在重复使用图片时采用 Files API。使用 file_id 可避免每次重复传图像数据。

在允许修改前先获得初步反应

在附带的图片中，我先询问模型会优先检查什么，但未提供任何工具。这样我可以在其动手修改前检视它的计划。回复建议先列出项目文件、追踪 CSS 变量并截图；我使用了 reasoning: {"effort": "high"}，这是 DeepSeek 的默认思维强度。

步骤 2：为智能体提供可用工具

智能体获得四个 函数工具 和一个自定义工具。 

• list_files 与 read_file 用于检查项目，且都限制在 dashboard/ 与 tests/ 目录内。

• run_tests 运行 pytest。

• capture_dashboard_screenshot 通过 Playwright 启动无头 Chromium。

自定义工具为 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 或服务端会话。思维模式还要求包含先前工具轮次的每一条推理。

重要提示：如果将工具输出插在同一轮的两个调用之间，下一次请求会返回 400 错误。请依次追加 response.output 中的每个条目，然后再运行工具并追加其结果。

运行器将智能体限制在 14 轮以内，且仅可访问 dashboard/ 与 tests/ 目录。它不提供 shell 访问、会校验工具参数，并用 pytest 做验证。

DeepSeek V4.1 Flash 是否支持结构化输出？

支持。通过 Responses API，DeepSeek V4.1 Flash 可在 text.format 中接受 JSON Schema。Chat Completions 的 response_format 支持 JSON 模式但不支持 schema。循环停止后，最终请求会记录缺陷、修复、测试结果、截图结果与验证方式。

项目还包含一个 Streamlit 应用 app_streamlit.py。相同的智能体以生成器形式运行，设置 stream=True 后，页面会边到边显示推理文本与工具调用。侧边栏可调整推理强度与图像细节。

Streamlit 界面实时展示智能体运行。视频来源：作者。

步骤 4：运行可视化修复缺陷的智能体

从补丁层面看似乎已完成，但在线页面并不认同。

定位并修复缺陷

智能体在前两轮先“看”不“动”：第一轮列出文件并拍基线截图，第二轮读取 app.py、index.html、style.css 与测试文件。

第三轮运行 pytest，第四轮应用一个补丁，修正了转化率公式、调整了指标颜色，并将 JavaScript 的查找与 canvas ID 对齐。

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

第五轮跑测试显示 5 项全部通过。此处开始就不再“整洁”了。每次新截图仍显示 15% 转化率与空白图表。

发现系统陈旧并加以修复

智能体确认磁盘上的文件已包含修复内容，重试截图，并探查服务器是否加载了变更后的 Python 与模板文件。两个临时新鲜度检查同样未在在线页面上体现。

到第十四轮，循环用尽预算并找到了原因：run_tests 检查的是磁盘上的代码，而截图检查的是一个状态陈旧的运行中进程。Flask 启动时 设置了 debug=False，因此没有重载器去加载已变更的 Python 模块，模板也未启用自动重载。

CSS 变化生效了，但由 Python 计算的值与模板驱动的图表仍然陈旧。Pytest 从磁盘导入 app.py ，因此测试变绿并不保证页面是最新的。

我重启 Flask 后，仪表盘与参考图一致。缺失的其实是一个 restart_server 工具，而非另一个代码补丁。

重启后，补丁产生的更改在仪表盘上可见。图片来源：作者。

智能体是否修好了仪表盘？

是的，智能体修好了磁盘上的仪表盘。它只改动了那三个有问题的文件，pytest 从 4 个失败变为 5 个通过。Flask 重启后，在线页面展示了所有修复。

步骤 5：衡量用量、缓存与成本

由于智能体会重发历史记录，后续请求会重复前几轮的大量输入。DeepSeek 会将这一重复前缀与其自动缓存比对。缓存按尽力而为运作，因此这些数字仅适用于本次运行。

在 14 轮修复与最后一次 JSON 报告请求中，API 报告的输入 tokens 为 156,724，其中 137,088 个来自缓存，命中率 87%。输出为 11,497 个 tokens，其中 9,362 个为推理 tokens。运行发生在非高峰时段，因此 15 次请求总成本约 $0.0103。

推理输出是最大的成本类别。图片来源：作者。

更大的代码库、更多截图或更低的缓存命中率都会改变 token 数与成本。

DeepSeek V4.1 Flash API 的限制

在将该运行器扩展到演示之外前，有三点 API 限制需要了解。

• 不支持后台响应，长轮次会阻塞直至完成。

• parallel_tool_calls 与 max_tool_calls 会被忽略；并行工具调用保持启用。

• 不支持自动截断，超过上下文上限的请求会返回 400 错误。

DeepSeek V4.1 Flash 智能体部署清单

在将此模式用于线上服务前，请将控制逻辑放在应用代码中，而非模型指令中。

• 强制执行轮次与成本上限，并在达到时告警
• 限制文件访问并校验每个工具参数
• 提供用于重启与检查服务的工具，确保验证基于当前代码
• 记录 token 用量、工具调用、测试结果与最终状态

何时使用 apply_patch，何时使用普通函数工具？

当一次变更需要同时修改多个文件时，请使用 apply_patch，本例正是如此。补丁后立即运行测试，因为一次不当调用可能损坏多个文件。

当每次编辑都需要单独检查或审批时，请使用 read_file 与 write_file 。它们会多花几轮，但一次错误编辑只会影响一个文件。

结语

可视化修复循环通过一次补丁修好了三个缺陷，但这次运行并非完全顺利。pytest 通过时，Flask 仍在提供旧的 Python 与模板输出，因此在我重启服务器前，智能体无法确认最终页面。

在测试更大的应用前，我会加入一个 restart_server 工具与像素级对比。我会保留文件边界与轮次上限，并将 pytest 与截图对比视作两项独立检查。其一通过绝不能替代另一项的通过。