从环境搭建、密钥托管到流式对话与工程化封装，完整走通Python调用DeepSeek API的落地路径，并给出教学场景下的稳定性与成本控制要点。
DeepSeek开放平台在接口层面兼容OpenAI的调用规范，这意味着熟悉openai库的开发者几乎不需要重写调用层，替换base_url与模型名就能完成迁移。对AI指导老师来说，这种兼容性带来的直接价值是教学示例可以复用，学员不必在两套SDK之间反复切换。但真正把接口用稳，远不止跑通一行client.chat.completions.create，密钥如何托管、流式输出如何拼接、多轮上下文如何裁剪、异常如何重试，都是实际项目里绕不开的环节。下面按一条完整的落地路径展开，代码以可直接运行的最小片段呈现，并在关键处标注容易踩坑的细节。
1. 依赖选型与本地环境准备
动手写第一行代码之前，先把Python版本和依赖版本固定下来，能省掉后面大量莫名其妙的报错。建议使用Python 3.9及以上版本，用venv创建独立虚拟环境，避免与系统里其他项目的包相互污染。openai库必须使用1.x版本，这一点尤其重要：0.x时代的openai.ChatCompletion.create写法在1.x中已被彻底移除，而网络上仍有大量旧教程在流传，学员照抄后遇到AttributeError往往一头雾水。安装时直接在命令中锁定大版本，可以让环境在数月后重建时依然一致。
“python python -m venv .venv # macOS / Linux source .venv/bin/activate # Windows # .venv\Scripts\activate pip install "openai>=1.30,<2.0" python-dotenv “
选择openai SDK而不是直接用requests裸调HTTP接口，理由在于前者已经封装了连接池复用、超时控制、指数退避重试和完整的类型提示，这些能力自己实现一遍既费时又容易出错。当然，如果课程目标是讲清楚SSE协议本身，用requests配合iter_lines手写解析依然有价值，但那属于原理课，不适合作为第一个可运行示例。
目录结构上建议保持极简：项目根目录放置demo.py作为入口，.env存放密钥，requirements.txt记录固定版本，.gitignore里务必写入.env和.venv。requirements.txt中把版本写成openai==1.30.0这类精确值，而不是留空或写>=，这样学员在不同机器上复现出来的行为才会一致。虚拟环境目录不要提交到仓库，否则仓库体积会迅速膨胀到几百兆。
2. 密钥托管与首个可用调用
API Key在DeepSeek开放平台的控制台创建，创建后只完整显示一次，务必立即复制保存。密钥绝不能硬编码进源码，一旦提交到公开仓库，爬虫扫描到之后几分钟内就可能被刷走余额。正确做法是通过环境变量注入，本地开发用python-dotenv从.env读取，线上部署则使用平台提供的密钥管理服务。代码里用os.environ读取，并在启动阶段做一次非空校验，缺失时直接抛出明确错误，而不是等到发起请求才返回401。
“`python import os from dotenv import load_dotenv from openai import OpenAI
load_dotenv api_key = os.environ.get(“DEEPSEEK_API_KEY”) if not api_key: raise RuntimeError(“未找到 DEEPSEEK_API_KEY，请检查 .env 文件”)
client = OpenAI(api_key=api_key, base_url=”https://api.deepseek.com”)
resp = client.chat.completions.create( model=”deepseek-chat”, messages=[ {“role”: “system”, “content”: “你是一位耐心的Python助教。”}, {“role”: “user”, “content”: “用三句话解释什么是生成器。”}, ], temperature=0.7, max_tokens=512, timeout=30, ) print(resp.choices[0].message.content) print(resp.usage) “`
base_url写即可，SDK会自动拼接/chat/completions路径；写成带/v1的形式同样可用，因为平台保留了OpenAI兼容路径。模型方面，deepseek-chat对应通用对话模型，适合绝大多数教学问答；deepseek-reasoner是推理模型，会在响应中额外返回reasoning_content字段，展示思考过程，这个字段不应直接混入最终答案展示给学员，否则界面会显得杂乱。调用成功后重点看usage字段，其中prompt_tokens、completion_tokens、prompt_cache_hit_tokens、prompt_cache_miss_tokens直接决定本次请求的费用，把这几项打印出来，学员对成本的感知会立刻具体起来。常见错误码也要能读懂：401是密钥无效或未加载，402是余额不足，429是触发限流，400多半是模型名拼错或参数越界。
3. 流式输出与多轮上下文管理
对话类应用如果等完整响应再一次性渲染，用户会盯着空白界面好几秒，体验很差。开启stream=True后，服务端以SSE逐块推送，前端可以边收边显示。解析时遍历chunk.choices[0].delta.content，需要注意首个数据包的delta可能只包含role字段，content为None，直接拼接会抛类型错误，必须先做判空。使用推理模型时还要单独取出delta.reasoning_content，把它渲染到“思考中”的可折叠区域，正文区只显示最终内容，这样既保留了推理透明度，又不干扰阅读。
“python stream = client.chat.completions.create( model="deepseek-chat", messages=messages, stream=True, ) for chunk in stream: delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True) “
多轮对话的本质是把历史消息按顺序追加进messages列表，每次请求都完整带上。这会带来两个实际问题：上下文长度有上限，以及token费用随轮次线性增长。deepseek-chat的上下文窗口为64K token，看起来宽裕，但一份长文档加十几轮追问就能逼近上限。实践中常用的裁剪策略是保留system提示、最近若干轮原文，再对更早的对话做一次摘要压缩后作为一条system消息插入，既控制了长度，又保住了关键背景。另外，流式请求一旦网络中断，已经输出的内容无法回滚，需要在异常分支里给前端打上“回答不完整”的标记，并提供重新生成按钮，而不是让半截答案留在屏幕上误导用户。
4. 工程化封装与教学场景的稳定性设计
把调用逻辑散落在各处是维护灾难的开始，应该尽早封装成一个类或一组函数，统一处理客户端初始化、重试策略、超时和日志。重试不要简单地写while循环，openai SDK自带max_retries参数，配合指数退避能有效应对429和5xx；对401、402这类不可恢复错误则应立即失败，重试只会浪费时间。每次请求结束后记录一条结构化日志，包含响应id、模型名、输入输出token数、耗时，这些字段在排查问题和核对账单时非常关键，尤其是响应id，它是与平台侧对账的唯一凭据。
教学场景往往面临几十名学员在同一时段集中调用的情况，很容易触发限流。解决办法是用信号量或队列控制并发度，异步场景下使用AsyncOpenAI配合asyncio.Semaphore，把并发数压到账号配额允许的范围内，再让请求排队而不是直接失败。同步场景可以用线程池加固定大小的工作队列，效果类似。对于课堂上反复出现的相同提问，在应用层加一层结果缓存能显著降低成本，也能让响应从两三秒降到毫秒级。
成本控制要落到可执行的机制上。按usage累计每个学员、每次会话的token消耗，设置日预算阈值，超出后自动降级到更短的max_tokens或直接拒绝。固定不变的长系统提示词放在messages最前面，可以命中平台的上下文缓存，输入侧费用会明显下降，这个细节在批量评测和长文档问答中收益尤其可观。提示词本身也应该版本化，把不同版本的system内容存成独立文件并记录对应的效果指标，否则改了措辞之后效果变好还是变坏，根本无从判断。把这些环节都补齐，一个能扛住真实课堂流量的接入层才算真正成形。
