企业官网建设流程全解析

1. 为什么企业需要一个“会说话”的知识库

1.1 从“翻文档”到“问问题”的转变

我在过去几年帮不少团队做过内部知识管理，最常见的场景就是：新同事入职，想查一个报销流程，翻了三四个共享文件夹，最后在某个两年前的邮件附件里找到一份已经过期的PDF。老员工也好不到哪去，产品文档、技术方案、会议纪要散落在各个协作工具里，真正要用的时候，搜索出来的结果要么不相关，要么版本对不上。

传统知识库的本质是“文件柜”，你得知道文件放在哪一格，才能找到它。而大语言模型驱动的知识库，本质是“懂业务的同事”，你直接用自然语言问它，它去把散落各处的资料翻出来，读懂，然后用一段通顺的话回答你。这中间的差别，就是检索增强生成（RAG，Retrieval-Augmented Generation）带来的。

WeKnora 就是腾讯开源出来的一套企业知识库搭建框架，它把文档解析、向量化、检索、大模型问答这一整条链路打包好了，你不需要从零去拼 LangChain 的各个组件，也不用自己调 Milvus 或者 pgvector 的连接池。说得直白一点，它解决的是“我有一堆文档，我想让大模型基于这些文档回答问题，但我不想花三个月造轮子”这个问题。

这篇文章适合谁看？如果你是后端开发、运维、技术负责人，或者只是对 RAG 感兴趣想动手跑一个 demo 的人，都能跟着走下来。我会从架构思路讲到部署实操，再到踩坑记录，尽量把每一步的“为什么”说清楚。

1.2 WeKnora 在整个 RAG 生态里的位置

RAG 这个概念这两年火得不行，但真正落地的时候，大家会发现它不是一个单一技术，而是一条流水线。这条流水线上有文档加载器、文本切块器、嵌入模型、向量数据库、检索器、重排序器、大模型接口，每一环都有无数选择。LangChain 和 LangGraph 提供了编排能力，pgvector 和 Milvus 提供了向量存储，但把这些东西串起来并且调到一个可用的状态，工作量并不小。

WeKnora 的定位是“开箱即用的企业知识库方案”。它基于 FastAPI 做服务层，用 LangChain 和 LangGraph 做流程编排，底层向量存储支持 pgvector 这类方案，前端也给了可交互的界面。你可以把它理解成一个已经组装好的 RAG 应用骨架，你只需要把文档喂进去，配置好模型接口，它就能跑起来回答问题。

和纯框架相比，它的优势在于省去了大量胶水代码；和纯 SaaS 产品相比，它的优势在于可以本地部署，数据不出内网，这对很多企业来说是硬性要求。热词里提到的“docker 部署 weknora”“本地部署大语言模型”其实都指向同一个诉求：可控、可私有化。

2. 动手之前：把架构和依赖理清楚

2.1 核心组件拆解与选型逻辑

在真正敲命令之前，我习惯先把一个项目的组件图在脑子里过一遍，这样出问题的时候知道该去哪个环节排查。WeKnora 的链路大致是这样的：

• 文档接入层：负责接收上传的 PDF、Word、Markdown、TXT 等文件，做格式解析和文本抽取。
• 切块与向量化层：把长文本切成合适大小的片段，调用嵌入模型转成向量。
• 向量存储层：把向量和原文的映射关系存进数据库，供后续检索。
• 检索与重排层：用户提问时，先把问题向量化，去库里找最相似的片段，必要时做重排序。
• 生成层：把检索到的片段作为上下文，拼进提示词，交给大语言模型生成回答。
• 服务与界面层：FastAPI 提供接口，前端提供问答界面和知识库管理界面。

为什么切块这一步这么关键？因为大模型的上下文窗口是有限的，你不可能把一整本产品手册塞进去。切块就是把文档切成一段段“语义相对完整”的小块，每块单独向量化。切得太碎，语义丢失，检索出来的片段答非所问；切得太粗，一块里混了好几个主题，检索精度下降。常见的做法是按字符数切，比如 500 到 1000 字符一块，块与块之间留一点重叠，避免一句话被硬生生切断。

向量数据库的选择上，pgvector 的好处是你如果本来就在用 PostgreSQL，不需要额外引入一套数据库，运维成本低。Milvus 则在超大规模向量检索上更有优势。WeKnora 支持多种后端，具体用哪个取决于你的数据量和现有技术栈。

2.2 环境准备与依赖清单

部署之前，先把环境盘清楚。我一般会列一个清单，逐项确认，避免装到一半发现缺东西。

这里有个容易被忽略的点：如果你打算用本地大语言模型而不是调云端 API，那显存和内存的需求会陡增。一个 7B 参数的模型，量化后大概需要 6 到 8GB 显存；13B 的话就要 12GB 以上。如果机器没有独立显卡，用 CPU 推理会非常慢，体验很差。所以我的建议是，初期验证阶段先用云端大模型 API，把流程跑通，等确认价值之后再考虑本地化。

提示：部署前务必确认 Docker 的镜像加速配置是否可用，否则拉取镜像会很慢。另外检查服务器时间是否同步，时间偏差过大会导致某些鉴权失败。

3. 从零部署：一步步把服务跑起来

3.1 获取代码与目录结构说明

第一步是把项目代码拉到本地。WeKnora 是开源项目，你可以直接从官方仓库克隆。拉下来之后，先别急着启动，花两分钟看一下目录结构，这对后面排查问题很有帮助。

git clone <项目仓库地址> cd weknora ls -la

典型的目录里会有这么几块：docker目录放的是容器编排文件，backend是 FastAPI 服务端代码，frontend是前端界面，config或者.env.example是配置模板。我习惯先把配置文件复制一份，改成自己的，而不是直接改模板，这样后面升级不会冲突。

cp .env.example .env

打开.env文件，你会看到一堆配置项。别被吓到，初期只需要关注几个核心的：数据库连接、向量库类型、大模型接口地址和密钥、嵌入模型配置。其他的保持默认即可。

3.2 配置文件的关键参数怎么填

配置这块是最容易出错的地方，我逐个说清楚。

数据库配置：如果你用 Docker Compose 起 PostgreSQL，主机名就填服务名，比如postgres，而不是localhost。这是新手最常踩的坑，因为在容器里localhost指的是容器自己，不是宿主机。

向量库配置：选择 pgvector 的话，需要确保 PostgreSQL 装了 pgvector 扩展。Docker 镜像一般会预装，但如果你用的是已有的数据库，得手动执行CREATE EXTENSION vector;。

大模型配置：这里分两种情况。用云端 API 的话，填好 base_url 和 api_key 就行。用本地模型的话，需要先起一个兼容 OpenAI 接口的推理服务，比如用 vLLM 或者 Ollama，然后把 base_url 指向那个服务。

嵌入模型配置：嵌入模型负责把文本转成向量，它和大语言模型是两回事。嵌入模型一般用 BGE、M3E 这类专门做检索的模型。注意，嵌入模型的维度必须和向量库的维度对上，比如 BGE-large 是 1024 维，你在建表的时候就要用 1024 维，否则插入数据会报错。

# 示例：关键配置项 DATABASE_URL=postgresql://user:password@postgres:5432/weknora VECTOR_STORE_TYPE=pgvector LLM_BASE_URL=https://api.example.com/v1 LLM_API_KEY=your_key_here EMBEDDING_MODEL=BAAI/bge-large-zh-v1.5 EMBEDDING_DIMENSION=1024

注意：API 密钥这类敏感信息不要提交到代码仓库，用环境变量或者密钥管理服务注入。我见过有人把密钥硬编码进代码然后推到公开仓库，结果被扫到盗刷，损失不小。

3.3 启动服务与验证

配置填好之后，就可以启动了。用 Docker Compose 的话，一条命令搞定。

docker compose up -d

-d是后台运行。启动之后用docker compose ps看一下各个容器的状态，确认都是running或者healthy。如果有容器反复重启，用docker compose logs <服务名>看日志。

服务起来之后，访问前端界面，一般是http://服务器IP:端口。第一次进去需要注册管理员账号。热词里有人问“weknora知识库修改注册名字”，其实就是指这个初始账号的设置，进去之后在用户管理里改就行。

验证服务是否正常，我一般分三步：先看前端能不能打开，再上传一个小文档测试解析，最后提一个问题看能不能返回答案。这三步都过了，说明主链路是通的。

4. 让知识库真正“会说话”：数据接入与调优

4.1 文档上传与解析的实操细节

服务跑起来只是第一步，真正决定体验的是数据质量。我见过太多人兴冲冲传了一堆文档，结果问答效果一塌糊涂，问题往往出在文档本身。

首先，扫描版的 PDF 是没法直接解析的，因为它本质是图片，需要 OCR。WeKnora 的解析能力取决于它集成的解析器，如果文档是扫描件，你得先做 OCR 处理，或者确认框架是否支持 OCR。其次，格式混乱的 Word 文档，比如大量用文本框、艺术字排版的，解析出来会丢内容。我的经验是，尽量用结构清晰的 Markdown 或者纯文本作为知识源，效果最稳定。

上传的时候注意文件大小限制，太大的文件解析会超时。如果一份文档有几百页，建议先拆成几个小文件再传。另外，上传后要检查解析结果，看看文本有没有乱码、有没有把表格内容搞乱。这一步花几分钟，能省后面大量调试时间。

4.2 切块策略与检索效果的关系

切块参数是影响检索质量的核心变量，但很多人直接用默认值，从不调整。我建议你根据文档类型来定。

对于技术文档、产品手册这类结构清晰的，按标题层级切块效果最好，每个小节一块，语义完整。对于会议纪要、聊天记录这类口语化的，按固定字符数切，比如 500 字符，重叠 50 字符。重叠的作用是防止关键信息正好落在切割边界上被切断。

检索的时候，还有一个参数叫 top_k，就是返回最相似的几个片段。设太小，可能漏掉关键信息；设太大，会引入无关内容干扰大模型。一般从 3 到 5 开始试，根据回答质量调整。如果发现回答经常缺信息，就调大；如果回答经常跑题，就调小或者加一个相似度阈值过滤。

4.3 提示词工程：让回答更贴合业务

检索到的内容怎么交给大模型，提示词怎么写，直接决定回答的风格和准确度。默认的提示词通常是“根据以下上下文回答问题”，但企业场景往往有更细的要求。

比如客服场景，你希望回答礼貌、简洁、不瞎编；技术场景，你希望回答准确、带出处、能给出操作步骤。这些都可以通过提示词来约束。我一般会在提示词里加几条硬性规则：只根据提供的上下文回答，上下文没有的信息就说“暂无相关信息”，不要自己编；回答时尽量引用来源文档的名称。

还有一个技巧是让模型在回答里标注引用，比如“根据《XX操作手册》第3节”，这样用户能追溯，信任度更高。WeKnora 的流程编排基于 LangGraph，提示词模板一般可以在配置或者代码里找到，改起来不难。

5. 踩坑实录与常见问题排查

5.1 部署阶段的典型报错

部署阶段的问题，八成集中在网络和配置上。我整理了几个高频的。

容器起不来，日志显示数据库连接失败：先确认数据库容器是否健康，再看连接字符串里的主机名是不是服务名。如果数据库还没初始化完，应用就急着连，也会失败，加个健康检查或者重启一下应用容器通常能解决。

拉取镜像超时：这是网络问题，配置镜像加速或者换网络环境。如果公司网络有代理，记得给 Docker 也配上。

端口冲突：默认端口被占用，改.env里的端口映射就行。用netstat -tlnp看哪个进程占了端口。

pgvector 扩展缺失：报错里会出现type "vector" does not exist，进数据库执行CREATE EXTENSION IF NOT EXISTS vector;即可。

5.2 问答效果差的排查思路

效果问题比部署问题更磨人，因为它没有明确的报错。我的排查顺序是这样的：

先看检索环节。把用户的问题拿去检索，看返回的片段是不是真的相关。如果不相关，问题出在嵌入模型或者切块上。换个更强的嵌入模型，或者调整切块策略。如果相关，但回答还是不对，那问题出在生成环节，检查提示词和大模型本身的能力。

再看向量维度是否匹配。嵌入模型换了但没重建索引，会导致检索结果完全错乱。换嵌入模型一定要重新向量化所有文档。

还有一种情况是文档本身就没有答案，模型只能瞎编或者拒答。这时候要补充知识源，而不是调参数。

5.3 性能与成本优化经验

跑通之后，下一步就是让它跑得又快又省。检索这块，给向量字段建索引能大幅提升查询速度，pgvector 支持 IVFFlat 和 HNSW 两种索引，数据量大的话建议用 HNSW，查询快但建索引慢、占内存多。

大模型调用是成本大头。如果问答量不大，用云端 API 按量付费更划算；如果量大且数据敏感，本地部署虽然前期投入高，但长期看单次成本低。还有一个省钱的技巧是缓存，相同或相似的问题直接返回缓存结果，不用每次都走完整链路。

嵌入模型的计算也可以优化，文档向量化是一次性的，做完就存库了，但用户提问每次都要向量化，这部分开销相对小。如果并发高，可以考虑把嵌入服务单独部署，做水平扩展。

6. 后续扩展的一些想法

跑通基础版本之后，能做的事情还有很多。比如接入企业现有的账号体系做单点登录，把知识库嵌进内部办公工具，或者加一个反馈按钮让用户对回答打分，用这些数据持续优化检索和提示词。

多轮对话也是很多人的需求。基础版一般是无状态的单轮问答，要做多轮，需要在流程里维护对话历史，把之前的问答也作为上下文传进去。但要注意，历史太长会挤占上下文窗口，需要做摘要或者截断。

还有一个方向是权限控制。企业知识库往往不是所有人都能看所有文档，需要按部门、角色做检索过滤。这要求在向量库里给每个片段打上权限标签，检索时带上过滤条件。这块实现起来有一定复杂度，但对企业场景是刚需。

我自己在实际操作中的体会是，RAG 项目的成败，七分在数据，两分在检索调优，一分在模型选择。很多人一上来就纠结用哪个大模型，其实先把文档整理干净、切块调好，效果提升比换模型明显得多。另外，别指望一次调到位，上线后持续收集 bad case，针对性优化，才是正道。