模型与多模态实用指南2026年9月22日Flatkey Team

通过兼容 OpenAI 的路由器访问 DeepSeek API

通过直接使用 DeepSeek 密钥，或使用 Flatkey 的兼容 OpenAI 路由器来配置 DeepSeek API 访问，并进行模型检查、日志记录、价格审核和回滚。

通过兼容 OpenAI 的路由器访问 DeepSeek API，是一种实用的设置模式，适合那些希望使用 DeepSeek 模型、但又不想把每次供应商选择都变成一次新的 SDK 集成的独立开发者。

你有两条清晰的路径。直接的 DeepSeek 路径使用 DeepSeek API 密钥、DeepSeek 的 OpenAI 兼容基础 URL，以及 DeepSeek 的模型名称。路由器路径使用 Flatkey 的 OpenAI 兼容基础 URL、Flatkey API 密钥，以及你账户可用的 DeepSeek 模型 ID。这两种都可以工作。正确的选择取决于 DeepSeek 是你唯一的模型家族，还是多模型产品中的一条路由。

本指南将展示如何设置通过兼容 OpenAI 的路由器访问 DeepSeek API，如何让直接的供应商路径保持便于调试，以及在流量进入生产环境之前需要验证什么。

快速回答：通过兼容 OpenAI 的路由器访问 DeepSeek API

对于 OpenAI 风格的应用，DeepSeek API 访问有两条实用路线。

决策	直接使用 DeepSeek API	通过 Flatkey 使用 DeepSeek
API 密钥	DeepSeek API 密钥	Flatkey API 密钥
基础 URL	`https://api.deepseek.com`	`https://router.flatkey.ai/v1`
Anthropic 格式选项	`https://api.deepseek.com/anthropic`	使用你的路由所支持的 Flatkey API 形状
当前需要检查的 DeepSeek 模型名称	`deepseek-flash`、`deepseek-v4-pro`	Flatkey `/v1/models` 和模型目录中你账户可访问的 DeepSeek 模型 ID
最适合的场景	只使用 DeepSeek 的原型或特定供应商集成	希望使用一个客户端、一个密钥、一次使用情况审查，并更容易回退的多模型应用
运维检查	DeepSeek 控制台、供应商文档、最新价格表	Flatkey 模型列表、使用日志、定价页面、状态页面和回滚清单

当 DeepSeek 是你唯一需要的模型，并且供应商级控制最重要时，使用直接路径。当 DeepSeek 与 GPT、Claude、Gemini、Qwen、媒体模型或编码代理路由一起存在于同一个兼容 OpenAI 的客户端后面时，使用 Flatkey。

DeepSeek 对 API 兼容性的确认内容

DeepSeek 当前的 API 文档说明，DeepSeek API 使用与 OpenAI 和 Anthropic 兼容的 API 格式。OpenAI 格式的基础 URL 是：

https://api.deepseek.com

DeepSeek 也记录了一个 Anthropic 格式的基础 URL：

https://api.deepseek.com/anthropic

同一份文档将 deepseek-flash 和 deepseek-v4-pro 列为模型选项。文档还说明，为了兼容，旧名称 deepseek-v4-flash 和 deepseek-v4-flash-vision-exp 仍然可接受，但这些请求由 DeepSeek-V4.1-Flash 提供服务，并按 Flash 价格计费。对于新代码，应将旧名称视为迁移风险，而不是应复制到新产品中的名称。

DeepSeek 的定价页面目前将 deepseek-flash 描述为 DeepSeek-V4.1-Flash，将 deepseek-v4-pro 描述为 DeepSeek-V4-Pro-0813。页面还列出了 1M 的上下文长度和最高 384K 的输出，并且两个模型都显示支持 JSON 输出、工具调用、Responses API 和 Anthropic API。Flash 列出了视觉支持，而 Pro 没有。请在你自己的文档中发布精确价格之前先查看实时的 DeepSeek 定价页面，因为表格使用的是峰值和非高峰 token 费率。

Flatkey 带来的变化

Flatkey 并不会消除选择有效 DeepSeek 模型 ID 的需要。它改变的是路由配置的位置，以及你验证结果的位置。

Flatkey 的快速开始和模型 API 文档使用这个兼容 OpenAI 的基础 URL：

https://router.flatkey.ai/v1

Flatkey 的 /v1/models 端点会以兼容 OpenAI 的格式返回你账户可用的模型 ID。Flatkey 的使用文档说明，每个请求都可以连同所用模型、输入和输出 token 数、成本、时间戳、API 密钥以及状态一起查看。当 DeepSeek 只是多个模型中的一个候选项时，这会让通过兼容 OpenAI 的路由器访问 DeepSeek API 更容易运维。

路由版本的路由记录应当明确：

deepseek_route:
  provider_access_layer: flatkey
  base_url: https://router.flatkey.ai/v1
  api_key_source: FLATKEY_API_KEY
  candidate_models:
    - deepseek-flash
    - deepseek-v4-pro
  verify_before_launch:
    - account_accessible_v1_models
    - live_model_directory
    - pricing_page_units
    - usage_log_readback
    - fallback_or_rollback_policy

不要在应用代码中把模型名称隐藏为一个字符串。把它放到配置文件或模型清单中，这样 DeepSeek 模型更新就是一次可审查的变更，而不是一次紧急部署。

步骤 1：选择直接使用 DeepSeek 还是使用路由器

先从运维决策开始，而不是从 SDK 开始。

问题	以下情况通常直接使用 DeepSeek 就足够了...	以下情况通常路由器更合适...
你只调用 DeepSeek 吗？	是，产品只使用 DeepSeek。	否，DeepSeek 只是与其他提供商并列的一条路由。
你需要特定于提供商的控制吗？	是，你的团队希望使用 DeepSeek 原生设置并查看账单。	否，你的应用需要共享访问层和共享日志。
用户或任务会切换模型吗？	否，一个固定模型就足够了。	是，工作负载可能在 DeepSeek、Qwen、Gemini、Claude、GPT 或其他模型家族之间迁移。
谁来审查成本和故障？	一名开发者就能检查 DeepSeek 账户。	你需要一个覆盖密钥、模型和环境的统一使用账本。
如果路由失败会怎样？	你可以暂停该功能或稍后重试。	你需要故障切换、回滚或分阶段发布控制。

对于大多数独立开发者来说，首次发布可以很简单。对于单模型原型，直接使用 DeepSeek 就可以。随着产品开始比较模型、运行编码代理、以不同延迟或成本需求服务客户，或者需要一个地方来调试 token 使用情况时，通过兼容 OpenAI 的路由器访问 DeepSeek API 会更清晰。

步骤 2：设置 Flatkey OpenAI 客户端

如果你的项目已经使用 OpenAI SDK，那么路由器设置主要只是更改 base URL 和密钥。

Python:

import os
from openai import OpenAI

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

Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

直接使用 DeepSeek 的版本采用相同的 OpenAI 风格客户端结构，但指向 DeepSeek：

import os
from openai import OpenAI

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

将这两个密钥都保存在环境变量或机密存储中。切勿将 FLATKEY_API_KEY、DEEPSEEK_API_KEY 或临时环境覆盖提交到仓库中。

步骤 3：在第一次请求之前验证模型 ID

通过兼容 OpenAI 的路由器访问 DeepSeek API 应从模型发现开始，而不是直接复制一个模型字符串。

对于 Flatkey，请向路由器查询你的账户可以访问哪些模型 ID：

curl https://router.flatkey.ai/v1/models \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

然后在实时的 Flatkey 模型目录和定价页面上确认候选模型。对于直接使用 DeepSeek，请在 DeepSeek 文档和定价页面中确认模型名称。根据当前来源检查，DeepSeek 文档会将新代码指向 deepseek-flash 和 deepseek-v4-pro，同时警告旧的 V4 Flash 别名只是兼容性名称。

创建一个小型清单：

models:
  deepseek_default:
    id: deepseek-flash
    route: flatkey
    base_url: https://router.flatkey.ai/v1
    use_for:
      - coding_assistant
      - structured_extraction
      - long_context_review
    owner: product_engineering
    rollback: previous_production_model

这就是 DeepSeek 路由审查记录。它为你提供了一个位置，可以在生产流量依赖该路由之前记录模型 ID、路由负责人、使用场景和回滚目标。请将其与发布检查清单一起保存，这样在上线后，DeepSeek API Access Through an OpenAI-Compatible Router 仍然可以被审计。

步骤 4：进行首次聊天补全

从一个简短且确定性的请求开始。这是一次路由测试，不是基准测试。

response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": "Return concise implementation advice."},
        {"role": "user", "content": "Explain why base_url configuration matters in one sentence."},
    ],
    temperature=0.2,
    max_tokens=120,
)

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

如果请求失败，请按以下顺序检查：

检查项	可捕获的问题
`base_url`	直连与路由器混用、缺少 `/v1`、提供方路径错误
API key 变量	环境变量为空、密钥类型错误、在生产环境中使用了测试密钥
模型 ID	已弃用的别名、账户无访问权限、拼写错误
端点形态	Chat Completions、Responses 与 Anthropic Messages 不匹配
功能支持	视觉、思考模式、JSON、工具或流式传输假设
使用日志	请求未到达路由器、提供方故障、token/成本不匹配

这个顺序可以避免一个常见的调试错误：把配置失败当成模型失败。

步骤 5：测试你的应用实际使用的功能

兼容 OpenAI 并不意味着每个提供方、模型或路由器路径的行为都完全相同。请测试与你的工作负载相关的功能。

功能	冒烟测试	通过条件
非流式聊天	一个简短提示	返回可用消息并带有 usage 数据
流式传输	相同提示，启用流式传输	分块按顺序到达，UI 正常关闭
JSON 输出	一个小型提取任务	输出可根据你的 schema 或修复路径验证通过
工具调用	一个简单的函数 schema	工具调用字段可解析，无需自定义黑魔法
长上下文	具有代表性的长输入	延迟、成本和质量仍保持可接受
视觉	仅在使用支持视觉的模型时使用图像提示	请求仅在支持视觉的路由上成功
错误处理	在 staging 中使用无效的模型 ID	应用记录路由失败，但不泄露密钥

每次 Flatkey 测试后，打开 Usage Logs。请求应显示预期的模型、token 数、状态、时间戳、API key、延迟和成本。如果没有任何内容出现，请确认请求实际使用的 base URL 和密钥。

步骤 6：按已接受输出对成本进行归一化

DeepSeek 公布的 token 价格看起来很有吸引力，但 token 价格只是生产成本的一部分。请按已接受输出进行比较。

使用这个工作表：

指标	为什么重要
输入 token	长上下文提示可能主导成本。
输出 token	Agent 和编码任务生成的回复可能比聊天任务长得多。
缓存行为	命中缓存和未命中缓存的输入定价可能不同。
重试率	一个便宜的路由如果需要反复重试，最终会变贵。
拒绝率	无效 JSON、较弱的工具调用或低质量答案都应计入该路由的成本。
回退使用	回退流量必须可见，而不能被视为四舍五入误差。
人工修复时间	手动清理是实际产品成本的一部分。

实用公式：

accepted_output_cost =
  (successful_request_cost + retry_cost + fallback_cost + human_repair_cost)
  / accepted_outputs

使用 DeepSeek 的实时定价页面获取直接提供方单位。使用 Flatkey 的实时定价页面和你的使用日志来计算路由路径费用。不要在应用文档中复制静态价格行，除非有已核对的日期和负责刷新的人。

第 7 步：添加回滚策略

通过兼容 OpenAI 的路由器访问 DeepSeek API 在用户依赖它之前应该是可逆的。

deepseek_rollout:
  environment: production
  default_model: deepseek-flash
  route: flatkey
  start_percentage: 10
  increase_when:
    - accepted_output_rate >= 0.95
    - p95_latency_ms <= 4500
    - error_rate <= 0.02
    - usage_log_present: true
    - accepted_output_cost_within_budget: true
  rollback_when:
    - error_rate > 0.05
    - schema_failures_above_threshold: true
    - usage_log_missing: true
    - unexpected_cost_spike: true
  rollback_action:
    set_model: previous_production_model
    notify: engineering_owner

此策略不需要平台团队。它需要一个路由负责人、一个模型清单、一个使用审查习惯，以及在增加流量之前进行一次预发布测试。

它在 Flatkey 中的位置

当 DeepSeek 是更广泛的模型路由工作流的一部分时，Flatkey 就很适合：

你已经在使用兼容 OpenAI 的 SDK，并且希望为多个模型家族使用一个基础 URL。
你需要为开发、预发布、生产或编码代理设置单独的密钥或配额。
你希望通过一个模型目录和使用工作流来审查 DeepSeek、Qwen、Gemini、Claude、GPT 以及其他模型。
当模型 ID、价格单位、功能或提供方路由发生变化时，你需要一条回滚路径。

从 Flatkey API 快速开始入手；如果你正在替换直接提供方调用，请使用 OpenAI API 替代迁移指南；当成本敏感型工作负载比较区域提供方时，将此清单与 DeepSeek 与 Qwen API 路由检查配对使用。

对于生产决策，请查看实时的 Flatkey 模型目录、定价页面和状态页面。对于 DeepSeek 模型行为和直接提供方定价，请在你上线当天查看 DeepSeek 的 API 文档和定价页面。

通过兼容 OpenAI 的路由器访问 DeepSeek API 的最终检查清单

在将 DeepSeek API 访问发布给用户之前，请确认：

模型 ID 以 DeepSeek 文档和 Flatkey 账户可访问的模型列表中的信息为准。
直接 DeepSeek 测试使用 https://api.deepseek.com 和 DeepSeek API 密钥。
Flatkey 路由器测试使用 https://router.flatkey.ai/v1 和 Flatkey API 密钥。
你不应将 deepseek-v4-flash 或 deepseek-v4-flash-vision-exp 作为新的生产模型名称来使用。
当你的应用需要时，会分别测试聊天、流式输出、JSON 输出、工具调用、长上下文和视觉能力。
使用日志会显示预期的模型 ID、状态、令牌数量、时间戳、延迟、API 密钥和成本。
成本按已接受的输出进行归一化，而不仅仅是按标称令牌费率计算。
回滚是一次配置变更，而不是紧急的代码重写。
提供方密钥存储在环境变量或密钥存储中，绝不写入代码。

通过兼容 OpenAI 的路由器访问 DeepSeek API 是一种简单的集成模式，只要路由路径明确即可。如果你只需要 DeepSeek，就直接使用 DeepSeek。如果 DeepSeek 是多模型产品的一部分，并且需要一个客户端、一个基础 URL、一个使用循环以及一个清晰的回滚路径，就使用 Flatkey。