DeepSeek V3 接口返回 504 错误通常表示网关超时，核心解决方向是客户端增加重试机制并调整超时阈值。适用场景为网络波动或服务端高负载，风险边界在于避免无限重试导致资源耗尽。

命令速用版

以下 Python 代码片段展示了如何使用 requests 库配置重试机制，适用于大多数 HTTP 接口调用场景。

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[502, 503, 504],
    allowed_methods=["POST"]
)
adapter = HTTPAdapter(max_retries=retry)
session.mount("https://", adapter)

try:
    response = session.post(
        "https://api.deepseek.com/chat/completions",
        json={"model": "deepseek-chat", "messages": []},
        timeout=(5, 30)
    )
except requests.exceptions.Timeout:
    print("请求超时")

为什么会这样

504 Gateway Timeout 错误表明上游服务器未在指定时间内响应网关请求。这通常不是客户端代码逻辑错误，而是服务端负载过高或网络链路不稳定导致。DeepSeek API 兼容 OpenAI 格式，底层通信遵循标准 HTTP 协议，当模型推理耗时超过网关设定阈值或网络波动时，网关会主动切断连接并返回 504 状态码。

分步处理

按照以下顺序排查和配置，确保每一步都有明确的检查点。

步骤 1：检查网络连通性
在客户端服务器执行 curl 命令测试接口可达性，排除本地防火墙或 DNS 问题。

curl -I https://api.deepseek.com

如果无法连通，需检查服务器出站规则；如果能连通但业务请求超时，进入步骤 2。

步骤 2：调整超时配置
将客户端请求超时时间设置为连接超时 5 秒，读取超时 30 秒以上。避免设置过短导致正常长尾请求被误杀，也避免过长导致线程阻塞。

步骤 3：实施重试策略
仅针对 502、503、504 状态码启用重试，不要对 400 系列错误重试。使用指数退避算法，每次重试等待时间递增，防止瞬间流量冲击服务端。

步骤 4：记录详细日志
在代码中捕获异常并记录时间戳、请求 ID 和状态码。不要只记录错误，也要记录成功请求的耗时，以便区分是偶发波动还是持续超时。

怎么验证是否生效

通过日志分析重试次数和最终成功率来判断配置是否有效。

检查点 1：状态码分布
统计单位时间内 504 错误占比，配置重试后，最终成功请求的比例应上升，且 504 错误不应持续集中出现。

检查点 2：响应耗时
观察成功请求的平均耗时，如果耗时显著增加但状态码为 200，说明重试生效但服务端负载依然较高。

检查点 3：资源监控
监控客户端 CPU 和内存使用率，确保重试机制没有导致线程池耗尽或内存溢出。

常见坑

无限重试循环
如果不设置最大重试次数，网络持续故障时程序会陷入死循环。必须设置 total 上限。

混淆 429 和 504
429 Too Many Requests 是速率限制，504 是超时。对 429 重试需要遵循 Retry-After header，直接套用 504 重试策略可能导致封禁。

忽略幂等性
POST 请求重试可能导致重复扣费或重复生成内容。确保业务逻辑支持幂等，或在重试时携带唯一请求 ID。

常见问题

504 错误和 500 错误有什么区别？

504 是网关超时，500 是服务器内部错误。504 通常建议重试，500 可能需要等待服务端修复。

重试次数设置多少次合适？

公开资料中没有看到可靠的量化数据，通常建议 3 到 5 次，过多重试会增加延迟且收益递减。

重试会增加 API 调用成本吗？

如果请求未到达模型推理层即超时，通常不计费，但需查阅 DeepSeek 官方计费规则确认。

参考来源

• DeepSeek 开放平台，API 文档，https://platform.deepseek.com
• MDN Web Docs, HTTP Status 504, https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504