MAI Gateway 接入 DeepSeek，可以拆成两段配置。

一段连接模型供应商，使用 DeepSeek 的地址和密钥；另一段连接业务应用，使用企业网关地址和应用令牌。把这两段分开，换密钥、查错误和迁移应用都会更容易。

一、先把六项配置对应起来

MAI Gateway 支持 DeepSeek 接入和 OpenAI 兼容接口，业务应用可以通过统一入口调用模型。

配置项	填写内容	常见错误
上游 API 基础地址	https://api.deepseek.com	把网页聊天地址填进来
上游 API Key	DeepSeek 平台生成的密钥	使用网关应用令牌代替
上游模型名称	DeepSeek 当前提供的模型标识	使用已经失效的旧名称
应用访问地址	企业 MAI Gateway 的 API Base URL	把管理控制台地址当作 API 地址
应用访问令牌	网关分配的调用令牌	把管理员登录密码当作令牌
应用调用模型名	网关对应用开放的模型名称	与网关中的模型配置不一致

截至 2026 年 11 月 6 日，DeepSeek 官方快速入门列出的模型名称包括 deepseek-flash 和 deepseek-v4-pro。接入时应使用当前模型标识，不能把旧教程中的名称一直沿用下去。

二、按这个顺序配置

1. 配置供应商连接

在网关中配置 DeepSeek 上游连接，录入基础地址和 API Key。

基础地址与完整请求地址需要区分。https://api.deepseek.com 是基础地址，/chat/completions 是聊天请求路径。需要 Base URL 的位置，不要填入完整请求路径后再让客户端重复拼接。

2. 配置模型对应关系

选择准备开放的上游模型，再确定业务应用使用的模型名。

如果网关配置了对外模型名称，应用应填写该名称；网关转发时再对应到上游模型。两者可以相同，也可以按企业命名规则配置，但必须对应准确。

上线前保存一份模型对应表。

记录项	作用
应用调用模型名	方便开发人员配置
上游模型标识	确认实际调用对象
所属上游连接	确认使用哪个供应商账号
业务负责人	模型替换时找到验收人
验证过的能力	记录文本、流式、工具调用等测试结果

模型能返回普通文本，并不代表工具调用或结构化输出也已经通过验证。

3. 分配应用令牌

MAI Gateway 支持令牌管理、权限隔离和配额控制。建议按应用及环境分开分配令牌，开发、测试和生产环境不要共用一枚令牌。

这样处理后，测试脚本发生异常时，可以只停用测试令牌，不必影响生产应用。

4. 使用最小请求验证

下面的示例适用于 Python 后端。先安装 OpenAI SDK。

pip install openai

由部署环境注入三个变量。

环境变量	内容
MAI_BASE_URL	网关的实际 API Base URL，包含部署要求的路径前缀
MAI_API_KEY	当前应用的网关令牌
MAI_MODEL	网关开放给当前应用的模型名称

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["MAI_BASE_URL"],
    api_key=os.environ["MAI_API_KEY"],
    timeout=60.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model=os.environ["MAI_MODEL"],
    messages=[
        {"role": "user", "content": "请用一句话说明大模型网关的作用。"}
    ],
    stream=False,
)

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

示例中的 60 秒是客户端超时设置示例；联调阶段关闭 SDK 自动重试，便于观察一次请求对应的错误。生产环境应根据业务等待时间调整。

三、通过基础请求后，再增加复杂能力

验证阶段	请求内容	主要检查什么
第一轮	短文本、非流式	地址、鉴权和模型名称
第二轮	短文本、流式	数据分段返回与代理缓冲
第三轮	接近真实业务的输入长度	超时、输出完整性
第四轮	工具调用或结构化输出	参数传递、返回结构、应用解析
第五轮	并发与异常测试	限流、重试和故障处理

推理模式、工具调用等参数，应当按目标模型的接口要求逐项加入。OpenAI 兼容接口便于统一调用方式，但不能据此认定所有模型参数都完全相同。

四、错误处理要先判断发生在哪一段

同一个 HTTP 状态码，可能由网关返回，也可能来自上游。排查时先看错误来源和错误内容，再决定是否重试。

下表对应 DeepSeek 上游错误。

错误码	含义	建议处理
400	请求格式错误	检查请求体和字段结构
401	API Key 鉴权失败	检查网关保存的上游密钥
402	账户余额不足	检查上游账户余额
422	参数无效	检查模型支持的参数与取值
429	请求频率或并发超限	降低并发，使用有上限的退避重试
500	上游服务错误	短暂等待后有限重试
503	上游服务过载	降低请求压力，有限重试

密钥错误和余额不足，不会因为连续重试而恢复。对这些错误，应当停止重复请求并通知维护人员。

五、生产环境优先落实四件事

统一重试责任。 应用、SDK 和网关同时重试，会放大请求量。选择主要重试位置，明确重试次数、等待间隔和总时长。

分开设置超时。 连接超时、等待首个返回片段的时间和整次生成时间，解决的是不同问题。流式请求尤其需要检查入口代理的读取超时。

控制日志内容。 错误排查优先保留请求标识、模型、状态和耗时。完整提示词、客户资料与密钥不应随调试日志长期保存。

用真实任务验证备用模型。 MAI Gateway 支持故障转移，但备用模型仍需通过业务测试。