← COMP5511 全部讲次
T07b · 第 11 周

T07b 做一个论文检索工具(下):搭后端、照截图做前端、先定标准再测

论文检索工具的后半程:按批准的计划搭检索接口并用 curl 测连通,从参考截图拆出界面元素再搭前端,收藏存在浏览器里、导出 CSV;最后用事先定好的相关性判断写六类测试,量 Recall@10。

一句话版

上一页 T07a 把检索设置定死了,这一页把工具真正做出来并验收。先让 agent 照计划搭好检索接口,用一条 curl 命令确认它能用;再从参考截图拆出界面元素,搭好前端;最后写测试。测试这一段课件最看重的一条是:哪些论文算相关,要在跑检索之前就定好。

先认识这几个词

读之前最好先看过 T07a,知道检索分数怎么算、同分怎么排。

词 全称 / 读法 一句人话
前端 / 后端 frontend / backend 前端是你在浏览器里看到的界面,后端是服务器上算结果、管数据的程序
API 接口 前端向后端要数据的那个入口,这里是 GET /api/search
HTTP 状态码 status code 后端回给请求的一个数字,说明这次请求成功了还是哪里出错
curl 读作 curl 在命令行里发一次网络请求、看返回内容的工具
浏览器存储 browser storage 网页存在你自己浏览器里的一小块数据,刷新页面也不会丢
相关性判断 relevance judgments 人事先定好的名单:某个查询下,哪些论文算相关
Recall@10 读作 recall at ten,召回率 该找到的相关论文里,有多少出现在了前 10 条结果中
fixtures 测试数据 测试要用的固定数据,这里主要是自己定的查询和相关性判断

题目地图

顺序 题目 阶段 考什么 主要失分点
4 步骤 4:搭后端并测连通 Build 接口路径、参数、返回字段 不先说预期状态码就去跑 curl
5 步骤 5:照截图做前端 Build 截图元素对应到接口或浏览器状态 照抄截图里数据集根本没有的字段
6 步骤 6:写测试并运行 Test and revise 六类测试、相关性判断先定 看了检索结果再去定「正确答案」
7 Exercise:小型向量检索应用 课后 三样交付物、记录选择 交了应用,没记下模型和排序规则

题号接着上一页往下排。步骤 4 和 5 属于 Build,步骤 6 属于 Test and revise,最后的 Exercise 让你自己把六个步骤从头走一遍。四道题都要求交出能检查的东西:一条启动命令、一个本地网址、一个 tests 文件夹,或者一份测试报告。

概念卡

1. 前端、后端和接口

人话定义:前端是浏览器里的界面,负责收你的输入、画出结果。后端是服务器上的程序,管论文数据和检索算法。两者之间靠接口说话:前端把查询发给 Search API,后端算好结果再送回来。

例子:这个工具的接口是 GET /api/search,参数 q 放查询内容。后端返回六个字段:paper_id、title、authors、year、abstract、score,按名次排好。查询为空时后端返回 HTTP 400,前端就知道这次请求被拒绝了。

常见误解

以为前端要自己算分数 → 打分和排序都在后端做完,前端只按返回的顺序把行画出来,再显示一共有几条。

试一下

前端搜索框里输入了「graph learning」。它应该向哪个地址发请求,查询内容放在哪个参数里?

答案

GET /api/search,查询内容放在参数 q 里。

回讲义:L09a 从大模型到 Agent

2. 阅读清单存在浏览器里

人话定义:收藏和移除只跟你自己有关,课件让前端把已收藏的 paper_id 记在浏览器存储里。页面刷新时,前端从浏览器存储里把清单读回来;导出时,把清单里的论文写成一个 CSV 文件。

例子:收藏三篇,刷新页面,三篇都还在;移除其中一篇再导出,CSV 里只剩两篇。后端在这个过程中一次都不用参与,它只管检索。

常见误解

以为阅读清单得存在后端 → 课件写明用浏览器存储。它的代价是换一个浏览器就看不到原来的清单,这个工具是本地单人用的,所以够用。

试一下

「刷新页面后收藏还在」这件事,是前端还是后端负责?

答案

前端。课件要求收藏用浏览器存储,刷新后从浏览器存储里读回来。

回讲义:L09a 从大模型到 Agent

3. 召回率 Recall@10:先定答案再打分

人话定义:针对一个查询,先由人判定哪些论文算相关,这份名单叫相关性判断。Recall@10 看的是:这些相关论文里,有多少出现在了检索结果的前 10 条中。算法是命中数除以相关总数。

例子:某个查询事先判定 4 篇相关,前 10 条结果里出现了其中 3 篇,Recall@10 就是 3 ÷ 4 = 0.75。课件要求相关性判断在跑检索之前定好。先看结果再定答案,答案就会照着结果写,分数怎么都好看。

常见误解

以为 Recall@10 管排名先后 → 它只数前 10 条里有没有,不管排第 1 还是第 10。要连名次一起打分,用的是讲义里的 NDCG。

试一下

相关论文 5 篇,前 10 条里命中 5 篇,Recall@10 是多少?前 10 条里另外 5 篇不相关,会扣分吗?

答案

5 ÷ 5 = 1,满分。不扣分,Recall 只看相关的有没有找全,混进来的不相关论文要用别的指标去量。

回讲义:L08e NDCG@K

逐题拆解

接着上一页的计划往下做。计划里已经写死了模型、编码时机、打分方式、最多 10 条、同分规则和空查询返回 400,这一页的提示词都假定 agent 手里有这份批准过的计划。

步骤 4:搭后端并测连通

进入 Build 阶段。课件分两个小请求,先搭接口:

Implement the retrieval plan using data/papers.json.
Load MiniLM once, batch-encode the papers at startup and reuse those vectors
for each search. Expose GET /api/search with a q parameter.
Return paper_id, title, authors, year, abstract and score in rank order.
Start the backend and give me the launch command.

再测连通:

Give me one curl command to test GET /api/search.
Use the running backend's host and port and a valid q value.
Tell me what HTTP status and response to expect.

第一个请求把上一页的计划落成代码:模型只加载一次,论文在启动时批量编码,之后每次搜索都复用这些向量。第二个请求让 agent 先说出预期的状态码和返回内容,你跑完再拿实际结果去对。

提示

一个有效的查询请求,后端正常处理完会返回哪一类状态码?返回内容里应该出现哪几个字段、按什么顺序排?

解答

有效查询应该返回 200(表示成功),内容是一个按 score 从高到低排好的论文列表,最多 10 条,每条带 paper_id、title、authors、year、abstract、score 六个字段。课件只写明了空查询要返回 400,正常情况的状态码是本页按网络请求的通用约定补的。验收时看三点:状态码和 agent 事先说的一致,字段齐全,score 确实从高到低。

步骤 5:照截图做前端

还是 Build。课件让你把参考截图附进提示词,分两步。先拆元素:

Extract the layout and list its search controls, result columns and row actions.
Match each to the existing API or browser state.

再照清单搭页面、接接口:

Build the interface from that list. Call GET /api/search with q and render
the ranked rows and result count. Use browser storage for Save and Remove,
and export the saved list as CSV. Start the app and give me the local URL.

参考截图是一个真实论文检索网站的结果页。顶部是搜索框,结果区标题写着论文数量,旁边有排序和筛选按钮。表格三列分别是标题、摘要、操作。每行显示会议和年份、标题、作者、一个分数徽标,操作列有收藏按钮,已收藏的行显示移除。

提示

截图里每个元素都问一句:它的数据从接口的六个字段里拿得到吗?它的状态要不要记在浏览器里?两样都对不上的怎么办?

解答

对得上接口的:搜索框 → q 参数;结果数 → 返回列表的条数;标题、作者、年份、摘要、分数 → 同名字段;行的先后 → 返回顺序。对得上浏览器状态的:收藏和移除按钮 → 浏览器存储里的已收藏 paper_id 列表;导出 → 把已收藏的论文写成 CSV。对不上的:截图里的会议名、会议等级、PDF 链接、类型标签、被引次数,在这份数据里都没有。这些要么不做,要么换成数据里有的字段,比如 topic。照抄截图让 agent 去编这些数,正是第一步「对应到已有接口」要防的事。

步骤 6:写测试并运行

最后一个阶段 Test and revise。课件先列了四条想验证的行为:

目标 预期行为
相关论文排在前面 按余弦分数最多返回 10 篇,同分顺序稳定;拿相关性判断去量 Recall@10
处理空输入 查询为空或只有空格时返回 HTTP 400
保留阅读清单 刷新页面后,收藏的 paper_id 还在
导出 CSV 移除一篇以后导出,CSV 里只有还留着的那些

然后让 agent 写测试并运行:

Write and run tests for corpus loading, retrieval relevance, top-10 ranking
and tie handling, API input validation, reading-list persistence and CSV export.
Create your own queries, relevance judgments and edge cases.
Set the relevance judgments before running retrieval on data/papers.json.
Store runnable tests in tests/ and fixtures in tests/fixtures/.
Put the run commands and results in tests/README.md.
Report failures and any checks you couldn't run.

测试一共六类:语料加载、检索相关性、前 10 排序和同分、接口输入校验、阅读清单持久化、CSV 导出。查询、相关性判断和边界情况都要你自己出,课件没有给现成的。

一步一步看

目标:用一个查询算一次 Recall@10,看为什么相关性判断必须在跑检索之前定。

这里的论文名和结果是本页自编的,只为演示怎么数。

  1. 跑检索之前,先给这个查询定好哪几篇算相关。这里定了 4 篇。

    Recall 第 1 步:左列四个框论文 b、e、g、k 用青绿标出,标题是相关性判断事先定,右侧十个结果框还是灰色

  2. 跑检索,记下前 10 条,这一步先不判断对错。

    Recall 第 2 步:右侧两排共十个结果框用青绿标出,第 1 名到第 10 名依次是论文 e、c、b、d、g、f、h、i、j、l

  3. 数前 10 条里有几篇在相关名单上,除以相关总数。

    Recall 第 3 步:第 1 名论文 e、第 3 名论文 b、第 5 名论文 g 用青绿标出,左列论文 k 变灰,底部写着命中 3 除以相关 4 等于 0.75

方法与验收

对照上面的四条行为和六类测试,检查 agent 交回来的测试。

提示

把四条预期行为和六类测试一条条连起来。哪一类测试对应哪一条行为?有没有哪类测试不在四条行为里?

解答

「相关论文排在前面」对应检索相关性(量 Recall@10)和前 10 排序与同分两类;「处理空输入」对应接口输入校验,至少测空字符串和只有空格两种;「保留阅读清单」对应阅读清单持久化,收藏后刷新再读;「导出 CSV」对应 CSV 导出,先移除一篇再导出,核对行数。语料加载不在四条行为里,它是前提:先确认 120 条都读进来了、paper_id 没有重复,后面的测试才有意义。验收时看 tests/、tests/fixtures/、tests/README.md 三处都在,README 里有运行命令、结果、失败项和没跑成的检查。

Exercise:一个小型向量检索应用

课后作业:复用课上的论文数据,做一个小型向量检索应用,并记下你选的模型和排序规则。要交三样:一个能运行的应用、一份阅读清单 CSV、一份简短的测试报告。课件没给时长、CSV 列名和评分标准。

提示

把步骤 1 到 6 的产出各对应到三样交付物里的哪一样。「记下模型和排序选择」要写到什么程度,别人才能照着复现出一样的顺序?

解答

能运行的应用来自步骤 4 和 5,附上启动命令和本地网址。阅读清单 CSV 是在页面上收藏几篇、移除一篇以后导出的那份。测试报告就是步骤 6 的 tests/README.md,写清跑了哪些测试、结果如何、哪些没通过、哪些没跑成。模型和排序选择要写到能复现:模型名 all-MiniLM-L6-v2,嵌入标题加摘要,归一化后点积打分,最多 10 条,同分按 paper_id 升序,空查询返回 400。少了同分规则这一条,别人跑出来的顺序就可能和你不一样。

课件里的坑

  • [读图提醒] 课件封面写的是 Tutorial 2,本站记作 T07,分成 T07a、T07b 两页,本页是后半。p.13–14 属于 Build,p.16 属于 Test and revise;p.15 没有顶部进度条,是夹在中间的验收清单页。
  • [课件留白] p.14 的参考截图来自真实网站,结果数写着 228,还有会议等级、被引次数等字段;材料包里只有 120 篇、七个字段。截图里收藏按钮叫 Pocket,课件文字叫 Save。照截图做前端时以数据为准。
  • [课件留白] p.15 要求测 Recall@10,但课件没给相关性判断,也没给定义,要你自己定查询和相关名单。
  • [课件留白] p.13 只规定空查询返回 HTTP 400,没写正常查询的状态码;p.17 没给 CSV 该有哪些列,也没给评分标准。
  • [课件留白] p.15 写「by cosine score」,p.12 写「dot product」,两者因为向量都归一化过而相等,推导见 T07a 的概念卡 2。
  • [补充] 召回率的定义是:与查询相关的文档里,被成功检索出来的比例;Recall@10 就是只看前 10 条时的召回率。出处:Wikipedia: Evaluation measures (information retrieval)

课后 10 分钟:考点复习

这 10 分钟怎么用:先合上页面,用自己的话说一遍:做完后端和前端以后,你打算用哪几条测试证明它做对了。然后用 3 分钟读必背 7 条,重点是第 2 条的接口和第 7 条的 Recall 算法;中间 4 分钟默写完整例题;最后 3 分钟做变式题,先自己写再展开对照。

必背

  1. vibe coding 四阶段:Set the goal 定目标和约束、Refine the plan 定选项和决定、Build 改代码出能跑的结果、Test and revise 拿证据决定下一处修改
  2. 后端接口 GET /api/search 用 q 参数传查询,按名次返回 paper_id、title、authors、year、abstract、score 六个字段
  3. 测连通时先让 agent 说出预期的 HTTP 状态和响应,再跑一条 curl 拿实际结果对照
  4. 照截图做前端先拆出搜索控件、结果列和行操作,逐个对应到已有接口或浏览器状态,再照清单搭页面
  5. 收藏和移除用浏览器存储,刷新页面后收藏的 paper_id 仍在,移除一篇后导出的 CSV 只含剩下的论文
  6. 测试覆盖语料加载、检索相关性、前 10 排序与同分、接口输入校验、阅读清单持久化、CSV 导出六类,失败项和没跑成的检查也要报告
  7. 相关性判断要在跑检索之前定好,Recall@10 = 前 10 条里命中的相关论文数 ÷ 事先判定的相关论文总数

完整例题

题面:按课件 p.15 的四条预期行为,为这个工具各写一条可执行的检查,并写出预期结果。相关性检查用这组数据:查询事先判定 4 篇相关,检索返回的前 10 条里有其中 3 篇。阅读清单检查用这组操作:收藏 P003、P007、P010,刷新页面,移除 P007,导出 CSV。

解法:

  1. 相关论文排在前面:对这个查询调用 GET /api/search,返回不超过 10 条,score 从高到低,同分的按 paper_id 升序;Recall@10 = 3 ÷ 4 = 0.75。
  2. 处理空输入:分别用空字符串和一串空格作为 q 去请求,两次都应返回 HTTP 400。
  3. 保留阅读清单:收藏 P003、P007、P010 后刷新页面,三篇仍显示为已收藏。
  4. 导出 CSV:移除 P007 后导出,CSV 里只有 P003 和 P010 两行数据。
  5. 写进报告:每条检查的命令、实际结果、是否通过,记进 tests/README.md;跑不了的检查也写上,说明原因。

自查:每条检查都能照着做一遍,预期结果是一个能对上的数字或状态,没有「应该正常」这类说法。再看相关的 4 篇是不是在跑检索之前定的。

答题格式:按四条行为分四行,每行写「操作 → 预期结果」,Recall 那一行写出算式。

变式题(先自己做)

改编自课件 p.14–16。

(a) 某查询事先判定 5 篇相关,前 10 条结果里出现了 2 篇。Recall@10 是多少?如果是看了结果才把这 2 篇定成相关,这个分数还能说明什么?

(b) 参考截图里有「被引次数」和会议等级。有人在前端提示词里直接写「照截图做,每列都要有」。会出什么问题?按课件的做法该怎么改?

(c) 接口输入校验至少要测哪两种输入?各自预期什么?

提示

(a) 回到概念卡 3:答案该在什么时候定。(b) 先看材料包里的数据有哪七个字段。(c) 课件对空查询的说法里有两个词。

判分点与答案(非官方评分标准)

判分点:① (a) 算出数值并说出先定判断的理由;② (b) 说出数据里没有这些字段,并给出「先拆元素、对应接口」的改法;③ (c) 两种输入和预期状态码都写出。

(a) 2 ÷ 5 = 0.4。如果是看了结果再定相关名单,名单就是照着结果写的,分数只说明「结果和你照结果写的答案一致」,量不出检索好不好,所以课件要求先定判断再跑检索。

(b) 数据只有 paper_id、title、authors、year、abstract、topic、synthetic 七个字段,没有被引次数和会议等级。agent 照截图硬做,要么留空列,要么编出数来。课件的做法是先让 agent 拆出元素清单,把每个元素对应到已有接口或浏览器状态,对应不上的不做或换成 topic、year 这类已有字段。

(c) 空字符串,和只有空格的查询。两者都应返回 HTTP 400,因为查询要先去掉首尾空格,空格去掉后也为空。

闪卡自测

1. 前端和后端各管什么?中间靠什么连接?

前端是浏览器界面;后端是服务器上的逻辑和数据,包括 Search API、检索算法、论文数据。查询从前端发到 Search API,结果再送回前端(p.5)。

2. 检索接口的路径、参数和返回字段是什么?

GET /api/search,参数 q;按名次返回 paper_id、title、authors、year、abstract、score(p.13)。

3. 测连通的请求要 agent 交回什么?

一条用正在运行的后端地址和端口、带有效 q 的 curl 命令,并说明预期的 HTTP 状态和响应(p.13)。

4. 照截图做前端,第一步要 agent 做什么?

拆出布局,列出搜索控件、结果列和行操作,并把每个元素对应到已有接口或浏览器状态(p.14)。

5. 前端的收藏、移除和导出怎么实现?

收藏和移除用浏览器存储,把已收藏的列表导出成 CSV;页面要显示排好序的结果行和结果数(p.14)。

6. 课件想验证的四条行为是什么?

按余弦分数最多返回 10 篇、同分稳定,并用相关性判断量 Recall@10;空查询或只有空格返回 HTTP 400;刷新后收藏的 paper_id 还在;移除后导出的 CSV 只含剩下的论文(p.15)。

7. 测试要覆盖哪六类?

语料加载、检索相关性、前 10 排序与同分处理、接口输入校验、阅读清单持久化、CSV 导出(p.16)。

8. 测试放在哪里?要报告什么?

测试放 tests/,测试数据放 tests/fixtures/,运行命令和结果写进 tests/README.md;还要报告失败项和没能跑的检查(p.16)。

9. 课后 Exercise 要交哪三样?

一个能运行的应用、一份阅读清单 CSV、一份简短的测试报告;同时记下模型和排序选择(p.17)。

下一步

这两页把上一节 T06a 的写提示词、做核对用到了一个完整的小项目上。检索结果怎么打分还可以往深里看:Recall@10 只数找没找全,回 L08e 看把名次也算进去的 NDCG。想看 agent 交来结果以后怎样系统地验收,回 L09b-2。

下一讲的通俗笔记上完课会补,先回 COMP5511 课程页。

个人整理的学习笔记,不是官方材料;数字与结论以课件和讲师为准。