围绕AI教学与开发入门，拆解DeepSeek API从密钥创建、请求发送到流式响应与错误处理的最短闭环，帮助学习者在五分钟内完成首次可用调用。
DeepSeek API 兼容 OpenAI 的接口规范，这让已经用过 OpenAI SDK 的开发者几乎不需要重新学习一套协议。所谓“五分钟搞定”，并不是把生产级集成压缩成五分钟，而是先跑通最小闭环：拿到密钥、配置入口、发出第一条消息、看到模型返回。AI指导老师在实际带教中会发现，初学者卡住的地方往往不是模型能力，而是密钥写错位置、base_url遗漏、模型名混淆或账户余额不足。先把这些环节逐一确认，后面的多轮对话、流式输出和工程封装才有稳定基础。
1. 账号、密钥与调用入口确认
打开 platform.deepseek.com 注册并登录，进入 API Keys 页面创建密钥。密钥通常只完整显示一次，复制后应立即放入环境变量，例如 DEEPSEEK_API_KEY，不要直接写进 notebook、Git 仓库或前端代码。教学场景中常见错误是把密钥提交到公开仓库，导致额度被刷。若使用 Colab，可用 secrets 面板保存；本地开发可用 .env 文件并加入 .gitignore。账户需要确认余额或赠送额度是否可用，否则后续请求可能返回 402。这个准备环节通常两分钟以内完成。
DeepSeek 的调用入口为 ，也兼容带 /v1 的写法。它兼容 OpenAI SDK，因此 Python 环境只需 pip install openai，然后初始化 OpenAI(api_key=..., base_url="https://api.deepseek.com")。模型名常用 deepseek-chat 与 deepseek-reasoner，前者适合通用对话、写作和代码辅助，后者适合需要推理链或复杂数学逻辑的任务。若把模型名写成 OpenAI 的 gpt-4o，请求会直接报模型不存在，这不是网络问题。
AI指导老师应把入口确认做成检查清单式口头提示，但不必让学生背参数。关键只有三项：密钥是否来自环境变量、base_url 是否指向 DeepSeek、模型名是否在可用列表内。确认后可以用官方文档的 curl 示例做一次最小连通测试，排除 SDK 版本、代理和证书干扰。五分钟目标里，这一节承担“把门打开”的作用，门没打开，后面所有优化都没有意义。
2. 最小请求结构与首个对话
最小请求可以用 Python 的 OpenAI SDK 完成。代码结构是：导入 OpenAI，从环境变量读取密钥，创建客户端，调用 client.chat.completions.create，传入 model 和 messages。messages 是对话数组，常见角色有 system、user、assistant。例如 system 设定“你是一位耐心的AI指导老师”，user 输入“用三句话解释什么是大语言模型API”。stream=False 时，程序会等待完整结果返回，适合第一次验证。
请求体里还可以加入 temperature、max_tokens、top_p 等参数。教学演示建议先把 temperature 设为 0.3 到 0.7，减少随机性；max_tokens 设为 256 或 512，避免课堂演示时等待过久或消耗过多额度。若用 curl，则向 发送 POST 请求，请求头包含 Content-Type: application/json 和 Authorization: Bearer $DEEPSEEK_API_KEY，请求体写入模型与消息数组。两种等价，选择自己熟悉的即可。
收到响应后，主要读取 response.choices[0].message.content。如果返回为空，先检查是否被内容过滤、是否达到 max_tokens、是否把流式响应当成非流式解析。AI指导老师可以让学生把原始响应打印出来，观察 id、model、usage 等字段，理解 token 消耗和请求标识。首个对话跑通后，再改为多轮消息，把上一轮 assistant 回复追加进 messages，就能形成连续对话。这个最小结构是后续所有应用的地基。
3. 流式输出、超时与错误定位
流式输出适合课堂演示和交互式应用。把 stream=True 传入请求后，返回对象变成可迭代的 chunk，每个 chunk 的 choices[0].delta.content 可能是一小段文字，也可能是空值。前端或 notebook 中逐段拼接并刷新，用户会感觉模型在实时打字。处理时要判断内容是否为 None，否则容易出现类型错误。DeepSeek 的流式格式与 OpenAI 兼容，因此已有 OpenAI 流式处理代码通常只需替换客户端配置。
生产或教学环境必须设置超时和重试。SDK 初始化时可配置 timeout=30，避免网络异常时无限等待；对 429 限流和 500、503 服务错误可做指数退避重试，但 401、402、400 不应盲目重试。401 通常表示密钥缺失或错误，402 表示余额不足，429 表示请求过快或额度受限，400 多数是参数格式、模型名或消息角色不合法。定位顺序建议先用 curl 排除 SDK 问题，再检查环境变量、base_url、模型名和账户余额。
教学场景还要处理代理与证书问题。部分校园网或企业网络会拦截 HTTPS，表现为连接超时或 SSL 证书错误，此时需要配置合规代理或更换网络。日志中不要打印完整密钥，可只保留前后各四位。对于流式输出，若中途断开，要捕获异常并给用户可读提示，而不是把堆栈直接抛到界面。把错误分类讲清楚，学生才能从“调用失败”变成“知道下一步查什么”。
4. 教学封装与可复用调用模板
当首个请求跑通后，AI指导老师应引导学生做一层轻量封装，而不是在每个 notebook 里复制粘贴。可以建立 deepseek_client.py，内部读取 DEEPSEEK_API_KEY，初始化客户端，提供 ask(prompt, system=None, stream=False) 函数。函数统一处理超时、重试、异常转换和返回值，外部只关心问题和答案。这样既减少密钥泄露面，也让课堂示例从“能跑”走向“可复用”。
在 Colab 或 Jupyter 中，密钥可通过 getpass 输入或平台 secrets 读取，避免出现在共享屏幕和导出文件中。项目结构可以保持简单：一个配置文件、一个客户端封装、一个演示 notebook。演示 notebook 只调用 client.ask("解释一下DeepSeek API的用途", system="你是AI指导老师")，学生能直观看到输入输出。若要支持多轮对话，可在封装内维护 messages 列表，或让调用方传入历史消息。成本控制方面，设置默认 max_tokens、对常见问题做缓存、限制并发和调用频率，都能避免教学账号被快速消耗。
评估教学效果时，不只看能否返回文字，还要记录延迟、token 用量、失败类型和重试次数。这些数据能帮助学生理解 API 工程的真实约束：模型能力只是其中一环，密钥管理、错误处理、成本控制和数据脱敏同样重要。对于涉及学生隐私或内部资料的内容，应避免直接发送到外部接口，必要时先做脱敏或改用本地模型。完成这一层封装后，五分钟的首次调用就变成了可扩展的教学脚手架。
