兼容性指南

DeepSeek API 提供与 OpenAI API 的高度兼容性，使您能够轻松迁移现有应用程序或集成到现有的 AI 工作流中。本指南详细介绍了兼容性特性、迁移步骤和最佳实践。

概述

DeepSeek API 兼容性特性：

• OpenAI API 兼容: 支持 OpenAI 的主要 API 接口
• SDK 兼容: 可直接使用 OpenAI 官方 SDK
• 参数兼容: 支持大部分 OpenAI API 参数
• 响应格式兼容: 返回格式与 OpenAI 一致

OpenAI API 兼容性

支持的端点

OpenAI 端点	DeepSeek 支持	说明
/chat/completions	✅	完全支持
/completions	✅	完全支持
/models	✅	返回 DeepSeek 模型列表
/embeddings	❌	暂不支持
/images/generations	❌	暂不支持
/audio/transcriptions	❌	暂不支持

支持的参数

Chat Completions

# 支持的参数
response = client.chat.completions.create(
    model="deepseek-chat",           # ✅ 必需
    messages=[...],                  # ✅ 必需
    max_tokens=1000,                 # ✅ 支持
    temperature=0.7,                 # ✅ 支持
    top_p=0.9,                       # ✅ 支持
    n=1,                            # ✅ 支持
    stream=True,                     # ✅ 支持
    stop=["END"],                    # ✅ 支持
    presence_penalty=0.0,            # ✅ 支持
    frequency_penalty=0.0,           # ✅ 支持
    logit_bias={},                   # ✅ 支持
    user="user123",                  # ✅ 支持
    response_format={"type": "json_object"},  # ✅ 支持
    tools=[...],                     # ✅ 支持（函数调用）
    tool_choice="auto"               # ✅ 支持
)

Text Completions

# 支持的参数
response = client.completions.create(
    model="deepseek-chat",           # ✅ 必需
    prompt="Hello",                  # ✅ 必需
    max_tokens=100,                  # ✅ 支持
    temperature=0.7,                 # ✅ 支持
    top_p=0.9,                       # ✅ 支持
    n=1,                            # ✅ 支持
    stream=False,                    # ✅ 支持
    logprobs=None,                   # ❌ 暂不支持
    echo=False,                      # ✅ 支持
    stop=["END"],                    # ✅ 支持
    presence_penalty=0.0,            # ✅ 支持
    frequency_penalty=0.0,           # ✅ 支持
    best_of=1,                       # ❌ 暂不支持
    logit_bias={},                   # ✅ 支持
    user="user123"                   # ✅ 支持
)

迁移指南

从 OpenAI 迁移

1. 最小化迁移

只需要修改两个配置：

# 原 OpenAI 代码
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx"  # OpenAI API Key
)

# 迁移到 DeepSeek
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",  # DeepSeek API Key
    base_url="https://api.deepseek.com"  # 添加这一行
)

# 其他代码保持不变
response = client.chat.completions.create(
    model="deepseek-chat",  # 只需修改模型名称
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

2. 环境变量迁移

# 原 OpenAI 环境变量
export OPENAI_API_KEY="sk-xxx"

# 迁移到 DeepSeek
export DEEPSEEK_API_KEY="sk-xxx"
export DEEPSEEK_BASE_URL="https://api.deepseek.com"

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url=os.getenv("DEEPSEEK_BASE_URL")
)

3. 配置文件迁移

# config.py
class APIConfig:
    def __init__(self, provider="openai"):
        if provider == "openai":
            self.api_key = os.getenv("OPENAI_API_KEY")
            self.base_url = None
            self.default_model = "gpt-3.5-turbo"
        elif provider == "deepseek":
            self.api_key = os.getenv("DEEPSEEK_API_KEY")
            self.base_url = "https://api.deepseek.com"
            self.default_model = "deepseek-chat"

# 使用
config = APIConfig("deepseek")
client = OpenAI(
    api_key=config.api_key,
    base_url=config.base_url
)

模型映射

OpenAI 模型	DeepSeek 等效模型	说明
gpt-3.5-turbo	deepseek-chat	通用对话模型
gpt-4	deepseek-chat	高级对话模型
gpt-4-turbo	deepseek-chat	最新对话模型
code-davinci-002	deepseek-coder	代码生成模型

# 模型映射函数
def map_model(openai_model):
    model_mapping = {
        "gpt-3.5-turbo": "deepseek-chat",
        "gpt-4": "deepseek-chat",
        "gpt-4-turbo": "deepseek-chat",
        "code-davinci-002": "deepseek-coder"
    }
    return model_mapping.get(openai_model, "deepseek-chat")

# 使用示例
original_model = "gpt-3.5-turbo"
deepseek_model = map_model(original_model)

框架集成

LangChain 集成

from langchain.llms import OpenAI
from langchain.chat_models import ChatOpenAI

# 使用 LangChain 的 OpenAI 包装器
llm = OpenAI(
    openai_api_key="your-deepseek-api-key",
    openai_api_base="https://api.deepseek.com",
    model_name="deepseek-chat"
)

# 聊天模型
chat_model = ChatOpenAI(
    openai_api_key="your-deepseek-api-key",
    openai_api_base="https://api.deepseek.com",
    model_name="deepseek-chat"
)

# 使用示例
response = llm("解释什么是机器学习")
print(response)

LlamaIndex 集成

from llama_index.llms import OpenAI
from llama_index import ServiceContext, VectorStoreIndex

# 配置 DeepSeek
llm = OpenAI(
    api_key="your-deepseek-api-key",
    api_base="https://api.deepseek.com",
    model="deepseek-chat"
)

# 创建服务上下文
service_context = ServiceContext.from_defaults(llm=llm)

# 使用示例
index = VectorStoreIndex.from_documents(
    documents, 
    service_context=service_context
)

Haystack 集成

from haystack.nodes import OpenAIAnswerGenerator

# 配置 DeepSeek
answer_generator = OpenAIAnswerGenerator(
    api_key="your-deepseek-api-key",
    api_base="https://api.deepseek.com",
    model="deepseek-chat"
)

# 使用示例
answers = answer_generator.predict(
    query="什么是人工智能？",
    documents=documents
)

兼容性测试

功能测试套件

import unittest
from openai import OpenAI

class DeepSeekCompatibilityTest(unittest.TestCase):
    def setUp(self):
        self.client = OpenAI(
            api_key="your-deepseek-api-key",
            base_url="https://api.deepseek.com"
        )
    
    def test_chat_completion(self):
        """测试聊天完成功能"""
        response = self.client.chat.completions.create(
            model="deepseek-chat",
            messages=[{"role": "user", "content": "Hello"}],
            max_tokens=50
        )
        
        self.assertIsNotNone(response.choices[0].message.content)
        self.assertEqual(response.choices[0].message.role, "assistant")
    
    def test_streaming(self):
        """测试流式输出"""
        response = self.client.chat.completions.create(
            model="deepseek-chat",
            messages=[{"role": "user", "content": "Count to 5"}],
            stream=True,
            max_tokens=50
        )
        
        content_parts = []
        for chunk in response:
            if chunk.choices[0].delta.content:
                content_parts.append(chunk.choices[0].delta.content)
        
        self.assertTrue(len(content_parts) > 0)
    
    def test_function_calling(self):
        """测试函数调用"""
        tools = [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "获取天气信息",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {"type": "string"}
                        }
                    }
                }
            }
        ]
        
        response = self.client.chat.completions.create(
            model="deepseek-chat",
            messages=[{"role": "user", "content": "北京天气如何？"}],
            tools=tools,
            tool_choice="auto"
        )
        
        self.assertIsNotNone(response.choices[0].message)
    
    def test_json_mode(self):
        """测试 JSON 模式"""
        response = self.client.chat.completions.create(
            model="deepseek-chat",
            messages=[{"role": "user", "content": "生成一个用户信息JSON"}],
            response_format={"type": "json_object"},
            max_tokens=100
        )
        
        import json
        try:
            json.loads(response.choices[0].message.content)
            json_valid = True
        except:
            json_valid = False
        
        self.assertTrue(json_valid)

if __name__ == "__main__":
    unittest.main()

性能对比测试

import time
import statistics

def performance_comparison():
    """比较 OpenAI 和 DeepSeek 的性能"""
    
    # OpenAI 客户端
    openai_client = OpenAI(api_key="openai-key")
    
    # DeepSeek 客户端
    deepseek_client = OpenAI(
        api_key="deepseek-key",
        base_url="https://api.deepseek.com"
    )
    
    test_prompts = [
        "解释什么是机器学习",
        "写一个Python函数",
        "总结人工智能的发展历史"
    ]
    
    def measure_latency(client, model, prompts):
        latencies = []
        for prompt in prompts:
            start_time = time.time()
            response = client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": prompt}],
                max_tokens=100
            )
            end_time = time.time()
            latencies.append(end_time - start_time)
        return latencies
    
    # 测试 OpenAI
    openai_latencies = measure_latency(
        openai_client, "gpt-3.5-turbo", test_prompts
    )
    
    # 测试 DeepSeek
    deepseek_latencies = measure_latency(
        deepseek_client, "deepseek-chat", test_prompts
    )
    
    print("性能对比结果:")
    print(f"OpenAI 平均延迟: {statistics.mean(openai_latencies):.2f}秒")
    print(f"DeepSeek 平均延迟: {statistics.mean(deepseek_latencies):.2f}秒")

差异和限制

主要差异

1. 模型名称: 需要使用 DeepSeek 的模型名称
2. 基础URL: 需要设置 base_url 为 DeepSeek API 地址
3. 某些高级功能: 如 logprobs、best_of 等暂不支持

不支持的功能

# 以下功能暂不支持
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}],
    # logprobs=5,        # ❌ 不支持
    # best_of=3,         # ❌ 不支持
    # suffix="END"       # ❌ 不支持
)

行为差异

1. Token 计算: 可能与 OpenAI 略有不同
2. 响应时间: 根据地理位置和网络条件可能有差异
3. 内容过滤: 遵循不同的内容政策

最佳实践

1. 渐进式迁移

class APIProvider:
    def __init__(self, provider="openai"):
        self.provider = provider
        if provider == "openai":
            self.client = OpenAI(api_key="openai-key")
            self.model = "gpt-3.5-turbo"
        elif provider == "deepseek":
            self.client = OpenAI(
                api_key="deepseek-key",
                base_url="https://api.deepseek.com"
            )
            self.model = "deepseek-chat"
    
    def chat(self, messages, **kwargs):
        return self.client.chat.completions.create(
            model=self.model,
            messages=messages,
            **kwargs
        )

# 使用环境变量控制
provider = os.getenv("AI_PROVIDER", "openai")
api = APIProvider(provider)

2. 错误处理和降级

def robust_api_call(messages, primary_provider="deepseek", fallback_provider="openai"):
    providers = {
        "deepseek": OpenAI(
            api_key="deepseek-key",
            base_url="https://api.deepseek.com"
        ),
        "openai": OpenAI(api_key="openai-key")
    }
    
    models = {
        "deepseek": "deepseek-chat",
        "openai": "gpt-3.5-turbo"
    }
    
    try:
        # 尝试主要提供商
        response = providers[primary_provider].chat.completions.create(
            model=models[primary_provider],
            messages=messages
        )
        return response
    except Exception as e:
        print(f"主要提供商失败: {e}")
        
        # 降级到备用提供商
        try:
            response = providers[fallback_provider].chat.completions.create(
                model=models[fallback_provider],
                messages=messages
            )
            return response
        except Exception as fallback_error:
            print(f"备用提供商也失败: {fallback_error}")
            raise

3. 配置管理

# config.yaml
api_providers:
  deepseek:
    api_key: "${DEEPSEEK_API_KEY}"
    base_url: "https://api.deepseek.com"
    model: "deepseek-chat"
    max_tokens: 1000
  openai:
    api_key: "${OPENAI_API_KEY}"
    base_url: null
    model: "gpt-3.5-turbo"
    max_tokens: 1000

# config.py
import yaml
import os

class ConfigManager:
    def __init__(self, config_file="config.yaml"):
        with open(config_file, 'r') as f:
            self.config = yaml.safe_load(f)
    
    def get_provider_config(self, provider):
        config = self.config["api_providers"][provider].copy()
        # 替换环境变量
        for key, value in config.items():
            if isinstance(value, str) and value.startswith("${") and value.endswith("}"):
                env_var = value[2:-1]
                config[key] = os.getenv(env_var)
        return config

常见问题

Q: 如何确保完全兼容？

A: 使用我们提供的兼容性测试套件，并在迁移前进行充分测试。

Q: 性能是否有差异？

A: 可能有轻微差异，建议进行性能基准测试。

Q: 如何处理不支持的功能？

A: 可以移除不支持的参数，或实现降级逻辑。

Q: 是否支持所有 OpenAI SDK 版本？

A: 支持 OpenAI Python SDK v1.0+ 版本。

相关资源

• DeepSeek API 参考

---

最后更新: 2025年1月27日