Model and Modality Playbooks2026年6月22日Big Y

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

使用这份 DeepSeek V4 迁移清单，替换 deepseek-chat 和 deepseek-reasoner，测试思考模式，验证 Flatkey 路由，并安全回滚。

DeepSeek V4 迁移现在不是单纯的模型升级，而是一项有截止日期的清理任务。DeepSeek 的官方 API 文档表示，旧的 deepseek-chat 和 deepseek-reasoner 别名将在 2026 年 7 月 24 日 15:59 UTC 之后被完全停用且无法访问。受支持的 V4 模型 ID 是 deepseek-v4-flash 和 deepseek-v4-pro。

好消息是，对许多团队来说，这应该只是一次受控的配置变更。DeepSeek 建议保持相同的直接 base_url，并更新模型名称。如果你通过 Flatkey 路由模型，也可以用同样的思路：让你的应用继续指向 https://router.flatkey.ai/v1，将别名替换为当前的 Flatkey DeepSeek V4 模型行，并在生产流量切换之前验证响应行为、思考模式、使用日志、定价和回滚。

这份 DeepSeek V4 迁移检查清单为你提供了具体步骤：映射旧别名，选择 deepseek-v4-flash 或 deepseek-v4-pro，测试思考和非思考行为，更新 SDK 配置，并避免在截止日期临近时进行未经审查的模型切换。

快速回答：DeepSeek V4 迁移会有哪些变化？

最紧急的变化是模型字符串。不要让生产代码、环境变量、提示路由器、评测任务或回退策略硬编码为 deepseek-chat 或 deepseek-reasoner。

旧别名	当前官方行为	要测试的迁移目标	需要验证的风险
`deepseek-chat`	当前路由到 `deepseek-v4-flash` 非思考模式	`deepseek-v4-flash`，关闭思考，除非你有意选择其他 V4 模式	输出风格、延迟、成本、解析器兼容性，以及任何被忽略的参数
`deepseek-reasoner`	当前路由到 `deepseek-v4-flash` 思考模式	`deepseek-v4-flash` 或 `deepseek-v4-pro`，并明确测试思考功能	`reasoning_content`、token 用量、多轮处理，以及 SDK 支持
DeepSeek Anthropic API 中的 Claude 风格模型名称	DeepSeek 将 Claude Opus 名称映射到 V4 Pro，将 Claude Haiku/Sonnet 名称映射到 V4 Flash	在你的路由层允许的情况下，优先使用明确的 DeepSeek V4 模型 ID	不受支持的 Anthropic 字段、图片/文档内容支持，以及工具调用行为

对于直接的 DeepSeek 调用，官方 OpenAI 格式的 base URL 仍然是 https://api.deepseek.com。对于 Flatkey，路由器 base URL 仍然是 https://router.flatkey.ai/v1。无论走哪条路径，DeepSeek V4 迁移都应被视为模型和行为变更来测试，而不仅仅是一次搜索替换。

为什么别名截止日期很重要

DeepSeek 的 V4 预览页面写明，API 现在可用，deepseek-v4-pro 和 deepseek-v4-flash 都支持 1M 上下文以及思考和非思考两种模式，而旧别名将在 2026 年 7 月 24 日 15:59 UTC 之后退役。这意味着，一个过时的别名在退役窗口之后会从“今天能用”变成“直接失败”。

首页快速开始表还将 deepseek-chat 和 deepseek-reasoner 列为将于 2026/07/24 弃用的别名。它说明，为了兼容性，这些别名分别对应 deepseek-v4-flash 的非思考和思考模式。

这个兼容性细节很有用，但这不是等待的理由。一次干净的 DeepSeek V4 迁移 能让你有时间对比输出、更新运行手册、培训支持团队，并确保在截止日期前生产监控面板已显示新的模型 ID。

直接 DeepSeek 与 Flatkey 路由对比

有两种常见的迁移路径。

决策	直接使用 DeepSeek API	通过 Flatkey 使用 DeepSeek
Base URL	`https://api.deepseek.com`	`https://router.flatkey.ai/v1`
API key	DeepSeek API key	Flatkey API key
Model selection	官方 DeepSeek model ID	当前 Flatkey DeepSeek model row
Primary benefit	Provider-direct setup	一个 key、一个 router、跨提供商共享的使用日志、配额和计费可见性
Production check	DeepSeek 响应、thinking mode、定价和错误	响应、路由状态、所选 model row、使用日志、定价单位、配额和回滚

Flatkey 的公开产品文案将平台定位为：一个 API key、一个兼容 OpenAI 的 base URL、清晰的定价、统一计费，以及一个用于管理 keys、usage 和 routing 的仪表板。对于已经通过同一网关承载 GPT、Claude、Gemini、Qwen、MiniMax 和 DeepSeek 流量的团队来说，DeepSeek V4 迁移 是一个很好的时机，可以在整个技术栈中标准化 model ID 和日志记录。

DeepSeek V4 的 Flatkey 目录检查

本文中，我于 2026 年 6 月 16 日检查了 Flatkey 的公开定价 API。该快照返回了 638 条模型总行数和 19 条以 DeepSeek 命名的行。它在 Standard 组中列出了 deepseek-v4-pro 和 deepseek-v4-flash，并支持 openai 端点。

请将这视为目录层面的时间点证据，而不是对你的账户和路由已就绪的承诺。在同一快照中，这两条 V4 记录的可用性状态均为 unknown_failure，这意味着在真实流量依赖该路由之前，应在当前的 Flatkey pricing 视图或仪表板中确认可用性。谨慎的 DeepSeek V4 migration 应在切换当天包含一次实时冒烟测试和使用日志检查。

DeepSeek V4 迁移检查清单

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

盘点每一个别名。 在应用代码、环境变量、prompt-router 规则、评测配置、后台作业、笔记本、文档和支持运行手册中搜索 deepseek-chat 和 deepseek-reasoner。
对每个工作负载进行分类。 将每条路由标记为聊天、推理、Agent 工具使用、结构化输出、长上下文、批量评测或仅回退。不要假设每条路由都应该迁移到相同的 V4 模式。
选择目标模型。 当你希望获得与当前别名最接近的替代时，先从 deepseek-v4-flash 开始。若工作负载需要更强能力，并且你可以在测试后接受其成本和延迟表现，则评估 deepseek-v4-pro。
明确思考模式。 对于旧的 deepseek-chat 行为，测试非思考模式。对于旧的 deepseek-reasoner 行为，测试思考模式，并确认你的 SDK 如何处理 reasoning_content。
将模型 ID 保留在配置中。 把目标模型放在环境变量或路由表中，不要直接写死在应用逻辑里。
运行成对输出测试。 在具有代表性的提示、解析器、JSON 模式任务、工具调用以及拒绝/错误场景上，对比旧别名响应和新的 V4 响应。
验证流式传输和用量计费。 检查最终用量是否出现在你的计费或可观测性代码预期的位置，尤其是对于流式响应。
检查成本和配额。 先确认 provider 定价或 Flatkey 定价，然后在生产流量增加之前设置较低的配额或测试预算。
记录新的模型 ID。 确保追踪、告警和计费导出显示 deepseek-v4-flash 或 deepseek-v4-pro，而不只是一个通用的 provider 标签。
准备回滚。 在 V4 路由通过真实工作负载测试之前，保留之前的 provider 或回退模型配置。
清理过时文档。 更新内部搭建指南，避免新开发者把已弃用的别名再次复制回生产环境。

Flatkey 的配置模板

仅模板：使用有效的 Flatkey 密钥以及当前目录中已确认的 Flatkey DeepSeek V4 模型 ID 来运行此示例。其形式是常规的 OpenAI SDK 用法，但路由、模型状态、思考行为和使用日志仍需要测试。

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

# 在上线过程中保持目标易于更改。
# 若要直接对比 DeepSeek：
DEEPSEEK_BASE_URL="https://api.deepseek.com"

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-v4-flash"),
    messages=[
        {
            "role": "user",
            "content": "用一句话回复，确认 DeepSeek V4 路由已配置。",
        }
    ],
)

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

对于直接的 DeepSeek 测试，请遵循 DeepSeek 官方的 OpenAI SDK 思考模式示例。思考指南说明，thinking 开关默认启用，OpenAI 格式的 effort 参数支持 high 和 max，较低的 effort 标签会向上映射以保证兼容性。如果你的应用依赖非思考响应，请明确做出该选择并进行测试，不要依赖别名。

切换前的测试矩阵

只有在测试了您的产品实际使用的行为之后，才应接受 DeepSeek V4 migration。

测试	检查内容	通过信号
基础聊天	简单提示、响应形状、解析器行为	应用接收到符合预期的内容，没有 schema 或角色错误
思考模式	`thinking`、`reasoning_effort` 和 `reasoning_content`	推理输出会根据您的产品策略进行处理或有意抑制
流式传输	分块格式、最终 usage、超时行为	客户端解析器和计费钩子仍然可用
工具调用	工具 schema、参数、多步代理轮次	工具调用能够生成并被消费，且没有畸形 JSON 或缺失 ID
结构化输出	JSON 模式提示和验证	验证器通过率保持在您的发布阈值内
长上下文	大提示、截断、缓存假设	上下文处理可预测，成本可接受
Flatkey 可观测性	路由状态、模型 ID、token 使用量、成本和错误日志	仪表板条目与您发送的请求一致
回滚	之前的提供方或备用模型	流量可以通过配置切回，而无需部署

常见错误

将DeepSeek V4 迁移视为一次全局搜索替换，而不进行输出评估。
替换deepseek-reasoner，却忘记在多轮对话中测试reasoning_content。
在评估任务、支持示例或回退规则中保留别名，而生产代码使用 V4 ID。
未检查路由状态和使用日志，就假设直接 DeepSeek 与经由 Flatkey 路由的行为完全相同。
从旧文章中复制模型 ID，而不是使用当前的 Flatkey 定价页面或仪表板。
因为第一次冒烟测试返回了正常答案，就跳过成本检查。
一直等到 2026 年 7 月 24 日，才发现某个计划任务或后台工作进程仍在使用一个已无法访问的别名。

这如何与其他 Flatkey 迁移指南配合

如果你还没有集中管理提供商配置，请先阅读更广泛的 OpenAI 兼容 API 迁移指南。它涵盖了基础 URL 变更、冒烟测试以及适用于 DeepSeek 之外的回滚模式。

如果你仍在决定是直接路由 DeepSeek 还是通过单一网关路由，请将此页面与现有的 DeepSeek API 访问指南进行比较。对于预算和模型行检查，请使用 AI 模型定价比较工作流以及当前的 Flatkey 定价页面。

常见问题

`deepseek-chat` 和 `deepseek-reasoner` 什么时候弃用？

DeepSeek 的官方文档将 2026 年 7 月 24 日 15:59 UTC 列为退役时间，之后 deepseek-chat 和 deepseek-reasoner 将无法访问。请在该日期前完成DeepSeek V4 迁移。

`deepseek-chat` 应该替换成什么？

若要获得最接近的行为，请测试带非思考行为的 deepseek-v4-flash。DeepSeek 说明 deepseek-chat 目前路由到 deepseek-v4-flash 的非思考模式。

`deepseek-reasoner` 应该替换成什么？

根据您的质量、成本和延迟需求，测试启用思考的 deepseek-v4-flash 或 deepseek-v4-pro。DeepSeek 说明 deepseek-reasoner 目前路由到 deepseek-v4-flash 的思考模式。

我需要更改 DeepSeek 基础 URL 吗？

对于直接的 DeepSeek OpenAI 格式调用，官方基础 URL 仍为 https://api.deepseek.com。对于 Flatkey 调用，请使用 https://router.flatkey.ai/v1 和 Flatkey API 密钥。

Flatkey 支持 DeepSeek V4 吗？

2026 年 6 月 16 日的 Flatkey 定价 API 快照列出了支持 openai 端点的 deepseek-v4-pro 和 deepseek-v4-flash。同一快照还显示这些条目的可用性状态为 unknown_failure，因此在生产流量之前，请验证当前定价页面、控制台路由状态以及一次线上冒烟测试。