我为什么给自己写了个查文档的机器人-RAG

我的痛点：不是学不会，是查不到

去年到今年，我陆续买了正点原子 DNESP32S3 的开发板和几套教程资料。文档是齐全的：

• 《DNESP32S3 使用指南》Arduino 版、IDF 版、MicroPython 版（三个版本各一份）

• 《FreeRTOS 开发指南》《LVGL 开发指南》

• 《Espressif IDE 使用说明》《基于 LINUX 环境下开发 ESP32》

• 还有一份 644 页、1094 张图的手册

问题不在于文档不够，而在于查起来太慢。

举个真实场景：

我想用 IDF 版做个 WiFi 连接。

我大概记得好像在哪份指南的第 3 章，于是打开 PDF → 搜索「WiFi」→ 命中 200 多处 → 一页页翻。

翻到第 12 页终于看到配置代码 —— 但我已经花了十几分钟。

说实话，只要有成套 PDF 操作指南的地方，就有这个毛病。产品手册是这样，内部技术文档也是这样。

传统搜索解决不了：我搜WiFi 连不上，文档里写的是STA 模式连接失败——词对不上，就搜不到。

这就是 RAG（检索增强生成）要解决的场景。

它不是聊天机器人，是能标出处的问答

很多人的第一反应是-不就是套个 ChatGPT 让它读文档吗？——差别很大。

我给它的定义只有一句话：

一个能读 PDF 操作指南、能用自然语言问、能标出处的本地知识库工具。

关键在最后四个字：标注出处。

我的演示场景是这样的：

我问：怎么配置 WiFi 连接？

页面流式打出答案（一个字一个字往外蹦，不用干等），

而答案下面挂着一张引用卡片：

「摘自《DNESP32S3 使用指南-IDF 版》第 12 页 · 相似度 0.83」

——点一下，展开原文段落。

为什么我坚持要出处？

• 嵌入式文档不能瞎编。
   引脚接错、寄存器写错是要烧板子的。答案必须可回溯。

• 标出处本身就是最好的信任设计。
   招聘方、甚至我自己，第一眼看到的是它敢标来源。

• 它让面试叙事完整。
   我做了个问答很平；我做了一个答案可追溯到页码的问答立刻有工程含量。

范围我刻意收得很小：单机、单用户、本地数据。不做多用户、不做云端。

第一版就只服务一件事：让 10 个问题答得漂亮，胜过 100 个问题答得稀烂。

开始之前，先说好三个事情

吃过亏的人都知道：业余项目最怕的不是难，是做着做着跑偏。所以我在写第一行代码前先定了三条纪律：

一：别一上来追求什么都能答。

先让 10 个问题答得漂亮。一上手就想覆盖所有文档类型、所有提问方式，结果一定是全都半成品。

二：先实现功能，不要先做界面。

RAG 的命脉在检索。检索不准，界面做得再花哨，也是个漂亮的空壳——用户问三句就发现你在瞎答。

三：每个决策写一行理由。

做的时候顺手写一行，几个月后它就是面试时一句顶一万句的弹药。

这三条在后面 10 篇文章里会反复出现：我几乎每一次返工，都是因为违反了其中某一条。

它被我拆成了 9 个里程碑，每一步都有一个能跑的东西

我讨厌「写了三周还看不到结果」。所以整个项目按里程碑推进，每一步结束都有一件能当场演示的东西：

M8 的效果是这样的：打开网页 → 把一份新 PDF 拖进上传区 → 页面实时显示「解析中 → 切块中 → 嵌入中 → 入库完成，共 XXX 块，耗时 XX 秒」→ 切到问答页直接提问。

现场拖文档、当场提问——「解析中 → 切块中 → 嵌入中 → 入库完成」这条实时链条摆在那儿，比任何静态演示都说明问题。

我的干活方式：核心代码我亲手写，杂活交给我的 AI 军师

这部分我本来不打算写，但想想还是写了吧——2026 年的独立开发者，你怎么用 AI本身就是能力的一部分。

我的分工很明确：

• 我亲手写核心代码。
   切块器的策略、检索的实现、提示词的组装——这些是「理解」的地方，别人代写等于白做。

• AI 助手负责它擅长的：
   环境搭建与排错、架构评审、代码诊断、把我踩的坑整理成检查清单。

• 它还会做一件很有用的事：验收。
   我写完一个里程碑，它按需求文档逐条核对、指出问题。

举个真实例子，你感受一下这个协作方式：

M2 我写完切块器，跑出来 3495 个块，看起来挺好。

块数正常、外表正常，只有核对数据才会发现这是错的。

这件事我单独写了一篇（第 5 篇）。

「跑通了」和「数据是对的」是两件事。

技术栈先交个底（第 2 篇会逐项讲为什么）：

语言      Python 数据库    PostgreSQL + pgvector（一个库同时管元数据和向量） 解析      PyMuPDF 嵌入      BGE 中文系（先小后大） 大模型    DeepSeek 接口（封装成可替换的统一接口） 编排      手写函数管道（不用 LangChain） 接口/前端 FastAPI + Vue3

【下期预告】

下一期会讲下为什么要用这些技术，这就涉及你的项目大小决定的技术选型

💡 如果你也在做 RAG，或者正被一堆 PDF 手册折磨——这套东西的完整代码、踩坑清单我都会在后面写出来。

有具体想看的环节（比如切块策略、检索调优），留言告诉我，我优先写。