课程资料问答助手是智能体开发里非常典型的一个案例把老师上课用的PPT、讲义PDF、教材章节、实验指导书、历年答疑记录这些分散资料统一整理成一个能听懂自然语言问题、能给出带出处答案的问答系统。它不是写一个普通的“大模型聊天框”而是把文档加载、切片、向量检索、提示词设计、多轮对话串联起来核心是检索增强生成RAG。这篇内容围绕一个高校课程案例展开适合正在学习AI编程和智能体开发的初学者也适合刚接触RAG、想把本地文档变成知识库问答助手的开发者。我会按从零搭一个可用Demo的顺序来讲同时把资料准备、切片参数、检索策略、验证方式和常见坑一起说清楚。先给结论这个案例能不能做好不取决于大模型本身而是取决于资料整理和检索链路。模型能力再强检索回来的内容不对回答就是错的。下面按实际落地顺序拆一遍。1. 先想清楚这个问答助手要解决什么而不是急着写代码1.1 课程资料场景的真实痛点课程资料看起来简单真正要处理的时候会发现问题很多。第一是文件类型杂。课件是PPT讲义可能是PDF实验指导书可能是Word有些课程还配套网站、网页教程和参考文档。不同格式的文本抽取方式完全不同不能指望一个PDF解析器处理所有文件。第二是知识分散。同一个概念在PPT里可能只有一句话在教材里会展开讲一段在实验指导书里又换了一种说法。学生提问的时候往往不知道这个问题该看哪份资料。老师要反复回答“这个公式在哪一章”“作业格式要求是什么”这类重复问题。第三是普通大模型聊天框解决不了这个问题。如果只接一个通用大模型它没有课程内部资料只能凭训练时的通用知识回答。遇到课程特有的实验步骤、评分标准、项目要求很容易答错甚至会一本正经地编一个答案出来。所以这个案例真正要解决的需求是把分散的课程资料变成一个集中入口学生问问题系统先从资料里找回相关片段再让模型根据片段生成回答同时标注出处。这样既能减少重复答疑又能让答案有据可查。1.2 从需求拆解出三个核心能力动手写代码之前我建议先把需求拆成三个能力后续所有实现都是围绕这三个能力展开。一是文档接入能力。系统能处理PPT、PDF、Word、网页等多种格式并且能保留标题、页码、文件名等来源信息。这部分做不好后面的切片和检索都会受影响。二是检索增强能力。用户提问之后系统先从向量库或索引中找出相关文档片段而不是直接把整个资料库塞给模型。这样才能控制上下文长度也能提高答案准确率。三是可控回复能力。模型只能根据检索回来的资料回答问题。资料里没有相关内容就直接说“资料中没有找到”而不是靠幻觉补一个答案。同时回答末尾要给出引用让提问者能自己回去核对。这三个能力对应到技术上就是文档解析、文本切片、向量化、相似度检索、提示词构造和模型调用。下面开始讲每一步怎么做。2. 搭建环境与准备课程资料前置工作决定后续成功率2.1 基础环境怎么搭这个案例并不需要特别高端的硬件。我实际测试时用的是普通开发机CPU运行也能跑通只是批量向量化阶段会慢一些。建议环境大概是这样环境项建议配置说明操作系统Windows / macOS / Linux 均可主要跑Python脚本跨平台问题不大Python版本3.10 或更高过低版本可能装不上较新的依赖库内存8GB起步16GB更稳向量化大量文档时内存消耗明显GPU可选没有也能跑有CUDA显卡批量Embedding会快很多大模型API一个支持Embedding和文本生成的模型服务中文场景优先选用中文效果好的模型向量数据库Chroma 或 FAISS学习阶段用Chroma更省事依赖库方面我建议先安装这些基础包langchain-community、langchain-text-splitters、chromadb、pypdf、python-pptx、python-docx。不过要注意不同版本的依赖库之间可能存在兼容问题落地时以你实际安装的版本为准。如果不想用LangChain也可以自己写管道后面会单独说。大模型接口建议用一个支持OpenAI兼容接口的服务商只需要配置base_url、api_key和模型名称。每个服务商的具体参数不一样但思路相同一个是文本生成模型负责最终回答一个是Embedding模型负责把文本变成向量。2.2 课程资料如何整理很多人会把这一步跳过结果就是后面各种问题。资料整理直接决定回答质量我一般会先花半小时把资料整理干净。整理清单大概是这样的文件命名规范。比如01-课程导论.pptx、02-实验指导-发票识别.docx。文件名会成为引用来源的一部分命名太乱引用就没法看。确认PDF是否可复制文本。如果PDF是扫描版需要先用OCR工具识别这一步会引入额外误差。删除重复和过期版本。同一份讲义可能有好几个版本只保留正式发布版。检查敏感信息。课程资料中如果有身份证号、电话、内部评分表等内容不能直接放进问答系统。分类存放。建议目录结构用docs/01课程讲义、docs/02实验指导、docs/03常见问题这种方式后续方便按路径追溯。我经常看到的问题是学生把几十个文件一股脑丢进一个文件夹解析的时候有的文件编码不对有的PPT页脚混入了大量无关文字有的PDF提取出来全是乱码。这些都会直接影响切片和检索结果。与其到后面排查不如一开始就整理干净。3. 数据清洗与切片问答质量的第一个分水岭3.1 文本抽取不同格式分开处理课程资料里最常见的格式是PDF、PPT、Word和网页。每种格式都要单独处理不能用一个万能库搞定所有文件。PDF优先按页读取。用pypdf或类似工具把每一页文本提取出来同时记录页码。如果遇到扫描版PDF需要先OCR。OCR会耗时很多而且识别结果可能有错字可以先从非扫描版本做起。PPT读取时要注意标题和正文分离。很多PPT在备注栏里也有文字不一定都需要纳入知识库。一般来说只需要提取每页幻灯片的标题、正文和图表中的关键文字。表格信息如果被拆散了要做简单拼接。Word按照段落读取比较合理。Word里经常有目录、页眉页脚、批注这些内容要过滤掉。只保留正文段落并在切片时把段落关联到对应章节。网页或HTML文档要去掉导航栏、广告、脚本标签只保留正文内容。如果是课程平台上的网页还需要确认是否有权限导出。这里我建议先写一个加载函数每种格式返回统一的结构文本内容、来源文件名、章节或页码。这个结构后面会一直用到。# 示例结构每个 Document 包含三个字段 document { content: 这是课程讲义中的一段文字……, source: 01-课程导论.pptx, page: 第12页 }为什么要统一结构因为后面切片、向量化、检索和引用展示都要依赖这些元数据。如果每个格式字段不一致代码会越写越乱。3.2 切片策略多长一个块、要不要重叠切片是决定检索效果的关键环节。切片太粗一个块里包含多个主题检索时语义不聚焦切片太细关键上下文被切断模型看不懂片段在说什么。我实际使用的切片参数可以参考下面这个范围参数推荐范围说明chunk_size300-800字符中文场景按字符计算不要贪大chunk_overlap50-150字符相邻切片之间保留一定重叠元数据来源文件名、页码、标题必须保留用于引用溯源是否按标题分割是优先按章节切切不动再按字符数切切片为什么要重叠一句话中间可能被切断重叠部分能让模型读上一个切片时保留下一段的开头信息减少语义断裂。我一般会先拿一份内容比较杂乱的PPT测试切片效果打印出前几个切片看一眼有没有明显被切碎。不要一开始就处理全部文件先跑通一条小样本。4. 向量化与检索让模型先“查资料”再“写答案”4.1 向量模型和向量库选型文本切片完成之后需要把每一段文本变成向量。这里推荐使用中文表现较好的Embedding模型不要拿一个面向英文的模型硬套中文资料。向量库的选择学习阶段我建议用Chroma。它的优势是部署简单、API友好数据量在几万条以内性能足够。如果课程资料量特别大或者需要长期做增量更新再考虑FAISS或Elasticsearch。向量库难度资源占用适合场景Chroma低中等学习、Demo、小规模知识库FAISS中较低大规模向量检索、性能优先Elasticsearch高较高需要和已有检索体系结合这里要注意所有写入向量库的向量必须来自同一个Embedding模型。如果中间更换了模型之前的向量就无法继续使用需要重新生成。4.2 检索策略TopK和阈值用户提问后系统把问题转成向量再从向量库中找出最相似的几段文本。这个数量就是TopK。我建议从k5开始测试不要一开始就拉大到20。TopK太大会把不相关的片段也带进提示词模型容易被噪音干扰。TopK太小又可能漏掉关键内容。实际教学测试里3到8个片段通常是比较合理的范围。还要设置一个相似度阈值。不是所有召回的片段都值得给模型。低于阈值的片段说明跟问题关系不大不应该进入提示词。这个阈值要结合你使用的Embedding模型来调整不同模型分数分布差异很大不能照搬别人的数字。检索时要注意是“先检索再生成”不是把整个资料库拼进提示词。原因很简单课程资料可能几十万字甚至上百万字全部塞进大模型上下文既不经济模型也容易丢失重点。检索只取最相关的几个片段既节省token又能让答案更有针对性。# 检索阶段的核心逻辑 user_question 实验报告里的发票识别部分要求提交什么格式 question_vector embedding_model.encode(user_question) results vector_store.similarity_search_by_vector( question_vector, k5, score_threshold0.35 ) for item in results: print(item.source, item.page, item.content[:50])这个阶段的输出最好先打印出来人工看一眼。检索结果不对说明前面切片或向量选择有问题先别急着改Prompt。5. 生成回答与引用溯源把助手变成可用产品5.1 Prompt设计与限定规则模型生成回答前要把检索到的文本片段和用户问题一起组织成提示词。这里最关键的是限定规则。我常用的Prompt模板是这样的翻译成实际使用时可以直接套用你是一个课程资料问答助手。 你的任务是根据提供的课程资料片段回答用户问题。 规则 1. 只能使用资料片段中的内容回答。 2. 如果资料中没有相关内容请回答“资料中没有找到”。 3. 回答时要简洁、有条理并标注每条信息的来源。 4. 不要编造资料中不存在的内容。 资料片段 {retrieved_chunks} 用户问题 {user_question}为什么这个Prompt这么重要因为通用大模型默认会“尽力回答”即使不知道也会结合自己的记忆编一个答案。通过Prompt明确限制能大幅降低幻觉。同时要在Prompt里要求“标注来源”。让模型在回答结束后用类似“来源《实验指导书》第3页”这样的格式标明出处。这样学生可以直接去核对也更方便老师和助教判断回答是否准确。5.2 多轮对话和引用展示如果学生连续追问不能只把当前问题发给模型需要带上历史对话记录。但历史记录不能无限长否则上下文会膨胀。一个简单的做法是保留最近3到5轮对话超过之后就折叠掉。多轮对话要注意一个问题学生的后续问题往往省略了上下文比如“那考试范围呢”如果直接把这句话拿去检索效果很差。更稳妥的方案是把最近几轮对话和当前问题一起发送给模型让模型在生成前先“重写”出一个完整的问题。不过这一步在入门阶段可以先不做先保证单轮问答效果再加历史对话。引用展示方面我建议在回答下方单独输出一个“参考资料”部分每一条参考资料包含文件名和页码。如果是网页资料还可以给出链接。这样整个回答看起来更像一个学习辅助工具而不是一个黑盒聊天框。6. 从单机脚本到智能体工具调用和低代码方案怎么选6.1 问答助手和智能体的区别课程资料问答助手做到上面这一步已经是一个能用的RAG应用。如果要往智能体方向扩展需要再增加几个组件。智能体的核心是大模型把工具调用来完成复杂任务。比如把“课程资料检索”注册成一个工具把“计算成绩”注册成另一个工具模型根据用户意图决定先调用哪个工具。甚至可以让智能体在第一次检索结果不充分时换一个关键词重新检索。把问答助手升级成智能体通常要增加三块意图识别判断用户是想要课程资料还是想找某个实验报告模板还是想了解考试安排。工具注册把文档检索、FAQ匹配、公开课查询等能力封装成可调用函数。流程编排设计“先检索再判断再回答”的循环而不是一次调用就结束。我建议不要一上来就设计太复杂的智能体流程。先把基础的RAG问答跑稳定然后选择一个高频场景比如“查作业格式要求”做成一个可以自动调用检索工具并给出答案的智能体流程。6.2 低代码平台和代码开发如何取舍现在有不少低代码智能体平台可以在界面上拖拽配置知识库、测试对话、发布应用。这类平台适合快速验证流程也适合非技术背景的助教或老师使用。我自己的经验是低代码平台适合在早期快速看效果导入几份课程资料配置一下系统提示词马上就能测出来“这个课程资料问答助手到底有没有用”。如果效果已经很好了再用代码实现一套更可控的方案接入自己的网站或教务系统。代码开发的好处是灵活和可控。可以自定义切片逻辑、检索后处理、日志记录还能把问答助手封装成内部API。坏处是前期的工程工作量更大。所以我的建议是先低代码验证再代码落地二者不是冲突关系。不管用什么平台背后的数据链路都是一样的文档导入、切片、向量化、检索、生成。把这条链路想明白换工具只是换API的事。7. 实测验证与常见问题排查7.1 验收标准能答、答对、能溯源、不瞎编很多开发者的习惯是跑通Demo就认为完成了。但课程资料问答助手要真正投入使用需要一套验收标准。我建议拿学生的真实问题做测试而不是只拿自己设计的问题。准备20到30个问题覆盖几个维度测试类别样例问题预期结果事实查询实验报告截止日期是答案来自实验指导书能列出处过程查询发票识别步骤分几步能按资料流程回答不遗漏关键步骤资料外问题这学期总成绩怎么算资料没有时回答“资料中没有找到”多轮问题先问作业要求再问格式多轮对话能衔接上下文边界问题推荐一下这门课之外的书能拒绝或引导回课程资料测试完成后最直观的指标就是“过线率”。比如20个问题里18个回答正确且能溯源就算基本达标。如果准确率过低不要急着调Prompt先检查检索回来的片段对不对。7.2 高频问题和排查顺序我踩过的一些坑这里按排查顺序列一下。如果回答为空或者直接报错先看模型调用这一层。API key是否有效、接口地址是否能访问、依赖库版本是否匹配、日志里有没有异常返回。这类问题通常和资料处理无关。如果回答不对也就是模型答非所问优先看检索结果。把检索到的片段打印出来看是不是和问题相关。如果不相关问题出在切片或Embedding模型如果相关但还是答错再看Prompt规则是否足够明确。如果模型回答明显是编造的也就是幻觉重点检查两件事一是是否禁止了模型使用资料之外的知识二是相似度阈值是否过低导致不相关内容进了上下文。如果处理速度慢先看是哪个阶段慢。向量化阶段慢通常是因为文件太多、后台任务串行生成阶段慢通常是模型本身响应慢可以考虑更换更快的模型或降低输出长度。最后还有一个很常见的坑修改了资料内容之后向量库没有更新。学生问的还是旧内容。这个问题最简单也最容易忽略。每次更新资料一定要重新跑一遍文档加载和向量化流程或者使用支持增量更新的向量库。我个人建议真正落地时把输入输出日志都记录下来。每一条问答记录检索到的片段、模型返回的内容、引用来源。这样出了问题可以直接回溯而不是每次重新猜。课程资料问答助手最关键的从来不是界面有多好看而是资料整理是否干净、检索是否准确、回答是否可控。把这三点做好再谈智能体也不迟。