围绕DeepSeek接入Dify的模型配置、工作流编排与教学场景验收，梳理可复用的实施路径和风险控制要点。
在AI指导老师场景里，DeepSeek承担讲解生成、错题归因和追问引导，Dify负责模型接入、知识库检索、工作流编排与日志留痕。把两者接起来并不是填一个API Key就结束，接口兼容性、上下文长度、流式输出、计费口径和内容安全都会影响教学体验。实际落地时，需要把模型能力拆到具体教学环节，用可验证的配置和可回滚的发布流程控制风险。
1. 接入前的模型与接口核对
DeepSeek提供OpenAI兼容接口，Dify可以通过OpenAI-API-compatible模型供应商接入。配置前要核对Base URL、模型名和认证，常见Base URL为://api.deepseek.com，具体取决于Dify版本对路径拼接的处理；模型名可选用deepseek-chat和deepseek-reasoner。教学场景中，chat更适合日常答疑、知识点讲解和多轮追问，reasoner更适合复杂解题与多步推理，但首token延迟通常更高。还需要确认上下文窗口、最大输出token、流式支持、并发限制和计费口径，避免上线后才发现长题目被截断或高峰期限流。
接口兼容不等于行为完全一致。OpenAI兼容层在参数命名、错误码、流式分片和工具调用支持上可能存在差异，Dify测试连接时要重点观察401认证失败、404路径错误、429限流和请求超时。AI指导老师往往需要多轮对话，历史消息不能整段课堂记录直接塞入上下文，应按学科、学段和最近轮次做裁剪。某职业教育内容团队用20条典型问题做冒烟测试，覆盖数学公式、编程代码和语言学习，发现reasoner在直播答疑中首token延迟偏高，后来把日常答疑切到chat，复杂题放到异步工作流处理。
接入前还要准备测试题集和合规边界。学生隐私、题目版权和日志脱敏应在接口层确认，API Key放入环境变量或Dify凭证管理，不暴露到前端。模型版本和计费口径也要核对，免费额度到期或模型下线会直接影响线上服务。开发、测试、生产环境使用不同Key并分配最小权限，避免一个Key贯穿所有工作区，后续排查成本和权限问题时才不至于失去控制。
2. Dify侧模型供应商配置
在Dify控制台选择OpenAI-API-compatible供应商后，需要填写API Key、Base URL和模型名，并将模型类型设为LLM，再设置上下文长度、最大token、温度和流式输出。Dify会把这些配置封装成模型凭证，供工作流LLM节点和Agent调用。教学团队不要只建一个模型条目，可以按任务建立chat和reasoner两个条目，工作流根据意图路由。答疑节点温度控制在0.2到0.4更利于稳定讲解，知识库检索后的回答节点要限制最大token，防止长答案拖慢前端。流式输出对前端体验重要，但需要后置处理时关闭流式或做缓冲。
凭证管理和多环境隔离是配置阶段容易忽略的细节。开发、测试、生产应使用不同API Key或项目，Dify工作区也要隔离。多学科团队按学科建应用，不共用一个模型配置随意改参数，因为模型配置变更会影响所有引用该凭证的应用。测试连接时要区分429限流、401认证失败和404路径错误，Dify中的重试策略可用指数退避，超时设置不宜过长，否则教学高峰会出现排队。每次修改模型名或Base URL都应记录变更人和时间，便于回滚。
参数需要和提示词配合。温度、top_p、最大token和上下文长度决定输出风格与长度，AI指导老师需要稳定讲解，温度不宜过高。reasoner对温度参数的支持可能与chat不同，配置时以实际测试为准。提示词里写清学段、学科、讲解粒度和输出结构，模型参数只负责风格和长度控制。配置完成后先做小流量验证，观察首token延迟、答案完整性和知识库引用情况，再决定是否扩大到正式班级。
3. 工作流与教学Agent编排
Dify工作流可组合开始、知识库检索、LLM、条件分支、代码、变量聚合和结束节点。教学流程可以设计为学生输入题目后先做意图分类，区分知识点问答、错题诊断和学习计划，再检索课程知识库，由DeepSeek生成分步讲解，最后进入追问引导。系统提示词要写清角色、学段、讲解粒度和禁止超纲要求。某K12辅导团队用条件分支把客观题导向判题加解析，把主观题导向评分要点加改进建议；知识库检索top_k控制在3到5并做重排，先筛选片段再交给模型，避免无关材料干扰讲解。
Agent与工作流的选择要看教学任务的可控性。Dify Agent适合开放式工具调用和探索型任务，工作流更适合确定性教学流程。AI指导老师需要可解释和可审计，优先用工作流固化关键步骤。变量可以传递学生年级、学科和历史错题，会话变量保存学段和薄弱点，DeepSeek在长链工作流中要控制上下文，只传最近几轮对话和检索片段。这样既能保留追问连续性，也能降低token消耗和幻觉概率。
提示词模板和输出结构决定前端渲染效率。教学回答可要求输出结论、步骤、易错点和追问，便于页面分块展示。结构化输出需要测试DeepSeek兼容性，不稳定时用代码节点校验JSON格式。内容安全节点和敏感词过滤应放在生成之后、返回之前。某职业教育团队把代码题讲解拆成代码格式校验和讲解生成两个节点，减少模型输出格式错误，也方便教师抽查。工作流版本发布前保留旧版本，出现教学事故时可快速切回。
4. 联调、监控与教学场景验收
联调要从单节点走向端到端，依次验证模型连接、单轮问答、多轮追问、知识库命中和异常分支。监控指标包括首token延迟、总延迟、请求成功率、429和5xx比例、token消耗、单次答疑成本、知识库命中率与追问完成率。Dify日志能记录节点输入输出，便于定位是检索问题还是模型生成问题。教学验收用同一组题对比教师评分，重点看步骤完整性、知识点准确性、超纲比例和事实性错误。灰度发布先放10%流量，观察一周后再扩大范围。
成本与稳定性需要同步控制。DeepSeek按token计费，教学高峰集中在晚间，限流和队列不能缺。工作流中设置最大token和超时，失败时降级到chat模型或固定话术，避免学生长时间等待。API Key定期轮换，日志脱敏，学生隐私信息不落盘。模型版本变化会改变输出风格和推理长度，每次升级都要跑回归测试，重点覆盖数学步骤、代码可运行性和语言表达准确性。
教学效果闭环依赖真实数据回流。收集学生追问、教师批注和低评分回答，定期更新知识库和提示词。知识库命中率低的章节补材料，教师批注进入下一轮提示词优化，线上异常样本回流到测试题集，下一轮灰度再用同一批指标复测。每次模型配置变更记录版本、测试题结果和线上指标，形成可追溯的教学质量台账。
