Model and Modality Playbooks2026年9月16日Flatkey Team

DeepSeek V4 迁移清单：安全替换已弃用别名

使用这份 DeepSeek V4 迁移清单，替换已退役的 Flash 别名、测试 thinking mode、验证 Flatkey 路由，并安全回滚。

DeepSeek V4 迁移不再是一个泛泛的“升级到 V4”任务。截至 2026 年 9 月 16 日，迁移风险已经很具体：DeepSeek 表示，旧名称 deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 仍可出于兼容性被接受，但这些已退役的模型名称由 DeepSeek-V4.1-Flash 提供服务，并按 Flash 价格计费。DeepSeek 还表示，deepseek-v4-pro 的 API 服务在 2026 年 9 月 14 日之后仍会继续，计费方式保持不变，除非 DeepSeek 另行通知。

这意味着，安全的做法不是追逐每一个历史别名。安全的做法是将新工作标准化为 deepseek-flash，记录 deepseek-v4-pro 仍被有意使用的地方，并验证你的产品实际调用的是哪条路由。如果你通过 Flatkey 路由，同样适用这一原则：让 OpenAI 兼容客户端指向 https://router.flatkey.ai/v1，从实时目录中选择当前的 DeepSeek 行，执行一次冒烟测试，并在生产流量切换前确认使用日志。

本DeepSeek V4 迁移清单：安全替换已弃用别名指南为独立开发者和小型 AI 产品团队提供一个实用的上线流程：审计已弃用别名、更新模型 ID、测试思考模式、验证 Responses API 和工具调用行为、检查计费单位，并保持回滚简单。

快速回答：应该改什么？

使用 deepseek-flash 作为当前 Flash 模型名称。将 deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 视为兼容性别名，应从新代码、路由策略、文档和评测表中移除。仅在你有理由直接测试和监控 Pro 路由时，才保留 deepseek-v4-pro。

在你的技术栈中发现的字符串	当前官方语境	建议操作	需要测试的迁移风险
`deepseek-v4-flash`	旧名称；请求为兼容性由 DeepSeek-V4.1-Flash 提供服务。	在进行路由冒烟测试后替换为 `deepseek-flash`。	路由器、仪表盘、允许列表或过时文档中的 model-not-found 错误。
`deepseek-v4-flash-vision-exp`	旧名称；请求为兼容性由 DeepSeek-V4.1-Flash 提供服务。	替换为 `deepseek-flash`，然后显式测试图像输入路径。	视觉负载处理、工具输出图像以及解析器预期。
`deepseek-flash`	DeepSeek 文档中的当前 Flash 模型名称。	在完成实时路由验证后，作为 Flash 工作负载的默认目标使用。	思考默认值、计费窗口、输出长度、流式传输和工具调用。
`deepseek-v4-pro`	DeepSeek 表示，API 服务在 2026 年 9 月 14 日之后继续，且除非另有通知，计费方式保持不变。	仅在工作负载有意使用 Pro 且监控为最新时保留。	提供商生命周期变更、更高的成本配置、路由策略漂移以及回退行为。

实用的 DeepSeek V4 迁移 规则很简单：别名应出现在审计报告中，而不是新的生产配置里。

为什么这次迁移不同于六月清单

本文最初版本聚焦于 deepseek-chat 和 deepseek-reasoner 在 2026 年 7 月退役的情况。对于当前页面来说，这已不再是最安全的表述。DeepSeek 当前官方文档强调的是 V4.1 Flash 版本、deepseek-flash 模型名称、已退役的 Flash 和 Flash Vision 别名，以及 deepseek-v4-pro 的持续 API 服务说明。

对于小团队来说，这会改变迁移计划。你不需要匆忙重写每一处与 DeepSeek 相关的提及。你需要的是带有日期证据的受控别名清理：

代码、环境变量、评测任务和文档中仍然存在哪些模型字符串？
哪些字符串是兼容性别名，哪些字符串是当前模型 ID？
哪些路由是直接 DeepSeek 路由，哪些路由是通过 Flatkey 或其他网关？
哪些工作负载依赖视觉、思考、Responses API、工具调用、结构化输出、长上下文或流式传输？
哪些仪表板可以证明新的模型 ID 确实在处理流量？

这就是别名替换与可靠的 DeepSeek V4 迁移 之间的区别。

在编辑代码前需要锁定的源事实

在更改模型字符串之前，请保存一条简短的迁移说明，包含来源日期和你检查过的确切页面。对于这次更新，源事实如下：

需要验证的事实	当前来源说明	如何使用
当前 Flash 名称	DeepSeek 文档说明应使用 `deepseek-flash` 作为模型名称。	将 `deepseek-flash` 设为 Flash 路由的目标模型字符串。
旧版 Flash 别名	`deepseek-v4-flash` 和 `deepseek-v4-flash-vision-exp` 仍被接受，但其对应模型已退役，并由 V4.1 Flash 提供服务。	在新代码中替换这些别名，并计划清理现有配置。
Pro 生命周期	DeepSeek 表示 `deepseek-v4-pro` 的 API 服务在 2026 年 9 月 14 日之后仍会继续，计费方式不变，待进一步通知。	不要声称 Pro 已关闭；应将其作为一个有意保留的路由进行监控。
直接 DeepSeek 基础 URL	DeepSeek 文档为 OpenAI 格式调用提供 `https://api.deepseek.com`，为 Anthropic 格式调用提供 `https://api.deepseek.com/anthropic`。	将基础 URL 的更改与模型名称的更改分开处理。
Flatkey 基础 URL	Flatkey 文档显示 OpenAI SDK 指向 `https://router.flatkey.ai/v1`。	在测试 Flatkey 路由时，使用一个可配置的基础 URL 和一个模型字段。

不要在没有时间戳的情况下把定价数字粘贴到应用文档中。DeepSeek 当前的定价页面按每 100 万 token 列出价格，区分缓存命中输入、缓存未命中输入和输出 token，并注明峰时/非峰时窗口。这已经足以说明，应在上线时检查实时定价，而不是依赖迁移脚本中的静态估算。

DeepSeek 直连与 Flatkey 路由对比

DeepSeek V4 迁移可以直接进行、通过 Flatkey 路由，或者在测试期间两者同时进行。

Path	Use It When	What Must Be Verified
Direct DeepSeek API	你希望直接访问服务商，并直接控制 DeepSeek 账户。	Base URL、API key、`deepseek-flash`、`deepseek-v4-pro`、thinking mode、Responses API、image input、tool calls、pricing units，以及 429 处理。
Flatkey gateway route	你希望使用一个 key、一个兼容 OpenAI 的 base URL、一个模型目录，并在不同服务商之间共享用量审查。	当前的 Flatkey model row、route health、endpoint family、request logs、token 和 cost 字段、fallback policy、quota，以及 rollback model。
Dual-route validation	在将生产流量迁移或更改面向客户的工作流之前，你需要获得信心。	相同的 prompt set、相同的 parser、相同的 streaming mode、相同的 tool-call test、相同的 accepted-output metric，以及带日期标注的 source checklist。

当运维问题比单一路径的 DeepSeek 调用更复杂时，Flatkey 很有用：例如分散的 provider keys、重复的 SDK 修改、请求级成本不清晰，以及难以审计的 fallback 决策。但 gateway 并不能消除验证 model ID 的必要性。务必测试你的账户将要调用的确切 model row。

DeepSeek V4 迁移清单

在生产环境中替换别名之前，请使用此清单。

冻结源日期。 记录你检查 DeepSeek 文档、Flatkey 文档、Flatkey 模型目录、定价和路由状态的日期。对于本文的更新，这个日期是 2026 年 9 月 16 日。
搜索整个技术栈。 查找 deepseek-v4-flash、deepseek-v4-flash-vision-exp、deepseek-flash、deepseek-v4-pro，以及那些告诉开发者复制过期值的旧文档。
对每个匹配项分类。 区分生产代码、预发布配置、评估任务、提示路由器策略、客户文档、支持宏、笔记本、CI 固件和示例。
替换已弃用的 Flash 别名。 只有在你已经有测试路由和回滚计划之后，才将 deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 迁移到 deepseek-flash。
保持 Pro 显式。 不要悄悄把 deepseek-v4-pro 工作负载迁移到 Flash。如果仍在使用 Pro，请标注负责人、原因、检查日期和备用模型。
使思考模式显式化。 DeepSeek 文档说明思考模式默认启用，默认 effort 为 high。如果你需要非思考行为，请有意配置并测试。
如果你使用过 vision 别名，请测试图像输入。 对于曾使用 deepseek-v4-flash-vision-exp 的工作负载，请通过你实际要上线的路由运行图像输入测试。
单独测试 Responses API。 DeepSeek 的 Responses API 兼容性包含受支持、部分支持、忽略和不支持的字段。不要只根据 Chat Completions 推断行为。
运行工具调用和结构化输出测试。 验证工具 schema、函数参数、JSON 解析、重试以及多轮行为。
检查流式输出和使用情况。 在直接的提供商日志或 Flatkey Usage Logs 中确认分块形状、超时处理、最终用量、token 计数和计费字段。
更新文档和示例。 删除会在下一次入门或修复 bug 时重新引入已弃用别名的过期片段。
通过配置逐步发布。 将目标模型放入环境变量或路由表中。避免在业务逻辑内硬编码字面量。
观察首个生产流量切片。 从低风险流量开始，比较可接受输出率和每个可接受响应的成本，然后只在日志干净后再逐步扩容。

可复制的别名审计模板

将此模板用作简短的迁移记录。把它保存在你的代码仓库、问题跟踪器或运行手册中，这样未来的修复就能知道别名为何发生变更。

deepseek_v4_migration:
  checked_at_utc: "2026-09-16T00:00:00Z"
  source_pages:
    - "https://api-docs.deepseek.com/"
    - "https://api-docs.deepseek.com/quick_start/pricing"
    - "https://api-docs.deepseek.com/news/news260910"
    - "https://api-docs.deepseek.com/guides/thinking_mode"
    - "https://api-docs.deepseek.com/guides/responses_api"
    - "https://docs.flatkey.ai/quickstart.md"
    - "https://docs.flatkey.ai/guides/openai-sdk.md"
  replacements:
    - from: "deepseek-v4-flash"
      to: "deepseek-flash"
      reason: "旧版 Flash 别名；由 V4.1 Flash 提供路由以保持兼容性"
      owner: "engineering"
      status: "test_before_merge"
    - from: "deepseek-v4-flash-vision-exp"
      to: "deepseek-flash"
      reason: "旧版视觉实验别名；请验证图像输入行为"
      owner: "engineering"
      status: "test_before_merge"
  intentionally_kept:
    - model: "deepseek-v4-pro"
      reason: "Pro 路由仍然有意保留评估"
      next_review_date: "2026-09-30"
  required_tests:
    - plain_chat
    - thinking_enabled
    - thinking_disabled_if_used
    - responses_api
    - image_input_if_used
    - tool_calls
    - json_output
    - streaming
    - usage_log_readback
    - rollback

Flatkey 配置模式

最安全的 Flatkey 设置是将供应商特定的模型选择保留在配置中，同时保持 OpenAI 兼容客户端接口稳定。

FLATKEY_API_KEY="sk-your-flatkey-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_DEEPSEEK_MODEL="deepseek-flash"

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ.get("FLATKEY_DEEPSEEK_MODEL", "deepseek-flash"),
    messages=[
        {
            "role": "user",
            "content": "返回一句话，确认 DeepSeek 路由在线。",
        }
    ],
    stream=False,
)

print(response.choices[0].message.content)
print(response.usage)

请求完成后，打开 Flatkey Usage Logs 并验证模型名称、token 数、延迟、成本、密钥、时间戳和错误状态。如果日志与您发送的请求不一致，则迁移尚未完成。

切换前的测试矩阵

测试	重要性	通过信号
普通聊天	确认认证、基础 URL、模型 ID 以及基础解析器兼容性。	请求返回预期内容，并在日志中记录目标模型。
思考模式	DeepSeek 的思考行为可能改变输出形态和 token 使用量。	你的应用会有意处理或禁用推理输出。
Responses API	某些参数仅部分支持、被忽略或不受支持。	你的客户端不会依赖被忽略的字段来保证正确性。
视觉输入	旧的视觉别名意味着需要真实测试的图像输入用例。	图像输入通过你将要上线的实际路由进行处理。
工具调用	当工具参数、ID 或多轮消息发生偏移时，智能体就会失败。	工具调用生成和工具结果续接都能通过。
结构化输出	普通答案也可能破坏 JSON 校验器。	校验器通过率保持在你的上线阈值以内。
流式传输	流式错误通常只会在第一个分块之后才出现。	分块、最终消息、超时处理以及用量统计都能通过。
成本和配额	缓存命中、缓存未命中、输出、峰值/非峰值、重试和回退行为都会影响实际成本。	财务和工程团队都能解释每个已接受响应的成本。
回滚	别名迁移应当可逆，且无需匆忙部署。	可以通过配置将流量切回已知路由。

常见错误

在不查看当前 DeepSeek 文档的情况下，把 DeepSeek V4 迁移 当作纯文本替换。
用 deepseek-flash 替换 deepseek-v4-flash-vision-exp，却从不测试图像输入。
在当前文档明确表示服务继续的情况下，仍假设 deepseek-v4-pro 已在 2026 年 9 月 14 日后停用。
更新了应用代码，却把过时别名留在评测任务、笔记本、客户示例或回退策略中。
只比较表面 token 单价，而不是按每个已接受响应的成本来比较。
在没有检查真实路由和日志的情况下，假设直接 DeepSeek 行为与 Flatkey 路由行为完全一致。
让不受支持的 Responses API 参数悄悄改变产品行为。

下一步的内部链接

如果你仍在选择 DeepSeek 路由，请将这份清单与 DeepSeek V4 Pro vs Flash 和 DeepSeek vs Qwen API routing checks 搭配阅读。如果更大的项目是网关标准化，请阅读 Flatkey API quickstart、AI model catalog guide，以及 AI routing API metrics。对于对区域敏感的提供商决策，请使用 regional LLM provider routing。

FAQ

当前的 DeepSeek Flash 模型名称是什么？

DeepSeek 文档中当前的 Flash 模型名称是 deepseek-flash。安全的 DeepSeek V4 迁移应在路由测试之后，将已弃用的 Flash 别名切换到该模型字符串。

`deepseek-v4-flash` 和 `deepseek-v4-flash-vision-exp` 是否已失效？

DeepSeek 说这些旧名称仍然可接受，但其对应模型已退役，请求由 DeepSeek-V4.1-Flash 提供服务。该兼容性在迁移期间很有用，但新代码应避免依赖已退役的别名。

`deepseek-v4-pro` 是否在 2026 年 9 月 14 日后停止工作了？

没有。当前 DeepSeek 文档说明 deepseek-v4-pro 的 API 服务在 2026 年 9 月 14 日后仍会继续，除非 DeepSeek 提供进一步通知，否则计费方式保持不变。如果你使用它，请保持显式配置并持续监控。

我需要更改 DeepSeek 基础 URL 吗？

对于直接的 OpenAI 格式 DeepSeek 调用，不需要。DeepSeek 将 https://api.deepseek.com 文档化为 OpenAI 格式的基础 URL。对于 Flatkey，请使用带有 Flatkey API key 的 https://router.flatkey.ai/v1。

Flatkey 会替代按提供商的路由测试吗？

不会。Flatkey 可以集中管理密钥、基础 URL、目录和使用情况审查，但你的团队仍然需要验证确切的模型行、功能行为、成本字段、路由健康状况以及回退方案。

是否应将所有工作负载都迁移到 `deepseek-flash`？

不应。deepseek-flash 是当前的 Flash 目标，但那些有意使用 deepseek-v4-pro 的工作负载应单独测试和跟踪。应按工作负载选择，而不是按全局替换规则。

最终上线建议

DeepSeek V4 迁移清单：安全替换已弃用别名 的结尾应该以证据为准，而不只是一个已合并的 diff。替换已退役的 Flash 别名，保持 Pro 路由的明确意图，测试你的产品实际使用的功能，并在日志中验证请求。然后在你将生产流量迁移之前，检查当前的 Flatkey model directory 和 Flatkey pricing 页面。