深入阅读

做完以后，理解这些选择

操作步骤、配置和验收已集中在三步跟练。本页解释为什么这样拆分、模型如何用工具，以及能从这次练习学到什么。

你与 Qoder 如何分工

你决定任务、提供服务商信息并验收结果；Qoder 检查环境、编写代码、安装依赖和排错。环境安装不应成为本课先修知识，但系统授权、账号登录和自己的密钥仍由你处理。

为什么这次选择 FastAPI

本课选框架的重点，是让交付物容易验证，让错误容易定位。业务同事不必先写一个前端，就能亲手查工作日。这个反馈速度，比在小练习里追求性能指标更有教学价值。

• Swagger UI 让人直接试。FastAPI 默认提供 /docs，可看接口、填参数、执行请求。先在这里验证日历 API，再接聊天页面，问题发生在哪一层更容易查。
• OpenAPI 让接口说明随代码生成。/openapi.json 描述路径、参数和返回结构，Qoder 可据此编写调用代码，减少手写文档与实现脱节。需让 Qoder 实际读取且能访问该地址，不能据此保证接入一定正确。
• 输入校验给出可处理的错误。FastAPI 配合 Pydantic 在收到请求时检查声明的字段。把具体错误交给 Qoder，比只说“坏了”更有帮助。月份 1–12、未知年份和业务口径仍需代码明确约束。

类型注解不会自动保证所有错误都在运行前发现，默认校验还可能做类型转换。Swagger 请求成功而聊天网页失败时，优先比对地址、参数、请求内容和运行环境；这能缩小排查范围，不能绝对排除后端问题。HTTP 200 也不等于工作日数量算对。

FastAPI 官方功能说明。这种选型思路可迁移到其他工具：是否有清楚的接口说明、可独立验证的入口、具体的错误反馈。

模型调用、凭证与协议

LLM API 就是让程序向模型发送消息、接收回答的接口。网页把你的消息交给本机后端，后端再请求模型服务。你使用哪家服务，就从哪家取得以下配套信息：

协议约定请求和回答怎么组织。本课使用 OpenAI Chat Completions 兼容格式：用 messages 传对话，model 指定模型，第三步再加 tools 并回传工具结果。兼容这种格式的其他服务也可配置；仍要确认具体模型支持工具调用。只有不同原生协议的接口，需要 Qoder 另外适配，不能只换网址。

LLM_BASE_URL=服务商提供的接口基础地址
LLM_API_KEY=在本机填入自己的密钥
LLM_MODEL=服务商的准确模型编号

DeepSeek 只是本课已实测的示例：Base URL 为 https://api.deepseek.com/v1，Model 可填 deepseek-flash；自己的 Key 从其开放平台取得。其他服务照自己的官方文档填写。参考项目通过 LLM_EXTRA_BODY 接收必要的服务商专属参数，默认 {}；DeepSeek 示例使用 {"thinking":{"type":"disabled"}} 关闭思考以减少课堂等待。不要给其他服务照抄专属参数。

API Key 只在本机后端保存，不进入前端、提示词、截图和仓库。Qoder 或 ChatGPT 的订阅通常不等于模型 API 额度。调用、连续对话和每一轮工具结果回传都可能消耗额度；具体费用由你选择的服务和模型决定。

OpenAPI 与 OpenAI 不是同一个概念

OpenAPI 是描述业务 API 的规范，FastAPI 自动生成的 /openapi.json 属于它。OpenAI Chat Completions 是本课选用的模型通信格式，部分其他服务也兼容。第一个帮我们说明工作日接口，第二个帮应用与模型对话。

Swagger 并不会自动让模型知道工作日 API。第三步仍要给模型工具说明，并由应用实现执行和结果回传。请求格式相同也不保证模型能力相同，所以先测普通聊天，再测工具调用。

第一步的作用：单独验证工具

日历数据是一个对象，记录在 dates 数组中。public_holiday 是放假安排，transfer_workday 是补班。只列例外日，普通周末由程序计算。打开完整操作、提示词和 Swagger 截图。

第二步的作用：单独验证模型连接

先证明消息能通过后端到达模型、连续对话能保留上下文、新建对话会清空。此时工作日答案还不是工具证据。打开配置、提示词和聊天截图。

第三步的作用：连接并观察循环

模型提出调用请求，应用执行 API，把结果交回，模型再决定下一步。打开提示词和工具调用验收。

理解 Agentic 循环：谁决定，谁执行

工具定义告诉模型三件事：叫什么、适用于什么问题、需要哪些参数。比如 get_workdays 接收整数年份和月份。它只是“使用说明”，实际执行代码还在你的应用中。

1. 应用把用户消息和工具说明一起发给模型。
2. 模型可能直接回答，也可能返回结构化的 tool call，例如年份 2026、月份 10。
3. 应用识别调用，校验工具名称和参数，真正 HTTP 请求第一步 API。
4. 应用保留模型的调用消息，再用 role: tool、对应的 tool_call_id 和工具结果继续请求模型。
5. 模型根据新结果回答，或者在设定限制内继续调用。比较两个月时，可能一次返回两个调用，也可能分两次查询。

本课最多允许 3 轮工具调用。某轮的工具全部处理完，再让模型继续。到达上限或遇到失败时明确说明，不能把没有查到的数量补成一个看似合理的答案。

本课选择 Chat Completions 兼容格式。服务商和具体模型还需支持工具调用，其他原生协议需要另外适配。

执行记录应该包含什么

上表为便于阅读的摘要，参考界面可展开详细结果。工具命名和版式可不同，信息要能对上。日志不应包含模型密钥、Authorization 请求头或模型内部隐藏思考。

参考实现的本机实跑截图。自己的 Qoder 生成界面可能不同，按信息和行为核对。

三步完成后的验证

每条问题新建对话再测。比较数字也检查执行记录。下面的标准先由日历口径确定，再与应用输出比对。

程序测试适合直接检查 API 的数字、日期、参数校验和失败处理。真实模型试跑还要检查工具选择、执行和结果反馈。两者可以使用相同的正确答案，但只跑固定程序测试不能代替整条模型链路的验证。

课程实跑采用三步跟练页的主提示词，并按实际报错补充修复。查看实跑摘要。这组样例验证本次实现，不能推出所有自然语言问法都能百分之百正确。

参考实现：卡住时再对照

下载完整参考项目。这是三步完成并检查后的版本，不是第一步的起始文件。正常跟练从空文件夹开始，遇到问题再对照源码、README 和测试。

解压后在目录中创建自己的 .env。参考项目不含真实密钥或虚拟环境。可让 Qoder：“按照 README 配置并启动这个参考项目，不要输出 .env 内容。”

技术同事也可按 README 创建虚拟环境、安装依赖、启动。运行程序测试不需要真实模型密钥；运行真实聊天需要自己的密钥和可用额度。网络日历与模型调用的结果分别记录，测试替身不能标成真实模型成功。

日历口径和适用范围

本课按中国大陆普通双休和国务院放假安排计算，企业轮班、个别地区假期、员工请假、每日工时都不在这个口径内。业务要用“有效出勤天数”时，还要接入对应业务规则。

日历来自 holiday-calendar@1.3.3，由 UNPKG 分发，是开源整理数据，不是政府官方 API。核对 2026 年样例时，使用国务院办公厅通知。固定版本的数据覆盖到 2026 年，之后要确认来源更新并验证，不能自动把新年份当作纯周末日历。

public_holiday 包含放假安排中的周末等日期，不等于法定节假日的单独天数。来源超时或未知年份时，应清楚报错；若使用已核对缓存，要说明来源和版本。

程序可以确定地算工作日，但整条自然语言链路仍可能理解错年份、选错参数或回答出错。通过工具、参数校验和验证问题提高可靠性，避免承诺任意问题 100% 正确。

下一次可以换成什么

可以把工作日工具替换成订单状态、费用规则计算或制度查询。仍按“先单独验证工具，再接聊天，再观察循环”的顺序完成。优先只读、边界清楚、结果可核对的任务。

把本机原型提供给多人使用之前，还要考虑访问控制、请求限额、会话隔离、超时、重试、密钥管理和费用。本课没有把应用部署成公开的模型代理。后续可单独介绍 API、MCP、CLI 等连接方式，以及多工具和实际业务接入。

来源与延伸阅读

• DeepSeek 官方 API 与模型名称
• DeepSeek 工具调用与结果回传
• FastAPI 入门与交互文档
• holiday-calendar 开源项目与许可
• 国务院办公厅 2026 年放假安排（北京市政府转载）
• FastAPI 自动文档与数据校验
• Chat Completions 请求与返回格式

课程版本 1.1.0，资料核对于 2026-10-16。模型名称、数据覆盖和接口规则可能更新，请以所选服务的官方文档为准。