本文面向 Python 开发者，系统讲解 DeepSeek API 的接入、对话管理、函数调用与成本优化，帮助读者从基础调用进阶到生产级集成。
DeepSeek 开放平台提供与 OpenAI 兼容的 HTTP 接口，Python 开发者可以沿用 openai 库的调用习惯，只需替换 base_url 和模型名称。对于 AI 指导老师而言，这意味着可以快速搭建代码辅导、习题生成和知识问答等教学工具。但要把原型变成稳定服务，需要掌握消息结构、流式响应、工具调用和错误恢复等关键环节。以下内容从环境配置开始，逐步深入工程实践。
1. 环境配置与首次 API 调用
在 DeepSeek 平台注册账号并创建 API Key，建议将密钥写入环境变量，例如 DEEPSEEK_API_KEY，避免硬编码。Python 环境要求 3.8 以上，使用 pip install openai 安装官方 SDK，当前 1.x 版本对 DeepSeek 的兼容性最好。初始化客户端时，将 base_url 指向 ，不要遗漏 v1 路径的兼容写法，部分旧版 SDK 需要写成 。模型选择上，通用对话用 deepseek-chat，复杂推理用 deepseek-reasoner，后者会在响应中返回思维链字段，适合数学和逻辑任务。
首次调用可构造一个教学场景：让模型解释 Python 装饰器。代码中创建 messages 列表，包含 system 角色设定“你是一名耐心的 Python 指导老师”，以及 user 角色提问。调用 client.chat.completions.create(model="deepseek-chat", messages=messages) 后，从 response.choices[0].message.content 读取文本。注意 DeepSeek 按 token 计费，输入和输出分别计价，首次测试可设置 max_tokens=256 控制成本。若返回为空，检查 finish_reason 是否为 length，并确认账户余额。
为了验证环境是否正常，可以打印 response.usage，观察 prompt_tokens、completion_tokens 和 total_tokens。教学场景中，建议将每次调用的耗时和 token 消耗记录到日志，为后续优化提供依据。若遇到连接错误，优先检查网络代理和 DNS 解析，DeepSeek 的 API 域名在国内可直接访问，通常不需要额外代理。完成这一步后，就具备了最基本的模型交互能力。
2. 多轮对话与流式输出
多轮对话的核心是维护 messages 列表。每轮将用户输入以 {"role": "user", "content": ...} 追加，再把模型回复以 {"role": "assistant", "content": ...} 追加，下一次请求时传入完整列表。教学助手需要记住学生之前问过的知识点，例如先问“列表推导式”，再问“它和生成器表达式的区别”，模型必须依赖历史消息才能给出连贯回答。但上下文长度有限，DeepSeek 当前模型支持 64K 上下文，超出后会报错或截断，因此需要设计摘要策略，把较早的对话压缩成简短摘要或只保留最近若干轮。
流式输出能显著改善交互体验。调用时将 stream=True，响应变为可迭代对象，每次返回一个 chunk，内容位于 chunk.choices[0].delta.content。在终端或 Web 前端逐字打印，学生不必等待完整响应。需要注意，流式模式下 usage 字段通常只在最后一个 chunk 出现，且部分 chunk 的 delta 可能为空。建议在循环中判断 content 是否为 None，再决定是否输出。对于教学直播或代码演示，流式输出还能让教师实时观察模型推理方向，及时中断错误回答。
异步场景可使用 AsyncOpenAI，配合 async for 遍历流。FastAPI 或 Django 的异步视图里，这种可以避免阻塞事件循环。一个常见案例是在线编程辅导平台，学生提交代码后，后端同时调用 DeepSeek 进行错误分析和优化建议，流式返回给前端。此时要设置合理的超时时间，例如 30 秒，并在客户端断开时取消请求，防止资源浪费。多轮对话与流式输出的组合，是构建教学聊天机器人的基础。
3. 函数调用与结构化数据生成
函数调用让模型能够连接外部工具。DeepSeek 的 deepseek-chat 支持 OpenAI 风格的 tools 参数，开发者用 JSON Schema 描述函数名称、参数和用途。例如定义一个 run_python_code 函数，接收 code 字符串，模型在需要执行代码时会返回 tool_calls，而不是直接生成最终答案。收到后，应用程序在沙箱中执行代码，再把结果以 {"role": "tool", "tool_call_id": ..., "content": ...} 回传，模型据此继续推理。教学场景中，这可以用来验证学生代码是否通过单元测试，或自动计算算法复杂度。
结构化输出适用于生成练习题、评分表或知识点卡片。设置 response_format={"type": "json_object"} 后，模型会尽量返回合法 JSON，但提示词中必须明确字段结构，例如要求返回 {"question": "...", "options": [...], "answer": "..."}。DeepSeek 对 JSON 模式的支持较好，但仍可能因提示模糊而生成多余文本。建议在系统消息中强调“只输出 JSON，不要添加解释”，并在代码中用 json.loads 解析，捕获 JSONDecodeError 后重试。对于批量生成习题的任务，可以先用少量样本测试字段稳定性，再扩大规模。
函数调用与结构化输出结合，可以构建自动批改系统。假设学生提交一道 Python 编程题，模型先通过函数调用运行测试用例，获取通过率，再按预设 JSON 格式输出评语、得分和改进建议。这里要注意安全，执行代码必须在隔离容器中进行，限制 CPU、内存和运行时间。DeepSeek 本身不执行代码，只负责决策和生成，因此沙箱由开发者维护。把工具调用结果作为新消息追加后，模型能基于真实执行结果给出反馈，比单纯让模型“猜”代码是否正确可靠得多。
4. 错误处理、成本控制与性能优化
生产环境必须处理 API 异常。常见错误包括 401 无效密钥、429 速率限制、500 服务端错误和超时。建议使用指数退避重试，首次等待 1 秒，随后 2 秒、4 秒，最多重试 3 次，并加入随机抖动避免惊群。对于 429，要检查账户的并发限制和 RPM/TPM 配额，教学平台在高峰时段可能同时有大量学生请求，需要在前端排队或降低并发。使用 try...except 捕获 openai.APIError 及其子类，记录请求 ID 和错误信息，便于向 DeepSeek 支持团队反馈。
成本控制从 token 管理开始。每次调用后读取 response.usage，累计输入和输出 token，按 DeepSeek 的定价估算费用。优化手段包括：把固定系统提示压缩到最短，删除无关历史消息，对长文档先分段摘要再提问，以及为常见问题建立本地缓存。例如同一道 Python 基础题的解释，如果多个学生重复提问，可以缓存模型回复，设置 24 小时过期。选择模型时，简单问答用 deepseek-chat，复杂推理才用 deepseek-reasoner，后者输出 token 更多，成本更高。
性能优化还包括异步并发和连接复用。使用 httpx 作为底层传输时，可以配置连接池和超时。对于批量任务，不要串行调用，而是用 asyncio.gather 并发执行，但要注意控制并发数，例如通过 asyncio.Semaphore(5) 限制同时请求。监控方面，记录 P95 延迟、错误率和 token 消耗趋势，当错误率超过 1% 时触发告警。教学系统还可以在模型响应前显示“正在思考”，用流式输出降低等待焦虑。经过这些调整，Python 集成才能从入门示例走向稳定可靠的生产服务。
