项目一:个人知识库助手 — 资料是爬来的,而且进库前先被压过一遍
这一章讲三件事: 一个真项目怎么分层;知识库的资料从哪儿来、进库前经过了什么; 以及问答那一头被包成了什么样子。
它在全书链条里的位置: 这是第三部分的第一篇。 它不教新机制,它教「同样的机制在真项目里长什么样」——尤其是数据那一头。
本章主走查:
datawhalechina/pumpkin-book(南瓜书)这个仓库的说明文件(README)。 它会依次被爬下来、洗掉两样东西、压成 200 字以内的摘要、进库,最后在一次提问里被取回。 每一步的做法、参数、要过滤掉的那串词都是书里的; 但书没有点名走查用的是哪个仓库,也没有印出任何一份说明文件或摘要—— 所以下面那份说明文件片段和那份 200 字摘要是我们为演示编的,每处都当场标了。 挑pumpkin-book是 因为它确实在这个组织下,而且你在第 05 章已经见过它的内容。
1. 这个项目分五层
这一节先给全景,因为后面每一节都对应其中一层。
书给的分层是从下往上五层1:
⑤ 服务层 Gradio 做的界面 + FastAPI 做的接口 ← 第 6 节
─────────────────────────────────────────────
④ 应用层 在框架的检索问答链上再包一层,支持换模型 ← 第 5 节
─────────────────────────────────────────────
③ 数据库层 Chroma 向量库 ← 第 4 节
─────────────────────────────────────────────
② 数据层 知识库源文件 + 向量模型 ← 第 2、3、4 节
─────────────────────────────────────────────
① LLM 层 四家模型的统一封装,随时可切换 ← 第 02、07 章
图说:第 ① 层就是第 02 章那四个同名的 get_completion 加第 07 章那种自定义写法;
第 ③ 层就是第 06 章那个库。这一章真正新的东西全在第 ② 层。
书自己对这个项目核心的一句话总结是:针对四种模型的接口实现了底层封装, 基于框架搭了一条可切换模型的检索问答链,并实现了接口与界面两种部署2。
注意「可切换模型」这五个字,它是这个项目和教程版最大的结构差异—— 教程版每一章写死一家,项目版把「换一家」做成了一个参数。
2. 知识库的资料是爬来的
这一节是主走查的第 1 步,也是这一章最有价值的一节。
书写明这个项目要做的事是:基于 Datawhale 现有项目的说明文件做知识问答, 让用户可以快速了解 Datawhale 现有项目情况3。
它的知识库源数据一共四类——这里的「开源」指的是把代码和内容公开放在网上、允许别人自由取用4:
| 是什么 | 格式 |
|---|---|
| 《机器学习公式详解》(南瓜书) | |
| 《面向开发者的 LLM 入门教程 第一部分 Prompt Engineering》 | md |
| 《强化学习入门指南》 | MP4(视频) |
| datawhalechina 这个组织下所有开源项目的说明文件 | md |
第四类是这一章的主角,因为它不是人整理的,是程序爬来的。
爬的做法很直接:调用代码托管平台的接口5:
① 列出组织下的仓库:GET /orgs/datawhalechina/repos
每页 200 个,把仓库名逐行写进 repositories.txt
② 对每个仓库要它的说明文件:GET /repos/datawhalechina/<仓库名>/readme
平台返回的正文是编码过的,要先解码回文字
③ 每个仓库单独建一个目录,把说明文件存成 README.md
图说:这一步的产物是一堆原始说明文件,还不能用。
为什么不能用,下一节说。
走查落到具体一个仓库上是这样的:
① 列仓库 → repositories.txt 里出现一行:pumpkin-book
② 要说明文件 → GET /repos/datawhalechina/pumpkin-book/readme
拿回来的正文长这样(这是我们编的示范片段,书没有印过任何一份说明文件):
# 南瓜书 PumpkinBook
《机器学习》(西瓜书)是机器学习领域的经典入门教材之一。
本书旨在对西瓜书里比较难理解的公式加以解析,并补充推导细节。
在线阅读:(一个 github.io 的网址)
最新版 PDF:(一个 github.com 的下载页网址)
扫描下方二维码关注公众号,回复关键词「南瓜书」加入读者交流群。
LICENSE:知识共享署名-非商业性使用-相同方式共享 4.0
③ 存盘 → pumpkin_book/README.md,这段示范片段一共 257 个字符
(真实仓库的说明文件通常是这个的十几倍到几十倍长)
图说:注意最后三行——两个网址、一句「扫描下方二维码关注公众号,回复关键词」、
一个 LICENSE。它们下一节会被逐条删掉,而删的理由各不相同。
环境变量就是操作系统里存着的一批「名字→值」,程序启动时能读到,而它们不写在代码里。
这一步需要一把访问凭证(代码里那个 TOKEN),它就是从环境变量里读的5。
3. 爬下来不能直接进库:先删两样,再压成 200 字
这一节是主走查的第 2、3 步,而且它是这个项目最值得抄走的一处设计。
书对原始说明文件的判词是:这些说明文件含有不少无关信息6。 处理分两步:先过滤,再让模型压缩。
第一步,删两样东西7:
| 删什么 | 为什么 |
|---|---|
| 所有网址 | 说明文件里全是链接,对回答问题没用 |
| 一串特定词汇 | 书的原话是「过滤了可能引起大模型风控一些词汇」 |
那串被过滤的词书原样列了出来7:
扫描下方二维码关注公众号 提取码 关注 科学上网
回复关键词 侵权 版权 致谢
引用 LICENSE 组队打卡 任务打卡
组队学习的那些事 学习周期 开源内容 打卡
组队学习 链接
图说:这一串分两类——前一半是会触发模型服务方审核的字眼,
后一半是社区活动的套话,留着只会让检索被这些高频词带偏。
这一条在教程前九章里完全没有出现过,而它是真项目才会遇到的问题: 你的资料里可能有让模型服务方拒绝回答的内容。
把这两条规则套到走查那份说明文件上,当场看它掉了多少:
进来:257 个字符(上一节那份示范片段)
删网址 → 「在线阅读」和「最新版 PDF」后面那两条网址全掉
删词表 → 「扫描下方二维码关注公众号」「回复关键词」「LICENSE」三处命中,
那两行整句失去意义,只剩残句
出去:真正说清「这是什么」的只剩前三行,77 个字符;后四行只剩标点和残句。
图说:七行里有四行是网址和套话,占掉七成篇幅——
这就是「无关信息」四个字的具体分量。
(257 和 77 都是我们数这份示范片段数出来的;书没有印过任何一份说明文件,
也没有说过滤之后残下的标点怎么处理。)
第二步,让模型把每一份压成摘要8。用的提示词是:
1:这个仓库名是 {repo_name}. 此仓库的readme全部内容是: {readme_content}
2:请用约200以内的中文概括这个仓库readme的内容,
返回的概括格式要求:这个仓库名是...,这仓库内容主要是...
图说:注意第 2 行那个格式要求——它规定了输出的句式。
这正是第 03 章那个「要求结构化输出」的技巧,用在了建库这一头。
压完的摘要存成 <仓库名>_summary.md,放进知识库目录。原始说明文件不进库。
走查这一步压出来的东西长这样(这份摘要是我们照那段提示词的格式编的示范, 书没有印过任何一份真实摘要):
这个仓库名是 pumpkin-book,这仓库内容主要是对周志华《机器学习》(西瓜书)中
省略掉的公式推导做补充解析。西瓜书为照顾更多读者,很多公式只给了结论、
没有推导过程;南瓜书把这些难懂的公式逐条拆开,以本科数学基础的视角讲清
每一步怎么来的。它的定位是配着西瓜书读的辅助材料,不能单独当教材:
遇到推不出来或看不懂的公式时再来查阅。仓库同时提供在线阅读与 PDF 下载。
存成:pumpkin_book/pumpkin-book_summary.md,一共 185 个字符
(提示词要的是「约 200 以内」,这份 没超)
图说:注意第一句的句式——「这个仓库名是……,这仓库内容主要是……」,
和提示词里那句格式要求一字对得上。这一点下面第三张表会用到。
这个设计值得单独说清楚,因为它同时解决了三个问题:
| 解决了什么 | 怎么解决的 |
|---|---|
| 说明文件太长、夹杂太多无关内容 | 200 字的摘要干净得多 |
| 一份说明文件会被切成很多块、彼此割裂 | 200 字大概率就是一块,不会被切开 |
| 提问「这仓库是干什么的」和说明文件对不上 | 摘要的句式就是「这仓库内容主要是……」,和提问的说法天然接近 |
第三点尤其值得记住:它正面绕开了第 06 章那个「配对不是因果」的坑。 你不是在改检索,你是在改被检索的东西的写法。
书还留了两处很实在的工程细节9:
- 每压一份要停 60 秒——代码里写着「访问受限,每分钟一次」;
- 压失败的也要留档:触发风控的存成
<仓库名>_summary风控.md, 说明文件不存在的存成<仓库名>_summary不存在.md。 而建库时会用一条规则把带「不存在」和「风控」字 样的文件跳过。
4. 进库:和第 06 章一样的动作,换了参数和向量模型
这一节是主走查的第 4 步。
加载那一步按扩展名分派10:PDF 用第 05 章那个读取工具,md 用那个 md 读取工具, txt 用一个通用读取工具。书在这里插了一句很坦白的提醒: 数据处理是一件非常复杂和业务个性化的事——PDF 里包含图表、图片、文字以及不同层次的标题, 这些都需要根据业务进行精细化处理10。
切分参数是 500 / 15011。注意这和第 05 章那一版不一样: 教程版是 500 / 50,项目版把重叠从 50 提到了 150。 书没有解释为什么改,但项目那一章给了一条教程版没给的理由: 片段与片段之间的一些重叠内容,能保证检索的时候能够检索到相关的文档片段11。
向量模型有三种可选12:
| 选项 | 是什么 |
|---|---|
m3e | 一个下载到本地跑的模型,不用调远程接口 |
openai | 第 04 章那个 |
zhipuai | 第 04 章那个(书自己封装的) |
第一个选项是这一章新出现的东西,它的意义比看起来大: 本地模型意味着建库不花钱、不受限速、不受网络影响—— 回想第 06 章第 2 节那笔账(720 次网络往返、要跑好几分钟),本地跑就没有这个问题了。 代价是你的机器要能装下它、跑得动它。
建库和落盘与第 06 章完全一样:Chroma.from_documents 加 vectordb.persist()13。
走查这一步的账很短: 那份 185 个字符的摘要送进一个一块装 500 个字符的切分器, 切出来是 1 块,一刀都没切——这正是上一节第二张表说的「200 字大概率就是一块」。 它会被算成一串数存进库,和其他仓库的摘要并排放着。 (185 是我们数那份示范摘要数的,500 / 150 是书里的。)
5. 取出来:两个类,一个带历史一个不带
这一节是主走查的第 5 步。
项目把第 07、08 两章那两条链各包成了一个类——类就是把「一堆数据」和「操作这堆数据的几个动作」 装在一个盒子里、给这个盒子起个名字;第 06 章那个基类就是这种盒子的一份空壳14:
| 类 | 对应本组拆解 |
|---|---|
QA_chain_self | 第 07 章那条不带历史的检索问答链 |
Chat_QA_chain_self | 第 08 章那条带历史的对话检索链 |
带历史那个类的参数表最能说明「真项目要考虑什么」15:
| 参数 | 干什么 | 对应哪一章 |
|---|---|---|
model | 调哪一家模型 | 第 02 章 |
temperature | 温度,默认 0.0 | 第 02 章 |
top_k | 取回前几块,默认 4 | 第 07 章 |
chat_history | 历史记录列表 | 第 08 章 |
history_len | 保留最近几次对话 | 第 08 章 |
file_path / persist_path | 建库文件在哪、库落盘到哪 | 第 06 章 |
embedding / embedding_key | 用哪个向量模型、它的密钥 | 第 04 章 |
api_key / appid / 两个 secret | 四家各自要的凭证 | 第 02 章 |
这张表就是这一章的价值所在:前面九章每一章留下的那个「写死的值」, 在真项目里全都变成了一个参数。
走查的最后一步: 拿一句提问调 answer() 方法,它会
用当初那个向量模型打开库 → 按 top_k 取回 4 块 → 连同历史一起交给链 → 拿回答案,
并把这一问一答追加进历史15。
落到走查那句提问上:
提问:南瓜书是干什么的? top_k = 4,历史为空
取回第 1 块 「这个仓库名是 pumpkin-book,这仓库内容主要是……」 ← 就是我们那份摘要
取回第 2、3、4 块 另外三个仓库的摘要,句式一模一样、内容不相干
判定:答案落在第 1 块里 → 按第 11 章第 7 节那个口径,这一次算检索成功。
图说:注意第 1 块为什么能被取到——提问是「南瓜书是干什么的」,
而摘要的第一句就是「这仓库内容主要是……」,两句话在说同一件事、句式还接近。
这正是第 3 节那张表第三行讲的东西。
(这次取回的四块是我们照库里的形状编的示范,书没有印过任何一次检索输出。)
6. 跑起来:两种服务方式
这一节讲最上面那一层。
书给了两条命令16:
① 起一个本地接口服务(给别的程序调):
cd project/serve
uvicorn api:app --reload # Linux
python api.py # Windows
② 起一个带界面的应用(给人用):
cd llm-universe/project/serve
python run_gradio.py -model_name='chatglm_std' -embedding_model='m3e' \
-db_path='../../data_base/knowledge_db' \
-persist_path='../../data_base/vector_db'
图说:注意第 ② 条命令里那四个参数——
模型、向量模型、知识库路径、向量库路径全在命令行上,一个都没写死。
用的界面工具是 Gradio,不是第 09 章那个 Streamlit1。 书没有解释为什么换,两者定位相同(都让你只写 Python 就能做界面)。
运行环境要求也比教程版明确:书写的是 Intel 第 5 代处理器, 上云的话建议选两核以上;至少 4 GB 内存、Python 3.9 以上; 操作系统三种都行,而且同样不要求显卡17。
7. 边界:这个项目的完成度,和一处对不上的参数
这一节交代这个项目当时的状态。
第一,它有版本号,而且不高。 书写着:当前版本 0.2.0,更新于 2024 年 3 月 17 日; 这一版新增的是本地向量模型 m3e、新增知识库内容、 新增全部说明文件的摘要、以及修复界面显示错误18。 未来规划只有一条:更新智谱的向量模型。
第二,切分参数和教程版不一致:教程版 500 / 50,这里 500 / 150,书没有解释。 如果你照书搭,两处会给出不同的库,而书没有提醒你这一点。
第三,项目自己列了三条未来方向19:支持用户自主上传并建立个人知识库; 从检索增 强的普遍架构升级到多个智能体协作的框架; 改进检索函数以提高检索准确性。
第四,这一篇的写法和前九章明显不同。 它开头有整整两节讲「项目背景」「目标与意义」, 用的是提升信息获取效率、增强知识管理能力、促进决策支持这类项目申报式的话20。 那两节没有任何可执行的内容,读的时候可以直接跳过。
判断(我们的,不是书里的): 这个项目里最值得抄走的不是架构,是第 3 节那个「先摘要再进库」。 它用一次模型调用换来了三样东西:无关内容变少、块不被切碎、摘要句式与提问句式对齐。 而教程前九章从头到尾都在改检索侧,没有一章想过去改被检索的那一侧。 如果错,会错在: 如果你的资料本身就短小整齐(比如常见问题条目),摘要这一步纯属多花钱; 而且摘要是有损的——用户问细节时,细节已经在压缩时被丢掉了。判据是: 你的用户问的是「这是什么」还是「具体怎么做」;前者适合摘要,后者不适合。
8. 可带走的
- 五层分工:模型层、数据层、数据库层、应用层、服务层;真正新的东西全在数据层;
- 知识库的资料是爬来的:调代码托管平台的接口,列出组织下所有仓库、逐个取说明文件;
- 爬下来不能直接进库,要先删两样:所有网址,以及一串可能触发模型服务方审核的词;
- 然后让模型把每一份压成 200 字以内的摘要,只有摘要进库;200 字以内的摘要在 500 字的切分器下就是 1 块,一刀都不会挨;
- 摘要这一步同时解决三个问题:无关内容太多、块被切碎、以及摘要句式和提问句式天然接近;
- 第三点是正面绕开第 06 章那个「配对不是因果」的坑——改的不是检索,是被检索的东西;
- 两处工程细节:每压一份停 60 秒;压失败的也留档,建库时按文件名跳过;
- 切分参数是 500 / 150,和第 05 章的 500 / 50 不一样,书没解释;
- 向量模型多了一个本地选项 m3e:建库不花钱、不受限速,代价是机器要跑得动;
- 两条链各包成一个类,带历史那个的参数表把前九章每个写死的值都变成了参数;
- 默认
top_k是 4——第 07 章那个没写出来的默认值,在这里写出来了; - 两种服务方式:本地接口(给程序调)和 Gradio 界面(给人用);
- 版本 0.2.0,未来规划只有一条;项目开头那两节是申报式的话,可以跳过。
9. 原文地图
| 主题 | 原书章 | 原文位置 |
|---|---|---|
| 五层分工 | 个人知识库助手项目 | text/08-p141-160.txt:309(搜 「从底向上依次分为 LLM 层」) · text/08-p141-160.txt:311(搜「⽀持⽤户以统⼀的入⼝」) |
| 项目核心一句话 | 个人知识库助手项目 | text/08-p141-160.txt:302(搜「核⼼是针对四种⼤模型 API 实现了底层封装」) |
| 主要功能与四类源数据 | 个人知识库助手项目 | text/08-p141-160.txt:209(搜「基于 Datawhale 的现有项⽬ README 的知识问答」) · text/08-p141-160.txt:370(搜「机器学习公式详解》PDF版本」) · text/08-p141-160.txt:373(搜「datawhalechina」) |
| 爬说明文件 | 个人知识库助手项目 | text/08-p141-160.txt:378(搜「test_get_all_repo.py」) · text/08-p141-160.txt:396(搜「api.github.com/orgs」) |
| 删网址与审核词 | 个人知识库助手项目 | text/08-p141-160.txt:453(搜「含有不少⽆关信」) · text/08-p141-160.txt:471(搜「过滤文本中链接防」) · text/08-p141-160.txt:478(搜「科学上」) |
| 200 字摘要的提示词 | 个人知识库助手项目 | text/08-p141-160.txt:496(搜「这个仓库名是」) · text/08-p141-160.txt:498(搜「以内的中文概括这个仓库readme的内容」) |
| 每分钟一次、失败留档 | 个人知识库助手项目 | text/08-p141-160.txt:527(搜「time.sleep(60)」) · text/08-p141-160.txt:541(搜「⻛控.md」) · text/08-p141-160.txt:602(搜「不存在 |
| 按扩展名分派、精细化处理那句 | 个人知识库助手项目 | text/08-p141-160.txt:592(搜「def file_loader」) · text/08-p141-160.txt:577(搜「精细化处理」) |
| 500 / 150 与重叠的理由 | 个人知识库助手项目 | text/08-p141-160.txt:651(搜「chunk_size=500, chunk_overlap=150」) · text/08-p141-160.txt:622(搜「能保证检索的时候能够检索到相关的文」) |
| 三种向量模型 | 个人知识库助手项目 | text/08-p141-160.txt:673(搜「get_embedding」) · text/08-p141-160.txt:676(搜「moka-ai/m3e-base」) |
| 建库与落盘 | 个人知识库助手项目 | text/08-p141-160.txt:691(搜「chromadb 向量数据库」) · text/08-p141-160.txt:734(搜「vectordb.persist()」) |
| 两个类与参数表 | 个人知识库助手项目 | text/09-p161-180.txt:67(搜「QA_chain_self.py」) · text/09-p161-180.txt:98(搜「top_k:int=4」) · text/09-p161-180.txt:157(搜「search_kwargs={'k': top_k}」) |
| 两种服务方式 | 个人知识库助手项目 | text/08-p141-160.txt:251(搜「uvicorn api:app --reload」) · text/08-p141-160.txt:260(搜「run_gradio.py」) |
| 运行环境要求 | 个人知识库助手项目 | text/08-p141-160.txt:220(搜「Intel 5代处理器」) · text/08-p141-160.txt:222(搜「4 GB」) |
| 版本 0.2.0 与更新内容 | 个人知识库助手项目 | text/08-p141-160.txt:267(搜「0.2.0」) |
| 三条未来方向 | 个人知识库助手项目 | text/09-p161-180.txt:189(搜「未来发展」) · text/09-p161-180.txt:192(搜「Multi-Agent」) |
| 项目背景那两节 | 个人知识库助手项目 | text/08-p141-160.txt:190(搜「提升信息获取效率」) |