这个教程要解决的事情很简单在你自己电脑上用 Docker 部署一套完全本地运行的 AI 知识库。所谓本地不只是界面上有个聊天框而是模型推理、文档存储、问答检索这些环节全部发生在本机——由 Ollama 负责模型推理Open WebUI 负责网页交互和知识库管理。整套方案跑通之后你甚至可以把网线拔了继续用所有对话记录、上传的文档都不会离开这台机器。我在 Windows、macOS 和 Linux 三种环境里都反复部署过这套组合中间踩过的坑基本上能覆盖大多数人的问题Docker Desktop 启动报错、Ollama 模型下载超时、Open WebUI 连不上 Ollama、知识库上传后答非所问……这篇文章就是把这些实测经验整理出来的保姆级操作手册。适合完全没接触过 Docker 的新手也适合已经在用 Docker 但没跑过本地模型的老手。目标只有一个让你照着步骤走就能把本地知识库跑起来并且知道每一步为什么要这么做。1. 部署前先想清楚这套方案到底解决什么问题1.1 为什么是 Ollama Open WebUI 这套组合市面上能本地跑大模型的项目不少我先说说为什么最后选定这套组合。Ollama 的优势在于三点模型管理极其简单、API 接口标准、资源占用克制。它把模型的下载、加载、推理全部封装成一条命令不需要手动配置 Python 虚拟环境、CUDA 工具链或者 Hugging Face 的依赖库这对普通用户来说是决定性的差异。Open WebUI 则是目前体验最接近 ChatGPT 的开源网页界面之一。它原生支持 Ollama只需要配置一个环境变量就能连通同时自带知识库功能支持上传 PDF、TXT、Markdown 等文档自动做切片和向量化检索这正好契合“知识库”这个核心需求。相比之下LM Studio 虽然界面友好但脚本化和远程管理能力偏弱不太适合跑在服务器或 NAS 上长期运行AnythingLLM 的文档问答做得不错可整体生态和社区活跃度不如 Open WebUI尤其是在多模型切换和 OpenAI 兼容接口的完善程度上差了一截。从实际部署的角度看这套组合还有一个特别大的优点两个服务都是独立容器通过 Docker Compose 统一管理镜像升级、数据备份、迁移换机都非常方便。如果后面想换一个模型不用重装任何东西一条命令下载新模型就行。1.2 从提问到回答整条链路是怎么走的很多人第一次部署时会困惑我明明装了两个服务到底谁在干活这里用最直白的话梳理一下。你在浏览器里打开 Open WebUI 的页面输入问题敲下回车请求先到达 Open WebUI 容器。它会做两件事第一从你选定的知识库里检索相关的文档片段第二把“你的问题 检索到的参考内容”拼成一段完整提示词发给 Ollama。Ollama 收到提示词后把模型加载进内存完成推理再把回答以流式方式回传给网页整个过程其实和 ChatGPT 网页版的工作方式很像只是一个在云端、一个在你本地。为什么要用 Docker 来编排这套链路根本原因是隔离和一致性。Ollama 和 Open WebUI 各自有依赖的运行时环境直接装在同一台机器上很容易因为系统库版本冲突导致其中一个跑不起来。Docker 把每个服务关进独立容器只暴露必要的网络端口和磁盘目录互不干扰。而且 compose 文件是纯文本夸机器部署时甚至不需要重装软件复制目录执行命令就能恢复整个服务。1.3 硬件门槛先确认电脑能跑多大模型本地跑模型和云服务器不一样没有算力池可以借用一切取决于本机配置。先说结论8GB 内存的普通办公电脑可以流畅跑 1.5B 到 3B 参数量的模型16GB 内存可以尝试 7B 参数量32GB 以上可以上 14B。如果你有 NVIDIA 独立显卡显存 6GB 以上就可以让推理速度快很多。注意这里说的是内存而不是显存因为 Ollama 支持纯 CPU 推理只是速度会慢一些。模型量化等级也直接影响资源占用一般推荐 Q4_K_M 这种 4bit 量化版本在显存占用和回答质量之间最平衡。我自己的建议是开始阶段别追求大模型先用 3B 模型把整条链路跑通再根据实际体验决定要不要换更大的。2. 环境准备Docker 装好接下来的坑提前避开2.1 Windows 安装 Docker Desktop一次配好 WSL2Windows 上装 Docker Desktop最核心的前置条件是 WSL2。很多人卡在这一步因为 Docker Desktop 默认使用 WSL2 后端来运行 Linux 容器如果系统里没有启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”这两个功能安装时必然出问题。打开“控制面板 - 程序 - 启用或关闭 Windows 功能”勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”重启后再打开管理员 PowerShell 执行wsl --install。安装完成后建议再跑一次wsl --update避免内核版本过旧导致 Docker 启动失败。Docker Desktop 的安装包本身不大但安装过程中如果 BIOS 没有开启硬件虚拟化会直接提示virtualization support not detected。这个报错的意思是“虚拟化支持未检测到”解决方案是重启进 BIOS找到 Intel VT-x 或 AMD SVM 选项并开启。判断是否开启成功可以打开任务管理器在“性能”页签里看“虚拟化”一栏是否显示“已启用”。还有一个容易忽略的点如果你的电脑本身是虚拟机比如在 VMware 里装 Windows那需要在虚拟机设置里打开“虚拟化 Intel VT-x/EPT”的嵌套虚拟化选项。装完 Docker Desktop 之后建议到设置里确认一下 WSL 集成状态。路径是 “Settings - Resources - WSL Integration”确保默认的发行版开关是打开状态。这一步经常被忽略结果 Docker 命令在终端里能用但容器一直起不来日志里全是诡异的网络错误。2.2 Linux 与 macOS 的安装差异Linux 上的安装方式相对自由但我不推荐直接用sudo apt install docker.io这种系统仓库的老旧版本功能缺失会影响 compose 使用。正确的做法是添加 Docker 官方软件源以 Ubuntu 为例需要先安装依赖包然后下载官方 GPG 密钥并配置源地址。如果官方源下载慢可以把源地址换成国内高校的镜像源地址这一点在社区里已经很成熟了。装完后记得执行sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin其中docker-compose-plugin是专门提供docker compose子命令的插件没有它后面就运行不了 compose 文件。macOS 用户相对省心Apple Silicon 和 Intel 芯片都有对应的 Docker Desktop 安装包。安装完成后有个细节Docker Desktop 在 macOS 上默认分配的内存可能偏小如果你准备跑 7B 模型建议在 “Settings - Resources” 里把内存调到 8GB 以上。macOS 上无法使用 Docker 直通 GPU所以纯 CPU 推理是常态模型选小一号更实际。2.3 镜像加速配置让 Pull 不再超时Docker 拉取镜像超时是本地部署环节里最劝退新手的问题。原因是 Docker Hub 的默认镜像源在部分地区访问不稳定。解决思路不是去改变网络环境而是给 Docker 配置镜像加速地址。打开 Docker Desktop 的 “Settings - Docker Engine”在 JSON 配置里加入registry-mirrors字段。Linux 用户则需要编辑/etc/docker/daemon.json不存在就新建一个改完重启 Docker 服务。以下是一份可以直接复制的配置示例{ registry-mirrors: [ https://docker.m.daocloud.io, https://hub-mirror.c.163.com, https://docker.mirrors.ustc.edu.cn ] }需要提醒的是这类公共加速地址有时会失效属于正常现象失效后换一个可用的即可。如果你用的是阿里云容器镜像服务控制台里会分配一个专属加速地址把那个地址填进去优先级最高因为它是按你的账号限流的稳定性通常比公共地址好。另外即便配置了加速器Open WebUI 的镜像体积比较大接近 2GB首次拉取花十几分钟都正常别急着判断是卡死了。2.4 Docker Desktop 启动失败的高频报错排查我在多台机器上装 Docker Desktop 时遇到过三个高频问题这里一并说明。第一个是启动时提示virtualization support not detected刚才已经说过去 BIOS 开虚拟化。第二个是 WSL 相关报错如果提示Please enable the Virtual Machine Platform或者 WSL 无法启动管理员权限执行bcdedit /set hypervisorlaunchtype auto然后重启。第三个是 CLI 里执行 docker 命令时报failed to connect to the docker api at npipe:////./pipe/dockerdesktop-linux这个报错的意思是没有连接上 Docker 服务通常是 Docker Desktop 没有启动、或者启动到一半崩了。先看托盘图标是否稳定运行再点 Restart 重启一次如果反复出现就去 “Settings - Troubleshoot” 里 Clean / Purge data前提是备份好你的数据目录。3. 模型下载慢三个可行方案总有一个能用3.1 常规方式容器内直接执行 ollama pullOllama 拉取模型的默认命令是ollama pull 模型名。在 Docker 部署场景下需要先进入容器再执行docker exec -it ollama ollama pull qwen2.5:3b执行的时候会看到进度条显示下载的层内容和速度。这个下载机制支持断点续传哪怕下到一半断网了重新执行同一条命令Ollama 会自动从断点继续不需要重新下载整个文件。这一点在官方文档里没有特别强调但实际使用中非常受用。如果你发现反复中断可以先把镜像里的模型列表确认一下看看之前有没有下载成功的残留docker exec -it ollama ollama list如果列表里是空的说明确实没下载成功。需要注意Ollama 本身不需要注册账号也不需要登录手机号模型下载是纯开放的不存在“不注册就下不了”的情况。经常看到有人问“注册 Ollama 账号手机号怎么填”其实那是混淆了 Open WebUI 的管理员注册后面会详细说。3.2 手动导入从 GGUF 文件创建本地模型如果ollama pull始终无法成功还有一个和下载源无关的解决办法去公开模型文件站下载 GGUF 格式的模型文件再导入到 Ollama 里。GGUF 是 llama.cpp 社区通用的模型量化格式几乎所有主流模型都会有对应的 GGUF 版本发布。具体操作分四步。第一步把下载好的 GGUF 文件放到你映射出来的模型目录里。假设你在宿主机上创建了./ollama_models这个目录后面 compose 章节会说明并且把 Docker 里的/root/.ollama映射到了这个目录那么文件实际存放路径可以写成./ollama_models/import/qwen2.5-7b-instruct-q4_k_m.gguf。第二步写一个模型定义文件比如创建ModelfileFROM /root/.ollama/import/qwen2.5-7b-instruct-q4_k_m.gguf注意这里的路径是容器内部路径因为 Ollama 服务跑在容器里看到的文件系统是容器视角。第三步进入容器执行docker exec -it ollama ollama create qwen2.5:manual -f /root/.ollama/Modelfileollama create会用 Modelfile 里指定的基础文件重新打包出一个模型生成时间取决于文件大小和磁盘速度一般几分钟内完成。最后用ollama list看一下如果能看到qwen2.5:manual就说明导入成功。这个方法唯一的限制是GGUF 文件需要从可信来源下载文件完整性要靠校验和确认否则模型可能加载失败或输出乱码。3.3 模型选型参考不同配置跑什么模型不同模型和不同配置之间不是一个“越大越好”的关系而是“刚好能跑”和“跑得舒服”的权衡。这里整理了一张参考表按照内存和显存两个维度列出我实际测过的组合模型名量化版本文件大小内存要求适用场景qwen2.5:1.5bQ4_K_M约1GB8GB可跑轻量问答、笔记检索qwen2.5:3bQ4_K_M约2GB8GB流畅入门首选、中文效果好qwen2.5:7bQ4_K_M约4.7GB16GB以上复杂推理、文档总结llama3.2:3bQ4_K_M约2GB8GB可跑英文场景更优nomic-embed-text嵌入模型约300MB内存占用小知识库向量化必需我的实操建议是第一轮部署只拉两个模型qwen2.5:3b和nomic-embed-text。前者负责对话回答后者负责把文档变成向量。这两个加起来不到 2.5GB普通电脑完全扛得住。等这条链路跑顺了再根据实际需求换更大的模型避免一上来就被下载超时和内存爆满劝退。4. 一键部署Compose 编排 Ollama Open WebUI4.1 编写 docker-compose.yml逐一解释每个字段Compose 文件是整套部署的核心建议先建一个干净的目录避免数据散落。在终端执行mkdir -p ~/docker/ollama-webui cd ~/docker/ollama-webui touch docker-compose.yml然后打开docker-compose.yml写入以下内容services: ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped volumes: - ./ollama_models:/root/.ollama ports: - 11434:11434 deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] open-webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui restart: unless-stopped depends_on: - ollama ports: - 8080:8080 volumes: - ./open_webui_data:/app/backend/data environment: - OLLAMA_BASE_URLhttp://ollama:11434逐行解释一下关键字段。volumes里把本机的./ollama_models目录映射到容器的/root/.ollama这是 Ollama 存放所有模型文件的根目录映射出来之后容器删了模型还在。open-webui的./open_webui_data映射到/app/backend/data存放聊天记录、用户账号、知识库索引数据同样保留在宿主机。depends_on控制启动顺序确保 Open WebUI 启动时 Ollama 已经就绪。OLLAMA_BASE_URLhttp://ollama:11434是 Open WebUI 连接 Ollama 的关键配置这里用的是 Docker 内部网络中的服务名ollama而不是localhost这是新手最容易写错的地方——两边容器互不共享 localhost。GPU 配置单独说明一下。deploy.resources.reservations.devices这段是给有 NVIDIA 显卡的 Linux 环境预留的如果电脑没有 N 卡或者用的是 Windows/macOS直接删除这段即可。Windows 的 Docker Desktop 通过 WSL2 可以自动共享 GPU无需手动配置macOS 不支持容器 GPU 直通删掉没毛病。使用这个配置前Linux 主机需要安装 NVIDIA Container Toolkit并重启 Docker 服务否则容器起不来。如果你用的是绿联 NAS、群晖这类设备这套 compose 文件同样适用把内容复制到设备的 Docker 管理界面新建项目即可。这类 NAS 的 Docker 内核默认支持多容器编排docker compose子命令基本都有路径不同但逻辑一样。4.2 启动容器并验证服务在 compose 文件所在目录执行docker compose up -d-d表示后台运行。第一次执行会拉取两个镜像耐心等进度条。拉取过程中可以每隔一段时间执行docker compose ps查看状态正常情况下两个服务都会显示Up。如果ollama容器反复重启多半是 GPU 配置有问题把deploy段删掉再试。如果open-webui容器一直处于starting状态用日志确认初始化进度docker compose logs -f open-webui看到日志里出现 “Started server process” 之类的输出说明服务已经起来了。接下来验证 Ollama 是否响应浏览器访问http://localhost:11434/api/tags或者执行curl http://localhost:11434/api/tags返回空 JSON 数组[]是正常现象说明 Ollama 在运行但还没有模型。这时候进容器把模型拉下来docker exec -it ollama ollama pull qwen2.5:3b docker exec -it ollama ollama pull nomic-embed-text两个模型下载完成后再访问一次/api/tags能看到模型列表就说明整条后端链路已经通了。4.3 完成 WebUI 初始化与模型联通打开浏览器访问http://localhost:8080Open WebUI 第一次打开会让你注册一个管理员账号。这里注意邮箱和密码随便填不需要任何邮箱验证第一个注册的用户自动成为管理员。注册登录后进入主界面看到的是一个和 ChatGPT 长得很像的对话页。接下来检查模型是否被正确识别。点击页面左上角或右下角的模型选择器正常情况下会列出已经下载的qwen2.5:3b。如果列表是空的优先检查OLLAMA_BASE_URL环境变量是否生效可以进容器看实际配置docker exec -it open-webui env | grep OLLAMA确认值是不是http://ollama:11434。如果值不对修改 compose 文件之后必须重新docker compose up -d只重启容器不会应用环境变量变更。模型联通后随便发一句“你好”如果能看到完整回答恭喜你已经成功跑起了一个完全本地的 AI 对话服务。4.4 让局域网设备也能访问知识库这套部署默认把端口映射到了0.0.0.0也就是说同一局域网内的其他设备可以直接用http://宿主机IP:8080访问 Open WebUI。这个方法特别适合办公室场景配一台小主机或者 NAS跑着这套服务同事们在各自电脑上打开浏览器就能用数据全部留在公司内部不经过任何外部服务器。如果你只想自己一个人访问不想暴露到局域网可以把 compose 里的端口映射改成127.0.0.1:8080:8080这样就只有本机能打开页面。Ollama 的 11434 端口同理生产环境中建议把 Ollama 端口只绑定在内网网卡或者干脆不映射——因为 Open WebUI 是通过内部网络访问它的宿主机其实不需要暴露这个端口。5. 从聊天机器人升级为知识库RAG 本地化5.1 下载嵌入模型为文档向量化做准备纯粹对话还不够做知识库的关键一步是让模型“读过”你的文档。Open WebUI 内置了一个知识库功能把文档上传后系统会对内容进行切分和向量化这个向量化过程需要一个嵌入模型。在第一节里我建议过先拉nomic-embed-text如果你还没拉现在执行docker exec -it ollama ollama pull nomic-embed-text嵌入模型和对话模型不一样它不负责生成回答只负责把一段文字转换成一串数字向量。举例来说“苹果”和“iPhone”这两个词在向量空间里距离很近而“苹果”和“汽车”距离很远。知识库的检索能力本质上靠的就是这种向量距离计算。5.2 在 Open WebUI 里创建知识库并导入文档打开 Open WebUI进入“工作区”或“知识库”页面新建一个知识库给它取个名字然后上传文档。支持的格式包括 PDF、TXT、Markdown、Word新版已支持 docx 解析。上传完成后Open WebUI 会自动完成切块、向量化、索引三步操作这几步都在本机完成整个过程中文档不会离开你的电脑。知识库建好之后回到聊天页面在聊天界面里选择刚才创建的知识库作为上下文来源然后提问。比如上传了一份公司产品说明书你可以直接问“这个产品的最大负载是多少”回答就会基于说明书内容给出而不是凭空编造。开启知识库引用后回答下方会显示引用了哪些文档片段这一点对验证回答准确性非常有帮助。5.3 知识库背后的 RAG 原理这个机制在技术圈叫 RAGRetrieval-Augmented Generation检索增强生成。它的核心思想是不直接让大模型凭空回答问题而是先从本地文档库里检索出和问题最相关的内容再把这些内容连同问题一起交给大模型生成回答。这样做的好处是大模型不需要把整个文档库背下来也能准确回答只存在于某份内部文档里的问题同时显著降低胡编乱造的概率。文案层面的应用场景也很直观。你可以把产品手册、支持工单、会议纪要、读书笔记分别建库让不同库服务不同场景。我在实际使用中有一个体会知识库回答质量的上限取决于文档内容的清晰度如果原文本身措辞混乱、缺少关键信息再大的模型也答不出花来。所以建库之前先花点时间整理文档比事后换更大的模型要有效得多。6. 常见问题速查与实战心得6.1 高频问题速查表现象可能原因解决办法Docker Desktop 报 virtualization support not detectedBIOS 未开启硬件虚拟化进 BIOS 开启 Intel VT-x / AMD SVM重启后再验证docker 命令报 npipe 连接失败Docker Desktop 未启动或 WSL 集成异常确认托盘图标正常运行Settings 里重启 WSL 集成容器反复重启GPU 配置无效删除 compose 中的 deploy 段重启容器拉取 open-webui 镜像慢镜像源连接不稳定配置镜像加速器或导入离线 tar 包Open WebUI 模型列表为空OLLAMA_BASE_URL 配置不对检查环境变量必须为 http://ollama:11434模型下载中断网络断开或超时重新执行 ollama pull支持断点续传知识库上传后答非所问文档质量差或未选中知识库确认聊天界面已关联知识库整理文档语句局域网访问不了防火墙拦截放行 8080 端口确认宿主机 IP6.2 部署过程中的几条真实避坑经验最重要的一条别一上来就拉 70B 大模型。很多人看到别人用大模型的截图就很兴奋结果下载了几个小时、内存直接爆掉、系统卡死。第一轮部署建议只跑qwen2.5:3b确认整条链路通了以后再升级模型这一步能帮你省掉至少半天的时间。第二条容器随便删数据目录不能丢。我见过有人清理 Docker 空间时直接docker system prune -a结果把模型文件和聊天记录全清掉了。只要./ollama_models和./open_webui_data还在容器重建之后服务照常跑模型和数据都不会丢。反过来升级镜像之前先备份这两个目录是永远不亏的操作。第三条8080 和 11434 是出问题的高发端口因为很多人电脑上已经有别的服务占用了。启动失败时不要急着怀疑镜像先用docker ps看容器状态再用本机网络命令查端口占用。Windows 上用netstat -ano | findstr 8080Linux/macOS 上用lsof -i:8080找到占用进程后停掉它或者改映射端口。6.3 扩展从知识库到生产力工具这套部署完成之后可扩展的方向非常多。Open WebUI 提供了一套兼容 OpenAI 接口的 API 端点在http://localhost:11434/v1几乎所有支持 OpenAI 接口的工具都可以直接接入这个地址这让本地模型可以被用来驱动各种自动化脚本、聊天工具、甚至 IDE 插件的代码补全。Ollama 的OLLAMA_NUM_PARALLEL和OLLAMA_KEEP_ALIVE环境变量可以用来调整并发能力和模型常驻时间对多人同时使用的场景很有帮助。最后说一点个人体会。我前前后后在三四台机器上搭过这套环境踩得最多的坑反而是最基础的文件路径和端口冲突。部署本身没有高深的技术真正决定成败的是耐心——先把docker compose ps的结果确认好再往下操作基本不会卡住。真正动手之后你会发现本地跑一个大模型并没有想象中那么神秘数据在自己手里想怎么调都行。先从 3B 模型开始把你的文档丢进去试一轮问答那种“私有 AI”的实感就来了。