DeepSeek API 兼容 OpenAI 接口，掌握密钥配置、模型选择、请求参数、流式输出与错误治理，即可在教学中稳定调用大模型。 DeepSeek 开放平台把大模型能力封装为标准 HTTP 接口，开发者无需自建推理集群，只要按兼容 OpenAI 的发送请求，就能获得对话、推理、工具调用与 JSON 输出等能力。对 AI 指导老师而言，理解从鉴权到响应的完整链路，比死记某段代码更重要，因为课堂问答、作业批改和项目辅导都依赖稳定、可控、可计量的调用。
1. 从开放平台到密钥：调用前的准备工作
DeepSeek API 的调用起点是开放平台账号与 API Key。开发者登录 platform.deepseek.com 后，在 API Keys 页面创建密钥，系统通常只在创建时完整展示一次，因此应立即写入环境变量或密钥管理服务，而不是硬编码在脚本、前端代码或公开仓库中。Base URL 使用 ，该地址兼容 OpenAI 的接口规范，所以已有 OpenAI SDK 经验的团队可以较低迁移成本接入。对于 AI 指导老师，建议把密钥放在后端网关，由服务端统一签名转发，避免学员在浏览器端直接接触密钥。
准备阶段还要确认账户余额、可用模型与计费。DeepSeek 按输入与输出 token 计费，不同模型价格不同，缓存命中的输入 token 通常有折扣，因此长系统提示、固定课程资料和重复上下文可以通过缓存降低开销。安装 SDK 时，Python 项目可安装 openai 包，Node.js 项目可使用 openai npm 包；若使用 curl 或 HTTP 客户端，则需手动设置 Authorization 为 Bearer 密钥，Content-Type 为 application/json。网络层面要确认出口可访问 API 域名，企业内网可能需要代理或白名单。
教学项目在动手写代码前，最好先明确调用目标：是课程答疑、作业批改、代码解释，还是学习路径规划。不同目标决定系统提示、上下文长度和模型选择。涉及学生个人信息、成绩或内部讲义时，应在请求前做脱敏和最小化处理，只发送完成任务所需的文本。日志中避免记录完整密钥和敏感原文，可记录请求 ID、模型、token 用量和耗时，为后续成本核算与故障排查留下依据。
2. 请求结构与模型选择：Chat Completions 的核心参数
DeepSeek 的核心调用端点是 Chat Completions，即向 /chat/completions 发送 POST 请求。请求体以 JSON 组织，关键字段包括 model、messages、stream、max_tokens、temperature、top_p、stop、tools、tool_choice 和 response_format。messages 是对话数组，每个元素包含 role 与 content，role 可为 system、user、assistant 或 tool。system 消息适合放置 AI 指导老师的角色设定，例如学科范围、讲解风格、输出格式和安全边界；user 消息承载学生问题；assistant 消息保留历史回答，从而形成多轮上下文。工具调用时，tool 消息用于回传函数执行结果。
模型选择直接影响效果、速度与成本。deepseek-chat 适合通用对话、知识讲解、文案生成和常规代码问答，响应较快，参数支持较完整；deepseek-reasoner 更偏向数学、逻辑推理、复杂代码和分步思考任务，但可能对 temperature、top_p、presence_penalty、frequency_penalty 等采样参数支持有限，使用前应查阅最新文档。温度参数控制随机性，教学解释通常用较低值保证稳定，创意练习可适度调高。max_tokens 限制输出长度，既能控制费用，也能防止冗长回答；stream 决定是否流式返回；response_format 可要求 JSON 输出，适合结构化批改结果。
响应结构同样需要理解。非流式响应通常包含 id、object、created、model、choices 和 usage；choices 中的 message.content 是最终文本，finish_reason 表示停止原因，常见值有 stop、length 和 tool_calls。推理模型可能在 message 中额外提供 reasoning_content，用于展示思考过程，但工程上不应把该字段直接回传给下一轮对话。usage 记录 prompt_tokens、completion_tokens、total_tokens 以及缓存命中与未命中 token，是成本监控的重要依据。多轮教学对话中，历史消息会不断累积，需要按 token 预算裁剪、摘要或分段检索，否则容易触碰上下文上限并推高费用。
3. 代码落地与流式输出：Python 与 OpenAI SDK 实践路径
Python 是最常见的 DeepSeek API 调用语言。安装 openai 包后，用 OpenAI 类初始化客户端，传入 api_key 与 base_url，base_url 指向 。随后调用 client.chat.completions.create，传入 model 和 messages，即可得到非流式响应。典型教学问答中，messages 可先放一条 system 消息定义“你是耐心、严谨的 AI 指导老师”，再放 user 消息描述学生问题。若需要结构化输出，可在提示词中明确要求返回 JSON，并设置 response_format 为 json_object，同时在提示词中给出字段示例，降低解析失败概率。
流式输出对在线课堂体验非常关键。将 stream 设为 True 后，接口会以 SSE 形式逐段返回数据，代码通过迭代响应对象读取 chunk.choices[0].delta.content，并实时推送到前端。对于 deepseek-reasoner，delta 中可能先出现 reasoning_content，再出现 content，前端可以分栏展示思考与答案，但最终展示策略要符合教学伦理，避免让学生直接依赖未校验的推理过程。流式场景要处理空 delta、结束标记和网络中断，服务端应设置合理超时，前端应提供停止生成按钮，并在异常时给出友好提示。
工具调用与 JSON 输出是进阶用法。开发者可在 tools 中声明函数名称、描述和参数 schema，模型返回 tool_calls 后，后端执行真实函数，例如查询课表、计算分数或检索题库，再以 role 为 tool、携带 tool_call_id 的消息回传，让模型生成最终回答。异步并发可提升批量批改效率，但要配合信号量控制并发数，并对 429、500、503 等错误做指数退避重试。所有调用都应捕获异常、记录请求 ID 和用量，避免单个学生请求拖垮整个教学服务。
4. 教学场景中的工程化封装与稳定性治理
在 AI 指导老师场景中，直接在前端调用 DeepSeek API 是高风险做法。更合理的架构是后端代理：前端只调用自有接口，后端负责密钥管理、提示词模板、模型路由、内容审核和用量统计。课程问答可把教材片段、知识点和常见错误预置为 system 上下文，再结合用户问题生成回答；作业批改可要求模型按评分标准输出 JSON，包含得分、错误类型和改进建议；代码辅导则可让模型解释报错、给出修复思路，而不是直接代写完整作业。通过统一封装，教师可以随时调整教学策略，而无需改动客户端。
稳定性治理离不开限流、重试与成本控制。DeepSeek API 可能因余额、并发或服务状态返回 401、402、429、500、503 等错误，后端应区分鉴权失败、余额不足、限流和临时故障，分别采取告警、充值、退避重试和降级回复。批量任务可使用异步队列，把非实时请求排队处理；实时对话则优先使用流式输出，降低首字等待。成本方面，应监控 token 用量，压缩重复提示，利用上下文缓存，按任务难度选择 deepseek-chat 或 deepseek-reasoner，避免所有请求都走推理模型。
安全与合规是教学落地的底线。学生姓名、学号、成绩、等敏感信息应在发送前脱敏，内部讲义和未公开试题要评估版权与保密要求。模型输出需要经过关键词过滤、格式校验和人工抽检，尤其是涉及价值观、心理辅导和学术诚信的内容。日志保留请求 ID、模型、耗时和 token 用量即可，避免存储完整对话原文。随着 DeepSeek 模型版本和参数支持不断更新，教学团队应建立文档复查机制，把 API 变更纳入版本管理，确保课堂服务长期可用。
