jonfairbanks/local-rag · 上手攻略
- 仓库：jonfairbanks/local-rag
- 链接：https://github.com/jonfairbanks/local-rag
- 分类：RAG·本地部署·Ollama·LlamaIndex
- 作者：Tom
- 更新：2026-09-02
这是什么
local-rag 是一个纯本地运行的 RAG 应用，对接 Ollama 聊天模型和 Ollama/Hugging Face embedding 模型，实现文件摄入 → 向量索引 → 流式 RAG 问答的完整流程。所有数据（聊天、embedding、索引内容）完全不离开本机网络，适合对数据隐私有要求、不希望文档上传到第三方的团队或个人。
基于 Streamlit 构建，UI 即开即用；后端用 LlamaIndex 实现 RAG 管道，支持本地文件上传、GitHub 仓库克隆和网站抓取三种摄入源。
解决什么问题
当你想在本地文档上跑 RAG 问答时，通常的选择是：
- 用 LangChain/LlamaIndex 搭一个脚本，门槛不低
- 用在线 RAG 服务（如 ChatGPT 文档问答、Notion AI），数据必须上云
local-rag 的目标是在两者之间提供一个零配置、带 UI、纯本地的中间方案：
- 不需要写代码，Streamlit UI 配置 embedding 模型、分块大小、Top-K
- 不需要数据上云，Ollama 和索引全在本地
- 支持 GitHub 仓库直接克隆摄入，适合工程师查代码文档
⚠️ 注意：Python 3.14+ 是官方声明的依赖（README 明确写了），低于此版本未测试。Windows WSL 实测未覆盖，Linux 宿主机效果最佳。
快速安装
方式一：pip（推荐有 Ollama 的机器）
pip install pipenv
pipenv install
pipenv run streamlit run main.py
访问 http://localhost:8501
方式二：Docker（开箱即用）
docker compose up -d
自动在 8501 端口启动，内含资源限制、tmpfs 缓存目录和 NVIDIA GPU 预留。AMD/ROCm 显卡用户请使用 docker-compose.yml-rocm 文件。
前置条件
必须先运行 Ollama：
# 安装 Ollama（https://ollama.com/download）
# 拉取聊天模型（任选其一）
ollama pull gemma4:latest
ollama pull llama3:8b
ollama pull llama2:7b
# 拉取 embedding 模型（默认使用 embeddinggemma）
ollama pull embeddinggemma
# 确认模型列表
ollama list
Ollama 端点默认 http://localhost:11434，可在 Settings tab 中修改。
如果 Ollama 在宿主机而非 Docker 容器内，Linux Docker 下需添加：
extra_hosts:
- 'host.docker.internal:host-gateway'
然后在 Settings 中将 Ollama 端点设为 http://host.docker.internal:11434。
核心用法
配置步骤
- 打开 Settings，确认 Ollama 端点正确
- 选择一个聊天模型（gemma4:latest / llama3:8b / llama2:7b 等）
- 选择 embedding 后端和模型（默认 Ollama → embeddinggemma）
- 确认后导入数据（文件 / GitHub / 网站）
- 摄入完成后在聊天框提问
数据摄入限制
| 限制项 | 值 |
|---|---|
| 单次上传文件数 | ≤10 个 |
| 单文件大小 | ≤25 MB |
| 单次总上传量 | ≤100 MB |
| 同时抓取网站 | ≤5 个 URL |
| 文档总数 | ≤1,000 个 |
| 加载文本总量 | ≤10 MB |
支持的文档格式
csv、docx、epub、ipynb、json、md、pdf、ppt、pptx、txt
三种摄入源详解
1. 本地文件上传
上传文件后自动写入临时 data/ 目录，完成索引后删除（除非重名文件触发复用）。相同文件重复上传会复用已有索引，文件内容变化才重新处理。
2. GitHub 仓库
支持两种格式：
- owner/repo（如 microsoft/vscode）
- https://github.com/owner/repo
使用 --depth 1 克隆到临时目录，索引完成后删除。只支持 github.com，issue/PR/branch 等子路径 URL 不支持。
3. 网站抓取
- 仅接受 HTTPS URL，内嵌凭证（用户名/密码）拒绝
- 本地网络、私有地址、link-local、multicast 等地址全部屏蔽
- 最多跟随 3 次重定向，响应体限制 5 MB/URL
- 只接受 HTML 或纯文本
流式 RAG 查询
摄入完成后即可在聊天框提问。答案以流式输出，内含行内引用直接跳转源文档段落。LlamaIndex query engine 在后端运行，Top-K 默认为 3（可调）。
设置参数说明
| 设置项 | 说明 | 默认值 |
|---|---|---|
| Ollama Endpoint | Ollama API 基础 URL | http://localhost:11434 |
| Chat Model | 聊天模型（需支持 completion） | gemma4:latest > llama3:8b > llama2:7b |
| Top K | 每次检索的相似 chunk 数量 | 3 |
| Embedding Backend | Ollama / Local Hugging Face | Ollama |
| Ollama Embedding Model | embedding 模型名 | embeddinggemma |
| Chunk Size | 分块最大 token 数 | 1024 |
| Chunk Overlap | 相邻块重叠 token 数 | 200（< chunk_size） |
| Chat Mode | LlamaIndex response mode | compact（当前 UI 禁用） |
导出聊天记录
Settings → Export Data → Chat History 导出当前对话记录为 JSON 文件。聊天记录不在浏览器 localStorage 中持久化，每次刷新 UI 会丢失。
典型适用场景
- 个人/小团队私有知识库：不需要任何数据上云的 RAG 问答
- 代码仓库文档问答：GitHub 仓库直接克隆摄入，不需要上传
- 本地隐私文档处理：医疗、财务、法律等敏感文档不上云
- 快速原型验证：不想搭 LangChain/LlamaIndex pipeline，先用 UI 验证 RAG 思路
坑与注意
- Python 3.14+ 依赖：README 明确要求，低于此版本未测试；生产环境建议用 Docker 规避版本问题
- Windows WSL 未覆盖：README 明确说不建议 WSL，Linux 宿主机是最佳选择
- Ollama 必须先行启动：local-rag 本身不包含 Ollama，Ollama 进程未运行则无法使用
- 文件上传后不留存：临时文件在索引完成后自动删除；如果需要保留，建议先 copy 一份再上传
- GitHub 仓库每次全量克隆：不支持增量更新，每次都是从头克隆再删除；频繁更新的仓库不友好
- embedding 模型名称需匹配：默认期望
embeddinggemma，如果用其他模型名需在 Settings 中手动配置 - 聊天记录不持久化：刷新页面或关闭浏览器后丢失，记得手动导出
与同类对比
| 项目 | 部署难度 | 数据是否离机 | 摄入源 | UI |
|---|---|---|---|---|
| local-rag | 极低（pip / docker） | 永不离开 | 文件/GitHub/网站 | Streamlit Web UI |
| AnythingLLM | 低 | 可选离机 | 文件/URL | Web UI |
| Max cutoff | 低 | 可选离机 | 文件/URL | Web UI |
| LlamaIndex（自搭） | 高（需写代码） | 永不离开 | 任意 | 自定义 |
| OpenAI Data Learning | 中 | 必须上机 | API | Web UI |
local-rag 的核心优势是极低门槛 + 纯本地 + 支持 GitHub 仓库摄入，代价是功能不如 AnythingLLM 丰富（不支持 URL 自定义爬取、不支持 Web Search）。
一句话结论
local-rag 把"本地 Ollama + LlamaIndex RAG"打包成了 pip install 就能用的 Streamlit 应用，GitHub 仓库直采是亮点；适合不想折腾代码、也不想把文档传到第三方的个人开发者或小团队，但需要注意 Python 3.14+ 和 Linux 优先的要求。