企业官网建设流程全解析

我把这套系统从拉代码到真正跑通问答，完整走了一遍。整个过程踩了不少坑，也摸索出一些值得记录的调优细节。这篇文章会把部署思路、关键配置、模型选型和常见问题一次性讲清楚，给准备自建知识库问答系统的朋友当个参考。

1. 项目概述与核心价值拆解

1.1 WeKnora是什么，解决的到底是什么问题

WeKnora是腾讯微信团队开源的一款AI知识库平台，定位很明确：把散落在文档、网页、表格里的企业知识，通过RAG（检索增强生成）的方式接入大模型，让用户用自然语言提问，系统自动检索相关资料并生成回答。

先说一个实际感受：现在很多团队用大模型的方式还是“直接聊天”。但通用大模型回答的是“它训练时学到的知识”，拿不到你公司内部的制度文档、产品手册、项目复盘。WeKnora解决的就是这个断层——它把内部文档变成大模型可检索的知识源，让回答有据可依。

和同类开源项目（如Dify、FastGPT、MaxKB）相比，WeKnora有几个差异点：一是腾讯内部业务场景磨出来的产品，对中文文档的解析和检索做了针对性优化；二是插件机制灵活，支持接入Ollama、DeepSeek、OpenAI兼容接口等多种模型渠道；三是自带权限管理和分享能力，适合团队协作使用。整体下来，它更像一个“企业级知识库问答底座”，而不是单纯的Demo项目。

1.2 为什么选择本地部署而不是直接上云

这个问题我在选型时纠结了一阵。直接原因有三个：

第一，知识库内容敏感。很多项目文档、产品方案涉及内部信息，传到云端SaaS服务，总归多一层合规风险。本地部署后数据完全落在自己服务器上，这一点对企业和个人都很重要。

第二，长期使用成本。SaaS知识库通常按用户数、文档量、问答次数多维计费，团队几十号人高频使用，一个月开销不小。本地部署一次性投入硬件，之后基本只有电费和模型调用成本。

第三，模型可控性。本地部署可以自由切换接入的模型，今天用Ollama跑的Qwen，明天换DeepSeek的API，后天想试新的开源模型，改配置就行，不受平台限制。API上下行数据也更可控。

当然，本地部署也有门槛，最大的门槛是硬件和运维。这篇文后面会详细算一笔账。

1.3 适合谁来用，应用场景有哪些

我把这套系统的典型使用场景列一下，大家可以对照自己的情况：

• 企业内部知识库：让新员工通过问答快速了解制度流程，不用翻几百页PDF。这是最典型的使用场景。
• 个人知识管理：把读书笔记、技术文档、过往项目资料统一放进知识库，写总结或回忆技术细节时直接问，比自己翻文件夹高效得多。
• 客服辅助系统：导入产品FAQ、售后手册，客服人员回答用户问题时，秒查标准答复。
• 教学与培训：把课件、教材导入知识库，学员可以随时提问，相当于配了个24小时答疑助手。

一句话总结：凡是有“大量文档 + 高频查找 + 自然语言提问”需求的场景，这套系统都值得部署试用。

2. 部署前的技术选型与环境准备

2.1 硬件要求算一笔账

很多人被“本地部署大模型”这几个字吓到，以为必须4张A100。实际看你怎么规划。WeKnora本身对硬件要求不高，真正吃资源的是你接入的大模型。我按三种方案算了下：

我自己用的是中间档：一台32GB内存的机器，GPU是RTX 4060 Ti 16GB，跑Qwen2.5-7B-Instruct量化版配合Ollama，效果足够日常使用。如果完全没GPU，用CPU跑7B模型也能出结果，就是速度慢一些，大概10秒到1分钟不等，按文档分块大小而定。

存储方面，文档本身占不了太多空间，但向量化后的索引数据会膨胀，建议预留100GB以上磁盘空间。

2.2 大模型与嵌入模型怎么搭配

很多初次用RAG的朋友会把“生成模型”和“嵌入模型”搞混。这里先明确：这两个是不同的东西，各司其职。

生成模型负责“根据检索到的资料生成回答”，是回答质量的核心。WeKnora支持OpenAI兼容接口，所以可以接入任何提供此类接口的服务，包括Ollama本地模型、DeepSeek、腾讯混元、MiniMax等。

**嵌入模型（Embedding模型）**负责把文档切成小块后转成向量，用户提问时也转成向量，然后用向量相似度匹配。它决定了检索的准确性，这个选不好，生成模型再强也白搭。

对于中文知识库，我实测下来比较推荐的组合是：

2.3 部署方式：Docker Compose是首选

WeKnora官方提供两种部署方式：源码编译和Docker Compose。我强烈建议首次部署用Docker Compose。

为什么？WeKnora依赖的组件不少——后端服务、前端页面、向量数据库、对象存储，这些要是手动一个个部署，光是环境依赖就能折腾一整天。Docker Compose把这一整套打包成编排文件，一条命令拉起所有服务，省时省力。源码编译更适合二次开发的场景。

另外准备一下：需要安装好Docker和Docker Compose插件，最好是Docker 20.10以上版本。我用的是Ubuntu 22.04系统，以下部署过程都以这个环境为例。

3. 本地部署实操全流程

3.1 拉取项目与目录规划

部署的第一步是获取代码。WeKnora的源码在GitHub上，项目名为weknora。拉下来后，先看目录结构，重点看docker-compose.yml和服务配置目录。

git clone https://github.com/weknora/weknora.git cd weknora ls -la

项目结构大致如下：

weknora/ ├── docker-compose.yml # 容器编排文件 ├── .env.example # 环境变量模板 ├── config/ # 服务配置文件 ├── docker/ # Dockerfile与初始化脚本 ├── modules/ # 源码模块（供二次开发） └── README.md

这里有个容易犯的错：直接复制.env.example为.env，不做任何修改就启动。其实需要修改的部分不少，后面一节细说。

建议先建一个数据目录，用于存放向量数据库的数据和上传文档，这样升级容器时数据不会丢。

mkdir -p /data/weknora/{elasticsearch,minio,uploads}

3.2 环境变量与关键配置详解

打开.env文件，重点配置以下几项：

基础配置

# 服务端口 SERVER_PORT=8080 # 管理员初始账号 ADMIN_USERNAME=admin ADMIN_PASSWORD=your_strong_password # 数据库配置（如果使用自带PostgreSQL） POSTGRES_PASSWORD=change_me

模型服务配置

这是最关键的部分，决定了系统怎么连上你的大模型和嵌入模型：

# 大模型服务地址与密钥（OpenAI兼容格式） LLM_BASE_URL=http://host.docker.internal:11434/v1 LLM_API_KEY=ollama # Ollama本地模式随便填 LLM_MODEL=qwen2.5:7b # 嵌入模型服务地址 EMBEDDING_BASE_URL=http://host.docker.internal:11434/v1 EMBEDDING_API_KEY=ollama EMBEDDING_MODEL=bge-m3

这里有个细节：容器内部访问宿主机的服务，要用host.docker.internal，而不是localhost或127.0.0.1。如果部署在同一台机器上的Ollama，这个地址是必须的。如果模型跑在另一台机器上，就填那台机器的局域网IP。

存储与检索配置

WeKnora支持多种向量检索方案，我用的Elasticsearch方案，稳定性好、资料多，遇到问题也好查。

# Elasticsearch配置 ES_HOST=elasticsearch ES_PORT=9200 ES_USERNAME=elastic ES_PASSWORD=change_me

改完配置后，执行docker compose up -d启动服务。

3.3 服务启动与页面登录

docker compose up -d

第一次启动会拉取镜像，速度取决于网络情况。镜像较大，建议预留10分钟以上时间。启动完成后，用docker compose ps查看容器状态，看到各服务都是running状态就说明启动成功。

访问http://服务器IP:8080，用刚配置的管理员账号登录。登录后第一步是修改密码，这是基本安全意识，不用多说。

进入系统后，先别急着传文档。我建议先到“模型设置”页面检查一下模型连通性。WeKnora通常有测试模型连接的功能，点击测试，如果显示连通成功，说明模型配置没问题，否则检查Ollama是否启动、模型是否已拉取到本地。

到这里，Core系统已经跑起来。接下来最花时间的是知识库构建和问答调优。

4. 知识库构建与问答系统调优

4.1 创建知识库与上传文档

进入“知识库”页面，点击新建知识库，填写名称和描述。这里有几个关键选项需要理解：

文档分块策略：系统会把文档切成小块，每块大小直接影响检索精度。块太大，检索出来的内容包含太多无关信息；块太小，语义完整性受损。我实测下来，默认参数通常够用，但中文场景建议适当调小，一般在256到512个token之间比较合适。因为中文信息密度高，同样长度下包含的意思比英文多，所以块小一点反而精确。

分块重叠：相邻分块之间保留一定重叠，避免语义断层。默认值通常是15%，追求精确匹配时可以降到10%。

上传文档时，WeKnora支持PDF、Word、Markdown、TXT、HTML等常见格式。这里要提醒一句：扫描版PDF必须先做OCR，否则知识库索引的都是图片内容，问答时找不到有效信息。我处理这类文件会用一些开源OCR工具先转成可检索文本，再上传。

特别注意：上传前检查文档中的页眉页脚、目录页、空白页，这些噪声会直接影响分块质量，进而拉低检索准确率。建议用开源文档清洗工具预处理一下。

4.2 检索引擎与Embedding的正确姿势

支撑检索效果的核心是Embedding。BGE-M3这个模型，我实测在中文场景下表现稳定，能处理中英混合文档，而且对长文本的支持好。首次上传文档时，系统会对文档进行向量化，这个阶段会比较慢，文档多的话耐心等待即可。

文档向量化完成后，可以在检索测试页面测试问答效果。输入一个问题，系统会展示检索到了哪些文档块，并标注相似度评分。这一步很有价值：如果返回的文档块不相关，说明Embedding配置或分块策略有问题，趁早调整，不要等问答效果出来再返工。

实际调优经验：不同知识库，最优分块大小并不一致。代码仓库类文档适合分块小，精确到函数级别；制度文档、流程说明适合分块略大，保留完整上下文。调优时不要嫌麻烦，多试几组参数，每组测试几十个典型问题，看召回准确率，不是越精细越好，是匹配你的内容形态才是最好。

4.3 提示词工程与回答风格调优

WeKnora允许自定义提示词模板。很多人忽略这个功能，直接用系统默认，回答质量打了折扣。

我常用的提示词结构是：

你是公司内部的智能助手。请根据以下资料回答问题。 要求： 1. 优先引用资料中的原文信息，不要自行编造。 2. 如果资料中没有相关信息，明确回答“资料中未找到相关内容”，不要硬答。 3. 回答语言简洁、逻辑清晰，使用与问题相同的语言回复。 4. 涉及多个要点时，分点列出。 资料： {context} 问题： {question}

注意{context}和{question}这两个变量是系统注入的，别改动。其中“找不到就直说”这一条非常重要——RAG系统最怕的就是模型瞎编，宁可不答，也不要胡编。实测加上这句话后，回答准确率提升明显，胡编乱造的情况大幅减少。

另外，如果硬件条件允许，建议用长上下文模型增强多轮对话记忆，让追问体验更好。7B模型在长对话时容易“忘”前面的内容，是我的真实体会。

5. 常见问题与排查经验实录

5.1 部署阶段高频问题

最值得展开的是模型超时问题。这问题非常典型——Ollama默认监听127.0.0.1，容器内根本访问不到你宿主机上跑的服务。解决方法是设置Ollama监听所有网卡：

# 设置环境变量后重启Ollama export OLLAMA_HOST=0.0.0.0

这个坑我印象很深，第一次部署光是排查这个问题就花了近半小时，因为页面报错信息比较模糊，只提示“模型连接失败”，得一步步查日志才最终定位。

5.2 问答阶段常见质量问题

温度参数（Temperature）这块值得多说一句。这是RAG问答最不该忽略、却最容易被忽略的参数。温度过高，模型回答发散，容易跑偏；温度过低，回答机械，缺乏组织性。我的经验是：知识库问答场景，温度设置在0.1到0.3之间比较合适，具体值根据你的模型微调。设置后同样的问题多测几遍，观察回答的一致性和合理性。

5.3 性能优化心得

用了两周后，我做了几项优化，效果明显：

检索层面：启用混合检索模式——同时使用向量检索和关键词检索，加权融合排序。纯向量检索对同义改写友好，但专有名词和编号类信息容易丢失；关键词检索正好补上这个短板，保证精确命中。这一项优化，让我的文档检索准确率提升不少。

模型层面：Qwen2.5-7B用Ollama跑时，设置OLLAMA_NUM_PARALLEL=4，允许多个请求并行处理，多人同时使用时排队时间明显减少。同时开启OLLAMA_KEEP_ALIVE，避免频繁重新加载模型到内存。

文档层面：持续维护——定期清理过期文档，更新新版本资料，删掉无用文件。知识库和代码仓库一样，也是需要持续维护更新的。这个点容易被忽略，却影响长期使用体验。

6. 扩展与进阶玩法

6.1 接入更多模型与插件体系

WeKnora支持OpenAI兼容协议，所以凡是提供这类接口的模型服务都能接。我在本地测试过几种搭配：

实际使用中，我是把本地Qwen作为默认模型，DeepSeek作为备用模型——遇到复杂问题或本地模型答得不好时，临时切换API模型。这个“本地为主、云端兜底”的混合方案，兼顾了数据安全和回答质量。

另外WeKnora有插件机制，支持扩展解析器、预处理器等能力。我在生产环境加过自定义文档解析插件，用来处理特定格式的业务报表。这块的扩展空间很大，适合有定制需求的团队研究。

6.2 权限管理与团队协作

如果团队多人使用，建议启用权限分组。WeKnora的权限管理可以做到：不同用户组看不同知识库，管理员统一配置模型权限，普通用户只能提问不能修改配置。多人协作时，这个能力能把“问答平台”变成“团队内部系统”。

同时建议开启审计日志，记录谁在什么时候问了什么问题、回答了什么、引用了哪些文档。后续排查问题时，这个日志能发挥很大作用。我知道很多人不爱开，但真遇到回答内容有问题的时候，没有日志就只能靠猜了。

6.3 数据备份与迁移

本地部署要面对的终极问题是：数据丢了怎么办。我的备份策略是每天夜里对数据目录做增量备份：

# 使用rsync做增量备份 rsync -avz /data/weknora/ /backup/weknora/

主要备份三个东西：Elasticsearch里的向量索引、PostgreSQL里的元数据、MinIO里的源文档。有了这三样，整套系统就能完整恢复。建议设定为定时任务，别等出问题才想备份这回事。

迁移到新服务器时，直接停服务、拷贝数据目录、启动新环境三步搞定，比重新部署省时间得多。

最后说几句实践体会

这套系统跑下来，我的核心感受是：WeKnora的部署难度，在同类开源知识库项目里属于中等偏下，Docker Compose一拉起来，环境基本就齐了。真正花时间的是知识库的构建和调优——模型选型、分块策略、提示词设计、温度参数，每一项都需要针对你的资料类型做适配，没有一套参数能通吃所有场景。

最开始我给知识库塞了一堆格式混乱、目录乱飞的旧文档，问答效果可想而知，检索经常命中无关内容。后来花时间做了文档清洗，重新调整分块参数和提示词，效果才真正立起来。所以我把这个经历写下来，劝各位部署前优先把文档整理好，这一步做扎实了，后面能省大量调优的精力。

硬件的选择上，还是建议在能力范围内配置好一点的GPU，24GB显存跑中大型量化模型，和8GB显存跑小模型，回答质量差距是实打实的。

如果你们团队正好在选型阶段，Deciding从WeKnora起步是个不错的折中选择：数据可控、二次开发空间大、社区也比较活跃。我自己用完最大的感觉是，以后新项目、新文档进来，不再是能问不能查的状态了。整套系统，能为后续的自动化办公场景做不少基础能力支撑。