Skip to content

docs: 添加第 2 章快速上手与研究助手 Notebook - #138

Merged
webup merged 3 commits into
datawhalechina:mainfrom
FenjuFu:docs/ch02-quickstart-notebooks
Oct 6, 2026
Merged

webup merged 3 commits into
datawhalechina:mainfrom
FenjuFu:docs/ch02-quickstart-notebooks

Conversation

@FenjuFu

@FenjuFu FenjuFu commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

Closes #123。对应课程共建 #105。

第 2 章拆成两份可独立运行的 Notebook。01-quickstart 跑通正文的 Hello World,逐条解读 invoke() 返回的消息;打印 calculate / convert_currency 的工具 Schema,对照类型标注、docstring、默认值三要素;计算器实验用实际换算结果核对 calculate 的输出,检查两步调用是否衔接;另外演示两类工具错误:参数不符合类型标注时返回错误 ToolMessage,函数内部异常则中断整次 invoke()。正文的 calculate 用 eval,这里在 eval 前只放行数字和四则运算符,并在文中说明原因。

02-research-assistant 按正文组装 internet_search + 系统提示词 + create_deep_agent(),显式启用 TodoListMiddleware()。检查分两类:成功的搜索(或 task 委派)和最终报告是必须项;todos 与虚拟文件属于可选行为,发生了才核对与调用是否一致,模型没有规划或写文件不算失败。offline 下 internet_search 返回本地样例,结构与 Tavily 一致,不联网;live 按 COURSE_MODE 而非 Key 是否存在切换到 TavilyClient,缺 TAVILY_API_KEY 直接报错。tavily-python==0.8.4 放在新的 search 依赖组,锁文件只新增这一个包,offline 与现有 CI 不需要安装。文中说明了 Tavily 额度(基础 1 Credit / 高级 2 Credits)、模型调用成本,以及 401 / 429 / 432 和网络失败会中断运行。

两份 Notebook 都有单变量练习,均已实际运行确认:01 把 USD 汇率改为 7.0,脚本仍写死 720.0 * 1.08,检查停在“calculate 没有算出 700.0 × 1.08 = 756”;02 去掉 TodoListMiddleware,write_todos 返回 “not a valid tool”,研究检查仍通过,状态中没有 todos。三个检查格由 tests/test_ch02.py 的 28 项用例覆盖通过与拒绝两个方向。同步更新 catalog、README 索引与推荐顺序、正文入口、.env.example。

验证:Windows 11 / Python 3.12.13,uv.lock 锁定环境(deepagents 0.7.15、langchain 1.4.2、langgraph 1.2.11、langchain-openai 1.6.2)。python -m course_notebooks.run ch02-quickstart ch02-research-assistant --write-back 两份均 passed (offline),--check-only 与 --check-reading 对全部 6 份通过;pytest notebooks/tests 69 项通过。唯一失败的是 test_ch06.py::test_pending_task_failure_closes_real_server,它在未改动的 main 上于 Windows 同样失败,与本 PR 无关。本次保存 offline 输出。

live 交叉验证:01-quickstart 用讯飞星辰 MaaS 的 OpenAI 兼容接口(MODEL_BASE_URL=https://maas-api.cn-huabei-1.xf-yun.com/v2,MODEL_NAME=spark-x2.5)执行 --mode live --output-dir artifacts/notebooks-live,passed (live)。模型实际调用 get_weather(city="北京");计算器实验先调用 convert_currency(amount=100, from_currency="USD", to_currency="CNY") 得到 720.0,再读取该结果调用 calculate("720.0 * 1.08") 得到 777.6,check_calculator 通过。live 输出未提交。02-research-assistant 的 live 需要 Tavily Key,本次未运行(not_run)。单个模型通过不代表其他模型同样适用。

Windows 贡献者注意:nbconvert 的 Markdown indent 过滤器按 os.linesep 判断是否去掉末尾缩进,Windows 上直接 --write-back 会在每段输出后多出一行 " ",Markdown 副本与 Linux CI 不一致(未改动的 main 在 Windows 上 --check-reading 即失败)。本次导出时把 os.linesep 固定为 "\n",并按 CI 的 LF 方式复核,阅读副本逐字节一致。需要的话可以另开 PR 在执行器中处理。

新增 notebooks/ch02 两份实验:01-quickstart 覆盖 Hello World、工具 Schema 三要素、计算器调用链与两类工具错误;02-research-assistant 覆盖搜索工具、TodoListMiddleware、todos 与虚拟文件的观察。offline 使用脚本模型与本地搜索样例,live 通过 search 依赖组接入 Tavily。

同步登记 catalog、README 索引、正文入口与 .env.example,并为三个检查格补充 pytest。

Refs datawhalechina#123, datawhalechina#105

Signed-off-by: FenjuFu <[email protected]>
@webup
webup self-requested a review September 29, 2026 15:46
@webup

webup commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

感谢 @FenjuFu!这两份 Notebook 整理得很用心,尤其是工具 Schema 怎么看、工具出错时会发生什么,以及练习做完怎么恢复,都照顾到了刚入门的同学。三种格式也都补齐了,后面其他章节可以参考这个写法。

整体结构我觉得可以保留,合并前主要再把几处检查补一下:

  1. 委派了任务,不一定就做了搜索。 研究助手现在只要有一次成功的 task 调用就能通过,但子 Agent 也可能直接凭已有知识回答。这里最好能看到这次任务确实调用了搜索、拿到了结果,主 Agent 和子 Agent 的搜索都算。前面单独试调用搜索工具的那次,要和正式运行分开。

  2. 检查文件时,先把路径统一一下。 比如传给 write_file 的是 research/notes.md,框架会保存成 /research/notes.md。现在直接拿原始路径去查,就会出现“文件已经写好了,检查却说找不到”的情况。写文件和编辑文件的路径都按框架的规则统一后再比较就好。

  3. 算出来的数字对了,还不一定说明两步接上了。 现在先调用 calculate("777.6")、再做换汇,也能通过检查。我们这里想让同学看到的是“先拿到换汇结果,再用这个结果计算”,所以需要把这个先后关系和计算参数一起检查一下,不必限制成某一种固定算式。文中“一次请求两个工具也不影响检查”这句也一起调整一下。

  4. 天气查的是不是题目里的城市,也要检查。 现在问北京、实际查上海,只要工具正常返回就能通过。可以把期望城市传给检查函数,允许“北京”“Beijing”这些写法,但换成其他城市就应该提示不符合要求。

这几处补好,再加上对应的正反例,用 --write-back 更新三种格式就可以了,不用重新组织整篇。Windows 导出兼容性那块,我们放到共享执行器里单独处理,这个 PR 先把第 2 章做好。感谢参与,一起把这套 Notebook 慢慢搭起来!

- 研究助手:在 internet_search 里记录 search_log,正式运行前清空,
  以本次运行真正执行且有结果的搜索为准(主 Agent、子 Agent 都算),
  只有 task 委派不再算通过
- 写文件/编辑文件的路径用 deepagents 的 validate_path 统一后再比较
- 换算与计算:要求 calculate 在换算结果返回之后请求,且算式用到了该结果;
  同一次请求并行调用两个工具不再通过,并改正文中的说明
- 天气:检查函数接收期望城市,默认接受 北京 / Beijing(不区分大小写)
- 补充对应正反例测试,--write-back 重新生成三种格式

Signed-off-by: FenjuFu <[email protected]>
@FenjuFu

FenjuFu commented Sep 30, 2026

Copy link
Copy Markdown
Contributor Author

@webup 谢谢细致的 review,四处都按建议改了(67f114b),结构没动:

  1. 搜索证据:internet_search 每次真正执行都会往 search_log 记一笔(查询词 + 结果条数)。主 Agent 和子 Agent 调用的是同一个函数,所以委派出去的搜索也能记到。第 3 节正式 invoke() 前先 search_log.clear(),第 1.1 节那次单独试调用就不会算进去。check_research(state, search_log) 要求这次运行里至少有一次拿到非空结果的搜索,只有成功的 task 不再算通过。
  2. 路径统一:write_file / edit_file 的路径都先经过 Deep Agents 自己的 validate_path(research/notes.md → /research/notes.md)再和 files 比较,和框架的规则保持一致。
  3. 换算与计算接上:检查现在要求 calculate 是在换算结果返回之后才请求的,且算式里出现了这个实际换算结果(不限写法,720 * 1.08、1.08 * 720.0 都行)。先算 777.6 再换汇、或同一次请求并行调两个工具,都会提示没接上。正文那句也改成了对应说明。
  4. 城市:check_weather(messages, city=("北京", "Beijing")),不区分大小写。问北京查上海,即使工具正常返回也会报“不是题目要求的城市”。

test_ch02.py 补了对应的正反例:上海 / Shanghai、并行调用、先算后换、算式没用到换算结果、委派但没搜索或搜索无结果、相对路径写入与编辑。我把新测试放到旧 Notebook 上跑过一遍,这些新增反例在旧版上确实都会被放行,改后 45 个全部通过。三种格式用 --write-back 重新生成,--check-only 和 --check-reading 也都通过。

另外说明一下:我这边是 Windows,导出时需要加 PYTHONUTF8=1,否则读 catalog.json 会报 GBK 解码错误,这应该就是你说的共享执行器那块,这个 PR 里没动。本机跑全套测试时,test_ch06.py::test_pending_task_failure_closes_real_server 在未改动的基线上也会失败,和本次改动无关。

@webup

webup commented Oct 1, 2026 •

Copy link
Copy Markdown
Collaborator

感谢修订!还有两处需要一些调整:

  1. 两份 Markdown 阅读副本的空白行与 LF 导出结果不一致。 01-quickstart.md 和 02-research-assistant.md 的输出块后多了只含四个空格的行,例如 01 第 48 行 和 02 第 62 行,会影响 Ubuntu CI 的阅读副本一致性检查。请按 LF 方式重新导出这两份文件;共享执行器的跨平台修复仍可另开 PR。

  2. 汇率练习的预期报错与新检查不一致。 快速上手第 5 节 仍说把 USD 汇率改为 7.0 后,会停在“calculate 没有算出 700.0 × 1.08 = 756”。但新加的算式衔接检查会先报“calculate 的算式没有用到换算结果 700.0。”。请同步修改练习的报错说明和解释,再从 Notebook 更新 Markdown / HTML。

@FenjuFu

FenjuFu commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor Author

@webup 两处都已改(dbad629):

  1. 两份阅读副本已按 LF 重新导出,输出块后只含四个空格的行没有了,--check-reading 通过。剩下的少数缩进空行是输出内容本身的空行(ch01 的副本里也有)。
  2. 第 5 节的预期报错改为停在“calculate 的算式没有用到换算结果 700.0。”,并补了原因:检查先看算式里有没有实际换算结果,720.0 * 1.08 里没有,所以还轮不到核对 700.0 × 1.08 = 756。Markdown / HTML 已从 Notebook 重新生成。

本地 tests/test_ch02.py 45 项通过。

@webup

webup commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator

感谢 @FenjuFu 的贡献和耐心修订!两处收尾问题都已处理,第 2 章的快速上手和研究助手 Notebook 也更完整了。谢谢参与课程共建!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Notebook] ch02:快速上手与研究助手

2 participants