1. 项目缘起：当“章鱼哥”遇上“Vibe Coding”

最近在社区里，“Vibe Coding”这个概念讨论得挺火。它不是什么新框架，更像是一种状态，一种心流。简单说，就是当你完全沉浸在编码的节奏里，工具、思路、反馈环都恰到好处，写代码就像即兴演奏，高效又愉悦。而“全栈实战”则是把这种状态从单一技术点，扩展到从前端到后端，再到AI集成的完整链路中。

这次我想分享的，就是这样一个典型的“Vibe Coding”全栈小项目：“章鱼哥解题”。它的核心场景很具体——一个学生，面对一本厚厚的教材，想快速找到某个知识点的讲解和例题。传统方式是手动翻书、搜索电子版，效率低下。我们的目标是：让用户拍下教材的某一页或输入关键词，系统能自动定位到相关章节，并生成一个针对该知识点的、清晰易懂的AI解答，甚至附上类似例题。

听起来是不是有点像RAG？没错，它的技术内核正是检索增强生成。但和常见的基于海量网络文档的RAG不同，我们面对的是结构相对固定但内容专业的教材。这带来了独特的挑战：如何精准地从书中检索？如何让AI的回答不天马行空，而是紧扣书本内容？这不仅仅是调用API，更涉及到文档处理、检索策略、提示工程和前后端协同的全栈思考。

整个项目走下来，我感觉它完美诠释了“Vibe Coding”的精髓：用一个明确、有趣的需求驱动，快速串联起多个技术栈，在解决实际问题的过程中获得持续的正反馈。下面，我就把这个项目的构建思路、关键技术和踩过的坑，毫无保留地拆解一遍。

2. 架构全景：一本教材的数字化与智能化之旅

在动手写代码之前，得先把蓝图画清楚。这个项目的目标很明确：输入问题，输出基于指定教材的答案。因此，整个系统的核心流水线可以概括为“教材数字化 -> 知识切片与嵌入 -> 精准检索 -> 智能生成”。

我选择的实战技术栈如下：

• 前端：Vue 3 + Vite。轻快、现代，组合式API非常适合构建交互复杂但逻辑清晰的应用。UI库用了Element Plus，省时省力。
• 后端：Node.js + Express。轻量级，异步友好，与我们的AI服务调用是绝配。数据库用PostgreSQL，存点用户查询记录、教材元数据够用了。
• AI核心：
  • 嵌入模型：选用text-embedding-3-small。对于教材文本，平衡了性能、效果和成本。
  • 大语言模型：Qwen2.5-7B-Instruct本地部署。为什么选它？首先，7B参数在消费级显卡上跑推理压力不大；其次，它在中文理解和指令跟随上表现相当稳健；最重要的是，本地部署避免了API调用延迟、费用和潜在的网络问题，让整个RAG流程更可控。
  • 向量数据库：Pgvector。直接作为PostgreSQL的插件，无需引入额外服务，利用现有数据库基础设施，管理和备份都方便。
• 文档处理：一套组合拳。pdfplumber或PyMuPDF提取PDF教材文本和基础布局；Unstructured库处理更复杂的版面分析；再用LangChain的RecursiveCharacterTextSplitter进行智能文本分割。

整个架构的数据流是这样的：

1. 预处理阶段：用户上传教材PDF。后端服务启动处理流程，解析PDF，按章节/知识点分割文本块，调用嵌入模型为每个文本块生成向量，最后存入Pgvector。
2. 查询阶段：用户在前端输入问题。前端将问题发送至后端。
3. 检索阶段：后端用同样嵌入模型将用户问题向量化，在Pgvector中执行相似度搜索，找出最相关的几个教材文本片段。
4. 生成阶段：后端将检索到的文本片段作为上下文，连同用户问题和精心设计的提示词，一并发送给本地部署的Qwen2.5模型。模型生成答案后，返回给前端展示。

这个架构清晰地将责任分层，每一层都可以独立优化。比如，检索不准可以调整文本分割策略或嵌入模型；回答不好可以优化提示词或切换LLM。

3. 核心战场一：教材的“结构化”切片艺术

项目成败的第一个关键点，就在于如何把一本厚厚的、可能排版复杂的教材，变成适合检索的“知识碎片”。直接整页扔进去或者按固定字符长度切，效果都会很差。

3.1 从“物理结构”到“语义单元”

教材是有内在结构的：章、节、小节、知识点、例题、图表。我们的切片目标，是尽可能让每个文本块都是一个完整的语义单元。比如，一个定义、一个定理及其证明、一道例题及其解析。

实际操作中，我采用了分层处理策略：

1. 初级解析：使用pdfplumber提取原始文本和粗略的坐标信息。这一步能拿到所有文字，但失去了大部分结构。
2. 版面分析：对于排版规范的教材，Unstructured库是神器。它能识别出标题、正文、列表等元素。我们可以利用标题的样式和层级，作为切分的天然边界。
3. 智能分割：这是核心。直接使用LangChain的RecursiveCharacterTextSplitter，并配置中文分隔符。我常用的分隔符优先级是：\n\n##,\n\n###,\n\n,。,；,，。它会递归地尝试用这些分隔符来切割，直到块的大小符合设定（比如500-800个字符）。同时，一定要设置overlap（重叠），比如100个字符，这能防止一个完整的句子被拦腰截断，保证检索时上下文的连贯性。

from langchain.text_splitter import RecursiveCharacterTextSplitter text_splitter = RecursiveCharacterTextSplitter( chunk_size=600, chunk_overlap=100, separators=["\n\n## ", "\n\n### ", "\n\n", "。", "；", "，", " ", ""] ) chunks = text_splitter.split_text(processed_text)

3.2 为切片注入“灵魂”：元数据

光有文本块还不够。检索时，我们不仅要知道内容相关，还要知道它出自哪里。因此，每个文本块必须携带丰富的元数据：

• source: 教材名称。
• chapter: 章节标题。
• page: 页码。
• type: 内容类型（如definition,theorem,example,normal_text）。

在存入向量数据库时，这些元数据要和向量一起存储。Pgvector允许你在同一张表里存向量和其他字段，查询时既能按向量相似度排序，也能用元数据过滤。例如，用户可以指定“只在第三章的例题里搜索”。

踩坑实录：初期我忽略了元数据，结果检索出来的答案虽然相关，但用户根本不知道是哪一章的内容，体验很差。后来强制给每个块打上章节标签，并在前端答案处显式标注“参考自《XX教材》第X章”，可信度瞬间提升。

4. 核心战场二：检索策略与“提示工程”的深度耦合

检索和生成不是两个孤立的步骤，而是需要紧密配合。检索为生成提供“弹药”，而生成的质量直接取决于“弹药”的质量和如何使用它们。

4.1 检索：不只是相似度匹配

最简单的检索就是计算用户问题向量与所有文本块向量的余弦相似度，取Top K。但这在教材场景下容易出问题。比如，用户问“什么是牛顿第二定律？”，很可能检索出一堆包含“牛顿”、“第二”、“定律”字眼，但其实是不同上下文（如历史背景、其他定律提及）的片段。

我的优化策略是：

1. 查询扩展：在将用户问题向量化前，先用LLM对问题进行一步“重写”或“扩展”。例如，原问题“牛顿第二定律”，可以扩展为“牛顿第二定律的公式、表述、物理意义、应用实例”。这能增加查询向量的信息量，匹配到更相关的文本。
2. 混合检索：结合稠密检索（向量相似度）和稀疏检索（关键词匹配，如BM25）。向量检索擅长语义匹配，关键词检索擅长精确匹配。将两者的结果按分数融合，能提高召回率。虽然Pgvector主要做向量检索，但我们可以将文本块的原始内容同时存一份，用简单的关键词匹配库辅助计算。
3. 元数据过滤：如前所述，利用章节、类型等元数据进行前置过滤，缩小搜索范围，提升精度和速度。

4.2 提示工程：让AI成为“助教”

检索到Top N个相关片段后，如何组装成给LLM的提示词，是决定答案质量的关键。这里的目标是让LLM扮演一个“精通这本教材的助教”。

我的提示词模板经过多次迭代，最终定型为以下结构：

你是一位专业的教学助手，精通《{教材名称}》这本教材。请严格基于以下提供的教材内容片段，回答用户的问题。 【相关教材内容】 {context_1} {context_2} ... 【结束】 用户问题：{question} 请遵循以下要求： 1. 答案必须严格以上述教材内容为依据，不要引入教材外的知识或编造信息。 2. 如果提供的教材内容不足以完全回答问题，请诚实告知“根据教材内容，无法完全解答该问题”，并仅就已有内容进行说明。 3. 组织语言清晰、易懂，像老师在讲解一样。如果可能，尝试用教材中的例题风格来举例说明。 4. 在答案末尾，注明答案主要参考了教材的哪些章节（例如：主要参考自第X章“XXX”）。

这个模板的精髓在于：

• 明确角色和边界：开头就限定LLM的角色和知识来源，极大减少了“幻觉”。
• 结构化上下文：用明确的标记【相关教材内容】和【结束】将上下文与指令分离，帮助模型理解。
• 强制引用与诚实：要求注明参考章节，并明确指示在信息不足时“诚实告知”，这比单纯说“不要编造”有效得多。
• 引导风格：要求“像老师讲解”，鼓励模型生成更友好、更具解释性的文本。

实操心得：提示词中的“如果可能，尝试用教材中的例题风格来举例说明”这一句，效果拔群。它激活了LLM的模仿能力，生成的答案常常会附带一个与教材风格高度一致的小例子，用户体验非常好。这比单纯要求“举例说明”更具体、更有效。

5. 核心战场三：全栈协同与性能调优

当AI核心流程跑通后，真正的“全栈”挑战才刚开始：如何让它成为一个稳定、可用、用户体验良好的产品？

5.1 前端：构建流畅的交互链路

前端不只是个输入框和提交按钮。需要考虑的状态和交互很多：

• 教材管理：上传PDF、显示处理进度、管理已上传的教材列表。
• 对话界面：显示连续的问答历史，区分用户消息和AI消息，AI消息中需要高亮显示引用的教材章节。
• 状态反馈：检索和生成需要时间，必须有加载状态提示（如骨架屏、进度条）。
• 错误处理：网络错误、模型生成错误、检索无结果等，都需要友好的用户提示。

我使用Vue 3的<script setup>语法和Composition API，将AI对话的状态、方法封装成一个可复用的useAIChatcomposable，使得业务组件非常清爽。

5.2 后端：异步、队列与缓存

关键的后端优化点：

• 异步处理：教材PDF解析和向量化非常耗时，绝不能阻塞HTTP请求。我使用了一个简单的任务队列（Bull库基于Redis），用户上传教材后，立即返回一个任务ID。前端通过轮询或WebSocket来获取处理进度。
• 缓存：对于相同的用户问题，如果教材内容未变，结果其实是一样的。我在内存（或Redis）中设置了一个简单的查询缓存，键由“用户问题+教材ID”的哈希生成，有效期内直接返回缓存结果，大幅降低LLM调用开销。
• API限流与超时：防止恶意请求，并对LLM调用设置合理的超时时间，避免长时间等待拖垮服务。

5.3 本地LLM服务部署与监控

本地部署Qwen2.5-7B，我选用的是ollama。它管理模型、提供类OpenAI的API接口，非常方便。

# 拉取并运行模型 ollama pull qwen2.5:7b ollama run qwen2.5:7b

服务启动后，会提供一个http://localhost:11434/v1/chat/completions的端点，我们的后端直接调用它即可。

监控方面，需要关注：

• GPU内存：7B模型在推理时大约需要14GB左右的GPU内存。确保你的显卡足够。
• 响应时间：记录每次生成的时间，如果平均时间过长，需要考虑优化提示词长度、启用流式输出以提升感知速度，或者对答案长度做限制。
• 异常日志：详细记录检索、生成过程中的任何错误，便于排查。

6. 避坑指南与进阶思考

项目上线后，通过实际用户反馈，又发现并解决了一些深层次问题。

6.1 常见问题与解决方案

• 问题：检索结果似乎相关，但生成的答案就是“答非所问”或很空洞。

  • 排查：首先检查检索到的文本片段。很可能这些片段只是“提及”了关键词，但并非核心解释。例如，检索到了“牛顿第二定律是经典力学的核心”，这句话本身没有信息量。
  • 解决：优化文本分割，确保每个块是自包含的语义单元。在检索后增加一个“重排序”步骤：用一个小型的、更快的模型（或交叉编码器）对Top K的结果进行相关性精排，只把最相关的1-2个片段送给生成模型。

• 问题：对于数学公式、图表，系统无能为力。

  • 解决：这是当前纯文本RAG的局限。进阶方案是采用多模态模型。例如，将教材页面转为图片，使用多模态嵌入模型（如CLIP）将图片和问题一起编码检索，或者使用GPT-4V等视觉模型来“阅读”页面。当然，这复杂度和成本会剧增。一个折中方案是，在文本切片时，记录下公式和图表所在的页码，在答案中提示用户“详见教材第X页图Y”。

• 问题：用户问题非常模糊，如“这里我不懂”。

  • 解决：前端交互上引导用户问得更具体。后端可以尝试一个“追问”机制：当检索到的片段置信度很低或非常分散时，让LLM生成一个澄清性问题反问用户，而不是强行生成一个可能错误的答案。

6.2 从RAG到Agentic RAG的展望

目前的系统是被动响应的。所谓的“Agentic RAG”是指让系统具备一定的自主规划和工具调用能力。在这个项目里，我们可以设想：

1. 用户问一个复杂问题，系统先将其分解成几个子问题。
2. 针对每个子问题，独立进行检索。
3. 综合所有子答案，组织成最终回答。
4. 甚至，在回答完后，可以主动提问：“我讲清楚了吗？关于其中的XX步骤，你需要更详细的解释吗？”

这需要更复杂的流程控制和LLM的规划能力，可以用LangGraph或Dify的Workflow来构建。例如，在Dify中，你可以可视化地搭建一个流程：先“问题分解”节点，然后并行多个“检索”节点，最后“综合回答”节点。这将是本项目一个非常自然的演进方向。

6.3 关于技术选型的再思考

• 为什么不用LangChain？本项目核心逻辑清晰，自己实现检索和提示词组装并不复杂，避免了LangChain的抽象开销，让代码更透明、更易调试。但对于想快速搭建或需要更多预制组件（如各种文档加载器、Agent工具）的开发者，LangChain仍是优秀选择。
• 向量数据库选型：Pgvector适合中等规模、已经使用PostgreSQL的场景。如果数据量极大（上亿条），或对检索速度有极致要求，可能需要考虑专业的向量数据库如Milvus或Pinecone。
• LLM选型：Qwen2.5-7B在中文和指令跟随上性价比很高。如果追求极致效果，可以考虑更大的模型如Qwen2.5-32B或GLM-4，但需要更强的算力。API方案（如DeepSeek、GPT）则省心但持续产生费用。

回过头看，“章鱼哥解题”这个项目，从想法到实现，正是一次完整的“Vibe Coding”体验。它从一个具体的痛点出发，迫使你去思考数据如何准备、模型如何调用、前后端如何衔接这些全栈问题。过程中，你会为精准检索到一个段落而兴奋，也会为提示词微调后答案质量的提升而感到满足。这种小步快跑、持续获得正反馈的循环，或许就是“Vibe”所在。

最后，分享一个让我自己都惊讶的发现：在项目后期，我有时会故意问一些教材边角料的问题，系统往往能准确地从某个不起眼的注释或习题提示里找到答案。那一刻的感觉，真的像是赋予了那本静态教材一个数字化的“灵魂”，而这一切，都始于几行代码和一个明确的想法。