1. 为什么企业需要一个“会说话”的知识库1.1 从“翻文档”到“问问题”的转变我在过去几年帮不少团队做过内部知识管理最常见的场景就是新同事入职想查一个报销流程翻了三四个共享文件夹最后在某个两年前的邮件附件里找到一份已经过期的PDF。老员工也好不到哪去产品文档、技术方案、会议纪要散落在各个协作工具里真正要用的时候搜索出来的结果要么不相关要么版本对不上。传统知识库的本质是“文件柜”你得知道文件放在哪一格才能找到它。而大语言模型驱动的知识库本质是“懂业务的同事”你直接用自然语言问它它去把散落各处的资料翻出来读懂然后用一段通顺的话回答你。这中间的差别就是检索增强生成RAGRetrieval-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 环境准备与依赖清单部署之前先把环境盘清楚。我一般会列一个清单逐项确认避免装到一半发现缺东西。依赖项建议版本说明操作系统Linux (Ubuntu 20.04)生产环境首选Windows 建议用 WSL2Docker20.10容器化部署的基础Docker Composev2多容器编排Python3.10如果走源码部署需要PostgreSQL14带 pgvector 扩展内存16GB含本地模型时建议 32GB磁盘50GB取决于文档量和模型大小这里有个容易被忽略的点如果你打算用本地大语言模型而不是调云端 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_URLpostgresql://user:passwordpostgres:5432/weknora VECTOR_STORE_TYPEpgvector LLM_BASE_URLhttps://api.example.com/v1 LLM_API_KEYyour_key_here EMBEDDING_MODELBAAI/bge-large-zh-v1.5 EMBEDDING_DIMENSION1024注意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 开始试根据回答质量调整。如果发现回答经常缺信息就调大如果回答经常跑题就调小或者加一个相似度阈值过滤。文档类型切块方式块大小重叠top_k技术手册按标题按节无3会议纪要固定字符500505问答对按条单条无3长篇文章固定字符80010044.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 问答效果差的排查思路效果问题比部署问题更磨人因为它没有明确的报错。我的排查顺序是这样的先看检索环节。把用户的问题拿去检索看返回的片段是不是真的相关。如果不相关问题出在嵌入模型或者切块上。换个更强的嵌入模型或者调整切块策略。如果相关但回答还是不对那问题出在生成环节检查提示词和大模型本身的能力。再看向量维度是否匹配。嵌入模型换了但没重建索引会导致检索结果完全错乱。换嵌入模型一定要重新向量化所有文档。还有一种情况是文档本身就没有答案模型只能瞎编或者拒答。这时候要补充知识源而不是调参数。现象可能原因解决方向检索结果不相关切块太碎/嵌入模型弱调整切块换嵌入模型回答缺信息top_k 太小调大 top_k回答跑题上下文噪声多加相似度阈值调小 top_k回答编造提示词约束不足强化提示词要求无据不答换模型后全乱向量维度不匹配重建索引重新向量化5.3 性能与成本优化经验跑通之后下一步就是让它跑得又快又省。检索这块给向量字段建索引能大幅提升查询速度pgvector 支持 IVFFlat 和 HNSW 两种索引数据量大的话建议用 HNSW查询快但建索引慢、占内存多。大模型调用是成本大头。如果问答量不大用云端 API 按量付费更划算如果量大且数据敏感本地部署虽然前期投入高但长期看单次成本低。还有一个省钱的技巧是缓存相同或相似的问题直接返回缓存结果不用每次都走完整链路。嵌入模型的计算也可以优化文档向量化是一次性的做完就存库了但用户提问每次都要向量化这部分开销相对小。如果并发高可以考虑把嵌入服务单独部署做水平扩展。6. 后续扩展的一些想法跑通基础版本之后能做的事情还有很多。比如接入企业现有的账号体系做单点登录把知识库嵌进内部办公工具或者加一个反馈按钮让用户对回答打分用这些数据持续优化检索和提示词。多轮对话也是很多人的需求。基础版一般是无状态的单轮问答要做多轮需要在流程里维护对话历史把之前的问答也作为上下文传进去。但要注意历史太长会挤占上下文窗口需要做摘要或者截断。还有一个方向是权限控制。企业知识库往往不是所有人都能看所有文档需要按部门、角色做检索过滤。这要求在向量库里给每个片段打上权限标签检索时带上过滤条件。这块实现起来有一定复杂度但对企业场景是刚需。我自己在实际操作中的体会是RAG 项目的成败七分在数据两分在检索调优一分在模型选择。很多人一上来就纠结用哪个大模型其实先把文档整理干净、切块调好效果提升比换模型明显得多。另外别指望一次调到位上线后持续收集 bad case针对性优化才是正道。 腾讯开源WeKnora企业知识库：RAG架构解析与Docker部署实战
1. 为什么企业需要一个“会说话”的知识库1.1 从“翻文档”到“问问题”的转变我在过去几年帮不少团队做过内部知识管理最常见的场景就是新同事入职想查一个报销流程翻了三四个共享文件夹最后在某个两年前的邮件附件里找到一份已经过期的PDF。老员工也好不到哪去产品文档、技术方案、会议纪要散落在各个协作工具里真正要用的时候搜索出来的结果要么不相关要么版本对不上。传统知识库的本质是“文件柜”你得知道文件放在哪一格才能找到它。而大语言模型驱动的知识库本质是“懂业务的同事”你直接用自然语言问它它去把散落各处的资料翻出来读懂然后用一段通顺的话回答你。这中间的差别就是检索增强生成RAGRetrieval-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 环境准备与依赖清单部署之前先把环境盘清楚。我一般会列一个清单逐项确认避免装到一半发现缺东西。依赖项建议版本说明操作系统Linux (Ubuntu 20.04)生产环境首选Windows 建议用 WSL2Docker20.10容器化部署的基础Docker Composev2多容器编排Python3.10如果走源码部署需要PostgreSQL14带 pgvector 扩展内存16GB含本地模型时建议 32GB磁盘50GB取决于文档量和模型大小这里有个容易被忽略的点如果你打算用本地大语言模型而不是调云端 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_URLpostgresql://user:passwordpostgres:5432/weknora VECTOR_STORE_TYPEpgvector LLM_BASE_URLhttps://api.example.com/v1 LLM_API_KEYyour_key_here EMBEDDING_MODELBAAI/bge-large-zh-v1.5 EMBEDDING_DIMENSION1024注意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 开始试根据回答质量调整。如果发现回答经常缺信息就调大如果回答经常跑题就调小或者加一个相似度阈值过滤。文档类型切块方式块大小重叠top_k技术手册按标题按节无3会议纪要固定字符500505问答对按条单条无3长篇文章固定字符80010044.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 问答效果差的排查思路效果问题比部署问题更磨人因为它没有明确的报错。我的排查顺序是这样的先看检索环节。把用户的问题拿去检索看返回的片段是不是真的相关。如果不相关问题出在嵌入模型或者切块上。换个更强的嵌入模型或者调整切块策略。如果相关但回答还是不对那问题出在生成环节检查提示词和大模型本身的能力。再看向量维度是否匹配。嵌入模型换了但没重建索引会导致检索结果完全错乱。换嵌入模型一定要重新向量化所有文档。还有一种情况是文档本身就没有答案模型只能瞎编或者拒答。这时候要补充知识源而不是调参数。现象可能原因解决方向检索结果不相关切块太碎/嵌入模型弱调整切块换嵌入模型回答缺信息top_k 太小调大 top_k回答跑题上下文噪声多加相似度阈值调小 top_k回答编造提示词约束不足强化提示词要求无据不答换模型后全乱向量维度不匹配重建索引重新向量化5.3 性能与成本优化经验跑通之后下一步就是让它跑得又快又省。检索这块给向量字段建索引能大幅提升查询速度pgvector 支持 IVFFlat 和 HNSW 两种索引数据量大的话建议用 HNSW查询快但建索引慢、占内存多。大模型调用是成本大头。如果问答量不大用云端 API 按量付费更划算如果量大且数据敏感本地部署虽然前期投入高但长期看单次成本低。还有一个省钱的技巧是缓存相同或相似的问题直接返回缓存结果不用每次都走完整链路。嵌入模型的计算也可以优化文档向量化是一次性的做完就存库了但用户提问每次都要向量化这部分开销相对小。如果并发高可以考虑把嵌入服务单独部署做水平扩展。6. 后续扩展的一些想法跑通基础版本之后能做的事情还有很多。比如接入企业现有的账号体系做单点登录把知识库嵌进内部办公工具或者加一个反馈按钮让用户对回答打分用这些数据持续优化检索和提示词。多轮对话也是很多人的需求。基础版一般是无状态的单轮问答要做多轮需要在流程里维护对话历史把之前的问答也作为上下文传进去。但要注意历史太长会挤占上下文窗口需要做摘要或者截断。还有一个方向是权限控制。企业知识库往往不是所有人都能看所有文档需要按部门、角色做检索过滤。这要求在向量库里给每个片段打上权限标签检索时带上过滤条件。这块实现起来有一定复杂度但对企业场景是刚需。我自己在实际操作中的体会是RAG 项目的成败七分在数据两分在检索调优一分在模型选择。很多人一上来就纠结用哪个大模型其实先把文档整理干净、切块调好效果提升比换模型明显得多。另外别指望一次调到位上线后持续收集 bad case针对性优化才是正道。