**摘要：**本文系统讲解基于 LlamaIndex 构建 RAG 知识库问答系统的完整实现。文章从前端聊天逻辑入手，详细拆解 ChatView.vue 与 ChatInput.vue 的交互流程、chat.ts 中消息发送与接口调用机制，并给出完整可运行的 Vue 代码；随后深入后端，介绍 RAGService 的初始化、文档摄取流水线、向量索引构建、混合检索（向量检索与 BM25 融合）以及语义重排等核心环节，最终实现支持知识库问答、流式输出与多会话记忆的完整应用。
内容参考于：图灵AI大模型全栈
首先是前端逻辑，聊天都是在chat.ts里实现的
首先在下图红框进行引用chat.ts，chat.ts文件中返回了一个叫useChatStore标识（它就代表了整个chat.ts文件里的代码）
上图ChatView.vue文件是下图的页面
然后在下图红框位置创建chat.ts实例
然后在下图红框位置创建了一个send的消息事件，它会监听子组件发送的send事件，子组件就是ChatInput.vue
在ChatInput.vue中它会调用sendMessage函数
上图红框和蓝框里的内容是页面上的输入框和发送按钮，如下图，上图红框的对应下图红框的输入框，上图蓝框的对应下图蓝框的发送按钮，在输入框中按下回车键（Enter）会触发sendMessage函数，鼠标点击下图蓝框的发送按钮会触发sendMessage函数
然后如下图红框，sendMessage函数中会给父组件也就是ChatView.vue发送一个send事件
如下图，它会通过 ChatView.vue 触发chatStore.sendMessage这个函数，也就是会执行到chat.ts文件中
然后在下图红框的函数中调用了聊天接口
如下图红框聊天接口
完整代码
ChatView.vue
TypeScript<!-- ChatView.vue 聊天主页面 作用：展示聊天对话气泡、历史消息；引入ChatInput输入子组件；监听子组件事件；调用pinia聊天仓库；渲染markdown消息；滚动控制 --> <script setup lang="ts"> // 导入vue内置API // onMounted：组件挂载完成之后执行的钩子函数；nextTick：DOM更新完成后执行；ref：创建响应式基础变量 import { onMounted, nextTick, ref } from 'vue'; // 导入pinia仓库 // userStore 用户状态仓库，存用户id登录信息 import { useUserStore } from '../stores/user'; // chatStore 聊天仓库，存放消息数组、发送消息、清空历史、加载历史消息业务函数 import { useChatStore } from '../stores/chat'; // vue-router路由，用于页面跳转 import { useRouter } from 'vue-router'; // 导入子组件：聊天输入控制面板组件 import Header from '../components/Header.vue'; import ChatInput from '../components/ChatInput.vue'; // watch：监听响应式数据变化 import { watch } from 'vue'; // marked：markdown解析库，把AI返回markdown文本转为html import { marked } from 'marked'; // highlight.js：代码高亮库，渲染代码块颜色 import hljs from 'highlight.js'; // marked-highlight：marked插件，集成hljs代码高亮 import { markedHighlight } from 'marked-highlight'; // element-plus消息提示组件，弹出成功/失败提示框 import { ElMessage } from 'element-plus'; // 获取pinia仓库实例 const userStore = useUserStore(); const chatStore = useChatStore(); // 获取路由实例 const router = useRouter(); // 响应式对象：记录每一条知识库来源面板是折叠还是展开 // key:消息的index索引；value:true折叠 false展开 const sourcesCollapsed = ref<{ [key: number]: boolean }>({}); // 页面刚加载，判断用户是否登录，如果没有userId，跳转到首页登录 if (!userStore.userId) { router.push('/'); } // 配置marked markdown渲染插件，实现代码块高亮 marked.use(markedHighlight({ // css类名前缀，配合highlight.js样式 langPrefix: 'hljs language-', // 对代码块进行高亮处理 highlight(code, lang) { // 如果识别到代码语言，并且hljs支持该语言 if (lang && hljs.getLanguage(lang)) { try { // 使用指定语言高亮代码，返回html字符串 return hljs.highlight(code, { language: lang }).value; } catch (err) {} } // 识别不出语言，自动猜测语言进行高亮 return hljs.highlightAuto(code).value; } })); /** @description 格式化消息内容，用户消息转义html；AI消息渲染markdown @param text 原始消息文本 @param role 消息角色 user用户 / assistant AI @returns 处理完成的html字符串 */ const formatMessage = (text: string, role: string) => { console.log('22', text) // 如果文本为空，直接返回空字符串 if (!text) return ''; if (role === 'user') { // 用户消息：不能渲染html，防止XSS攻击；把特殊符号转义；换行符替换成br换行标签 return text .replace(/&/g, '&') .replace(/</g, '<') .replace(/>/g, '>') .replace(/\n/g, '<br>'); } else { // AI消息：将markdown文本转为html return marked(text); } }; /** @description 切换知识库来源面板折叠/展开状态 @param messageIndex 当前消息数组的下标索引 */ const toggleSources = (messageIndex: number) => { // 取反布尔值，true变false，false变true sourcesCollapsed.value[messageIndex] = !sourcesCollapsed.value[messageIndex]; }; /** @description 初始化单条消息的折叠状态，如果没有设置过，默认折叠 true @param messageIndex 消息下标 */ const initSourcesCollapsed = (messageIndex: number) => { // 判断这个下标在对象里是否不存在 if (sourcesCollapsed.value[messageIndex] === undefined) { sourcesCollapsed.value[messageIndex] = true; // 默认折叠 } }; /** @description 文本截断，太长的来源内容做预览，超出部分显示省略号 @param text 原始文本 @param maxLength 最大允许字符 @returns 截断后的字符串 */ const truncateText = (text: string, maxLength: number = 150) => { if (!text) return ''; return text.length > maxLength ? text.substring(0, maxLength) + '...' : text; }; /** @description 聊天容器滚动到底部，查看最新消息 nextTick：等待DOM页面渲染完成之后再执行滚动操作 */ const scrollToBottom = () => { nextTick(() => { // 获取聊天容器dom元素 const chatContainer = document.getElementById('chat-container'); if (chatContainer) chatContainer.scrollTop = chatContainer.scrollHeight; }); }; /** @description 清空聊天记录，调用pinia仓库方法，同时重置本地折叠状态 */ const clearChatHistory = async () => { try { // 调用pinia store清空聊天记录异步函数 await chatStore.clearChatHistory(); // 清空所有来源面板折叠状态 sourcesCollapsed.value = {}; // element plus弹出成功提示 ElMessage({ message: '聊天记录已清空', type: 'success', duration: 2000, }); } catch (error) { console.error('清空聊天记录失败:', error); ElMessage({ message: '清空聊天记录失败，请重试', type: 'error', duration: 3000, }); } }; /** @description onMounted：组件挂载完毕（页面DOM已经渲染完成）执行 页面打开加载历史聊天记录 */ onMounted(() => { console.log(chatStore.loadChatHistory().then((aa) => console.log(aa))) // 调用pinia加载历史消息，加载完成滚动到底部 chatStore.loadChatHistory().then(() => scrollToBottom()); }); /** @description watch监听器 监听chatStore.messages聊天消息数组变化；deep:true深度监听数组内部修改 只要消息数组新增/修改消息，自动滚动页面到底部 */ watch( () => chatStore.messages, // 监听目标：pinia仓库里面messages () => { scrollToBottom(); // 回调函数，每次 messages 变化就滚动到底 }, { deep: true } ); </script> <template> <!-- 页面最外层容器，深色背景，全屏高度 --> <div class="min-h-screen bg-gray-900 text-white"> <!-- 顶部头部组件 --> <Header /> <!-- 页面主体容器，水平居中 --> <div class="flex justify-center px-4 py-6"> <!-- 最大宽度容器，弹性布局，高度扣除顶部高度 --> <div class="w-full max-w-4xl flex flex-col h-[calc(100vh-120px)]"> <!-- 聊天消息容器，id给js获取dom；overflow-y-auto内容超出出现滚动条 --> <div id="chat-container" class="flex-1 overflow-y-auto space-y-4 mb-4 px-4 py-4 rounded-lg shadow-lg"> <!-- v-if：消息数组为空，显示欢迎开始对话提示 --> <div v-if="chatStore.messages.length === 0" class="flex flex-col items-center justify-center h-full text-gray-400"> <div class="text-6xl mb-4">💬</div> <h2 class="text-2xl font-semibold mb-2">开始对话</h2> <p class="text-center">向我提问任何问题，我会尽力为你解答</p> </div> <!-- v-for循环渲染每一条聊天消息；key作为列表唯一标识 --> <div v-for="(msg, index) in chatStore.messages" :key="index" class="flex flex-col" :class="msg.role === 'user' ? 'items-end' : 'items-start'" > <!-- 消息气泡外层容器，用户居右，AI居左 --> <div class="flex items-start" :class="msg.role === 'user' ? 'justify-end' : 'justify-start'"> <!-- AI头像：AI消息才显示 --> <div v-if="msg.role !== 'user'" class="flex-shrink-0 mr-3"> <div class="w-8 h-8 bg-blue-600 rounded-full flex items-center justify-center text-sm font-semibold"> AI </div> </div> <!-- v-html：渲染html字符串，展示格式化后的消息内容 --> <div v-html="formatMessage(msg.content, msg.role)" class="max-w-2xl px-4 py-3 rounded-lg shadow-sm prose prose-invert max-w-none" :class=" msg.role === 'user' ? 'bg-blue-600 text-white rounded-br-sm prose-headings:text-white prose-p:text-white prose-strong:text-white prose-em:text-white' : 'bg-gray-700 text-white rounded-bl-sm prose-headings:text-gray-100 prose-p:text-gray-100 prose-strong:text-gray-100 prose-em:text-gray-100 prose-code:text-blue-300 prose-code:bg-gray-800 prose-pre:bg-gray-800 prose-blockquote:border-blue-500' " ></div> <!-- 用户头像：用户消息才显示 --> <div v-if="msg.role === 'user'" class="flex-shrink-0 ml-3"> <div class="w-8 h-8 bg-gray-600 rounded-full flex items-center justify-center text-sm font-semibold"> 我 </div> </div> </div> <!-- AI回复并且存在知识库来源信息，渲染来源折叠面板 --> <div v-if="msg.role === 'assistant' && msg.sources_info_list && msg.sources_info_list.length > 0" class="w-full max-w-2xl mt-3 ml-11" > {{ initSourcesCollapsed(index) }} <!-- 来源信息折叠面板外层盒子 --> <div class="bg-gray-800 rounded-lg border border-gray-600 overflow-hidden"> <!-- 折叠面板头部按钮，点击切换展开折叠 --> <button @click="toggleSources(index)" class="w-full px-4 py-3 bg-gray-800 hover:bg-gray-750 transition-colors duration-200 flex items-center justify-between text-left" > <div class="flex items-center space-x-2"> <svg class="w-5 h-5 text-blue-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"></path> </svg> <span class="font-medium text-gray-200">相关来源</span> <span class="text-sm text-gray-400">({{ msg.sources_info_list.length }} 个)</span> </div> <!-- 箭头图标，展开旋转180度 --> <svg class="w-5 h-5 text-gray-400 transform transition-transform duration-200" :class="{ 'rotate-180': !sourcesCollapsed[index] }" fill="none" stroke="currentColor" viewBox="0 0 24 24" > <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"></path> </svg> </button> <!-- v-show控制面板内容显示隐藏，true显示 false隐藏 --> <div v-show="!sourcesCollapsed[index]" class="border-t border-gray-600 bg-gray-750" > <div class="p-4 space-y-3 max-h-96 overflow-y-auto"> <!-- 循环渲染每一条知识库来源片段 --> <div v-for="(source, sourceIndex) in msg.sources_info_list" :key="sourceIndex" class="bg-gray-700 rounded-lg p-3 border-l-4 border-blue-500" > <div class="flex items-start justify-between mb-2"> <h4 class="font-medium text-gray-100 text-sm line-clamp-2"> {{ `来源 ${sourceIndex + 1}` }} </h4> <!-- 相似度分数百分比 --> <span v-if="source" class="ml-2 px-2 py-1 bg-blue-600 text-white text-xs rounded-full flex-shrink-0" > {{ Math.round(source.score * 100) }}% </span> </div> <!-- 来源片段预览文本 --> <p class="text-gray-300 text-sm leading-relaxed mb-2"> {{ truncateText(source.content) }} </p> <!-- 如果存在url，渲染原文链接，新标签页打开 --> <div v-if="source.url" class="flex items-center justify-between"> <a :href="source.url" target="_blank" rel="noopener noreferrer" class="text-blue-400 hover:text-blue-300 text-xs flex items-center space-x-1 transition-colors" > <svg class="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"></path> </svg> <span>查看原文</span> </a> </div> </div> </div> </div> </div> </div> </div> <!-- isLoading为true，显示AI加载中动画 --> <div v-if="chatStore.isLoading" class="flex justify-start"> <div class="flex-shrink-0 mr-3"> <div class="w-8 h-8 bg-blue-600 rounded-full flex items-center justify-center text-sm font-semibold"> AI </div> </div> <div class="bg-gray-700 text-white px-4 py-3 rounded-lg rounded-bl-sm shadow-sm"> <div class="flex items-center space-x-2"> <!-- 三个跳动圆点动画 --> <div class="flex space-x-1"> <div class="w-2 h-2 bg-gray-400 rounded-full animate-bounce"></div> <div class="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style="animation-delay: 0.1s"></div> <div class="w-2 h-2 bg-gray-400 rounded-full animate-bounce" style="animation-delay: 0.2s"></div> </div> <span class="text-sm text-gray-400">正在思考中...</span> </div> </div> </div> </div> <!-- ChatInput子组件：输入、参数控制面板 --> <!-- @send：监听子组件抛出send自定义事件，触发chatStore.sendMessage，子组件emit参数自动传入函数 --> <!-- @clear-chat：监听子组件清空聊天事件，触发父组件clearChatHistory方法 --> <div class="flex-shrink-0"> <ChatInput @send="chatStore.sendMessage" @clear-chat="clearChatHistory" /> </div> </div> </div> </div> </template> <style scoped> /* 样式 scoped代表只作用于当前组件，不污染其他组件 / / 之前的样式代码保持不变 */ </style>ChatInput.vue
TypeScript<!-- ChatInput.vue 子组件：聊天输入框、模型选择、知识库开关、温度滑块、文件上传按钮 职责：收集用户输入、参数；向外抛出自定义事件 send / clear‑chat；不维护聊天消息状态 --> <script setup lang="ts"> // ref 创建响应式变量 import { ref } from 'vue'; // axios http请求库，用于上传文件 import axios from 'axios'; // element-plus消息提示框 import { ElMessage } from 'element-plus' // pinia 用户仓库 import { useUserStore } from '../stores/user'; // 用户输入框内容 const message = ref(''); // 当前选中大模型 const model = ref("qwen3.7-plus"); // temperature 温度参数，控制AI创造性 const temperature = ref(0.7); // maxTokens AI最大输出token const maxTokens = ref(2000); // knowledge_bool 是否开启知识库RAG检索 const knowledge_bool = ref(false) // defineEmits：定义当前组件向外抛出的自定义事件 // send：发送消息事件；clear‑chat：清空聊天事件 const emit = defineEmits(['send', 'clear-chat']); // 模型下拉选择框选项数组 const models = [ { value: "qwen3.7-plus", label: "qwen3.7-plus" }, ]; // 文件是否正在上传中 const isUploading = ref(false); // 获取隐藏的file文件选择dom标签 const fileInput = ref<HTMLInputElement | null>(null); /** @description 发送消息按钮 / 回车按下执行函数 */ const sendMessage = () => { // 如果输入框全是空格，直接return，不发送 if (!message.value.trim()) return; // emit向外触发 send事件，把所有收集到的参数全部传给父组件 ChatView emit('send', message.value, model.value, knowledge_bool.value, temperature.value, maxTokens.value); // 发送完成清空输入框内容 message.value = ''; }; /** @description 点击清空记录按钮，抛出clear‑chat事件，通知父组件清空聊天 */ const clearChat = async () => { emit('clear-chat'); }; /** @description 文件选择框选择文件之后触发的回调，上传文档到后端接口 @param event change事件对象 */ const handleFileUpload = async (event: Event) => { // 获取事件目标，就是file input dom const target = event.target as HTMLInputElement; // 获取选中第一个文件 const file = target.files?.[0]; if (!file) return; // 修改状态：正在上传 isUploading.value = true; // FormData表单对象，用于传递二进制文件，文件上传必须使用FormData const formData = new FormData(); // 添加文件，字段名files，后端接口约定接收字段名 formData.append('files', file); try { // http post上传请求 const response = await axios.post( ${import.meta.env.VITE_API_URL}/api/docs/upload, formData, { headers: { // 请求头携带登录身份凭证 'Authorization': Bearer ${useUserStore().userId}, // ⚠️不要手动写Content-Type:multipart/form-data，浏览器会自动带上并且填充boundary分隔符，手动写会上传失败 } } ); // 判断后端返回状态成功 if (response.data.status === "success") { const result = response.data.processed_files; console.log('文件上传成功:', result); ElMessage({ message: `文件上传成功！共处理了 ${result.length} 个文件`, type: 'success', duration: 3000 }); } else { console.error('文件上传失败'); ElMessage({ message: '文件上传失败，请重试', type: 'error', duration: 3000 }); } } catch (error) { // 请求异常捕获，网络错误、后端报错会走到这里 console.error('上传错误:', error); } finally { // 无论成功失败，都会执行；关闭上传loading状态；清空file input的值，允许重复选择同一个文件 isUploading.value = false; if (target) target.value = ''; } }; /** @description 点击上传文档按钮，调用隐藏原生文件选择框点击，唤起选择文件弹窗 */ const triggerFileUpload = () => { fileInput.value?.click(); }; </script> <template> <!-- 当前ChatInput组件整体UI容器 --> <div class="p-6 bg-gray-900/50 backdrop-blur-sm rounded-xl border border-gray-700/50"> <!-- 第一行：各种控制按钮 知识库开关、模型下拉、上传文件、清空记录 --> <div class="flex flex-wrap items-center gap-6 mb-6"> <!-- 知识库开关按钮 --> <div class="flex items-center space-x-3"> <span class="text-sm font-medium text-gray-300">知识库</span> <!-- @click点击切换布尔值true/false --> <button @click="knowledge_bool = !knowledge_bool" :class="[ 'relative inline-flex h-6 w-11 items-center rounded-full transition-all duration-300 ease-in-out focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:ring-offset-2 focus:ring-offset-gray-900', knowledge_bool ? 'bg-gradient-to-r from-emerald-500 to-teal-600' : 'bg-gray-600' ]"> <span :class="[ 'inline-flex h-4 w-4 items-center justify-center transform rounded-full bg-white transition-all duration-300 ease-in-out shadow-lg', knowledge_bool ? 'translate-x-6' : 'translate-x-1' ]"> <svg :class="[ 'h-2.5 w-2.5 transition-colors duration-200', knowledge_bool ? 'text-emerald-600' : 'text-gray-400' ]" fill="currentColor" viewBox="0 0 20 20"> <path d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" /> </svg> </span> </button> </div> <!-- AI模型下拉选择框 --> <div class="flex items-center space-x-3"> <label class="text-sm font-medium text-gray-300">AI模型:</label> <div class="relative"> <!-- v-model双向绑定model响应式变量，下拉选择自动修改变量 --> <select v-model="model" class="appearance-none bg-gray-800 text-white text-sm rounded-lg border border-gray-600 px-4 py-2 pr-8 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500 min-w-[160px] transition-all duration-200 hover:bg-gray-700"> <!-- v-for循环渲染下拉选项 --> <option v-for="modelOption in models" :key="modelOption.value" :value="modelOption.value" class="bg-gray-800"> {{ modelOption.label }} </option> </select> <!-- 下拉箭头装饰图标 --> <div class="absolute inset-y-0 right-0 flex items-center px-2 pointer-events-none"> <svg class="w-4 h-4 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" /> </svg> </div> </div> </div> <!-- 上传文档按钮，点击唤起文件选择 --> <button @click="triggerFileUpload" :disabled="isUploading" :class="[ 'flex items-center gap-2 px-4 py-2 text-sm font-medium rounded-lg transition-all duration-200 transform hover:scale-105 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-gray-900', isUploading ? 'bg-gray-600 text-gray-400 cursor-not-allowed' : 'bg-gradient-to-r from-blue-500 to-purple-600 hover:from-blue-600 hover:to-purple-700 text-white shadow-lg hover:shadow-blue-500/25' ]"> <svg :class="[ 'w-4 h-4', isUploading ? 'animate-spin' : '' ]" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path v-if="!isUploading" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12" /> <path v-else stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" /> </svg> <span>{{ isUploading ? '上传中...' : '上传文档' }}</span> </button> <!-- 清空聊天记录按钮，点击抛出clear‑chat事件 --> <button @click="clearChat" class="flex items-center gap-2 px-4 py-2 text-sm font-medium rounded-lg border border-yellow-500/40 bg-yellow-500/10 text-yellow-200 hover:bg-yellow-500/20 hover:text-yellow-100 transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-yellow-500 focus:ring-offset-2 focus:ring-offset-gray-900" > <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 6h18M8 6V4h8v2m-9 4v8m5-8v8m5-8v8M5 6l1 14h12l1-14" /> </svg> <span>清空记录</span> </button> <!-- 原生隐藏文件选择框，accept限定允许选择文件后缀；@change选中文件后触发上传函数 --> <input ref="fileInput" type="file" @change="handleFileUpload" class="hidden" accept=".txt,.pdf,.doc,.docx,.md" /> </div> <!-- 第二行，两个滑块：创造性温度、最大响应长度 --> <div class="grid grid-cols-1 lg:grid-cols-2 gap-8 mb-6"> <!-- temperature温度滑块 --> <div class="space-y-3"> <div class="flex items-center justify-between"> <label class="text-sm font-medium text-gray-300 flex items-center space-x-2"> <svg class="w-4 h-4 text-orange-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" /> </svg> <span>创造性温度</span> </label> <!-- toFixed(1)保留一位小数展示 --> <div class="bg-gradient-to-r from-orange-500 to-red-500 text-white text-xs font-bold px-3 py-1 rounded-full"> {{ temperature.toFixed(1) }} </div> </div> <div class="relative"> <!-- v-model.number 数字双向绑定；range滑块 min最小值 max最大值 step步长 --> <input v-model.number="temperature" type="range" min="0" max="2" step="0.1" class="w-full h-3 bg-gray-700 rounded-lg appearance-none cursor-pointer temperature-slider" /> <div class="flex justify-between text-xs text-gray-500 mt-2"> <span class="flex items-center space-x-1"> <div class="w-2 h-2 bg-blue-400 rounded-full"></div> <span>保守</span> </span> <span class="flex items-center space-x-1"> <div class="w-2 h-2 bg-yellow-400 rounded-full"></div> <span>平衡</span> </span> <span class="flex items-center space-x-1"> <div class="w-2 h-2 bg-red-400 rounded-full"></div> <span>创新</span> </span> </div> </div> </div> <!-- maxTokens最大输出长度滑块 --> <div class="space-y-3"> <div class="flex items-center justify-between"> <label class="text-sm font-medium text-gray-300 flex items-center space-x-2"> <svg class="w-4 h-4 text-green-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" /> </svg> <span>响应长度</span> </label> <div class="bg-gradient-to-r from-green-500 to-emerald-500 text-white text-xs font-bold px-3 py-1 rounded-full"> {{ maxTokens.toLocaleString() }} </div> </div> <div class="relative"> <input v-model.number="maxTokens" type="range" min="100" max="8000" step="100" class="w-full h-3 bg-gray-700 rounded-lg appearance-none cursor-pointer tokens-slider" /> <div class="flex justify-between text-xs text-gray-500 mt-2"> <span class="flex items-center space-x-1"> <div class="w-2 h-2 bg-green-400 rounded-full"></div> <span>简短</span> </span> <span class="flex items-center space-x-1"> <div class="w-2 h-2 bg-yellow-400 rounded-full"></div> <span>适中</span> </span> <span class="flex items-center space-x-1"> <div class="w-2 h-2 bg-blue-400 rounded-full"></div> <span>详细</span> </span> </div> </div> </div> </div> <!-- 输入框和发送按钮 --> <div class="flex space-x-3"> <div class="flex-1 relative"> <!-- v-model双向绑定message；@keyup.enter 按下回车键触发sendMessage发送消息 --> <input v-model="message" @keyup.enter="sendMessage" placeholder="输入你的问题，开始AI对话..." type="text" class="w-full p-4 pr-12 rounded-xl bg-gray-800/80 text-white placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-blue-500 border border-gray-600/50 transition-all duration-200 hover:bg-gray-800 focus:bg-gray-800" /> <div class="absolute right-4 top-1/2 transform -translate-y-1/2"> <svg class="w-5 h-5 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z" /> </svg> </div> </div> <!-- 发送按钮 @click点击触发sendMessage；:disabled输入为空禁止点击 --> <button @click="sendMessage" :disabled="!message.trim()" :class="[ 'px-8 py-4 rounded-xl font-medium transition-all duration-200 transform focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-gray-900', message.trim() ? 'bg-gradient-to-r from-blue-500 to-purple-600 hover:from-blue-600 hover:to-purple-700 text-white cursor-pointer hover:scale-105 shadow-lg hover:shadow-blue-500/25' : 'bg-gray-700 text-gray-400 cursor-not-allowed' ]"> <div class="flex items-center space-x-2"> <span>发送</span> <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"> <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 19l9 2-9-18-9 18 9-2zm0 0v-8" /> </svg> </div> </button> </div> </div> </template> <style scoped> /* 滑块样式，只作用当前组件 / / 温度滑块样式 */ .temperature-slider::-webkit-slider-thumb { appearance: none; height: 24px; width: 24px; border-radius: 50%; background: linear-gradient(135deg, #f97316, #dc2626); cursor: pointer; border: 3px solid #1f2937; box-shadow: 0 4px 12px rgba(249, 115, 22, 0.4); transition: all 0.3s ease; } .temperature-slider::-webkit-slider-thumb:hover { transform: scale(1.2); box-shadow: 0 6px 20px rgba(249, 115, 22, 0.6); } .temperature-slider::-webkit-slider-runnable-track { height: 12px; background: linear-gradient(to right, #3b82f6 0%, #f59e0b 50%, #dc2626 100%); border-radius: 6px; } /* Token滑块样式 */ .tokens-slider::-webkit-slider-thumb { appearance: none; height: 24px; width: 24px; border-radius: 50%; background: linear-gradient(135deg, #10b981, #059669); cursor: pointer; border: 3px solid #1f2937; box-shadow: 0 4px 12px rgba(16, 185, 129, 0.4); transition: all 0.3s ease; } .tokens-slider::-webkit-slider-thumb:hover { transform: scale(1.2); box-shadow: 0 6px 20px rgba(16, 185, 129, 0.6); } .tokens-slider::-webkit-slider-runnable-track { height: 12px; background: linear-gradient(to right, #10b981 0%, #f59e0b 50%, #3b82f6 100%); border-radius: 6px; } /* Firefox 滑块样式 */ .temperature-slider::-moz-range-thumb, .tokens-slider::-moz-range-thumb { height: 24px; width: 24px; border-radius: 50%; cursor: pointer; border: 3px solid #1f2937; transition: all 0.3s ease; } .temperature-slider::-moz-range-thumb { background: linear-gradient(135deg, #f97316, #dc2626); box-shadow: 0 4px 12px rgba(249, 115, 22, 0.4); } .tokens-slider::-moz-range-thumb { background: linear-gradient(135deg, #10b981, #059669); box-shadow: 0 4px 12px rgba(16, 185, 129, 0.4); } /* 动画效果 */ @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } } .animate-pulse { animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite; } </style>chat.ts
TypeScript// 从 Pinia 中导入「创建状态仓库」的核心方法 defineStore import { defineStore } from 'pinia'; // 从 Vue 中导入 ref，用于创建响应式数据（基础类型/数组推荐用 ref） import { ref } from 'vue'; // 导入 axios，用于发送普通的 HTTP 请求（历史记录、清空记录接口用） import axios from 'axios'; // 导入用户状态仓库，用来获取用户ID、做接口身份认证 import { useUserStore } from './user'; // TypeScript 接口：约定「单条聊天消息」的数据结构，让代码有类型提示、更安全 interface ChatMessage { role: string; // 消息角色，比如 user（用户发的）、assistant（AI回复的） content: string; // 消息的文本内容 sources: any[]; // 这条消息关联的参考来源数据数组（比如知识库引用的文档） } // TypeScript 接口：约定「后端返回的历史消息」的数据结构 interface HistoryMessageResponse { messages: ChatMessage; // 后端返回的消息字段，里面是标准的聊天消息结构 } // 创建并导出名为 chat 的状态仓库（Pinia 组合式写法） export const useChatStore = defineStore('chat', () => { // 响应式数组：存放所有聊天消息 // 每条消息包含 3 个字段：角色、文本内容、参考来源列表 const messages = ref<{ role: string; content: string, sources_info_list: any }[]>([]); // 响应式布尔值：标记当前是否正在加载/请求中，用于页面显示加载动画 const isLoading = ref(false); // 获取用户仓库实例，后续用它拿用户ID做接口认证 const userStore = useUserStore(); // ------------------------------ // 方法1：加载聊天历史记录 // ------------------------------ const loadChatHistory = async () => { // 守卫判断：如果没有用户ID（未登录），直接不执行后续逻辑 if (!userStore.userId) return; try { // 发送 GET 请求，从后端获取历史聊天记录 // import.meta.env.VITE_API_URL 是环境变量里配置的接口基础地址 const { data } = await axios.get( `${import.meta.env.VITE_API_URL}/api/chat/history`, { // 请求头配置 headers: { 'Authorization': `Bearer ${userStore.userId}`, // 身份认证：把用户ID放在 Bearer 令牌里传给后端 'Content-Type': 'application/json' // 告诉后端请求体是 JSON 格式 } } ); // 处理后端返回的数据： // 1. filter：过滤掉没有内容的无效消息 // 2. map：把后端格式转换成前端页面需要的格式，赋值给本地消息列表 messages.value = data .filter((msg: HistoryMessageResponse) => msg.messages.content) .map((msg: HistoryMessageResponse) => ({ role: msg.messages.role, content: msg.messages.content, sources_info_list: msg.messages.sources || [], // 没有来源数据就给空数组兜底 })); } catch (error) { // 请求出错时，在控制台打印错误信息，方便调试 console.error('Error loading chat history: ', error); } }; // ------------------------------ // 方法2：清空聊天历史记录 // ------------------------------ const clearChatHistory = async () => { // 守卫判断：没有用户ID就不执行 if (!userStore.userId) return; // 发送 POST 请求，通知后端把当前用户的聊天历史清空 await axios.post( `${import.meta.env.VITE_API_URL}/api/chat/clear`, {}, // POST 请求体为空（不需要传额外参数） { headers: { 'Authorization': `Bearer ${userStore.userId}`, // 带上用户身份认证 'Content-Type': 'application/json' } } ); // 后端清空成功后，把本地前端的消息列表也清空，保持页面同步 messages.value = []; }; // ------------------------------ // 方法3：发送用户消息 + 接收AI流式回复 // ------------------------------ // 参数说明： // message 用户输入的问题内容 // model 选用的AI模型名称 // knowledge_bool 是否开启知识库问答 // temperature 模型温度（控制回复随机性，值越高越发散） // max_tokens 最大token数量（限制AI回复的长度） const sendMessage = async (message: string, model: string, knowledge_bool: boolean, temperature: number, max_tokens: number) => { // 守卫判断：消息是空的 / 没有用户ID，直接不执行 if (!message.trim() || !userStore.userId) return; // 先把用户发的消息加到聊天列表里，让页面立刻显示用户的提问 messages.value.push({ role: 'user', content: message, sources_info_list: [] }); // 开启加载状态，页面可以显示"AI正在思考/回复中"的效果 isLoading.value = true; try { // 调用流式响应处理方法，把所有参数传进去，接收AI的逐字回复 await handleStreamResponse(message, model, knowledge_bool, temperature, max_tokens); } catch (error) { // 请求出错时，在聊天列表里加一条错误提示，让用户知道失败了 console.error('Error sending message: ', error); messages.value.push({ role: 'assistant', content: 'Error: unable to process request', sources_info_list: [] }); } finally { // 无论成功还是失败，最后都关闭加载状态 isLoading.value = false; } }; /** 内部方法：处理流式响应（SSE 服务器推送事件，实现打字机效果） @param message - 用户输入的问题内容 @param model - AI模型名称 @param knowledge_bool - 是否开启知识库问答 @param temperature - 温度参数，控制回复的随机性 @param max_tokens - 最大token数量，限制AI回复的长度 */ const handleStreamResponse = async (message: string, model: string, knowledge_bool: boolean, temperature: number, max_tokens: number) => { // 记录这条AI回复在消息数组里的下标位置，后面用来实时更新内容 const aiMessageIndex = messages.value.length; // 先在消息列表里占一个位置，放一条空的AI消息，后续逐字往里面填内容 messages.value.push({ role: 'assistant', content: '', sources_info_list: [] }); try { // 用 fetch 发起流式请求（axios 不支持原生流式读取，所以用浏览器原生 fetch） const response = await fetch(${import.meta.env.VITE_API_URL}/api/chat/stream, { method: 'POST', // 请求方式是 POST headers: { 'Content-Type': 'application/json', // 告诉后端请求体是 JSON 格式 'Authorization': Bearer ${userStore.userId}, // 带上用户身份认证 }, // 请求体：把所有参数转成 JSON 字符串发给后端 body: JSON.stringify({ query: message, // 用户的问题 model: model, // 选择的AI模型 temperature: temperature, // 温度参数 max_tokens: max_tokens, // 最大生成长度 knowledge_bool: knowledge_bool, // 是否开启知识库 } ) }); // 检查HTTP请求是否成功，状态码不是 2xx 就抛出错误 if (!response.ok) { throw new Error(HTTP error! status: ${response.status}); } // 检查浏览器是否支持读取响应流，不支持就报错 if (!response.body) { throw new Error('ReadableStream not supported'); } // 获取流的读取器，用来一点点读取后端持续返回的数据 const reader = response.body.getReader(); // 创建文本解码器，把二进制的字节数据转换成可读的字符串 const decoder = new TextDecoder(); // 缓冲区：用来拼接被拆分的数据块 // 因为流式传输可能把一行完整数据拆成两次发，需要先拼起来再处理 let buffer = ''; // 循环：持续不断地读取流里的数据，直到流结束 while (true) { // 读取一块数据：done 表示是否全部读完了，value 是这一块的二进制数据 const { done, value } = await reader.read(); // 如果流结束了，跳出循环 if (done) break; // 把这块二进制数据解码成字符串，追加到缓冲区末尾 buffer += decoder.decode(value, { stream: true }); // 按换行符把缓冲区拆成一行一行的（SSE 协议规定按行传输数据） const lines = buffer.split('\n'); // 把最后一行拿出来放回缓冲区 // 因为最后一行大概率是不完整的，等下一块数据过来拼起来再处理 buffer = lines.pop() || ''; // 遍历每一行完整的数据，逐个解析处理 for (const line of lines) { const trimmedLine = line.trim(); // SSE 协议规定数据行以 "data: " 开头，只处理这种有效数据行 if (trimmedLine.startsWith('data: ')) { // 去掉开头的 "data: " 前缀，拿到里面的 JSON 字符串 const jsonStr = trimmedLine.slice(6); // 跳过空行，或者 SSE 标准的结束标记 [DONE] if (jsonStr.trim() === '' || jsonStr.trim() === '[DONE]') continue; try { // 把 JSON 字符串解析成 JS 对象，方便读取字段 const data = JSON.parse(jsonStr); // 如果后端返回结束信号（finished 为 true），就跳出数据处理循环 if (data.finished) { break; } // 根据后端返回的数据类型，做不同的处理 if (data.type === "sources") { // 类型是 sources：处理参考来源数据，更新到这条AI消息的来源列表里 if (data.content && Array.isArray(data.content)) { messages.value[aiMessageIndex].sources_info_list = data.content; } } else if (data.type === "content" || data.type === "text") { // 类型是 content/text：处理AI回复的文本 // 把新返回的文本追加到消息内容后面，实现逐字显示的打字机效果 if (data.content) { messages.value[aiMessageIndex].content += data.content; } } } catch (e) { // 某一行解析失败不影响整体流程，在控制台打印警告方便调试 console.warn('Failed to parse JSON:', jsonStr, e); } } } } // 读取完成后，释放读取器的锁，释放浏览器资源 reader.releaseLock(); } catch (error) { // 流式请求出错时，把之前占位的那条空AI消息删掉（避免页面留一条空消息） console.error('Stream error:', error); messages.value.splice(aiMessageIndex, 1); // 把错误抛出去，让外层的 sendMessage 捕获并做后续处理 throw error; } }; // 把状态和方法暴露出去，组件里导入仓库后就可以调用这些数据和方法 return { messages, isLoading, loadChatHistory, sendMessage, clearChatHistory }; });
聊天接口
如下图红框，它是聊天的接口
如下图红框处理聊天的接口
如下图红框，它调用了svc里的函数，然后svc是通过下图蓝框创建的
如下图红框 get_rag_service 的逻辑，它是创建一个RAGService，这个RAGService的逻辑上一节中写过了，就是初始化llamaindex构建rag的流程
主要就是下图红框里面的逻辑
首先他更新了一下模型信息
如下图红框update_model_config里调用的ingestion_pipeline的update_model_config
然后如下图红框 ingestion_pipeline里的update_model_config就是设置一下全局的大语言模型
然后update_model_config看完了，接下来是下图红框的 query_documents_stream
如下图红框它首先会获取聊天引擎
这里通过前端传来的标记来判断创建带知识库的聊天引擎，还是不带知识库的聊天引擎
索引的创建，上一节中写的索引默认是空的，这里就来看看如何创建的索引
获取索引
获取索引
这里通过存储管理器创建索引
上图这个存储管理器是在 RAGService 构造方法中创建的如下图
如果之前创建过知识库，并且本地已经有过知识的内容（索引）了，它才会创建，否则会创建一个空的
到这llamaindex索引的创建就完成了，然后创建一个检索器，这里使用融合检索器，BM25和向量检索
到这聊天引擎就完成了，然后就是下图红框的 查询、保存聊天记录、RAG检索的信息返回给前端了，然后就结束了
完整代码
代码中用了很多yield，它是使用实例
python# 第一种用法 def count(): yield 1 yield 2 # 函数执行到这里，没有更多代码了 gen = count() next(gen) # 1 next(gen) # 2 next(gen) # 抛出 StopIteration，代表生成完了 第二种用法 def count(): yield 1 yield 2 yield 3 for num in count(): print(num) #第三种用法 gen = count() while True: try: num = next(gen) # 手动调用 next 取下一个值 print(num) except StopIteration: # 捕获到结束异常 break # 退出循环rag.py，下方我们把 event_generator 函数给到了 StreamingResponse里，StreamingResponse里面会有上方第二种for循环写法的代码
python# 导入json标准库，用于将Python字典转成JSON字符串，满足SSE流式传输的数据格式要求 import json # 导入类型提示List，用来标注列表类型的返回值，提升代码可读性和编辑器的补全校验能力 from typing import List 从FastAPI导入路由管理器APIRouter和依赖注入工具Depends APIRouter：用来分组管理一组相关的接口，方便模块化拆分 Depends：依赖注入工具，自动帮我们获取/创建对象，不用手动实例化 from fastapi import APIRouter, Depends 导入流式响应类，专门用于返回SSE服务器推送事件的流式数据，实现前端打字机效果 from fastapi.responses import StreamingResponse 导入RAG服务类和获取服务单例的函数，负责处理聊天、上传等核心业务逻辑 from app.rag_service import RAGService, get_rag_service 导入用户模型和获取当前登录用户的函数，用于接口的身份校验 from app.routers.users import User, get_current_active_user 导入接口的数据模型（schema），用来规范请求和响应的数据格式 from app.schemas import ChatMessage, ChatRequest, CommonResponse, HistoryMessageResponse 导入日志工具函数，用于创建当前模块的日志记录器 from utils.logger import setup_logger 创建当前模块的日志记录器，用来打印接口调用过程中的信息、错误等日志 logger = setup_logger(name) 创建聊天模块的路由实例，所有聊天相关的接口都挂载在这个路由上 chat_router = APIRouter() 装饰器：注册一个POST类型的接口，路径为/stream，挂载在chat_router路由下 @chat_router.post("/stream") 异步接口函数：流式聊天接口，接收用户的聊天请求，返回SSE流式响应 async def chat_query_stream( # 请求体参数：前端传过来的聊天请求，包含问题、模型名称、是否开知识库、温度等字段 req: ChatRequest, # 依赖注入：自动获取当前登录的活跃用户 # 会自动执行get_current_active_user函数校验用户token，校验失败直接返回错误，不用自己写校验逻辑 current_user: User = Depends(get_current_active_user), # 依赖注入：自动获取RAG服务的单例实例，全局只有一个服务对象 svc: RAGService = Depends(get_rag_service), 函数返回值类型是流式响应 ) -> StreamingResponse: """流式聊天，直接转发 LlamaIndex streaming delta。""" # 定义内部异步生成器函数，用来生成符合SSE协议格式的流式数据 async def event_generator(): # 异常捕获：处理流式传输过程中可能出现的所有错误 try: # 异步遍历RAG服务返回的每一块流式数据（文本片段、来源、完成信号等） async for chunk in svc.query_stream( # 用用户名作为会话ID，每个用户独立保存自己的聊天记录 session_id=current_user.username, # 用户的问题文本 query=req.query, # 选择的AI模型名称 model=req.model, # 是否开启知识库问答 knowledge_bool=req.knowledge_bool, # 模型温度参数 temperature=req.temperature, # 最大输出token数 max_tokens=req.max_tokens, ): # 将数据块转成SSE协议规定的格式 # 格式规则：以 data: 开头，后面跟JSON字符串，最后加两个换行（空行分隔不同事件，前端才能正确解析） # ensure_ascii=False 保证中文正常显示，不会转成Unicode编码 yield f"data: {json.dumps(chunk, ensure_ascii=False)}\n\n" # 捕获所有类型的异常 except Exception as exc: # 构造统一格式的错误数据 error_data = { "type": "error", "content": f"流式传输错误: {exc}", "finished": True, } # 同样以SSE格式返回错误信息，标记对话结束 yield f"data: {json.dumps(error_data, ensure_ascii=False)}\n\n" # 返回流式响应对象，把生成器作为内容源，一边生成一边传输给前端 return StreamingResponse( # 流式内容源：就是上面定义的生成器函数 content=event_generator(), # 指定响应的媒体类型为SSE事件流，这是SSE协议的标准类型 media_type="text/event-stream", # 设置响应头，保证长连接和实时性 headers={"Cache-Control": "no-cache", "Connection": "keep-alive"}, ) 装饰器：注册一个GET类型的接口，路径为/history，获取用户聊天历史 @chat_router.get("/history") 异步接口函数：获取当前登录用户的所有聊天历史记录 async def get_user_history( # 依赖注入：校验并获取当前登录用户 current_user: User = Depends(get_current_active_user), # 依赖注入：获取RAG服务单例 svc: RAGService = Depends(get_rag_service), 返回值是历史消息响应对象的列表 ) -> List[HistoryMessageResponse]: """读取当前用户的 LlamaIndex Memory 历史。""" # 列表推导式：遍历用户的会话历史，转换成前端需要的标准响应格式 return [ # 用schema定义的历史消息模型包装每条消息，保证数据格式统一 HistoryMessageResponse( # 内层用聊天消息模型包装具体消息内容 messages=ChatMessage( # 消息角色：user（用户）或assistant（AI助手） role=msg["role"], # 消息的文本内容 content=msg["content"], # 消息关联的参考来源列表，没有就返回空数组兜底 sources=msg.get("sources") or [], ) ) # 从服务层获取当前用户的所有会话消息，用用户名作为会话ID for msg in svc.get_session(current_user.username) # 过滤条件：只保留有内容的消息，跳过空消息 if msg.get("content") ] 装饰器：注册一个POST类型的接口，路径为/clear，同时指定响应数据模型为通用响应格式 @chat_router.post("/clear", response_model=CommonResponse) 异步接口函数：清空当前用户的聊天记录和记忆 async def chat_clear( # 依赖注入：校验并获取当前登录用户 current_user: User = Depends(get_current_active_user), # 依赖注入：获取RAG服务单例 svc: RAGService = Depends(get_rag_service), 返回值是通用响应对象 ) -> CommonResponse: """清空当前用户的聊天记忆。""" # 调用服务层的清空方法，传入当前用户名（会话ID），清空对应的聊天记录和记忆 svc.clear_session(current_user.username) # 返回统一格式的成功响应 return CommonResponse(status="success", message="会话已清空")rag_service.py
python# 导入os标准库，提供操作系统级别的文件路径拼接、文件操作等基础功能 import os # 导入shutil标准库，提供高级文件操作，比如递归删除整个目录 import shutil # 导入tempfile标准库，用于创建临时文件和临时目录，用完可自动清理 import tempfile # 导入类型提示工具，用来标注变量、函数参数和返回值的类型，提升代码可读性和编辑器校验能力 from typing import Dict, List, Optional, Tuple 导入核心业务层的RAG应用类，所有知识库问答的核心逻辑都在这个类里 from core.application import RAGApplication 导入项目自定义的日志工具函数，用于创建当前模块的日志记录器 from utils.logger import setup_logger 创建当前模块的日志记录器，用来打印程序运行中的信息、错误等日志 logger = setup_logger(name) 定义RAG服务类：作为HTTP接口层的适配器，对接上层的HTTP请求，处理文件上传的临时存储逻辑，再调用核心RAG功能 class RAGService: """HTTP 层适配器：处理上传临时文件，并调用核心 RAG 应用。""" # 类的构造初始化方法，创建RAGService实例时自动执行 def __init__(self) -> None: # 实例化核心RAG应用对象，所有业务逻辑都委托给这个app对象处理 self.app = RAGApplication() # 处理上传文件的方法：接收文件二进制内容和文件名，保存为临时文件后交给核心应用处理 # 返回值是一个元组：(处理结果字符串, 文件名列表) def upload_and_process_files(self, files: List[bytes], filenames: List[str]) -> Tuple[str, List[str]]: # 创建一个临时目录，目录名前缀为rag_upload_，用来临时存放上传的文件 tmpdir = tempfile.mkdtemp(prefix="rag_upload_") # 定义空列表，用来保存每个临时文件的完整路径 paths = [] # try代码块：包裹可能出错的业务逻辑 try: # 同时遍历文件名列表和文件二进制内容列表，一一对应处理 for name, content in zip(filenames, files): # 拼接临时目录和文件名，得到临时文件的完整路径 path = os.path.join(tmpdir, name) # 以二进制写入模式打开这个临时文件，with语法会自动关闭文件 with open(path, "wb") as file: # 把上传的二进制文件内容写入到临时文件中 file.write(content) # 将这个临时文件的路径添加到路径列表中 paths.append(path) # 打印信息日志，记录本次上传的所有文件路径 logger.info("上传的文档: %s", paths) # 调用核心RAG应用的上传处理方法，传入文件路径列表，同时返回处理结果和原文件名 return self.app.upload_and_process_files(paths), filenames # finally代码块：无论上面的代码成功执行还是报错，都会执行这里的代码 finally: # 递归删除整个临时目录和里面的所有文件，ignore_errors=True表示删除失败也不抛出错误 shutil.rmtree(tmpdir, ignore_errors=True) # 异步方法：流式问答接口，接收查询参数，转发给核心应用，再流式返回结果给上层 async def query_stream( self, session_id: str, # 会话ID，用来区分不同的用户或者不同的聊天窗口 query: str, # 用户输入的问题文本 model: str, # 选择使用的AI模型名称 knowledge_bool: bool, # 是否开启知识库问答的开关 temperature: float, # 模型温度参数，控制回答的随机性 max_tokens: int, # 模型最大输出token数，限制回答长度 ): # 先调用核心应用的方法，更新模型的配置参数 self.app.update_model_config(model, temperature, max_tokens) # 异步遍历核心应用返回的流式数据块 async for chunk in self.app.query_documents_stream( session_id=session_id, query=query, knowledge_bool=knowledge_bool, ): # 将每一个数据块原样yield返回给上层调用者（也就是HTTP接口层），实现流式传输 yield chunk # 获取指定会话的历史聊天记录 def get_session(self, session_id: str): # 直接调用核心应用的获取历史方法，返回结果 return self.app.get_session_history(session_id) # 清空指定会话的聊天记录和记忆 def clear_session(self, session_id: str) -> None: # 直接调用核心应用的清空方法 self.app.clear_session(session_id) # 重置整个RAG系统 def reset_system(self) -> None: # 调用核心应用的重置方法 self.app.reset() 全局变量：存储RAGService的单例实例，初始值为None，类型是可选的RAGService _rag_service: Optional[RAGService] = None 全局函数：获取RAGService的单例实例，保证整个程序中只有一个RAGService实例 def get_rag_service() -> RAGService: # 声明要使用全局作用域的_rag_service变量 global _rag_service # 判断全局实例是否还没有被创建 if _rag_service is None: # 没有创建的话，就新建一个RAGService实例，赋值给全局变量 _rag_service = RAGService() # 返回全局的单例实例 return _rag_service
python# 导入Python标准库的Path类，用于安全、跨平台地处理文件和目录路径，避免字符串拼接路径的兼容性问题 from pathlib import Path # 导入Python类型提示工具集，用于标注变量、函数参数和返回值的类型，提升代码可读性和编辑器的补全校验能力 from typing import Any, AsyncGenerator, Dict, List, Optional 导入ChromaDB向量数据库，专门用于存储文本的语义向量，支持快速相似度检索，是RAG系统的核心存储组件 import chromadb 从LlamaIndex核心库导入多个核心组件，LlamaIndex是构建知识库问答（RAG）系统的主流开发框架 from llama_index.core import ( Settings, # Settings：LlamaIndex全局配置对象，统一管理整个项目的大模型、嵌入模型等全局配置 SimpleDirectoryReader, # SimpleDirectoryReader：文档读取工具，自动识别并读取多种格式的文档文件，转换为程序可处理的文档对象 StorageContext, # StorageContext：存储上下文，统一封装管理向量存储、文档存储、索引存储三类数据存储 VectorStoreIndex, # VectorStoreIndex：向量索引，基于文本向量构建的检索索引，用于实现语义相似度搜索 load_index_from_storage, # load_index_from_storage：工具函数，用于从本地持久化文件中加载已构建好的向量索引 ) 导入上下文聊天引擎，开启RAG知识库时使用，回答问题前会先检索知识库，再结合检索内容生成答案 from llama_index.core.chat_engine.context import ContextChatEngine 导入简单聊天引擎，纯对话模式使用，不检索知识库，直接和大模型进行对话 from llama_index.core.chat_engine.simple import SimpleChatEngine 导入标题提取器，可自动为每个文本块提取标题，本代码中暂时注释禁用 from llama_index.core.extractors import TitleExtractor 导入文档摄取流水线，可将多个文档处理步骤按顺序串联成自动化流水线 from llama_index.core.ingestion import IngestionPipeline 导入聊天记忆缓冲区，用于保存每个会话的聊天历史，让AI具备上下文记忆能力 from llama_index.core.memory import ChatMemoryBuffer 导入句子分割器，用于将长文档切分为固定大小的文本块（chunk），适配检索和向量化的要求 from llama_index.core.node_parser import SentenceSplitter 导入语义重排器，对初步检索的结果按语义相关性重新排序，提升检索准确率 from llama_index.core.postprocessor import SentenceTransformerRerank 导入查询融合检索器，可将多种不同检索方式的结果融合在一起，提升检索效果 from llama_index.core.retrievers import QueryFusionRetriever 导入向量索引检索器，专门负责从向量索引中执行语义相似度检索 from llama_index.core.retrievers import VectorIndexRetriever 导入简单文档存储，用于持久化保存原始的文档节点（文本块）数据 from llama_index.core.storage.docstore import SimpleDocumentStore 导入简单聊天存储，用于持久化保存所有会话的聊天记录数据 from llama_index.core.storage.chat_store import SimpleChatStore 导入简单索引存储，用于持久化保存向量索引的元数据信息 from llama_index.core.storage.index_store import SimpleIndexStore 导入HuggingFace嵌入模型，负责将文本转换为语义向量，是实现语义搜索的核心模型 from llama_index.embeddings.huggingface import HuggingFaceEmbedding 导入DashScope（阿里云通义千问）大模型适配器，本代码实际使用OpenAI兼容模式，此导入暂未直接使用 from llama_index.llms.dashscope import DashScope 导入BM25检索器，基于传统关键词匹配的检索方式，和向量检索形成互补 from llama_index.retrievers.bm25 import BM25Retriever 导入Chroma向量存储适配器，让LlamaIndex可以对接ChromaDB向量数据库 from llama_index.vector_stores.chroma import ChromaVectorStore 导入OpenAI兼容大模型适配器，只要接口符合OpenAI规范的大模型都可以用它对接 from llama_index.llms.openai_like import OpenAILike 导入项目自定义的配置类，并重命名为AppSettings，避免和LlamaIndex的Settings重名 from config.settings import Settings as AppSettings 导入项目自定义的日志工具函数，用于创建日志记录器 from utils.logger import setup_logger 创建当前模块的日志记录器，用于打印程序运行过程中的信息和错误日志 logger = setup_logger(name) 定义文档摄取管道类，负责完整的文档入库全流程：读取文档→切分文本→向量化→存入数据库→持久化保存 class DocumentIngestionPipeline: """文档摄取：把读取、切分、向量化和持久化交给 LlamaIndex。""" # 类的构造初始化方法，创建类实例时自动执行，返回值类型为None def __init__(self) -> None: # 实例属性：向量索引对象，类型为可选的VectorStoreIndex，初始值设为None，后续加载或创建后才会赋值 self.index: Optional[VectorStoreIndex] = None # 调用私有方法，初始化大语言模型和嵌入模型的全局配置 self._setup_models() # 调用私有方法，创建文档摄取流水线，串联文档切分、向量化等处理步骤 self._create_pipeline() # 调用私有方法，初始化各类存储组件（向量数据库、文档存储、索引存储） self._initialize_storage() # 定义更新模型配置的方法，支持动态切换模型、调整温度参数和最大输出长度 def update_model_config(self, model_name: str, temperature: float, max_tokens: int) -> None: # 更新LlamaIndex全局配置中的大语言模型，使用OpenAI兼容格式对接 Settings.llm = OpenAILike( model=model_name, # 注意参数名是 model 而不是 model_name api_key=AppSettings.API_KEY, # 大模型接口的认证密钥，从项目配置文件中读取 api_base=AppSettings.API_BASE_URL, # 大模型接口的基础访问地址，从项目配置文件中读取 temperature=temperature, # 温度参数，控制回答的随机性：值越高越发散有创意，值越低越稳定严谨 max_tokens=max_tokens, # 最大输出token数，限制AI回答的内容长度 context_window=32768, # 模型支持的最大上下文窗口大小，决定能处理的最长上下文 is_chat_model=True, # 标记该模型是对话型模型，适配聊天场景 ) # 打印信息日志，记录模型更新的参数 logger.info("模型已更新: model=%s, temperature=%s", model_name, temperature) # 定义文档摄取的核心方法，接收文件路径列表，返回处理结果字符串 def ingest_documents(self, file_paths: List[str]) -> str: # 校验所有传入的文件路径，只保留真实存在的文件，转换为字符串格式的有效路径列表 valid_paths = [str(Path(path)) for path in file_paths if Path(path).exists()] # 判断有效路径列表是否为空 if not valid_paths: # 没有有效文件时，直接返回提示信息 return "没有找到有效的文档" # 开始异常捕获，处理文档摄取过程中可能出现的所有错误 try: # 使用文档读取器加载所有有效文件，转换为LlamaIndex可处理的Document对象列表 documents = SimpleDirectoryReader(input_files=valid_paths).load_data() # 将文档送入摄取流水线，自动完成文本切分、向量化，得到处理后的文档节点列表 nodes = self.pipeline.run(documents=documents) # 判断生成的文档节点是否为空 if not nodes: # 没有生成有效节点时返回提示信息 return "没有生成有效的文档节点" # 判断当前向量索引是否为空（还没创建或加载） if self.index is None: # 尝试加载本地已有的索引 try: # 调用加载索引的方法，从本地持久化文件加载索引 self.load_index() # 捕获加载失败的运行时错误 except RuntimeError: # 加载失败则跳过，后续会新建索引 pass # 再次判断索引是否仍为空（加载失败或本来就没有索引） if self.index is None: # 调用私有方法，清空向量数据库中的旧数据，避免数据冲突 self._clear_vector_store() # 使用处理好的文档节点创建全新的向量索引 self.index = VectorStoreIndex( nodes, # 使用初始化好的存储上下文来管理数据存储 storage_context=self.storage_context, store_nodes_override=True, # 开启节点存储覆盖，确保节点数据完整存入文档存储 ) # 索引已经存在的情况 else: # 将新的文档节点追加到已有的向量索引中 self.index.insert_nodes(nodes) # 调用私有方法，将所有存储数据持久化保存到本地硬盘 self._persist_storage() # 拼接处理成功的结果信息，包含文档数量和节点数量 result = f"成功摄取了 {len(valid_paths)} 个文档，生成了 {len(nodes)} 个节点" # 打印信息日志，记录文档摄取成功 logger.info(result) # 返回成功结果信息 return result # 捕获所有类型的异常 except Exception as exc: # 拼接错误信息，包含异常详情 error_msg = f"文档摄取失败: {exc}" # 打印错误日志，记录失败原因 logger.error(error_msg) # 返回错误信息 return error_msg # 定义加载索引的方法，从本地持久化存储中加载已构建的向量索引 def load_index(self) -> None: # 打印日志，提示开始加载知识库索引 logger.info("从持久化存储加载知识库索引") # 异常捕获，处理加载过程中的错误 try: # 调用LlamaIndex提供的函数，从存储上下文中加载向量索引 self.index = load_index_from_storage( self.storage_context, store_nodes_override=True, # 开启节点存储覆盖，保证加载的节点数据完整 ) # 捕获值错误异常 except ValueError as exc: # 判断错误是否是"存储中没有索引"导致的 if "No index in storage context" in str(exc): # 转换为更易懂的运行时错误抛出，同时保留原始异常链 raise RuntimeError("知识库索引未初始化，请先上传文档") from exc # 其他类型的值错误直接抛出 raise # 私有方法：初始化全局模型配置 def _setup_models(self) -> None: # 配置全局使用的大语言模型，采用OpenAI兼容协议对接 Settings.llm = OpenAILike( model=AppSettings.MODEL, # 注意参数名是 model 而不是 model_name api_key=AppSettings.API_KEY, # 接口认证密钥，从配置文件读取 api_base=AppSettings.API_BASE_URL, # 接口基础地址，从配置文件读取 temperature=AppSettings.TEMPERATURE # 默认温度参数，从配置文件读取 ) # 配置全局使用的嵌入模型，基于HuggingFace的模型，负责将文本转换为语义向量 Settings.embed_model = HuggingFaceEmbedding(model_name=AppSettings.EMBEDDING_MODEL_PATH) # 私有方法：创建文档摄取流水线 def _create_pipeline(self) -> None: # 创建摄取流水线实例，将多个处理步骤按顺序串联 self.pipeline = IngestionPipeline( # 流水线的转换步骤列表，文档会按顺序经过每个步骤处理 transformations=[ # 第一步：句子分割器，将长文档切分为固定大小的文本块（chunk） SentenceSplitter( chunk_size=AppSettings.CHUNK_SIZE, # 每个文本块的大小，从配置文件读取 chunk_overlap=AppSettings.CHUNK_OVERLAP, # 相邻文本块的重叠内容大小，避免语义被截断 ), # TitleExtractor(nodes=AppSettings.TITLE_EXTRACTOR_NODES), # 标题提取器，暂时注释禁用 # 第二步：嵌入模型，将每个文本块转换为对应的语义向量 Settings.embed_model, ] ) # 私有方法：初始化所有存储组件 def _initialize_storage(self) -> None: # 创建持久化根目录，parents=True表示自动创建所有父目录，exist_ok=True表示目录已存在也不报错 Path(AppSettings.DEFAULT_PERSIST_DIR).mkdir(parents=True, exist_ok=True) # 创建ChromaDB持久化客户端，数据会永久保存在指定目录的本地硬盘 chroma_client = chromadb.PersistentClient(AppSettings.CHROMA_PERSIST_DIR) # 获取或创建ChromaDB的集合（相当于数据库中的表），用于存储向量数据 self.chroma_collection = chroma_client.get_or_create_collection(AppSettings.CHROMA_COLLECTION) # 将ChromaDB集合包装为LlamaIndex兼容的向量存储对象 vector_store = ChromaVectorStore(chroma_collection=self.chroma_collection) # 创建存储上下文，统一管理三类存储 self.storage_context = StorageContext.from_defaults( docstore=self._load_docstore(), # 传入文档存储实例，保存原始文本节点 index_store=self._load_index_store(),# 传入索引存储实例，保存索引的元数据 vector_store=vector_store, # 传入向量存储实例，保存语义向量 ) # 私有方法：加载文档存储，返回SimpleDocumentStore实例 def _load_docstore(self) -> SimpleDocumentStore: # 获取文档存储的本地文件路径 docstore_path = Path(AppSettings.DOCSTORE_PATH) # 判断本地是否已有保存的文档存储文件 if docstore_path.exists(): # 从本地路径加载已有的文档存储 return SimpleDocumentStore.from_persist_path(str(docstore_path)) # 没有本地文件则返回一个全新的空文档存储 return SimpleDocumentStore() # 私有方法：加载索引存储，返回SimpleIndexStore实例 def _load_index_store(self) -> SimpleIndexStore: # 获取索引存储的本地文件路径 index_store_path = Path(AppSettings.INDEX_STORE_PATH) # 判断本地是否已有保存的索引存储文件 if index_store_path.exists(): # 从本地路径加载已有的索引存储 return SimpleIndexStore.from_persist_path(str(index_store_path)) # 没有本地文件则返回一个全新的空索引存储 return SimpleIndexStore() # 私有方法：将所有存储数据持久化到本地硬盘 def _persist_storage(self) -> None: # 调用存储上下文的持久化方法，将所有数据保存到指定目录 self.storage_context.persist(persist_dir=AppSettings.DEFAULT_PERSIST_DIR) # 私有方法：清空向量数据库中的所有数据 def _clear_vector_store(self) -> None: # 获取集合中所有向量数据的ID列表，没有数据则返回空列表 ids = self.chroma_collection.get().get("ids") or [] # 判断ID列表是否不为空 if ids: # 根据ID列表删除集合中的所有向量数据 self.chroma_collection.delete(ids=ids) 定义RAG应用主类，是整个知识库问答系统的对外入口，整合文档管理、检索、聊天、记忆等所有功能 class RAGApplication: """RAG 应用入口：用 LlamaIndex 管理摄取、聊天、记忆和知识库问答。""" # 构造初始化方法，创建类实例时自动执行 def __init__(self) -> None: # 实例化文档摄取管道，负责文档入库的全流程处理 self.ingestion_pipeline = DocumentIngestionPipeline() # 获取聊天记录持久化存储的文件路径 self.chat_store_path = Path(AppSettings.CHAT_STORE_PATH) # 确保聊天记录文件的父目录存在，不存在则自动创建 self.chat_store_path.parent.mkdir(parents=True, exist_ok=True) # 加载聊天存储实例，用于持久化保存所有会话的聊天记录 self.chat_store = self._load_chat_store() # 字典，存储每个会话的记忆缓冲区，key是会话ID，value是对应的记忆对象 self.memories: Dict[str, ChatMemoryBuffer] = {} # RAG混合检索器，初始为None，采用懒加载模式，用到时再创建 self.rag_retriever: Optional[QueryFusionRetriever] = None # 语义重排器，初始为None，懒加载模式，用于对检索结果重新排序提升准确率 self.reranker: Optional[SentenceTransformerRerank] = None # 更新模型配置的对外方法，同步更新文档管道的模型配置 def update_model_config(self, model_name: str, temperature: float, max_tokens: int) -> None: # 调用文档摄取管道的更新方法，同步更新模型配置 self.ingestion_pipeline.update_model_config(model_name, temperature, max_tokens) # 处理用户上传文件的对外方法，接收文件路径列表，返回处理结果 def upload_and_process_files(self, file_paths: List[str]) -> str: # 判断文件路径列表是否为空 if not file_paths: # 为空则返回提示信息 return "请上传至少一个文件" # 调用摄取管道处理文档，完成知识库入库 result = self.ingestion_pipeline.ingest_documents(file_paths) # 文档更新后，旧的检索器不再适用，置空后下次使用会自动重新创建 self.rag_retriever = None # 返回处理结果 return result # 异步方法：流式问答，以异步生成器形式逐块返回数据，实现前端打字机效果 async def query_documents_stream( self, session_id: str, # 会话ID，用于区分不同的用户或不同的聊天窗口 query: str, # 用户输入的问题文本 knowledge_bool: bool, # 是否开启知识库问答的开关 ) -> AsyncGenerator[Dict[str, Any], None]: # 异常捕获，处理查询过程中的所有错误 try: # 根据是否开启知识库，创建对应的聊天引擎 chat_engine = self._get_chat_engine(session_id, knowledge_bool) # 异步发起流式聊天请求，得到流式响应对象 stream_response = await chat_engine.astream_chat(query) # 异步遍历流式响应的每个token（文本片段） async for token in stream_response.async_response_gen(): # 判断当前token不为空 if token: # 产出文本类型的数据块，标记未完成，内容是当前token yield {"type": "text", "finished": False, "content": token} # 从响应中获取检索到的来源节点，转换为字典列表，没有则返回空列表 sources = self._source_nodes_to_dicts(getattr(stream_response, "source_nodes", [])) # 判断是否有来源数据 if sources: # 产出来源类型的数据块，包含检索到的参考文档信息 yield { "type": "sources", "finished": False, "content": sources, "sources_data": sources, } # 将本次聊天记录持久化保存到本地 self._persist_chat_store() # 产出完成信号，标记对话结束，附带完整的回答内容 yield {"type": "complete", "finished": True, "content": stream_response.response} # 捕获所有类型的异常 except Exception as exc: # 拼接错误信息，包含异常详情 error_msg = f"查询失败: {exc}" # 打印错误日志，记录失败原因 logger.error(error_msg) # 产出错误类型的数据块，标记对话结束 yield {"type": "error", "content": error_msg, "finished": True} # 获取指定会话的历史聊天记录，返回字典列表格式 def get_session_history(self, session_id: str) -> List[Dict[str, Any]]: # 获取该会话的记忆对象，再取出所有历史消息 messages = self._get_memory(session_id).get() # 遍历所有消息，转换为前端需要的格式返回 return [ { # 消息角色，兼容枚举类型和字符串类型两种情况 "role": message.role.value if hasattr(message.role, "value") else str(message.role), # 消息内容，为空则返回空字符串 "content": message.content or "", # 来源列表，历史消息默认返回空 "sources": [], } for message in messages ] # 清空指定会话的聊天记录和记忆 def clear_session(self, session_id: str) -> None: # 判断内存中是否存在该会话的记忆 if session_id in self.memories: # 重置该会话的记忆缓冲区，清空内存中的历史 self.memories[session_id].reset() # 从持久化的聊天存储中删除该会话的所有消息 self.chat_store.delete_messages(session_id) # 保存修改后的聊天存储到本地 self._persist_chat_store() # 私有方法：获取指定会话的记忆对象，不存在则创建新的 def _get_memory(self, session_id: str) -> ChatMemoryBuffer: # 判断该会话ID不在记忆字典中 if session_id not in self.memories: # 为该会话创建新的记忆缓冲区 self.memories[session_id] = ChatMemoryBuffer.from_defaults( llm=Settings.llm, # 使用全局配置的大模型 chat_store=self.chat_store, # 使用全局的聊天存储做持久化 chat_store_key=session_id, # 用会话ID作为存储的键，区分不同会话 ) # 返回该会话的记忆对象 return self.memories[session_id] # 私有方法：加载聊天存储实例 def _load_chat_store(self) -> SimpleChatStore: # 判断本地是否有保存的聊天记录文件 if self.chat_store_path.exists(): # 从本地路径加载已有的聊天存储 return SimpleChatStore.from_persist_path(str(self.chat_store_path)) # 没有本地文件则返回全新的空聊天存储 return SimpleChatStore() # 私有方法：将聊天存储持久化到本地硬盘 def _persist_chat_store(self) -> None: # 调用聊天存储的持久化方法，保存到指定的文件路径 self.chat_store.persist(str(self.chat_store_path)) # 私有方法：根据知识库开关获取对应的聊天引擎 def _get_chat_engine(self, session_id: str, knowledge_bool: bool): # 先获取会话的记忆对象 memory = self._get_memory(session_id) # 开启知识库的情况 if knowledge_bool: # 创建上下文聊天引擎，支持RAG知识库问答 return ContextChatEngine.from_defaults( retriever=self._get_rag_retriever(), # 传入RAG检索器，用于检索知识库 memory=memory, # 传入会话记忆，支持上下文对话 llm=Settings.llm, # 使用全局大模型生成答案 node_postprocessors=[self._get_reranker()], # 传入重排器，对检索结果做重排序优化 ) # 不开启知识库，返回简单聊天引擎，纯对话不检索知识库 return SimpleChatEngine.from_defaults(memory=memory, llm=Settings.llm) # 私有方法：获取RAG混合检索器，采用懒加载模式 def _get_rag_retriever(self) -> QueryFusionRetriever: # 先确保向量索引已经加载完成 self._ensure_index_loaded() # 获取索引对象 index = self.ingestion_pipeline.index # 索引为空则抛出运行时错误 if index is None: raise RuntimeError("知识库索引未初始化，请先上传文档") # 检索器还没创建则进行创建 if self.rag_retriever is None: # 创建向量检索器，基于语义相似度做检索 vector_retriever = VectorIndexRetriever( index=index, similarity_top_k=AppSettings.SIMILARITY_TOP_K, # 返回最相关的前K条结果 ) # 收集所有有内容的文档节点，用于BM25关键词检索 bm25_nodes = [ node for node in index.docstore.docs.values() if node.get_content() ] # 没有可用的文档节点则抛出错误 if not bm25_nodes: raise RuntimeError("本地文档存储为空，请重新上传文档") # 创建BM25检索器，基于关键词匹配做检索 bm25_retriever = BM25Retriever.from_defaults( nodes=bm25_nodes, similarity_top_k=AppSettings.SIMILARITY_TOP_K, # 返回最相关的前K条结果 ) # 创建查询融合检索器，融合向量检索和BM25检索的结果 self.rag_retriever = QueryFusionRetriever( [vector_retriever, bm25_retriever], # 要融合的两个检索器：向量检索+BM25检索 num_queries=1, # 生成的查询数量，1表示用原查询直接融合 use_async=True, # 启用异步执行，提升检索速度 ) # 返回检索器实例 return self.rag_retriever # 私有方法：获取语义重排器，懒加载模式 def _get_reranker(self) -> SentenceTransformerRerank: # 重排器还没创建则进行创建 if self.reranker is None: # 创建重排器实例 self.reranker = SentenceTransformerRerank( model=AppSettings.RERANK_MODEL_PATH, # 重排模型的本地路径，从配置文件读取 top_n=AppSettings.RERANK_TOP_K, # 重排后保留的结果数量 ) # 返回重排器实例 return self.reranker # 私有方法：确保索引已经加载，没加载则尝试加载 def _ensure_index_loaded(self) -> None: # 索引已存在则直接返回，不做任何操作 if self.ingestion_pipeline.index is not None: return # 调用摄取管道的加载方法，从本地加载索引 self.ingestion_pipeline.load_index() # 加载后索引仍为空则抛出运行时错误 if self.ingestion_pipeline.index is None: raise RuntimeError("知识库索引未初始化，请先上传文档") # 静态方法，不需要实例也能调用，不依赖类的实例属性 @staticmethod # 静态方法：将来源节点对象转换为字典列表，方便返回给前端使用 def _source_nodes_to_dicts(source_nodes) -> List[Dict[str, Any]]: # 遍历所有来源节点，转换为指定格式的字典 return [ { "content": node.node.get_content(), # 来源节点的文本内容 "score": float(node.score) if node.score is not None else None, # 相关性得分，转为浮点数，没有则为None "metadata": node.node.metadata or {}, # 来源节点的元数据（如文件名、页码等），没有则为空字典 } for node in source_nodes or [] ]
