DeepSeek API 迁移 OpenAI SDK：请求适配与字段映射核验指南

将现有 OpenAI SDK 调用代码迁移到 DeepSeek API 时，直接替换 base_url 往往不够。两类接口在请求体字段、消息角色、参数命名和响应结构上可能存在差异，需要针对性适配。

重要前提：本文写作时未获得 DeepSeek 官方 API 文档的一手链接。因此，文中所有涉及 DeepSeek 具体 API 行为的内容均标注为“待官方文档核验”，不应作为确定结论直接用于生产环境。开发者应以 DeepSeek 官方文档（如 platform.deepseek.com 的 API 参考页）为最终依据，逐项确认后再实施迁移。

一、请求体字段：先核验再映射

OpenAI SDK 的请求体通常包含 model、messages、temperature、max_tokens、top_p、stream 等字段。DeepSeek API 的请求体结构可能类似，但以下项目必须逐项核验：

关于 system 消息：OpenAI 使用 system、user、assistant 三种角色。DeepSeek API 是否支持这三种角色、system 消息是否必须位于首位、是否允许多条，均需查阅目标模型的官方文档确认。在核验之前，不要假设存在“system 必须首位且仅一条”的限制，也不要据此改写消息结构。

关于参数过滤：封装层不应硬编码移除 frequency_penalty、presence_penalty 等参数。正确做法是维护一份“目标模型支持的参数白名单”，该白名单从官方文档核验后生成；白名单之外的参数记录告警并丢弃，白名单之内的参数原样透传。这样既避免请求被拒，也不会误删实际支持的功能。

二、响应结构：以官方示例为准

OpenAI 的响应包含 id、object、created、model、choices、usage 等字段。DeepSeek 的响应结构可能类似，但以下内容需核验：

• choices 中 message 的 content 字段格式；
• 是否返回额外字段（例如推理过程相关字段，具体名称以官方文档为准）；
• 流式响应的事件类型与 delta 字段命名；
• usage 中 token 计数字段的命名（prompt_tokens、completion_tokens、total_tokens 是否一致）。

解析响应时，建议仅提取业务必需的 content 字段，对未知字段做忽略处理而非报错。若代码依赖 usage 进行计费或统计，应先核验字段名，再增加映射逻辑；usage 缺失时应做可选处理，避免 KeyError。

三、封装方法：可调整的适配层

为保持调用层兼容，建议在 OpenAI SDK 与 DeepSeek API 之间增加适配层。适配层负责：

1. 请求转换：按核验后的参数白名单转换请求体，处理字段重命名与消息角色调整。
2. 响应转换：将 DeepSeek 响应映射为上层期望的格式，提取 content，统一 usage 字段（可选）。
3. 错误处理：捕获 DeepSeek 返回的错误码，转换为上层可统一处理的异常。

示例伪代码（参数白名单与字段映射需根据官方文档核验后填充）：

# 以下白名单与映射仅为结构示例，具体内容必须按官方文档核验后填写
SUPPORTED_PARAMS = {"model", "messages", "temperature", "top_p", "max_tokens", "stream"}

def adapt_request(openai_request):
    deepseek_request = {}
    for key, value in openai_request.items():
        if key in SUPPORTED_PARAMS:
            deepseek_request[key] = value
        else:
            # 记录告警，便于后续核验是否应加入白名单
            print(f"[adapt] param not in whitelist, dropped: {key}")
    deepseek_request["messages"] = adapt_messages(openai_request.get("messages", []))
    return deepseek_request

def adapt_messages(messages):
    # 消息角色与顺序调整逻辑需按官方文档核验后实现
    # 此处仅做透传示例，不要假设 system 位置限制
    return messages

def adapt_response(deepseek_response):
    usage = deepseek_response.get("usage") or {}
    return {
        "id": deepseek_response.get("id"),
        "object": "chat.completion",
        "created": deepseek_response.get("created"),
        "model": deepseek_response.get("model"),
        "choices": [
            {
                "index": choice.get("index"),
                "message": {
                    "role": choice.get("message", {}).get("role"),
                    "content": choice.get("message", {}).get("content"),
                },
                "finish_reason": choice.get("finish_reason"),
            }
            for choice in deepseek_response.get("choices", [])
        ],
        "usage": {
            "prompt_tokens": usage.get("prompt_tokens"),
            "completion_tokens": usage.get("completion_tokens"),
            "total_tokens": usage.get("total_tokens"),
        } if usage else None,
    }

注意：上述代码中的 SUPPORTED_PARAMS 和 adapt_messages 是占位结构，必须根据官方文档核验结果调整。不要直接复制到生产环境。

四、回归验证清单

迁移后需执行以下验证，每项验证前先确认对应 API 行为已核验：

1. 基础调用：发送单条 user 消息，确认返回 content 非空。
2. 多轮对话：包含 system、user、assistant 消息，确认角色顺序和内容符合官方文档要求。
3. 参数边界：测试 temperature 取边界值、max_tokens 取最小值，确认请求被接受。
4. 参数支持性：对 frequency_penalty、presence_penalty 等参数，分别测试“透传”与“不传”两种方式，记录官方返回结果，据此更新白名单。
5. 流式响应：开启 stream，确认数据块格式正确，拼接后内容完整。
6. 错误处理：发送无效 model 或超长消息，确认错误码被正确捕获和转换。
7. 用量统计：对比 usage 字段，确认 token 计数与预期一致；usage 缺失时确认代码不报错。

五、注意事项

• 不要假设 DeepSeek API 完全兼容 OpenAI 的所有参数，一切以官方文档核验结果为准。
• 封装层的参数白名单应可配置，便于后续根据官方文档更新。
• 迁移前备份原有代码，逐步替换并测试。

通过适配层隔离差异，并以官方文档核验为前提，可最小化迁移成本，保持上层业务代码稳定。