DeepSeek API 开发指南

二、快速开始

1. 获取 API Key

首先需要在 DeepSeek 官网注册账号并获取 API Key：

1. 访问 DeepSeek 开放平台 2. 注册并登录账号 3. 进入控制台，创建 API Key 4. 复制保存 API Key（只显示一次）

2. 环境配置

# 安装官方 SDK
pip install openai
# 或使用 httpx 进行更底层的调用
pip install httpx
# 环境变量管理
pip install python-dotenv

3. 基础调用示例

import os
from openai import OpenAI
from dotenv import load_dotenv
# 加载环境变量
load_dotenv()
# 初始化客户端
client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com/v1"
)
# 发送请求
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "你是一个有帮助的AI助手"},
        {"role": "user", "content": "请解释什么是深度学习？"}
    ]
)
print(response.choices[0].message.content)

三、模型选择与配置

1. 可用模型

DeepSeek 提供多个模型供选择：

| 模型名称 | 描述 | 适用场景 | |---------|------|---------| | deepseek-chat | 通用对话模型 | 日常对话、文本生成、问答 | | deepseek-coder | 代码专用模型 | 代码生成、调试、解释 |

# 使用通用对话模型
chat_response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "你好"}]
)
# 使用代码模型
coder_response = client.chat.completions.create(
    model="deepseek-coder",
    messages=[{"role": "user", "content": "写一个 Python 快速排序"}]
)

2. 参数详解

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "user", "content": "写一首关于春天的诗"}
    ],
    temperature=0.7,           # 创造性：0-2，越高越随机
    max_tokens=500,            # 最大输出长度
    top_p=0.9,                 # 核采样参数
    frequency_penalty=0.5,     # 频率惩罚：减少重复
    presence_penalty=0.3,      # 存在惩罚：鼓励多样性
    stop=["结束"],             # 停止词
    stream=False               # 是否流式输出
)

#### 参数说明

temperature（温度）

• 范围：0-2，默认 1
• 值越低，输出越确定、一致
• 值越高，输出越随机、创意
• 建议：代码生成用 0.2-0.5，创意写作用 0.7-1.0

• 控制输出长度
• 注意：输入+输出的总 token 数有限制
• 建议根据实际需求设置合理值

• 范围：0-1，默认 1
• 控制模型从概率最高的多少 token 中选择
• 与 temperature 二选一即可

• 范围：-2 到 2
• 减少重复内容
• 正值会惩罚重复，负值会鼓励重复

四、高级功能

1. 流式输出

流式输出可以实时获取生成内容，提升用户体验：

def stream_chat(prompt: str):
    """流式对话"""
    stream = client.chat.completions.create(
        model="deepseek-chat",
        messages=[{"role": "user", "content": prompt}],
        stream=True
    )
    
    full_response = ""
    for chunk in stream:
        if chunk.choices[0].delta.content is not None:
            content = chunk.choices[0].delta.content
            print(content, end="", flush=True)
            full_response += content
    
    print()  # 换行
    return full_response
# 使用示例
stream_chat("请讲一个简短的故事")

2. 多轮对话

实现上下文保持的多轮对话：

class ConversationManager:
    def __init__(self, system_prompt: str = None):
        self.messages = []
        if system_prompt:
            self.messages.append({
                "role": "system",
                "content": system_prompt
            })
    
    def chat(self, user_input: str) -> str:
        """发送消息并获取回复"""
        # 添加用户消息
        self.messages.append({
            "role": "user",
            "content": user_input
        })
        
        # 调用 API
        response = client.chat.completions.create(
            model="deepseek-chat",
            messages=self.messages,
            temperature=0.7
        )
        
        # 获取助手回复
        assistant_message = response.choices[0].message.content
        
        # 添加到历史记录
        self.messages.append({
            "role": "assistant",
            "content": assistant_message
        })
        
        return assistant_message
    
    def get_history(self) -> list:
        """获取对话历史"""
        return self.messages
    
    def clear_history(self):
        """清空对话历史"""
        self.messages = [self.messages[0]] if self.messages[0]["role"] == "system" else []
# 使用示例
conv = ConversationManager("你是一个 Python 专家")
print(conv.chat("什么是装饰器？"))
print(conv.chat("能举个例子吗？"))
print(conv.chat("装饰器有什么实际应用？"))

3. Token 统计

监控 API 使用量：

def chat_with_stats(prompt: str):
    """带统计的对话"""
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=[{"role": "user", "content": prompt}]
    )
    
    # 获取使用统计
    usage = response.usage
    print(f"提示 Token: {usage.prompt_tokens}")
    print(f"生成 Token: {usage.completion_tokens}")
    print(f"总计 Token: {usage.total_tokens}")
    
    return response.choices[0].message.content
# DeepSeek 价格参考（2024年数据）
# deepseek-chat: 输入 ¥0.001/千tokens, 输出 ¥0.002/千tokens
# deepseek-coder: 输入 ¥0.001/千tokens, 输出 ¥0.002/千tokens

4. 函数调用（Function Calling）

DeepSeek 支持函数调用功能，可以让模型调用外部工具：

import json
# 定义可用工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "温度单位"
                    }
                },
                "required": ["city"]
            }
        }
    }
]
def get_weather(city: str, unit: str = "celsius") -> dict:
    """模拟天气 API"""
    # 实际应用中应该调用真实的天气 API
    weather_data = {
        "北京": {"temp": 22, "condition": "晴"},
        "上海": {"temp": 25, "condition": "多云"},
        "广州": {"temp": 28, "condition": "小雨"}
    }
    return weather_data.get(city, {"temp": 20, "condition": "未知"})
# 发送带工具的请求
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "user", "content": "北京今天天气怎么样？"}
    ],
    tools=tools,
    tool_choice="auto"
)
# 处理工具调用
message = response.choices[0].message
if message.tool_calls:
    print(f"模型请求调用工具: {message.tool_calls[0].function.name}")
    
    # 解析参数
    args = json.loads(message.tool_calls[0].function.arguments)
    print(f"参数: {args}")
    
    # 执行函数
    result = get_weather(**args)
    print(f"执行结果: {result}")
    
    # 将结果返回给模型
    messages = [
        {"role": "user", "content": "北京今天天气怎么样？"},
        message,
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": json.dumps(result, ensure_ascii=False)
        }
    ]
    
    # 获取最终回复
    final_response = client.chat.completions.create(
        model="deepseek-chat",
        messages=messages
    )
    print(f"\n最终回复: {final_response.choices[0].message.content}")

五、代码生成实战

DeepSeek-Coder 在代码生成方面表现出色：

1. 代码生成

def generate_code(task: str, language: str = "Python") -> str:
    """生成代码"""
    prompt = f"""请用 {language} 编写代码完成以下任务：
{task}
要求：
1. 代码清晰、高效
2. 添加必要的注释
3. 处理边界情况
4. 包含使用示例"""
    response = client.chat.completions.create(
        model="deepseek-coder",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.3
    )
    
    return response.choices[0].message.content
# 示例
code = generate_code("实现一个线程安全的单例模式", "Python")
print(code)

2. 代码解释

def explain_code(code: str) -> str:
    """解释代码"""
    prompt = f"""请详细解释以下代码的功能和实现原理：

请包括：
1. 整体功能描述
2. 关键步骤说明
3. 使用的技术和算法
4. 可能的改进建议"""
    response = client.chat.completions.create(
        model="deepseek-coder",
        messages=[{"role": "user", "content": prompt}]
    )
    
    return response.choices[0].message.content

3. 代码调试

def debug_code(code: str, error_message: str = None) -> str:
    """调试代码"""
    prompt = f"""请分析以下代码中的问题并提供修复方案：
代码：

"""
    if error_message:
        prompt += f"\n错误信息：\n

response = client.chat.completions.create( model="deepseek-coder", messages=[{"role": "user", "content": prompt}], temperature=0.2 ) return response.choices[0].message.content

<h3>4. 代码重构</h3>

{code}

重构目标： 1. 提高可读性 2. 优化性能 3. 增强可维护性 """

if requirements: prompt += "\n额外要求：\n" + "\n".join(f"- {r}" for r in requirements) response = client.chat.completions.create( model="deepseek-coder", messages=[{"role": "user", "content": prompt}] ) return response.choices[0].message.content

<h2>六、错误处理与最佳实践</h2>
<h3>1. 错误处理</h3>

def safe_chat(messages: list, max_retries: int = 3) -> str: """带重试的安全调用""" for attempt in range(max_retries): try: response = client.chat.completions.create( model="deepseek-chat", messages=messages ) return response.choices[0].message.content except RateLimitError as e: wait_time = 2 ** attempt # 指数退避 print(f"触发限流，等待 {wait_time} 秒后重试...") time.sleep(wait_time) except APIConnectionError as e: print(f"网络连接错误: {e}") if attempt < max_retries - 1: time.sleep(1) continue raise except APIError as e: print(f"API 错误: {e}") raise raise Exception("达到最大重试次数")

<h3>2. 批量处理</h3>

async_client = AsyncOpenAI( api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com/v1" )

async def async_chat(prompt: str) -> str: """异步单次请求""" response = await async_client.chat.completions.create( model="deepseek-chat", messages=[{"role": "user", "content": prompt}] ) return response.choices[0].message.content

async def batch_chat(prompts: list) -> list: """批量异步请求""" tasks = [async_chat(prompt) for prompt in prompts] results = await asyncio.gather(*tasks) return results

# 使用示例 async def main(): prompts = [ "什么是机器学习？", "什么是深度学习？", "什么是强化学习？" ] results = await batch_chat(prompts) for q, a in zip(prompts, results): print(f"Q: {q}\nA: {a}\n")

asyncio.run(main())

<h3>3. 缓存优化</h3>

class ResponseCache: def __init__(self): self.cache = {} def _hash_key(self, messages: list) -> str: """生成缓存键""" key_str = json.dumps(messages, sort_keys=True) return hashlib.md5(key_str.encode()).hexdigest() def get(self, messages: list) -> str: """获取缓存""" key = self._hash_key(messages) return self.cache.get(key) def set(self, messages: list, response: str): """设置缓存""" key = self._hash_key(messages) self.cache[key] = response

# 使用缓存 cache = ResponseCache()

def cached_chat(prompt: str) -> str: """带缓存的对话""" messages = [{"role": "user", "content": prompt}] # 检查缓存 cached = cache.get(messages) if cached: print("从缓存返回") return cached # 调用 API response = client.chat.completions.create( model="deepseek-chat", messages=messages ) result = response.choices[0].message.content # 缓存结果 cache.set(messages, result) return result

<h2>七、与框架集成</h2>
<h3>1. 与 LangChain 集成</h3>

# 使用 DeepSeek 作为 LangChain 的 LLM llm = ChatOpenAI( model="deepseek-chat", openai_api_key=os.getenv("DEEPSEEK_API_KEY"), openai_api_base="https://api.deepseek.com/v1" )

# 创建链 prompt = ChatPromptTemplate.from_template("请用{style}风格解释：{topic}") chain = LLMChain(llm=llm, prompt=prompt)

# 执行 result = chain.run(style="幽默", topic="量子力学") print(result)

<h3>2. 构建聊天机器人</h3>

def create_chatbot(): """创建聊天机器人界面""" def chat(message, history): """处理聊天消息""" messages = [] # 添加历史对话 for human, assistant in history: messages.append({"role": "user", "content": human}) messages.append({"role": "assistant", "content": assistant}) # 添加当前消息 messages.append({"role": "user", "content": message}) # 调用 API response = client.chat.completions.create( model="deepseek-chat", messages=messages, stream=True ) # 流式输出 partial_message = "" for chunk in response: if chunk.choices[0].delta.content is not None: partial_message += chunk.choices[0].delta.content yield partial_message # 创建 Gradio 界面 demo = gr.ChatInterface( chat, title="DeepSeek 聊天机器人", description="基于 DeepSeek API 的智能对话助手" ) return demo

# 启动 # demo = create_chatbot() # demo.launch()

<h3>3. 构建知识库问答系统</h3>

def build_knowledge_base(docs_path: str): """构建知识库""" # 加载文档 loader = TextLoader(docs_path) documents = loader.load() # 分割文档 text_splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50 ) texts = text_splitter.split_documents(documents) # 创建向量存储（使用 DeepSeek 的嵌入） embeddings = OpenAIEmbeddings( openai_api_key=os.getenv("DEEPSEEK_API_KEY"), openai_api_base="https://api.deepseek.com/v1" ) vectorstore = FAISS.from_documents(texts, embeddings) return vectorstore

def query_knowledge_base(vectorstore, query: str) -> str: """查询知识库""" # 检索相关文档 docs = vectorstore.similarity_search(query, k=3) context = "\n\n".join([doc.page_content for doc in docs]) # 构建提示 prompt = f"""基于以下内容回答问题：

{context}

问题：{query}

请准确回答，如果内容中没有相关信息，请说明。""" # 调用 API response = client.chat.completions.create( model="deepseek-chat", messages=[{"role": "user", "content": prompt}] ) return response.choices[0].message.content

<h2>八、性能优化与成本控制</h2>
<h3>1. Token 优化</h3>

def truncate_history(messages: list, max_tokens: int = 4000) -> list: """截断对话历史，控制 token 数量""" # 保留最近的对话 # 实际应用中需要计算 token 数量 return messages[-10:] # 简化示例

<h3>2. 成本监控</h3>

# 使用 tracker = CostTracker()

response = client.chat.completions.create( model="deepseek-chat", messages=[{"role": "user", "content": "你好"}] )

tracker.track(response.usage)

<h2>九、安全与隐私</h2>
<h3>1. 敏感信息处理</h3>

def sanitize_input(text: str) -> str: """清理敏感信息""" # 移除可能的敏感信息 patterns = [ (r'\b\d{15,19}\b', '[卡号]'), # 银行卡号 (r'\b1[3-9]\d{9}\b', '[手机号]'), # 手机号 (r'\b[\w.-]+@[\w.-]+\.\w+\b', '[邮箱]'), # 邮箱 ] for pattern, replacement in patterns: text = re.sub(pattern, replacement, text) return text

<h3>2. 内容审核</h3>

<h2>十、实战项目：智能编程助手</h2>
将所学知识整合成一个完整的编程助手：

# 使用示例 # assistant = ProgrammingAssistant(os.getenv("DEEPSEEK_API_KEY")) # code = assistant.generate_code("实现一个 LRU 缓存") # explanation = assistant.explain_code(code) `

十一、总结

DeepSeek API 以其优秀的性能和极具竞争力的价格，为开发者提供了构建 AI 应用的优质选择。通过本指南，你已经掌握了：