同学们在实际开发课程项目时常常会遇到一类需求把课程讲义、课件、实验手册变成可以对话的知识库。比如期末复习时面对几十个 PPT 和 PDF想快速找到“进程和线程的区别”“什么是事务的隔离级别”如果靠人工翻阅资料效率很低。而直接问通用大模型又担心它给出的答案不在课程范围内甚至出现“编造”内容。本文就以“课程资料问答助手”为实战案例完整演示如何基于检索增强生成RAG架构从零构建一个能围绕指定课程资料回答问题的智能体。内容适合有 Python 基础、正在学习 AI 编程与大模型应用开发的同学也适合想把公开课资料做成内部问答知识库的教师或学习者。通过本文你将掌握课程资料问答助手的整体设计思路、文档加载与文本切分的实现方式、向量检索与大模型生成是如何协作的以及如何用一套可运行的 Python 代码搭建完整项目。1. 为什么需要课程资料问答助手1.1 课堂资料检索的现实痛点在一门课程中资料通常分散在多个文件中课程 PPT、实验指导书、课后习题、补充阅读材料。这些资料有几个共性格式不统一、篇幅较长、知识点分散。学生想查一个概念往往需要在多个文档之间反复跳转先找目录、再定位章节、最后还要自己归纳总结。通用大模型的出现解决了一部分问题但直接使用通用大模型仍有明显不足一是它不一定了解你这门课的具体内容尤其是老师自定义的案例、实验环境、评分标准二是当问题涉及课程内部细节时大模型容易“自由发挥”给出看似合理但实际不在资料范围内的回答。1.2 什么是课程资料问答助手课程资料问答助手的核心目标是让用户用自然语言提问系统从指定课程资料中检索相关内容再由大模型基于检索结果生成回答。它和普通聊天机器人的最大区别是回答必须“有据可依”即每个结论都尽量来自课程资料而不是大模型凭空生成。这种实现方式在业界称为 RAGRetrieval-Augmented Generation检索增强生成。RAG 的基本思路是先检索再生成先从知识库中找到与问题最相关的文本片段然后把这些片段作为上下文交给大模型让大模型根据上下文生成答案。1.3 从 AI 编程与智能体开发角度看这个案例近年来“AI 编程”和“智能体开发”成为人工智能应用领域的热门方向。AI 编程不仅指用 AI 工具辅助写代码也包含“具备大模型能力的软件开发”这一层含义。而智能体Agent通常指能够感知环境、做出决策并执行任务的系统。本文的课程资料问答助手从智能体角度看是一个简化版的“检索型智能体”。它具备以下能力接收用户问题相当于 Agent 的感知输入。判断应该从知识库中检索哪些内容相当于决策过程。调用大模型生成回答相当于执行动作。把问答助手作为智能体开发的入门案例最大的好处是结构清晰、原理明确不会一上来就涉及复杂的多智能体协作、任务规划等内容。学完这个案例后再继续学习 Agent 记忆、工具调用、多轮对话等进阶能力会更加顺畅。2. 核心原理RAG 架构拆解2.1 RAG 的整体流程课程资料问答助手的完整流程可以分为“知识库构建”和“问答检索”两个阶段。知识库构建阶段的流程如下加载课程资料文件如 PDF、Word、Markdown、TXT。按一定规则把长文本切分成多个文本块。使用嵌入模型Embedding Model将文本块向量化。将文本块和向量存入本地知识库。问答检索阶段的流程如下用户输入问题。将问题用相同的嵌入模型向量化。在知识库中计算相似度找出最相关的 top-k 个文本块。将文本块拼接为上下文构造提示词。调用大模型生成最终回答。对于初次接触 RAG 的同学可以把整个流程理解成“先查资料再写答案”。和人类写课程论文的流程非常像先找参考资料再组织语言。2.2 为什么选择 RAG 而不是直接训练模型有同学可能会问为什么不直接把课程资料拿去微调大模型或者为什么不让大模型直接学习资料内容直接微调模型有两个问题一是成本高需要 GPU 资源和较长的训练时间二是更新不灵活如果课程内容增删需要重新训练。RAG 方案则不同只需要更新知识库中的文档即可不需要重新训练模型成本低、更新快更适合课程资料这类数据量不大的场景。从回答准确性来看RAG 的一个关键优势是“可溯源”。回答中可以附带参考来源当用户对答案有疑问时可以回到原始资料中核对这对于学习场景非常重要。2.3 技术选型说明本案例使用以下技术组合Python 作为主要开发语言版本建议 3.10 及以上。PyMuPDF 解析 PDF 文件python-docx 解析 Word 文件。sentence-transformers 加载本地嵌入模型将文本转换为向量。numpy 或纯 Python 计算余弦相似度。OpenAI 兼容接口调用大模型如 DeepSeek、通义千问、Ollama 等统一走 HTTP 接口。为什么会选择 OpenAI 兼容接口因为目前国内外主流大模型服务大多提供兼容 OpenAI API 格式的接口只要修改 Base URL 和 API Key就能在同一个代码框架下切换不同模型非常适合教学演示。3. 环境准备与项目结构3.1 环境要求运行本文代码前需要准备以下环境依赖项说明操作系统Windows / macOS / Linux 均可Python建议 3.10 或更高版本大模型 API任意 OpenAI 兼容接口或本地 Ollama磁盘空间至少 2GB 用于存放嵌入模型和课程资料如果你没有大模型 API也可以使用本地部署的 Ollama 作为大模型后端。只要将base_url指向本地地址即可。3.2 安装依赖创建虚拟环境并安装依赖命令如下python -m venv venv source venv/bin/activate # Windows 下执行 venv\Scripts\activate安装依赖pip install openai python-docx PyMuPDF sentence-transformers numpy如果服务器位于国内sentence-transformers下载模型时可能较慢可以提前设置 Hugging Face 镜像export HF_ENDPOINThttps://hf-mirror.comWindows 命令行使用set HF_ENDPOINThttps://hf-mirror.com。3.3 项目结构项目目录结构如下course_assistant/ ├── config.py # 配置文件存储环境变量和模型参数 ├── kb_builder.py # 知识库构建模块 ├── assistant.py # 问答助手模块 ├── main.py # 交互式入口 ├── requirements.txt # 依赖清单 └── data/ # 存放课程资料 ├── 操作系统笔记.md └── 数据库实验手册.pdf下面逐个文件实现。3.4 准备课程资料在data目录下放入你的课程资料。格式不限本案例支持 Markdown、TXT、PDF、Word。如果资料较多建议先从一个最典型的文件开始例如一门课的 PPT 转成的 PDF或者课程笔记的 Markdown 文件。为了后续演示我准备了一段《操作系统》课程笔记的样例内容如下# 操作系统基本特征 操作系统有四个基本特征并发、共享、虚拟、异步。 并发是指两个或多个事件在同一时间间隔内发生。在单核 CPU 环境中 多个进程通过时间片轮转的方式交替执行宏观上看起来是同时进行的。 共享是指系统中的资源可供内存中多个并发执行的进程共同使用。 资源共享有两种方式互斥共享和同时访问。 虚拟是指通过某种技术把一个物理实体变为若干个逻辑上的对应物。 例如虚拟内存技术可以让物理内存较小的系统运行更大的程序。 异步是指进程以不可预知的速度向前推进。由于资源竞争 进程何时执行、何时阻塞并不确定因此操作系统需要提供同步机制。 # 进程与线程 进程是程序的一次执行过程是资源分配的基本单位。 线程是进程中的一条执行路径是 CPU 调度的基本单位。 同一进程中的多个线程共享进程的地址空间和资源。将内容保存为data/操作系统笔记.md。这段资料将成为后续代码测试的知识库内容。4. 代码实现4.1 配置文件 config.py配置文件用于集中管理大模型参数和检索参数避免把 API Key 硬编码在业务代码中。# 文件路径course_assistant/config.py import os # 大模型配置 # 如果你使用 DeepSeek保持默认地址即可 # 如果你使用 Ollama可将 base_url 改为 http://localhost:11434/v1 LLM_BASE_URL os.getenv(LLM_BASE_URL, https://api.deepseek.com/v1) LLM_API_KEY os.getenv(LLM_API_KEY, your-api-key) LLM_MODEL os.getenv(LLM_MODEL, deepseek-chat) # 嵌入模型配置 # 使用本地模型不需要联网调用 API EMBEDDING_MODEL os.getenv(EMBEDDING_MODEL, BAAI/bge-small-zh-v1.5) # 检索参数 CHUNK_SIZE 300 # 切分文本的块大小 CHUNK_OVERLAP 50 # 相邻文本块的重叠长度 TOP_K 3 # 检索返回的文本块数量这里使用os.getenv读取环境变量是一种安全实践。如果环境变量没有设置则使用默认值。在真实项目中API Key 不要写在代码里更不要提交到 Git 仓库。4.2 知识库构建模块 kb_builder.py知识库构建模块负责加载文档、切分文本、生成向量。先实现文档加载部分。# 文件路径course_assistant/kb_builder.py import os from pathlib import Path import fitz # PyMuPDF用于解析 PDF from docx import Document # python-docx用于解析 Word def load_text_file(file_path: str) - str: 加载 .txt 和 .md 文件 with open(file_path, r, encodingutf-8) as f: return f.read() def load_pdf_file(file_path: str) - str: 使用 PyMuPDF 提取 PDF 文本 text with fitz.open(file_path) as pdf: for page in pdf: text page.get_text() return text def load_docx_file(file_path: str) - str: 使用 python-docx 提取 Word 段落文本 doc Document(file_path) paragraphs [p.text for p in doc.paragraphs if p.text.strip()] return \n.join(paragraphs) def load_document(file_path: str) - str: 根据文件后缀选择对应的解析方式 suffix Path(file_path).suffix.lower() if suffix in {.txt, .md}: return load_text_file(file_path) elif suffix .pdf: return load_pdf_file(file_path) elif suffix .docx: return load_docx_file(file_path) else: raise ValueError(f暂不支持的文件格式{suffix})接着实现文本切分函数。切分的目的是把长文档拆成适合检索的小块。块太大检索到之后包含太多无关内容影响回答精度块太小单个块的信息量不足也容易丢失上下文。这里采用按固定长度切分并添加重叠窗口的策略def split_text(text: str, chunk_size: int 300, chunk_overlap: int 50) - list: 按固定长度切分文本并保留一定的重叠区域 text text.strip() chunks [] start 0 while start len(text): end min(start chunk_size, len(text)) # 尽量在标点符号处截断 if end len(text): last_period max(text.rfind(。, start, end), text.rfind(\n, start, end)) if last_period start chunk_size * 0.6: end last_period 1 chunks.append(text[start:end].strip()) start max(end - chunk_overlap, start 1) if start end: break return chunks这个函数的逻辑是每次取chunk_size长度的文本然后尝试在句号或换行处断句。如果找不到合适的断句位置就按最大长度截断。chunk_overlap保证相邻块之间有一定重叠避免关键信息被拦腰切断。然后是向量化和检索模块。我们需要把每个文本块用嵌入模型编码为向量同时保存文本块的原始内容和来源文件路径。from sentence_transformers import SentenceTransformer import numpy as np class KnowledgeBase: 课程知识库负责嵌入、存储、检索 def __init__(self, embedding_model: str): self.model SentenceTransformer(embedding_model) self.chunks [] # 文本块列表 self.sources [] # 来源文件列表 self.embeddings None # 向量矩阵 def add_document(self, file_path: str, chunk_size: int 300, chunk_overlap: int 50): 加载单个文档切分并向量化 text load_document(file_path) chunks split_text(text, chunk_size, chunk_overlap) new_embeddings self.model.encode(chunks, normalize_embeddingsTrue) if self.embeddings is None: self.embeddings np.array(new_embeddings) else: self.embeddings np.vstack([self.embeddings, new_embeddings]) self.chunks.extend(chunks) self.sources.extend([file_path] * len(chunks)) print(f已加载文档{file_path}新增 {len(chunks)} 个文本块) def search(self, query: str, top_k: int 3): 基于余弦相似度检索最相关的文本块 query_embedding self.model.encode([query], normalize_embeddingsTrue)[0] # 计算余弦相似度 scores self.embeddings query_embedding top_indices np.argsort(scores)[::-1][:top_k] results [] for idx in top_indices: results.append({ score: round(float(scores[idx]), 4), text: self.chunks[idx], source: self.sources[idx] }) return results这里的关键点是normalize_embeddingsTrue让向量归一化后向量点乘的结果就等价于余弦相似度。代码中使用self.embeddings query_embedding本质上是一次矩阵乘法一次性计算问题向量与所有文本块向量的相似度比 for 循环更快。4.3 问答生成模块 assistant.py知识库负责“找资料”大模型负责“写答案”。问答生成模块要完成两件事构造提示词调用大模型。提示词设计是整个问答效果的关键。对于 RAG 应用提示词必须明确告诉大模型只能使用给定资料回答资料里没有的内容要明确说不知道。# 文件路径course_assistant/assistant.py import os from openai import OpenAI from config import LLM_BASE_URL, LLM_API_KEY, LLM_MODEL from kb_builder import KnowledgeBase # 创建 OpenAI 兼容客户端 client OpenAI(base_urlLLM_BASE_URL, api_keyLLM_API_KEY) def build_prompt(question: str, contexts: list) - str: 根据检索结果构造提示词 context_text for i, ctx in enumerate(contexts): context_text f[资料{i1}]\n{ctx[text]}\n\n prompt f你是一名课程资料问答助手。请根据以下课程资料回答问题。 要求 1. 如果资料中包含答案请直接回答语言简洁准确。 2. 如果资料中没有相关信息请明确回答“当前资料中未找到相关内容”。 3. 回答时尽量引用资料中的原话并标注来源。 4. 不要输出资料之外的推测内容。 课程资料 {context_text} 问题{question} 回答 return prompt def ask(question: str, kb: KnowledgeBase, top_k: int 3) - str: 完整的问答流程检索 生成 contexts kb.search(question, top_ktop_k) prompt build_prompt(question, contexts) response client.chat.completions.create( modelLLM_MODEL, messages[ {role: system, content: 你是严谨的课程资料问答助手。}, {role: user, content: prompt} ], temperature0.2 ) answer response.choices[0].message.content # 在回答后面附上参考来源 sources list(set([ctx[source] for ctx in contexts])) if sources: answer \n\n参考来源 .join(sources) return answertemperature0.2表示生成结果更确定、更保守适合问答场景。如果temperature设置太高模型可能自由发挥太低则可能过于机械。4.4 交互式主程序 main.py主程序负责把知识库构建和问答串联起来。支持两种使用方式首次运行自动构建知识库之后可以连续提问。# 文件路径course_assistant/main.py from pathlib import Path from config import CHUNK_SIZE, CHUNK_OVERLAP, EMBEDDING_MODEL, TOP_K from kb_builder import KnowledgeBase from assistant import ask def build_kb(data_dir: str) - KnowledgeBase: 遍历 data 目录加载所有课程资料 kb KnowledgeBase(embedding_modelEMBEDDING_MODEL) for file_path in Path(data_dir).glob(*): if file_path.is_file(): suffix file_path.suffix.lower() if suffix in {.txt, .md, .pdf, .docx}: kb.add_document(str(file_path), chunk_sizeCHUNK_SIZE, chunk_overlapCHUNK_OVERLAP) print(f知识库构建完成共 {len(kb.chunks)} 个文本块) return kb def main(): data_dir data kb build_kb(data_dir) print(课程资料问答助手已启动输入问题开始提问输入 exit 退出。) while True: question input(\n问题).strip() if question.lower() exit: print(再见) break if not question: continue try: answer ask(question, kb, top_kTOP_K) print(\n回答\n answer) except Exception as e: print(f问答出错{e}) if __name__ __main__: main()这个主程序逻辑虽然简单但已经是一个完整的交互闭环加载资料、构建向量库、循环接收问题、检索生成回答。后续可以在此基础上增加 Web 页面、对话历史、资料实时更新等功能。5. 运行与验证5.1 启动助手在项目根目录执行python main.py程序会先加载嵌入模型。首次运行需要下载BAAI/bge-small-zh-v1.5模型耗时取决于网络状况。下载完成后会遍历data目录加载课程资料并输出类似日志已加载文档data/操作系统笔记.md新增 6 个文本块 知识库构建完成共 6 个文本块 课程资料问答助手已启动输入问题开始提问输入 exit 退出。5.2 提问示例问一个知识库中有明确答案的问题问题操作系统的四个基本特征是什么预期回答会从切分好的文本块中检索到相关内容大模型基于这些内容生成类似根据课程资料操作系统的四个基本特征是并发、共享、虚拟、异步。 并发是指两个或多个事件在同一时间间隔内发生 共享是指系统中的资源可供多个并发执行的进程共同使用 虚拟是通过某种技术把一个物理实体变为若干个逻辑上的对应物 异步是指进程以不可预知的速度向前推进。 参考来源data/操作系统笔记.md再问一个知识库中没有答案的问题问题什么是数据库索引由于资料中没有相关内容助手的回答应该是当前资料中未找到相关内容。 参考来源data/操作系统笔记.md从运行效果可以看出RAG 方案的“守住边界”能力非常关键。大模型不会因为熟悉数据库知识就强行解题而是遵循了提示词中“资料中没有相关信息时明确说明”的约束。5.3 效果评估与调优判断问答助手效果好不好不能只看个别问题。建议准备一组测试问题覆盖四类情况问题类型示例期望表现直接命中操作系统的四个特征回答准确有来源语义改写CPU 调度的最小单位是什么能识别出是“线程”相关知识点综合归纳并发和并行的区别能在多个文本块之间综合资料外问题推荐一部电影明确回答未找到当效果不理想时优先调整调大TOP_K让模型可以看到更多上下文。减小CHUNK_SIZE让每个文本块更聚焦。切换更强的嵌入模型例如BAAI/bge-base-zh-v1.5。优化提示词要求模型优先引用资料原文。6. 常见问题与排查思路6.1 常见报错与解决办法问题现象常见原因解决思路ModuleNotFoundError: No module named fitz未正确安装 PyMuPDF执行pip install PyMuPDF模型下载超时网络无法访问 Hugging Face设置HF_ENDPOINThttps://hf-mirror.com后重试OpenAI 接口报 401API Key 错误或未设置检查config.py中的LLM_API_KEYOpenAI 接口报 404Base URL 或模型名不对确认服务商提供的 Base URL 和模型名回答内容完全偏离资料检索到无关文本块增大TOP_K或更换嵌入模型启动程序后 CPU 占用高首次加载模型和向量化计算构建完知识库后模型常驻内存属于正常现象6.2 检索结果不相关的排查检索是 RAG 应用的核心环节。如果检索结果本身不相关大模型再聪明也回答不好。排查顺序如下打印检索结果观察score分数。如果所有分数都低于 0.5说明资料中可能确实没有相关内容。检查文本切分是否合理。如果CHUNK_SIZE太大一个块中混合多个主题容易检索到“沾边”但不精准的内容。检查嵌入模型是否与文本语言匹配。中文资料建议使用中文能力较强的嵌入模型。尝试用不同的问法测试例如把“CPU 调度最小单位”换成“线程”观察检索结果变化。6.3 大模型回答幻觉的预防RAG 并不能 100% 消除大模型幻觉。为了降低风险可以在三个层面加强约束提示词层面明确要求“只能使用资料内容回答”。参数层面降低temperature减少随机性。人工验证层面把参考来源展示给用户让回答可追溯、可核对。7. 工程化与学习建议7.1 从教学原型到工程系统的改进点当前案例是一个教学原型可以帮助理解 RAG 的核心原理。如果要部署到真实场景可以从以下几个方面优化。第一知识库持久化。目前每次运行都要重新加载文档、重新计算向量资料多时耗时长。改进方法是把文本块和向量保存到本地文件或向量数据库中下次启动直接加载。第二引入真正的向量数据库。当资料量达到数千个文本块后使用内存列表检索会变慢。推荐使用 Chroma、FAISS、Milvus 等向量数据库它们支持大规模向量检索并且通常提供持久化能力。第三增加多轮对话能力。当前每次提问都是独立的不保留上下文。改进方法是在大模型调用时携带历史消息记录让助手能理解“刚才说的那个概念”这类指代问题。第四增加文件上传功能。把本地data目录读取改成 Web 上传用户可以在网页上添加新资料后台自动更新知识库。配合 Streamlit 或 FastAPI可以快速做成一个 Web 应用。7.2 安全与使用边界在真实项目中有几个安全问题需要特别留意API Key 管理不要在前端代码或公开仓库中暴露 API Key建议使用后端环境变量。资料权限课程资料如果包含未公开内容应注意访问权限控制避免被非授权用户读取。内容边界如果助手会被学生大量使用最好在界面上明示“回答仅供参考关键结论请核对原始资料”。7.3 学习路线建议如果这个案例你已经完全掌握下一步可以按这样的顺序继续深入替换不同的嵌入模型和大模型对比同一组问题在不同组合下的回答质量。把内存知识库替换为 Chroma 向量数据库实现持久化。使用 FastAPI 封装接口制作一个简单的前端页面。加入对话历史实现多轮问答。尝试把“课程资料问答助手”扩展为“通用知识库问答助手”支持用户上传文档、指定知识库范围。随着 AI 编程工具的普及编写这类应用的门槛已经大幅降低。借助 Cursor、GitHub Copilot 等 AI 编程工具你可以快速完成代码的框架搭建和调试把更多精力放在数据质量、检索效果和产品体验上。这个案例虽然简单但它所涉及的“检索 生成”架构正是当前智能体开发中最常见的应用范式之一。