DeepSeek API 深度解析：从流式输出、Function Calling 到构建拥有“手脚”的 AI 应用

DeepSeek API 深度解析：从 Key 申请到构建第一个 AI 应用

前言

在上一波 AI 浪潮中，我们见识了 DeepSeek-V3 和 R1 的强大。对于开发者而言，DeepSeek 最大的吸引力在于：它完全兼容 OpenAI 格式的 API，且价格仅为 GPT-4o 的几十分之一。

很多教程只教了最简单的"问答"。但如果你想开发一个真正的 AI 助手（比如能查天气、能读数据库），光会问答是不够的。

本文将深入 DeepSeek API 的高级特性，涵盖：

1. 流式响应 (Streaming)： 像 ChatGPT 一样打字机式输出。
2. 多轮对话 (Context)： 如何让 AI 记住上下文。
3. Function Calling (工具调用)： 让 AI 具备执行代码或联网的能力。
4. 实战： 构建一个带有思维链（CoT）展示的终端助手。

---

一、 环境准备与基础配置

DeepSeek 官方兼容 OpenAI SDK，这意味着你不需要学习新的库。

1. 安装依赖

pip install openai python-dotenv

2. 基础配置

为了安全，建议将 API KEY 放在 .env 文件中，而不是硬编码在代码里。

# .env 文件内容
# DEEPSEEK_API_KEY="sk-你的key"

初始化客户端代码：

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"  # ⚠️ 必须指定 base_url
)

---

二、 进阶特性 I：流式输出 (Streaming)

在构建 Chatbot 时，如果等待 AI 生成完所有文字再显示，用户体验会非常差。流式输出可以让用户实时看到 AI 的生成过程。

代码实现

关键参数是 stream=True。

def chat_stream(prompt):
    response = client.chat.completions.create(
        model="deepseek-chat", # 指向 V3 模型
        messages=[
            {"role": "system", "content": "你是一个乐于助人的助手"},
            {"role": "user", "content": prompt}
        ],
        stream=True  # 开启流式模式
    )
    
    print("AI: ", end="", flush=True)
    for chunk in response:
        # 获取当前生成的字符
        content = chunk.choices[0].delta.content
        if content:
            print(content, end="", flush=True)
    print() # 换行

# 测试
chat_stream("请用300字解释量子纠缠")

原理： response 变成了一个生成器，我们循环读取 chunk，实现"打字机"效果。

---

三、 进阶特性 II：DeepSeek-R1 的思维链 (Chain of Thought)

DeepSeek-R1 是推理模型，它的特点是会在输出最终答案前，先输出一段"思考过程"。在 API 中，我们需要特殊处理才能看到这段精彩的"内心戏"。

• 模型名称： deepseek-reasoner
• 注意事项： R1 模型目前暂不支持 Function Calling。

获取思考过程代码

def chat_with_reasoning(prompt):
    response = client.chat.completions.create(
        model="deepseek-reasoner", # ⚠️ 切换为 R1 模型
        messages=[
            {"role": "user", "content": prompt}
        ],
        stream=True
    )

    print("\n=== 思考过程 ===")
    for chunk in response:
        # ⚠️ R1 的思考内容在 reasoning_content 字段中
        reasoning = getattr(chunk.choices[0].delta, 'reasoning_content', None)
        content = chunk.choices[0].delta.content
        
        if reasoning:
            print(reasoning, end="", flush=True)
        elif content:
            # 当思考结束，开始输出正文时，reasoning 为空，content 有值
            if not hasattr(chat_with_reasoning, "flag"):
                print("\n\n=== 最终回答 ===")
                chat_with_reasoning.flag = True
            print(content, end="", flush=True)

# 测试一个逻辑题
chat_with_reasoning("9.11 和 9.8 哪个大？")

---

四、 核心深水区：Function Calling (工具调用)

这是区别"聊天机器人"和"AI Agent"的分水岭。通过 Function Calling，DeepSeek 可以理解你的意图，决定是否需要调用外部函数（如查天气、查数据库），并根据函数返回的结果生成回答。

场景模拟： 用户问"杭州天气怎么样？"，AI 自动调用天气 API。

1. 定义工具 (Tools)

首先，我们要告诉 AI 我们有哪些工具可用。

# 模拟一个查询天气的函数
def get_weather(location):
    # 这里可以是真实的 API 调用，比如高德/心知天气
    if "杭州" in location:
        return '{"temperature": "15", "condition": "Cloudy"}'
    elif "北京" in location:
        return '{"temperature": "-2", "condition": "Snow"}'
    return '{"temperature": "unknown"}'

# 定义工具描述 (JSON Schema)
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定地点的当前天气情况",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "城市名称，如：北京、杭州"
                    }
                },
                "required": ["location"]
            }
        }
    }
]

2. 发送请求并处理调用

AI 不会自己执行代码，它会返回"请帮我执行 xxx 函数"的指令，我们需要捕获这个指令，执行 Python 代码，再把结果传回给 AI。

import json

def run_agent(user_query):
    messages = [{"role": "user", "content": user_query}]

    # 第一轮交互：询问 AI
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=messages,
        tools=tools, # 注入工具
        tool_choice="auto" # 让 AI 自动决定是否使用工具
    )

    response_message = response.choices[0].message
    tool_calls = response_message.tool_calls

    # 如果 AI 决定要调用工具
    if tool_calls:
        print(f"🤖 AI 决定调用工具: {tool_calls[0].function.name}")
        
        # 将 AI 的回复（包含函数调用需求）加入历史记录
        messages.append(response_message)

        # 遍历所有需要调用的函数
        for tool_call in tool_calls:
            function_name = tool_call.function.name
            function_args = json.loads(tool_call.function.arguments)
            
            # 手动执行 Python 函数
            if function_name == "get_weather":
                function_response = get_weather(
                    location=function_args.get("location")
                )
                
                # 将函数执行结果作为 "tool" 类型的消息传回给 AI
                messages.append({
                    "tool_call_id": tool_call.id,
                    "role": "tool",
                    "name": function_name,
                    "content": function_response,
                })

        # 第二轮交互：将函数结果给 AI，让它生成最终自然语言回复
        second_response = client.chat.completions.create(
            model="deepseek-chat",
            messages=messages
        )
        return second_response.choices[0].message.content
    else:
        return response_message.content

# 测试
print("User: 杭州今天天气如何？")
result = run_agent("杭州今天天气如何？")
print(f"Agent: {result}")

运行结果预期：

1. 用户发问。
2. DeepSeek 分析出需要调用 get_weather，参数是 杭州。
3. Python 代码执行函数，拿到 {"temperature": "15", ...}。
4. DeepSeek 收到 JSON 数据，转换成自然语言："杭州今天多云，气温 15 度。"

---

五、 总结与最佳实践

接入 DeepSeek API 后，你实际上已经拥有了构建复杂 AI 应用的基础。

几点避坑指南：

1. 超时设置： DeepSeek-R1（推理版）思考时间较长，建议将 timeout 设置得长一些（如 60秒以上）。
2. 上下文长度： 虽然 API 便宜，但无限堆叠历史记录会消耗大量 Token。建议使用"滑动窗口"策略，只保留最近 N 轮对话，或对旧记录进行摘要。
3. 模型选择： * 处理复杂逻辑、数学、代码生成 -> DeepSeek-R1 (deepseek-reasoner)

• 处理日常对话、格式化文本、Function Calling -> DeepSeek-V3 (deepseek-chat)

---