AI 原生开放教材

外观

动手学 CS146S 中文版系统课程·中文原文 ↗仓库 ↗

第 2 周：行动项提取器 ​

项目简介 ​

这是一个 FastAPI + SQLite 小应用，用来把会议记录或自由文本转换成行动项。它提供两种提取方式：

  • 规则提取：识别项目符号、复选框、TODO:、Action:、Next: 等格式，速度快且无需模型。
  • LLM 提取：调用本机 Ollama，按 JSON Schema 返回结构化行动项；模型不可用或返回格式错误时自动回退到规则提取。

网页端可以输入笔记、选择是否保存、提取行动项、勾选完成状态，也可以列出已保存笔记。数据保存在 week2/data/app.db，首次启动时自动创建。

环境配置 ​

要求：Python 3.10+、Poetry；使用 LLM 功能时还需要 Ollama。

bash
# 在仓库根目录安装依赖
poetry install

# 安装 Ollama 后拉取默认模型
ollama pull llama3.2:3b

默认模型是 llama3.2:3b。如需更换模型，在启动服务前设置环境变量：

bash
export OLLAMA_MODEL=gemma3:4b

Ollama 桌面程序通常会自动启动服务；命令行环境可另行运行 ollama serve。

启动与使用 ​

在仓库根目录运行：

bash
poetry run uvicorn week2.app.main:app --reload

打开 http://127.0.0.1:8000/。输入笔记后：

  1. “Extract”使用本地规则提取。
  2. “使用 LLM 提取”调用 Ollama；首次推理可能较慢。
  3. 勾选“Save as note”会同时保存原始笔记。
  4. “列出笔记”显示数据库中的全部笔记，最新记录排在前面。

FastAPI 自动接口文档位于 http://127.0.0.1:8000/docs。

API 端点 ​

方法路径功能请求体/参数
GET/返回网页界面无
POST/notes新建笔记{"content": "..."}
GET/notes列出全部笔记，按 ID 倒序无
GET/notes/{note_id}获取单条笔记路径参数 note_id
POST/notes/extract-llm用 Ollama 提取行动项，可保存原笔记{"text": "...", "save_note": true}
POST/action-items/extract用规则提取行动项，可保存原笔记{"text": "...", "save_note": true}
GET/action-items列出行动项；可按笔记过滤可选查询参数 note_id
POST/action-items/{id}/done修改完成状态{"done": true}

两个提取端点都返回：

json
{
  "note_id": 1,
  "items": [{"id": 1, "text": "Write tests"}]
}

未保存笔记时 note_id 为 null。缺少必填文本时返回 HTTP 400。LLM 调用失败不会让请求崩溃，而是使用本地规则继续提取。

测试 ​

在仓库根目录运行第 2 周测试：

bash
poetry run pytest week2/tests -v

只运行提取服务测试：

bash
poetry run pytest week2/tests/test_extract.py -v

测试通过 mock 替代真实 Ollama 调用，因此不要求下载模型，也不依赖网络。覆盖项目符号、关键字前缀、空输入、无结构文本、结构化模型响应、重复项和旧模型可能返回的 JSON 代码块。

目录结构 ​

text
week2/
├── app/
│   ├── main.py                 # FastAPI 应用入口
│   ├── db.py                   # SQLite 读写
│   ├── routers/                # 笔记与行动项接口
│   └── services/extract.py     # 规则与 LLM 提取逻辑
├── frontend/index.html         # 无构建步骤的网页端
├── tests/test_extract.py       # 提取逻辑单元测试
└── writeup.md                  # 作业过程记录

各练习的解题思路 ​

练习 1：LLM 提取 ​

给 Ollama 明确的系统提示，并用 JSON Schema 限定返回值为字符串数组。解析时兼容对象响应、字典响应和 Markdown JSON 代码块；清理空项并按大小写去重。模型不可用或 JSON 异常时调用原有规则函数，保证基本功能可用。

练习 2：单元测试 ​

所有模型调用都 mock 掉，测试只验证自己的输入、解析和回退逻辑。分别覆盖项目符号、关键字、空白输入、普通叙述和规范 JSON 响应，避免测试受网络和模型随机性影响。

练习 3：代码清理 ​

把“读取响应”和“解析行动项”拆成小函数，让每个函数只做一件事。路由统一检查空文本并返回固定结构；数据库操作继续集中在 db.py，前端不依赖 SQLite 细节。

练习 4：接口与网页集成 ​

新增 /notes/extract-llm 和 GET /notes。前端两个按钮分别调用接口，并用 DOM API写入模型文本和笔记内容，避免把用户内容直接拼进 HTML；请求失败时显示后端错误并恢复按钮状态。

练习 5：README ​

先按入口文件、路由、服务、数据库和测试梳理实际行为，再记录可直接执行的安装、启动和测试命令。接口表写清方法、路径、输入和作用，便于第一次接触项目的人快速运行与排错。