企业官网建设流程全解析

最近有个朋友来找我，说他们公司的合同模板、产品手册和售后 FAQ 散落得到处都是，想搞一个“内部版 ChatGPT”，但话还没说完就摇了摇头——这些文档里有客户名单、内部报价和未公开的技术参数，传到云端一旦泄露或被告知“数据被用于训练”，谁都担不起这个责任。他问我：有没有一个方案，可以离线运行、文档不出本机、还不用付订阅费？我第一个想到的就是PrivateGPT：一个开源免费的本地大模型问答框架，它能在你的电脑上读取 PDF、Word、Markdown 等文档，然后基于文档内容做问答。整个过程数据不出本机，天然满足数据隐私要求。

这篇文章面向的不是算法工程师，而是所有想把大模型用在自己私有资料上的普通人：可能是企业 IT 管理员、产品经理、研究助理，甚至只是收藏了一堆笔记想检索的独立开发者。我会从“为什么需要离线问答”讲起，把 PrivateGPT 的核心原理、部署步骤、常见报错排查和实际体验一次讲透，把我自己踩过的坑原原本本写出来。

1. 为什么我盯上了 PrivateGPT：从“文档不敢上云”开始说起

1.1 云端对话的便利与代价

ChatGPT 这类在线助手确实好用，你把它当成一个“什么都知道的顾问”，问它问题，它立刻回你。但它的使用方式天然要求你把内容交给它。日常闲聊、查资料、改文案，这没什么问题；可一旦对话内容变成“我们公司这个季度给经销商的政策是……”或者“新产品的内部测试数据表明……”，事情的味道就变了：

• 数据会经过服务端，上传到云端；即便服务商承诺不出售数据，你仍然失去了对数据的物理控制权。
• 在线服务有使用条款和日志记录，某些场景下（比如行业合规审计）根本不接受这类数据流向。
• 订阅费用也是一笔持续开销，几个人用还行，几十个人用起来账并不小。
• 有些公司在业务上压根不允许员工把内部信息贴进第三方对话框，甚至网络环境本身就限制访问外网服务。

这些约束叠加在一起，就有了一批真实的用户：他们不缺电脑，也有一定的动手能力，只是需要一套“数据永远睡在自己硬盘里”的问答方案。

1.2 真正需要本地离线问答的几类场景

我接触到的实际需求大概能分成这几类，你可以对照一下自己属于哪一种：

• 企业内网知识库：公司内部没有外网条件，或者外网管控很严。HR 政策、研发文档、生产规范不适合放到任何第三方平台，只希望在一个内网地址上提供问答能力。
• 个人机密资料整理：律师、医生、财务顾问这类职业，手里的卷宗、病历、报表都高度敏感。离线问答是刚需，不是偏好。
• 长期归档与可追溯需求：你以为“对话删了就没了”，但云端服务可能保留日志。合规要求高的项目，必须确保最终答案所依据的文档不会被服务器记录。
• 担心断网或服务不可用的使用者：把文档问答做成离线工具之后，不依赖任何外部服务，断电断网都不影响内部检索。

这些场景有一个共同点：用户要的是“私有数据上的可靠回答”，而不是“无所不知的聊天机器人”。这就是 PrivateGPT 这类工具的真正价值所在——它不追求无所不知，追求的是“你问什么，它只依据你给的文档答什么，别乱说”。

1.3 PrivateGPT 是什么，不是什么

PrivateGPT 是一个开源项目，GitHub 上的仓库地址在 imartinez/PrivateGPT 下，很长一段时间里是 LangChain 生态里最有代表性的本地问答项目之一。它做的事情用一句话概括就是：把文档切碎、向量化、存进本地向量库；你提问时，系统从向量库里找出最相关的片段，连同问题一起交给本地大模型，生成带来源依据的回答。

这个流程就是这两年很火的 RAG（检索增强生成），后面我会单独用一节来讲清楚。

但先把丑话说在前面，它不是万能的 ChatGPT 替代品：

• 它更像“私有文档的问答接口”，通用闲聊能力取决于你本地部署的模型，通常不如在线大模型。
• 它本身不需要 OpenAI API key。老版本默认用本地 llama.cpp 推理，新版本可以接 Ollama、也可以接 OpenAI 兼容接口。要做纯离线，就走 Ollama 本地模式。
• “免费”指的是软件本身开源、模型可免费下载，不代表零成本——你得自己有台配置够用的电脑，电费和硬件都是成本。

还有一个常见误解：以为装好 PrivateGPT 后，它就能像一个“拥有所有文档内容的大模型”那样，直接“记”住几万页资料然后自由对话。实际上它每次回答问题前都要临时去向量库里检索，检索质量决定了回答质量。搞懂这一点，你后面调参、排错时就不会抓瞎。

2. 部署前先弄懂 RAG：这套系统是怎么“读懂”你的文档的

2.1 为什么不直接把 PDF 甩给大模型

有人会问：大模型上下文窗口不是越来越大了吗，为什么不能把整本手册直接一次性塞给模型？

原因有三层。第一，模型没有“看过”你的私有文档，它只知道自己训练时见过的公开数据；你手上的内部手册它根本不知道。第二，就算你有办法把几十万字全部塞进上下文，当前的本地模型在长文本上依然会“迷失重点”——中间部分很容易被忽略，这是长上下文模型普遍存在的弱点。第三，成本不划算：把文档全文塞进去，每次提问都要重复处理一遍，太浪费算力。

RAG 的思路反过来：先把文档内容做预处理，建成一个可检索的索引；提问时只把最相关的几段内容提取出来喂给模型。相当于每次问人之前，先派一个检索员去资料室里翻出三页关键材料，再让专家根据这三页作答，而不是让专家把整栋楼的档案都背下来。

2.2 入库环节：切块、嵌入、向量化

PrivateGPT 处理一份 PDF 大约要经过这么几步：

1. 解析文本：从 PDF、Word、Markdown 等文件里抽取纯文本。这一步看起来简单，实际对扫描版 PDF 很头疼，那属于 OCR 范畴。
2. 切块：把长文本按固定长度切成小块，比如每 512 个 token 一块，块与块之间留一点重叠。为什么要重叠？因为如果恰好把一句话从中间切开，语义就断了，检索时容易漏掉关键内容。
3. 嵌入：把每个文本块丢给嵌入模型，转换成一串浮点数组成的向量。这个向量的巧妙之处在于：语义相近的句子，向量在空间里离得近；八竿子打不着的句子，向量离得远。
4. 入库：把向量和对应的文本块、来源页码、文件名一起存进向量数据库。默认用的是 Qdrant，数据落盘到local_data/private_gpt/qdrant。

一旦入库完成，文档就变成了一个“可检索的语义索引”。你以后提问，不需要再重新解析原始 PDF。

2.3 问答环节：检索增强生成的两步走

用户提问时，系统做的事也可以拆成两步：

• 第一步，检索：同样把问题转成向量，到向量库里找出最相似的几个文本块，一般默认取 4 个左右。这个检索用的是向量相似度计算，常见的是余弦相似度。
• 第二步，生成：把“检索到的文本块 + 用户问题 + 提示词模板”拼成一段上下文，交给大模型。模型在这个限定上下文中生成答案，并且可以附带指出答案来自哪一份文档的哪一页。

这就是“检索增强生成”的含义：不是让模型凭空答，而是先靠检索给它一本“开卷小抄”。它只能在开卷材料范围内回答，材料里没有的信息，它应该直接说不知道——当然，实际效果因模型而异，后面我会讲到它有时候也会嘴硬。

2.4 核心组件选型的逻辑

要跑通 PrivateGPT，你会遇到四个核心组件选型问题：

这里最容易被忽略的是嵌入模型。很多人把注意力全放在大模型上，觉得嵌入模型无所谓，结果中文文档配了个英文文本优化过的嵌入模型，检索效果差得离谱。如果文档以中文为主，建议优先考虑对中文支持较好的嵌入模型，比如 bge 系列或 text2vec 系列。实际上通过 Ollama 也能拉取nomic-embed-text这样的模型，效果在通用场景下够用，但遇到专业术语密集的中文资料时，还是值得多试一试不同嵌入模型。

我在实际项目中把“嵌入模型切换”当成调优的第一优先级，因为检索这一步错了，后面模型再好也白费。

3. 本地部署全记录：从空机器到第一次对话

3.1 硬件准备：内存决定下限，显卡决定体验

先说结论：想做纯 CPU 跑小模型，起步内存建议 16GB；想跑 7B-8B 级别模型并追求流畅体验，建议 NVIDIA 显卡显存 6GB 以上，内存 16GB 起步、32GB 更舒服。

我自己测试过的几档配置供参考：

如果你是重度用户，我的建议很直接：别在 CPU 上死扛。跑一次实验可以，真当工具用，GPU 带来的体验提升不是一点半点。另外，PrivateGPT 服务本身很轻，最耗资源的是 Ollama 里的 LLM 进程。

3.2 安装 Ollama 并拉取本地模型

新版 PrivateGPT 默认通过 Ollama 跑本地模型。Ollama 是个非常友好的本地模型运行器，官方支持 Windows、macOS、Linux，下载安装包后直接装，装完在终端里跑ollama serve就能启动服务。

我的建议顺序是：先装好 Ollama 并拉取模型，再装 PrivateGPT。否则 PrivateGPT 启动时找不到本地模型，你会误以为是 PrivateGPT 配置问题，实际是模型根本还没存在。

拉取模型就两条命令：

ollama pull llama3.1:8b ollama pull nomic-embed-text

第一个是对话用的大模型，第二个是嵌入模型。你也可以按需换成mistral:7b、qwen2.5:7b之类，但注意模型格式要写对。ollama list可以查看你本地已经有哪些模型，这个命令后面排错时会反复用到。

说到“ollama 离线安装包”，我的经验是：Ollama 本身有离线安装包，官网下载对应系统的安装文件拷到离线机器上装即可；但真正麻烦的是模型。模型在 Ollama 里不是“安装”，而是“拉取”，也就是下载一坨模型文件。离线环境下最简单的办法是：在能联网的机器上用ollama pull把模型拉好，然后找到 Ollama 的模型目录（Windows 一般在C:\Users\你的用户名\.ollama\models，Linux 在~/.ollama/models），把整个 models 目录打包拷贝到离线机器的相同位置。注意要保证用户路径一致或通过环境变量指定，否则 Ollama 找不到模型。

3.3 拉取 PrivateGPT 代码并完成配置

PrivateGPT 的安装流程网上教程很多，但版本差异特别大。老版本用 Python 脚本 + LangChain 管道，新版本则重构为 FastAPI 后端 + React 前端，配置文件和依赖方式都不一样。我建议直接拉取仓库最新版本：

git clone https://github.com/imartinez/PrivateGPT.git cd PrivateGPT

官方推荐用 Poetry 管理依赖。你如果不想装 Poetry，也可以用pip install -r requirements.txt，但版本锁的稳定性不如 Poetry。因为我踩过依赖冲突的坑，这里还是建议按官方文档来，用 Poetry 装：

poetry install

装完依赖后，关键一步来了：配置文件。新版仓库里的配置文件是settings.yaml，仓库一般会提供一个settings.yaml.example作为模板。你需要先复制一份：

cp settings.yaml.example settings.yaml

然后编辑里面的关键字段。我贴一个常见的、适合离线场景的配置（不同版本字段略有差异，以你拉取的版本实际模板为准）：

server: host: 127.0.0.1 port: 8000 llm: mode: ollama model: llama3.1:8b temperature: 0.1 embedding: mode: ollama model: nomic-embed-text vectorstore: database: qdrant qdrant: path: local_data/private_gpt/qdrant

有人会问了：为什么网上很多教程里写的是config.toml？这里说明一下：不同版本和不同二次开发分支的文件名不一样，老版本文档或者某些社区修改版确实会叫config.toml或settings.toml，而当前官方新版仓库用settings.yaml。无论文件名是什么，你要找的核心就是“配置文件模板 → 复制为正式配置 → 修改模型字段”这个过程。如果你照着某篇教程改了config.toml却启动失败，多半是版本对不上，先把文件命名拉回到你当前仓库实际约定的样子。

还有一个很重要的点：PrivateGPT 支持用环境变量覆盖配置。比如你用 Docker 部署时，可能通过PGPT_LLM_MODEL这类环境变量指定模型名，优先级高于配置文件。排错时如果改了配置文件没用，一定要想起来去检查环境变量。

3.4 启动服务、导入文档、验证问答

依赖和配置都搞定后，进入项目目录执行：

make run

这个命令会把后端 API 和前端界面一起拉起来。启动完成后，打开浏览器访问http://127.0.0.1:8000，就能看到 PrivateGPT 的网页界面。如果你不想用网页，直接用命令行调用 API 也行，新版提供了 OpenAI 兼容接口：

curl -X POST http://127.0.0.1:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "messages": [ {"role": "user", "content": "保修期内屏幕闪烁怎么处理？"} ] }'

首次提问前，先把文档导入。网页界面上通常有拖拽上传区，把 PDF 或 Markdown 文件拖进去，系统会自动完成解析、切块、嵌入、入库。文档数量多时，入库会花一些时间，这是正常现象。

我第一次跑通的时候时间不长，但过程中至少有三次想摔键盘。下面这一节，是我最想让你看到的部分——那些教程里不说、但你一定会遇到的坑。

4. 踩坑实录：配置文件失败、模型报错与离线安装连环倒霉

4.1 “配置文件加载失败”的完整排查链路

很多新手卡死在这类报错上：提示找不到配置文件，或“配置文件加载失败”，甚至直接告诉你某个 TOML/YAML 文件存在语法错误。这不是 PrivateGPT 独有的问题，离线部署类工具都这样。我建议按下面顺序排查：

第一步，确认文件名和版本。先去项目根目录看看到底有没有settings.yaml.example或config.toml.example之类的模板文件。有模板，就照着模板复制；没有模板，说明你拉到的分支和你看的教程不是一回事，直接看仓库 README，别硬套。

第二步，检查格式。YAML 和 TOML 都对缩进、引号、逗号敏感。多一个空格、少一个引号，解析器直接罢工。比如：

• TOML 里字符串必须加引号：model = "llama3.1:8b"，写成model = llama3.1:8b就会报错。
• YAML 里llm:下面的子项必须缩进对齐，用 Tab 还是空格都有讲究（推荐统一用两个空格）。

第三步，检查环境变量。如果你是通过 Docker 或服务管理工具启动的，配置文件可能本来就没被读取，或者配置项被环境变量覆盖了。命令行启动前可以先看一眼当前 shell 里有没有设置PGPT_*开头的变量：

env | grep PGPT

有输出的话，这些值会覆盖配置文件。调试时可以临时清掉：

unset PGPT_LLM_MODEL

再把服务拉起来。

第四步，检查字段名是否匹配当前版本。不同版本字段可能从model_name改成model，从ollama_base_url改成base_url。配置语法没错，但服务启动后才在运行时找不到属性，此时日志里通常有详细的异常栈，顺着异常栈定位到代码里的配置类，再回来看配置文件字段名，基本能对上。

4.2 “模型不被支持”这类报错怎么定位

热词里很多人搜“XX model is not supported”，这在我接触 PrivateGPT / Ollama 生态时也常遇到。这类报错的本质通常是：后端不知道你配置里写的那个模型是什么。

我用过最典型的场景是这样的：在 Ollama 里明明ollama list能看到llama3.1:8b，但 PrivateGPT 启动时却说模型不支持。排查方法：

1. 用ollama list看一下真实模型 ID。Ollama 的模型 ID 区分大小写和标签，比如你拉的是llama3.1，配置里写成llama3:8b，那显然找不到。
2. 确认 Ollama 服务在线。执行ollama list正常，不代表后台服务一定健康，直接访问http://127.0.0.1:11434/api/tags看有没有 JSON 返回。
3. 看 PrivateGPT 的版本。太老版本的 PrivateGPT 可能不认识新模型的某些标记符，尤其是带:latest这类标签时容易出问题。把 PrivateGPT 升级到最新版本，或者配置里写成完整且明确不带的标签（如llama3.1:8b）往往能解决。
4. 检查基础地址。如果配置里写了ollama_base_url或base_url，确认端口是 11434，而且没被防火墙拦掉。很多人把 Ollama 装在容器里，忘了把 11434 端口映射出来，结果 PrivateGPT 一直连不上，报错却五花八门。

这类错误几乎都是配置和后端不一致，不要一开始就怀疑代码有 bug，先排查模型是不是真的存在于 Ollama。

4.3 没网环境装依赖的三套方案

离线部署最常见的卡点不是 PrivateGPT 本身，而是 Python 依赖那几百个 wheel 包。没网的时候，你没法pip install，我的经验是三套方案混着用：

方案 A：提前下载 wheel 包再离线安装。在有外网的、和离线机相同操作系统架构的机器上执行：

pip download -r requirements.txt -d ./offline_pkgs

然后把offline_pkgs整个目录打包拷过去，目标机器上执行：

pip install --no-index --find-links ./offline_pkgs -r requirements.txt

这里有个坑：很多依赖包在下载时会做版本解析，你必须在和最终环境一致的系统上执行，否则会把 macOS 或某个发行版专用的包带过去，装不上反而更乱。

方案 B：Poetry 项目先导出 requirements。PrivateGPT 用 Poetry 的话，在联网机器上先：

poetry export -f requirements.txt -o requirements.txt

再走方案 A。

方案 C：模型文件整体拷贝。前面提过的 Ollama 模型目录直接拷贝。还有一个细节：模型拷过去后，要在离线机器上执行ollama list确认能识别，识别不了就检查目录权限和用户路径。千万别图省事只拷单文件，Ollama 的模型由多个层文件组成，目录结构必须完整。

关于 pip 下载慢的问题，我建议先检查公司内部有没有 PyPI 镜像或离线源。有的话配置index-url即可；没有的话老老实实用pip download方案，别在离线机上反复试装然后失败。

5. 实测点评：和 ChatGPT 比，它到底行不行

5.1 我用真实文档做的一次问答测试

为了写这部分，我拿一份 40 页的产品操作手册 PDF 和一份 30 多条的售后 FAQ Markdown 做了实测，环境是八核 CPU + 16GB 内存 + RTX 3060 12GB，模型用 Llama 3.1 8B，嵌入用 nomic-embed-text。

入库过程比想象中顺利，两份文档总共切成 200 多个文本块，耗时不到半分钟。我依次问了几个问题：

• “保修期内出现屏幕闪烁怎么办？”回答直接引用了 FAQ 第 3 条的处理步骤，包括先检查排线、再走售后流程，基本准确。
• “这台设备最大支持多大存储卡？”模型从规格表里检索到了参数，给出了正确的容量数字，而且我能在界面上看到它引用的来源页码。
• “总结一下手册里关于清洁保养的核心注意事项？”回答把四五个要点汇总得比较完整，虽然表述上不如在线大模型顺滑，但关键信息都在。
• “帮我写一首关于路由器的诗？”这个就明显露馅了。模型一本正经地生成了一段非常敷衍的押韵文字，质量明显不如在线大模型。

这个测试结果很有意思：越依赖文档内部事实的问题，PrivateGPT 表现越稳；越依赖模型自身知识储备和创造力的开放问题，它就越平庸。这正好印证了它的定位，它是一个“开卷考试”工具，不是全能选手。

5.2 能力边界：哪些地方明显不如 ChatGPT

把 PrivateGPT（本地 Ollama 模式）和在线 ChatGPT 放在一起比，还是一个很直观的表格：

差距最大的还是“通用知识丰富度”和“语言生成流畅度”。本地 8B 模型和在线顶级模型在推理深度、多轮对话连贯性上都有肉眼可见的差距。我见过一些朋友装了 PrivateGPT 后问了一堆日常问题，然后得出“这东西很笨”的结论。这其实是用错了场景——你应该问它关于你的文档的问题，而不是问它“黑洞是怎么形成的”。它读过的只有你给它的文件，训练时的世界知识有限。

5.3 什么样的项目适合用它，以及可以扩展的方向

基于上面的实测，我给出自己的判断标准：**如果你的核心诉求是“在我的文档上做可靠的、可溯源的问答”，而且数据不能出去，那么 PrivateGPT 是当前最值得试的路线之一。**尤其是下面这几种情况：

• 企业内部的知识管理系统，不想把资料传给任何第三方；
• 个人笔记、电子书、论文的语义检索，想用一种“和人对话”的方式来查；
• 需要在内网部署一个问答接口，给其他系统调用；
• 想完全掌控模型版本和数据存储，不接受任何订阅制的锁死。

扩展方向上，有几个我觉得性价比很高的思路：一是把嵌入模型换成更适配中文的版本，比如 bge-m3，检索质量提升明显；二是接入更大的模型，比如 14B 甚至 32B，只要显卡受得住，回答质量会显著提升；三是做多用户和权限控制，因为目前开箱体验基本是单机工具，企业级使用还得加一层鉴权；四是把入库流程脚本化，定时增量更新文档索引，而不是每次手动拖文件。

实际操刀下来，我的经验是：先跑通最小可用闭环，然后按“嵌入模型 → 切块参数 → 主模型”的顺序逐步调优。文档问答效果不好时，90% 的问题出在检索环节，而不是生成环节。先让检索准了，再说模型好不好。

最后再分享一点我的个人习惯：每次改配置之前，都会先存一份当前版本的配置文件备份，比如settings.yaml.bak.20250601。这个习惯救过我很多次，尤其是当你把某个参数改得“面目全非”之后，想回到能跑的状态却想不起原始值的时候，你会感谢这个备份的。另外，首次跑通后建议先用少量样例文档做实验，不要一上来就灌几百个 PDF，那样出问题后你会分不清到底是文档解析问题、检索问题还是模型问题。小步快跑，一步一步来，这套工具才能真正变成你手边可靠的生产力。