从模型调用到文档助手

这组教程用同一个文档问答任务贯穿四课：先组织一次请求，再筛选证据，再让模型调用一个只读工具，最后用固定样例检查改动。学完应能解释每一步的数据如何流动，并定位错误发生在检索、生成还是工具执行阶段。

准备与最终产物

需要会读 Python 函数、列表、字典和 JSON，并安装 Python 3.10 或以上版本。示例只用标准库，不需要安装 Agent 框架、向量数据库或额外 Python 包。示例已在 Python 3.13 上完成离线检查。

代码位于 AI Wiki 仓库的 examples/doc_assistant/。在当前文档站点仓库中，对应 docs/ai-wiki/examples/doc_assistant/。

doc_assistant/
├── common.py          # 请求契约、HTTP 调用、答案校验
├── call.py            # 第一课：单次调用
├── retrieval.py       # 第二课：关键词检索与证据问答
├── agent.py           # 第三课：工具调用循环
├── evaluate.py        # 第四课：检索评测
├── documents.json     # 四条教学资料
├── cases.json         # 八条教学评测样例
└── test_assistant.py  # 应用边界的离线测试

以下命令均从示例目录执行；先根据所在仓库进入目录：

# 位于 dispatch-docs 仓库根目录时
cd docs/ai-wiki/examples/doc_assistant

# 如果单独克隆了 AI Wiki，则从它的根目录执行：
# cd examples/doc_assistant

先用五分钟跑通离线路径

python -X utf8 call.py
python -X utf8 retrieval.py "如何构建文档"
python -X utf8 agent.py "如何构建文档"
python -X utf8 evaluate.py
python -X utf8 -m unittest -v

-X utf8 让 Windows、Linux 和 macOS 使用一致的文本编码。默认命令不读取 API 密钥，不访问网络，也不调用付费模型。

命令	实际执行的事情	不代表什么
call.py	打印将要发送的请求结构	没有生成模型答案
retrieval.py	对四条本地文档打分、排序	没有验证模型理解能力
agent.py	用脚本响应演示两轮工具协议	不是模型自主规划的效果
evaluate.py	检查检索命中与无证据判断	不是端到端答案质量评测
unittest	验证输入、引用、工具与停止边界	不证明提示词可以抵御所有攻击

四课学习顺序

首次接触这些概念时，先读 预备课：核心概念与任务拆解，再进入四课实作。

课程	你会完成什么	验收标准
01 模型调用与结构化输出	把问题、证据和输出格式变成明确契约	能解释每个请求字段，并拒绝不合规答案
02 检索与带引用的回答	建立可解释的检索基线，控制送入模型的资料	已知问题命中正确文档，无资料时停止猜测
03 工具调用与执行循环	把检索开放为一个受控只读工具	工具结果匹配调用 ID，未知工具无法执行，循环必定有上限
04 评测与迭代	把“感觉变好了”转为可回放的比较	分开统计检索、引用、回答和拒答错误

什么时候才开启真实调用

离线理解流程后，在示例目录执行相应命令并增加 --live。真实调用使用 OpenAI Responses API，模型由 OPENAI_MODEL 指定，密钥由 OPENAI_API_KEY 提供。所选模型需要支持 Responses、结构化输出；第三课还需要支持函数调用。

本教程不固定一个会过时的模型名称，也不代替账号的模型可用性检查。密钥仅放在当前终端环境中，不写进代码、Markdown 或截图。具体环境变量操作见第一课。

--live 会把问题及教学资料发送给 OpenAI，并产生 API 用量。资料文件只包含教学文本，不连接你的真实知识库。本次内容更新验证了离线逻辑，没有使用真实密钥验证模型输出。

学完后如何扩展

先把四条文档换成你熟悉的十到二十条资料，自己写出正确答案与证据位置，再尝试修改检索。出现明显同义词漏召回后，可以进入 Embeddings 与 混合检索。需要跨步骤选择工具时，再看 Agent 架构。

不要直接把示例作为生产服务：它没有用户认证、租户权限、文档版本管理、并发控制或持久化审计。各课会说明这些能力应加在哪一层。