Repository navigation
docs: 添加第 2 章快速上手与研究助手 Notebook - #138
Conversation
新增 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]>
|
感谢 @FenjuFu!这两份 Notebook 整理得很用心,尤其是工具 Schema 怎么看、工具出错时会发生什么,以及练习做完怎么恢复,都照顾到了刚入门的同学。三种格式也都补齐了,后面其他章节可以参考这个写法。 整体结构我觉得可以保留,合并前主要再把几处检查补一下:
这几处补好,再加上对应的正反例,用 --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]>
|
@webup 谢谢细致的 review,四处都按建议改了(67f114b),结构没动:
另外说明一下:我这边是 Windows,导出时需要加 |
|
感谢修订!还有两处需要一些调整:
|
Signed-off-by: FenjuFu <[email protected]>
|
@webup 两处都已改(dbad629):
本地 |
|
感谢 @FenjuFu 的贡献和耐心修订!两处收尾问题都已处理,第 2 章的快速上手和研究助手 Notebook 也更完整了。谢谢参与课程共建! |
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/tests69 项通过。唯一失败的是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 在执行器中处理。