local-assistant-examples

Local Assistant Examples：用 LangChain + Ollama + Streamlit 打造本地 ChatPDF

痛点切入：为什么需要本地 RAG？

当你试图用 ChatPDF 或 Notion AI 处理一份内部财务报告、技术专利文档时，数据隐私问题随之而来——文件上传意味着内容经过第三方服务器，在合规要求严格的金融、医疗、法律行业，这是无法接受的硬伤。同时，GPT-4 等大模型的 API 调用成本也在持续累积：一个 200 页的 PDF 问答场景，Token 消耗可能轻松突破几美元。

vndee/local-assistant-examples（曾用名 local-rag-example，现更名为 local-assistant-examples）正是为解决这两个问题而生的开源项目：让用户在本地构建一个功能完整的 ChatPDF 应用，100% 数据不出本机，零 API 费用，同时保持良好的交互体验。

项目背景与作者

项目作者是越南开发者 Duy Huynh（GitHub @vndee），他同时维护着一个技术博客 blog.duy.dev，持续输出 LLM 应用开发教程。项目最初源于一篇详细的博客文章《Build your own RAG and run it locally: Langchain + Ollama + Streamlit》，后扩展为多示例教育仓库，将不同类型的 LLM 应用场景整合到一个统一代码库中。

目前仓库包含两个核心示例：

simple-rag：基于 LangChain + Ollama + Streamlit 的本地 PDF 问答系统（完整 RAG 流程）
llm-website-scraper：基于 Playwright + Crawl4AI + 多 LLM Provider 的智能网页爬虫（多 Provider 支持 Ollama / OpenAI / Anthropic）

核心功能：本地 RAG 是怎么工作的？

文档摄入（Ingest）流程

用户上传 PDF → PyPDFLoader 加载 → RecursiveCharacterTextSplitter 分块
→ FastEmbedEmbeddings 向量化 → Chroma 向量数据库持久化存储

ChatPDF 类的 ingest() 方法负责将 PDF 文档转化为可检索的知识库：

文档加载：使用 PyPDFLoader 读取 PDF，返回 Document 对象列表
文本分块：通过 RecursiveCharacterTextSplitter 将长文档切分为 1024 字符一段、100 字符重叠的块，既保证上下文连贯，又避免单块超出 LLM 的上下文窗口
元数据过滤：filter_complex_metadata() 清理 LangChain 不支持的复杂元数据字段
向量存储：Chroma 是轻量级本地向量数据库，支持 persist_directory 持久化，重启后无需重新向量化

问答（Ask）流程

用户提问 → Chroma similarity search → Top-K 相关文本块 → LangChain Prompt Template
→ ChatOllama (本地 LLM) → 生成回答

ask() 方法执行的是标准 RAG Pipeline：

检索器配置：k=10 每次取 Top-10 相关块，score_threshold=0.0 不过滤低分结果，保证召回率
Prompt 模板：区分 system（设定 AI 角色）和 human（附上上下文和问题的结构化模板），避免 Prompt 注入
LLM 路由：默认使用 Ollama 本地模型 qwen2.5，支持初始化时动态切换任意 Ollama 支持的模型

Web 界面

Streamlit 提供了一个轻量级的浏览器交互界面：

文件上传：支持多 PDF 同时上传，Ingest 完成后自动清空临时文件
对话历史：用 streamlit-chat 实现对话气泡，区分用户消息和 AI 回复
分页存储：st.session_state 管理对话历史和向量存储状态，支持跨页面保留上下文

技术架构解读

这是一个典型的 LangChain LCEL（LangChain Expression Language） 链式架构：Retriever → Prompt → LLM → OutputParser，数据流清晰，组件可替换性强。

依赖栈分析：

LangChain 0.2.x：核心编排层，管理 Chain、Prompt、Retriever 的组合逻辑
Chroma 0.5.x：本地向量数据库，轻量无外部依赖
FastEmbed：本地 Embedding 模型（ONNX 推理），无需 GPU，比 OpenAI Embedding 快 3-5 倍
Streamlit 1.38+：Web 界面框架，5 行代码搭起一个可交互应用
PyPDF：Python 原生 PDF 解析，无外部依赖

llm-website-scraper：更广泛的 LLM 应用示例

除了核心的 RAG 示例，仓库还包含一个更复杂的智能网页爬虫：

BFS 遍历：基于广度优先搜索，按深度层级抓取网站页面，支持 max_pages 和 max_depth 控制范围
多 LLM Provider：同时支持 Ollama（本地）、OpenAI（GPT-4o-mini）、Anthropic（Claude）三种 LLM 后端
双策略模式：text 策略用 BeautifulSoup 提取纯文本；vision 策略用 Playwright 截图 + 多模态 LLM 分析页面结构
Crawl4AI 集成：新一代 AI 友好的网页爬虫，能够更好地处理 SPA（单页应用）和 JavaScript 渲染内容

上手门槛评估

维度	评估
部署难度	低（poetry install + streamlit run）
硬件要求	需要本地 GPU 或较强 CPU（qwen2.5 推荐 6GB+ VRAM）
前置依赖	Ollama 服务必须提前启动并拉取模型
进阶空间	高（可替换 Embedding 模型、切换 LLM、扩展多文档支持）

对于完全没有 LLM 本地部署经验的用户，主要挑战在于 Ollama 的安装和模型拉取（Mistral-7B 约 4GB，qwen2.5 约 4-5GB）。一旦 Ollama 服务启动，运行 Streamlit 应用本身非常顺畅。

项目局限与争议

生产环境不推荐：作者在 README 中明确说明"not intended for production use"，缺乏身份验证、并发控制、错误处理等生产级特性
Chroma 并发限制：Chroma 的本地持久化在多进程场景下存在锁竞争，生产环境应迁移至 Qdrant、Milvus 等分布式向量数据库
PDF 解析质量：PyPDF 对复杂排版（多栏、图表、扫描件）支持有限，企业场景需要换用 pymupdf 或 marker-pdf
检索精度有限：仅靠 similarity search 缺少混合检索（BM25 + vector）、重排序（Reranker）等高级优化手段

行业意义

RAG（检索增强生成）已经成为 LLM 应用的事实标准架构。本地化 RAG 的兴起反映了一个重要趋势：在数据隐私法规日趋严格的背景下，越来越多的企业和开发者倾向于将 LLM 应用部署在私有环境中，既保证数据主权，又避免 API 依赖和成本波动。

local-assistant-examples 的价值不在于它本身有多复杂，而在于它提供了一个完整可运行的最小 RAG 系统：代码量不大（rag.py 约 100 行），但涵盖了从文档加载、向量检索、Prompt 组装到 UI 交互的完整链路，非常适合作为 LLM 应用开发的入门教材和二次开发起点。随着 Ollama 生态的成熟（现已支持 100+ 模型），本地 LLM + RAG 的组合将在个人开发者和中小团队中持续普及。

核心技术栈：Python · LangChain · Chroma · FastEmbed · Streamlit · Ollama · Playwright

适用场景：本地 LLM 应用开发学习、RAG 架构验证、私有文档问答、数据隐私敏感场景原型开发