Local RAG源码解析：深入理解Streamlit+RAG架构

Local RAG源码解析深入理解StreamlitRAG架构【免费下载链接】local-ragIngest files for retrieval augmented generation (RAG) with open-source Large Language Models (LLMs), all without 3rd parties or sensitive data leaving your network.项目地址: https://gitcode.com/gh_mirrors/lo/local-ragLocal RAG是一个基于Streamlit框架构建的本地化检索增强生成(RAG)应用它巧妙地将用户友好的Web界面与强大的本地大语言模型(LLM)处理能力相结合。这个开源项目让用户能够在完全离线的环境中安全地处理本地文件、GitHub仓库和网站内容实现真正的数据隐私保护。本文将深入解析Local RAG的架构设计、核心组件实现以及Streamlit与RAG技术的完美融合。️ 项目架构概览Local RAG采用模块化设计主要分为四个层次Streamlit界面层、组件管理层、数据处理层和RAG引擎层。这种分层架构确保了代码的可维护性和扩展性。核心入口main.py项目的入口文件main.py简洁而高效展示了Streamlit应用的标准结构def main(): # 页面配置 set_page_config() # 初始化状态管理 set_initial_state() # 设置页面头部 set_page_header() # 显示聊天历史 for msg in st.session_state[messages]: st.chat_message(msg[role]).write(msg[content]) # 侧边栏组件 sidebar() # 聊天框组件 chatbox()这个简洁的入口点清晰地定义了应用的生命周期配置初始化 → 状态管理 → 界面渲染 → 用户交互。 状态管理与会话持久化智能状态初始化在components/page_state.py中set_initial_state()函数负责管理应用的全局状态。这个模块实现了智能的模型选择和状态恢复机制def set_initial_state(): # 从浏览器存储恢复设置 restore_settings_from_browser_storage() # 确保Ollama端点配置 ensure_ollama_endpoint(st.session_state) # 动态加载可用模型 if should_refresh_models_for_endpoint(st.session_state, ollama_models): try: models get_models() st.session_state[ollama_models] models except Exception: st.session_state[ollama_models] []Local RAG的状态管理系统特别值得关注。它通过st.session_state维护了整个应用的状态包括聊天模型选择如gemma4:latest, llama3:8b等嵌入模型配置支持Ollama或本地Hugging Face模型文档处理状态用户界面偏好设置浏览器本地存储集成项目通过utils/browser_settings.py实现了浏览器localStorage的集成确保用户设置在不同会话间持久化def persist_settings_to_browser_storage(): 将关键设置持久化到浏览器本地存储 settings_to_persist [ ollama_endpoint, selected_model, embedding_backend, ollama_embedding_model, embedding_model, system_prompt, top_k, chunk_size, chunk_overlap ] # ... 序列化并存储到浏览器这种设计避免了传统基于URL参数的设置持久化方案提供了更好的用户体验和隐私保护。 模块化组件设计侧边栏导航系统components/sidebar.py实现了应用的主要导航界面def sidebar(): with st.sidebar: tab1, tab2, tab3 st.sidebar.tabs([Data Sources, Settings, About]) with tab1: sources() # 数据源管理 with tab2: settings() # 设置管理 with tab3: about() # 关于页面每个标签页都对应一个独立的模块实现了关注点分离。数据源标签页进一步分解为三个子组件components/tabs/local_files.py - 本地文件上传components/tabs/github_repo.py - GitHub仓库导入components/tabs/website.py - 网站内容抓取 RAG管道核心实现数据处理管道utils/rag_pipeline.py是整个应用的核心实现了完整的RAG处理流程def rag_pipeline(uploaded_filesNone, documentsNone, data_dirNone, status_containerNone, initial_stagesNone): RAG处理管道的主要实现 # 1. 初始化LLM模型 llm ollama.create_ollama_llm( st.session_state[selected_model], st.session_state[ollama_endpoint], st.session_state[system_prompt], ) # 2. 配置嵌入模型 llama_index.setup_embedding_model( selected_embedding_model, chunk_sizechunk_size, chunk_overlapchunk_overlap, backendembedding_backend, ) # 3. 加载和处理文档 ingested_documents llama_index.load_documents(ingest_dir) # 4. 创建向量索引和查询引擎 llama_index.create_query_engine( st.session_state[documents], progress_callbackupdate_embedding_progress, )这个管道实现了从文档加载到查询引擎创建的全过程支持进度显示和错误处理。智能文档处理Local RAG的文档处理系统支持多种格式和来源本地文件上传- 通过Streamlit的文件上传组件GitHub仓库克隆- 使用GitPython库网站内容抓取- 基于requests和BeautifulSoup所有文档都经过统一的预处理流程文档加载和解析文本分块可配置chunk_size和chunk_overlap向量嵌入生成索引构建 LlamaIndex集成与优化自定义嵌入模型适配器utils/llama_index.py展示了如何深度集成LlamaIndex框架class ProgressReportingEmbedding(BaseEmbedding): 支持进度报告的嵌入模型包装器 def get_text_embedding_batch(self, texts, show_progressFalse, **kwargs): self.total_texts len(texts) result [] batch_size self.wrapped_model.embed_batch_size for start in range(0, len(texts), batch_size): batch texts[start:start batch_size] result.extend( self.wrapped_model.get_text_embedding_batch( batch, show_progressFalse, **kwargs ) ) self.completed_texts len(batch) self.progress_callback(self.completed_texts, self.total_texts) return result这个自定义类实现了进度回调功能让用户能够实时查看嵌入生成进度大大提升了用户体验。多后端嵌入支持项目支持两种嵌入模型后端Ollama嵌入- 通过OllamaEmbedding类实现本地Hugging Face模型- 使用HuggingFaceEmbedding类def setup_embedding_model(model, chunk_sizeNone, chunk_overlapNone, backendLocal Hugging Face, ollama_endpointNone): 设置嵌入模型支持多种后端 if backend Ollama: Settings.embed_model OllamaEmbedding( model_namemodel, base_urlollama_endpoint, ) else: Settings.embed_model HuggingFaceEmbedding( model_namemodel, devicedevice, # 自动检测CPU/GPU ) 安全与健壮性设计输入验证与防护项目在多个层面实现了安全防护文档大小限制- 防止内存溢出MAX_INGESTED_DOCUMENTS 1000 MAX_INGESTED_TEXT_CHARS 10 * 1024 * 1024 # 10MBGitHub URL验证- 防止任意代码执行def normalize_github_repo(repo_input): 规范化GitHub仓库输入 # 验证格式owner/repo 或 https://github.com/owner/repo临时文件清理- 自动删除处理后的文件if os.path.isdir(save_dir): shutil.rmtree(save_dir) # 清理临时数据错误处理与用户反馈每个关键操作都有完善的错误处理和用户反馈try: # 尝试执行操作 result perform_operation() except Exception as err: # 记录错误日志 logs.log.error(f操作失败: {str(err)}) # 显示用户友好的错误信息 st.exception(error) # 停止当前流程 st.stop() 配置与自定义灵活的模型选择Local RAG支持灵活的模型配置def default_chat_model(models): 智能选择默认聊天模型 preferred_models ( gemma4:latest, llama3:8b, llama2:7b, ) for model in preferred_models: if model in models: return model return models[0] if models else None高级参数调优用户可以通过设置界面调整多个RAG参数top_k- 检索结果数量chunk_size- 文本分块大小chunk_overlap- 分块重叠大小system_prompt- 系统提示词 测试与验证项目包含完整的测试套件确保核心功能稳定tests/test_browser_settings.py - 浏览器设置测试tests/test_github_repo.py - GitHub仓库处理测试tests/test_ollama.py - Ollama集成测试tests/test_security_controls.py - 安全控制测试 部署与运行本地开发环境# 安装依赖 pip install pipenv pipenv install # 启动应用 pipenv run streamlit run main.pyDocker部署项目提供完整的Docker支持Dockerfile - 基础镜像构建docker-compose.yml - 容器编排 架构亮点总结模块化设计- 清晰的组件分离便于维护和扩展状态管理优化- 基于Streamlit session_state的高效状态管理多源数据支持- 统一的文档处理接口进度可视化- 实时显示处理进度错误恢复机制- 完善的异常处理和用户反馈隐私保护- 完全本地化处理数据不出网络配置灵活性- 支持多种模型和参数配置Local RAG项目展示了如何将复杂的RAG技术封装成用户友好的Web应用同时保持代码的清晰和可维护性。它的架构设计为开发者提供了优秀的参考特别是如何将Streamlit的简单性与复杂的AI处理流程相结合。通过深入理解这个项目的源码开发者可以学习到Streamlit高级应用架构设计本地LLM集成最佳实践RAG管道实现细节生产级错误处理模式用户友好的进度反馈机制这个项目不仅是一个功能完整的RAG应用更是一个优秀的学习资源展示了现代Python Web应用与AI技术融合的最佳实践。【免费下载链接】local-ragIngest files for retrieval augmented generation (RAG) with open-source Large Language Models (LLMs), all without 3rd parties or sensitive data leaving your network.项目地址: https://gitcode.com/gh_mirrors/lo/local-rag创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考