DeepSeek

DeepSeek 通过托管 API 提供其语言和推理模型。应用通过稳定的 AISIX 别名调用这些模型，网关则确保 DeepSeek 凭证不会出现在客户端代码中。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 从 DeepSeek 平台获取的 DeepSeek API Key。
• curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为由 DeepSeek 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

由于 DeepSeek 提供 OpenAI 兼容 API，AISIX 会通过 openai 适配器进行连接，并使用 DeepSeek API 根地址作为 api_base。

创建服务提供方密钥

创建用于存储 DeepSeek 凭证和 API 根地址的服务提供方密钥，并允许其在该环境中使用：

# 请替换为实际值
export DEEPSEEK_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "deepseek-prod",
    "provider": "deepseek",
    "api_key": "'"${DEEPSEEK_API_KEY}"'",
    "api_base": "https://api.deepseek.com",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 deepseek。AISIX Cloud Admin API 会从目录服务提供方派生适配器；adapter 字段仅在 BYO 服务提供方密钥上被接受。

❷ api_key 存储 DeepSeek API Key。其行为遵循服务提供方密钥中的凭证处理方式。

❸ 对此目录服务提供方，api_base 为可选字段，因为省略时 AISIX Cloud Admin API 会填入相同的根地址。请显式设置该字段，使上游根地址在资源上保持可见。AISIX 会将端点路径追加到 api_base，因此请使用服务商根地址 https://api.deepseek.com，末尾不要带 /chat/completions。该值传到网关时绝不能是空值：对于使用 openai 适配器但服务提供方不是 openai 的情况，AISIX 不会回退到 api.openai.com，而是会返回上游配置错误。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "deepseek-v4-flash-prod",
    "model_name": "deepseek-v4-flash",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 DeepSeek 模型 ID，例如 deepseek-v4-flash 或 deepseek-v4-pro。

❸ provider_key_id 将别名关联到 DeepSeek 服务提供方密钥。

创建调用方 API Key

创建可访问模型别名的调用方 API Key 资源。网关会生成密钥值，明文只在创建响应中返回一次，因此请立即保存：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "deepseek-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值通过 ID 引用模型，因此该密钥只能访问已创建的别名。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export DEEPSEEK_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "deepseek-prod"
    provider: "deepseek"
    adapter: "openai"
    api_key: ${DEEPSEEK_API_KEY}
    api_base: "https://api.deepseek.com"

models:
  - display_name: "deepseek-v4-flash-prod"
    provider: "deepseek"
    model_name: "deepseek-v4-flash"
    provider_key: "deepseek-prod"

api_keys:
  - display_name: "deepseek-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "deepseek-v4-flash-prod"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from DeepSeek."
      }
    ]
  }'

网关会返回 OpenAI 兼容响应，其中回显面向调用方的别名 deepseek-v4-flash-prod。请在 DeepSeek 平台用量页面确认该请求。如果请求失败，请检查服务提供方密钥的 api_key、api_base，以及 model_name 中的 DeepSeek 模型 ID。

使用思考模式

DeepSeek V4 默认以 high 强度启用思考模式。如需对 Chat Completions 请求禁用思考，请在请求体中添加以下字段：

{
  "thinking": {
    "type": "disabled"
  }
}

启用思考时，请将顶层 reasoning_effort 字段设置为 DeepSeek 原生支持的三个等级之一：low、high 或 max。为兼容客户端，DeepSeek 也接受 medium 和 xhigh，并将二者都映射为 high。思考模式下，temperature 和 top_p 等采样字段不起作用。详情请参阅思考模式。

AISIX 会将这些控制项转发给 DeepSeek，并在流式和非流式响应的 reasoning_content 字段中保留返回的推理内容。当请求包含 tools 时，DeepSeek 要求保留并重放之前每一轮助手消息的 reasoning_content，包括模型没有进行工具调用的轮次。应用负责重放这些助手消息；省略该字段会导致 DeepSeek 返回 HTTP 400。

访问 DeepSeek 原生 API 形态

DeepSeek 提供原生 Responses API 和 Anthropic 兼容 API，AISIX Cloud 无需任何配置即可访问两者：DeepSeek 目录条目自带下面这份声明，因此对 DeepSeek 别名发起的 /v1/responses 和 /v1/messages 会直达 DeepSeek 自己的路由，而不是被转换成 Chat Completions。

{
  "apis": {
    "responses": {},
    "messages": { "base": "https://api.deepseek.com/anthropic" }
  }
}

responses 不带 base，因为 DeepSeek 就在该密钥已指向的 API Root 上提供它。该声明在密钥仍指向那个 Root 时生效；把 api_base 改指到自建端点就会失效，因为它描述的是 DeepSeek 的路径而不是你的。如果你用自己的网关代理 DeepSeek 且提供同样的路由，请在密钥上自行声明。参见声明 API 协议面。

开源 AISIX 网关没有目录，请在 resources.yaml 的服务提供方密钥条目上声明。

没有该声明时：

AISIX 配置或路由	上游行为
使用目录 DeepSeek 别名的 /v1/responses	在 DeepSeek Chat Completions 上使用 AISIX Responses 桥接。它不会调用 DeepSeek 原生 /responses 路由，且会忽略没有对应 Chat 语义的 Responses 专用字段。
/passthrough/deepseek/responses	调用 DeepSeek 原生 Responses 路由。请在 model 中发送上游模型 ID，而不是 AISIX 别名。声明 apis.responses 可以用 AISIX 别名到达同一条路由，通常那才是你想要的。
使用目录 DeepSeek 别名的 /v1/messages	将 Anthropic 形态的调用方请求转换为 DeepSeek Chat Completions，而不会调用 DeepSeek /anthropic/v1/messages 路由。
使用 adapter: anthropic 和 api_base: https://api.deepseek.com/anthropic 的单独 BYO 服务提供方密钥	使用 Anthropic 适配器调用 DeepSeek Anthropic 兼容 Messages 路由，代价是多一把密钥和多一个模型别名。在目录密钥上声明 apis.messages 可以用同一个别名到达同一条路由。
使用目录 DeepSeek 别名的 /v1/completions	无法访问 DeepSeek FIM Completion（Beta）路由；该路由仅在 /beta API Root 下提供。
/passthrough/deepseek/beta/completions	调用 FIM Completion（Beta）。请在 model 中发送 deepseek-v4-pro；AISIX 不会在透传路由上重写别名。

本页的 /passthrough/deepseek 路径假定一条透传路由认领该前缀，target_url 设为 DeepSeek 的 API 根地址；在调用方 Key 的 allowed_routes 上授予路由名称。路由会转发原生 Responses 请求和响应，且不会重写 AISIX 别名。AISIX 会从 input 检测 Responses 信封，并记录响应携带的所有受支持 Token 维度，包括输入、输出、缓存和推理详情。这些计数仅用于遥测：透传流量不会推进 tpm 或 tpd 计数器、解析模型成本，也不会增加预算消耗。如果响应不含任何可识别的 Token 字段，记录的 Token 数量为零。

端点覆盖范围

路由	使用 DeepSeek 目录别名时的行为
/v1/chat/completions	支持，包括 stream: true。
/v1/responses	直达 DeepSeek 原生 Responses API（由目录条目声明）。推理输出项得以保留，而 Chat Completions 转换承载不了它们。
/v1/messages	直达 DeepSeek 的 Anthropic 兼容路由（由目录条目声明），因此提示词缓存断点和思考块得以保留。/v1/messages/count_tokens 在同一条路由上可用。
/v1/completions	无法访问 DeepSeek FIM。请改用 /passthrough/deepseek/beta/completions 并发送 deepseek-v4-pro。
/v1/embeddings	不可用。DeepSeek 未在此 API Root 上提供 Embedding 端点。
/v1/audio/*	不可用。DeepSeek 未提供匹配的 OpenAI 形态音频路由。
/v1/images/generations	拒绝。该路由只接受服务提供方为 openai 的模型。
/v1/rerank	拒绝。该路由只接受 openai、cohere 和 jina 服务提供方值。
/v1/videos	拒绝。该路由的服务提供方允许列表不包含 deepseek。
/passthrough/deepseek/*	通过已配置的透传路由可用，支持 /responses 和 /models 等服务提供方原生路由，但需遵循上述别名和用量限制。

后续步骤

你已将 AISIX 连接到 DeepSeek，并验证了模型别名。接下来可阅读以下指南：

• 模型别名：为此别名配置路由、重试行为或成本元数据。
• 路由与故障转移：在 DeepSeek 和另一个服务提供方之间进行故障转移。
• 服务提供方特定覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。