WeKnora v0.8.0落地手记：构建有记忆、能调工具、支持技能包的RAG知识库

做知识库项目做久了，都会有一种很深的体会：知识库再大，也像个“只会考试的图书馆”——你问它问题，它给你翻资料，但资料翻完，后续的整理、汇总、发消息、改状态这些动作，它一概不管。上个月我把微信侧的智能问答机器人切到 WeKnora v0.8.0 之后，这种感觉开始松动了：它不光能从我电脑里那些散落的 Word、PDF、Excel 里把答案捞出来，还能记住我跟它聊过什么，会主动去调外部接口把实时数据拿回来，甚至能按预设的“技能包”把一套流程从头跑到尾。

这篇落地手记，想把 WeKnora v0.8.0 里最核心的三件事——记忆、手脚、技能——从设计逻辑到实操配置完整拆开讲一遍，顺便把微信入口的接入思路也写清楚。项目本身是开源的，我们可以用 Docker 方式自己部署，适合正在折腾 RAG 知识库、又想让知识库真正“干点活”的朋友。整个方案我是在 Ubuntu 服务器上完成的，配合企业微信自建应用接入，从部署到跑通大致花了一个周末，下面全是实际操作里的经验和坑。

1. 先理清主线：WeKnora 到底在解决什么问题

1.1 传统 RAG 知识库的死穴：只带眼睛，没有手脚

RAG（检索增强生成）知识库这两年已经很成熟了。Dify、RAGFlow、AnythingLLM 这些开源项目，我基本都搭过一遍。它们的核心能力高度一致：把文档切碎、向量化、存进向量库，用户提问时先检索相关内容，再让大模型基于检索结果生成答案。

这套模式的问题在于，知识库本质上是个“大脑”，而且是个不太记事的大脑。你问它“上个月的项目总结写了吗”，它能给你找出一堆文档摘抄，但不会自己去查项目系统里的实际数据，不会帮你生成一份日报，更不会把日报通过企业微信发给团队。说得直白点，传统 RAG 知识库只有眼睛和嘴巴，没有手和脚。

我之前的微信机器人就是这样，每个问题都要用户手动把上下文重新描述一遍，因为服务端没有记忆。问完“A 项目的预算范围”再问“那它的截止时间呢”，第二句就彻底失忆了。这种体验放到内部工具里还能忍，放到微信这种即时沟通场景里，基本没法用。

1.2 v0.8.0 的版本定位：记忆、手脚、技能三件事

WeKnora v0.8.0 这个版本，重点解决的就是上面说的三件事。

第一是记忆。系统开始区分短期记忆和长期记忆：短期记忆负责当前对话窗口的上下文连贯，你问完“预算”再问“截止时间”，它知道“它”指的是哪个项目；长期记忆负责把用户的历史偏好、历史结论沉淀下来，比如某个用户每次都习惯要表格形式的输出，下次直接默认给表格。

第二是手脚。这个版本强化了工具调用机制，核心是 Function Calling。大模型在回答过程中可以输出一个结构化调用指令，系统拿到指令后去执行真正的函数——查数据库、调 HTTP 接口、读文件、发消息——然后把执行结果再送回模型继续生成答案。知识库从一个“查资料的”，变成了一个“能办事的”。

第三是技能。技能可以理解成“预装工种”，一个技能包把提示词模板、需要用到的工具集合、指定的知识库范围、触发条件打包在一起。比如我导入一个“公众号文章技能包”，它在被触发后会自动按技能包里的流程工作：先解析文章链接、抓取正文、清洗内容、写入知识库，最后生成摘要。本质上就是给知识库装上了可插拔的“专业技能”。

1.3 我的选型理由：为什么是 WeKnora 而不是 Dify、RAGFlow

在决定用 WeKnora 之前，我其实犹豫过要不要继续用 Dify。Dify 的优势是 workflow 可视化编排，拖拽节点就能搭出一条知识库流水线，对非技术用户非常友好。但它的定位更像“流程工厂”，天然不适合做“有记忆的长期对话助手”。RAGFlow 的文档解析能力很强，尤其是深度文档理解做得不错，但它的工具调用和技能扩展偏弱。

WeKnora 给我的感觉正好卡在中间：部署复杂度比 Dify 低，直接 docker compose 拉起来就能用；工具调用和技能体系比 RAGFlow 完整；又专门把“记忆”作为一等公民设计。更重要的是，它支持标准的 OpenAI 兼容接口，意味着我本地不管跑的是 Ollama 还是 vLLM，都能直接接进来。

2. 部署 WeKnora v0.8.0：从 Docker 命令到可用的第一秒

2.1 部署前要准备的东西

我这边服务器是 Ubuntu 22.04 LTS，8 核 16G 内存，一块 500G 的 SSD。这个配置跑 WeKnora 加一个本地小模型比较紧张，所以我实际是让 WeKnora 去调远端的大模型 API，服务器只负责知识库服务、向量存储和应用服务。如果想把模型也本地化，建议至少 32G 内存加一张 24G 显存的卡，否则并发一上来就等着 OOM。

部署前需要确认以下环境：

• Docker 和 Docker Compose 插件。我这边用docker --version确认过，版本是 24.0 以上，Compose 用的是 v2 语法。
• 一个兼容 OpenAI 接口的模型服务，包括基础对话模型和 embedding 模型。我对话模型用的是远端 API，embedding 用的是本地的 BGE-M3，维度是 1024 维。
• 域名和 HTTPS 证书。微信接入强制要求回调地址是 HTTPS，所以提前准备一个能解析到服务器的域名，用 Caddy 或 Nginx 做反向代理都可以。

这里有个容易忽略的点：Embedding 模型一旦定下来，知识库里的向量维度也就定死了。中途换 embedding 模型意味着所有文档要重新切片、重新向量化，所以部署前一定要把 embedding 模型选好，我最后选了 BGE-M3，中文场景效果很稳。

2.2 用 docker compose 拉起服务

WeKnora v0.8.0 的官方部署推荐用 Docker Compose，核心服务分四个部分：server（后端 API 服务）、web（前端管理页面）、vector-db（向量数据库）、db（元数据存储）。不同分支或版本的服务命名会不一样，我这里只描述自己落地时的结构。

我本地的 docker-compose.yml 核心配置大概长这样：

version: "3.8" services: vector-db: image: qdrant/qdrant:v1.9.0 restart: always volumes: - ./data/qdrant:/qdrant/storage db: image: postgres:16-alpine restart: always environment: POSTGRES_USER: weknora POSTGRES_PASSWORD: change_me POSTGRES_DB: weknora volumes: - ./data/postgres:/var/lib/postgresql/data server: image: weknora/weknora-server:0.8.0 restart: always ports: - "8080:8080" environment: DB_HOST: db DB_PORT: 5432 DB_USER: weknora DB_PASSWORD: change_me DB_NAME: weknora VECTOR_DB_HOST: vector-db VECTOR_DB_PORT: 6333 LLM_BASE_URL: https://你的模型服务地址 LLM_API_KEY: sk-xxx LLM_MODEL: gpt-4o-mini # 也可以是 qwen、deepseek 等兼容模型 EMBEDDING_MODEL: bge-m3 depends_on: - vector-db - db web: image: weknora/weknora-web:0.8.0 restart: always ports: - "3000:3000" environment: SERVER_URL: http://server:8080 depends_on: - server

第一次启动前，先创建数据目录，避免容器以 root 身份写数据时产生权限问题：

mkdir -p ./data/qdrant ./data/postgres docker compose up -d docker compose logs -f server

看到日志里出现类似server started on port 8080的提示，就说明服务拉起来了。web 管理页面默认跑在 3000 端口，浏览器打开http://服务器IP:3000，用初始化账号密码登录后，第一件事就是去“模型设置”里把模型连接检查一遍。WeKnora 的管理页面里一般都有“测试连接”按钮，点一下能直接看到模型是否连通，这比什么都重要。

2.3 首次配置的 4 个关键参数

模型连通后，有几个参数我必须建议你多花两分钟看明白，否则后面会遇到很多“莫名其妙”的问题。

第一个是模型名称。很多人以为配了 base_url 和 api_key 就完事了，其实不同模型服务的 model 名称写法完全不同。OpenAI 兼容接口一般要求填完整的模型名，比如gpt-4o-mini、qwen-plus、deepseek-chat。填错的话，日志里会出现model not found或直接返回 404。

第二个是 embedding 维度。BGE-M3 是 1024 维，有些向量库默认建集合时用 768 维或 1536 维，如果不匹配，写入向量时会直接报维度错误。WeKnora 在创建知识库时一般会让你选 embedding 模型，选完它会自动按模型创建集合，这里千万不要手动乱改。

第三个是召回数量 topK。默认值通常是 3 到 5，但中文文档场景下，我建议先设成 8 到 10。因为中文句子切分后语义碎片化严重，只召回 3 段往往不够模型组织答案，先把召回量调大，看看答案质量再做减法。

第四个是上下文最大长度。这决定了模型能“看到”多少检索结果和聊天历史。如果模型上下文是 8K，建议把知识库检索回的片段总长度控制在 3K 以内，剩下留给对话历史和系统提示词。盲目把检索片段塞满，模型很容易丢掉真正关键的信息。

3. 让知识库“长记忆”：配置记忆系统的底层逻辑

3.1 记忆到底记什么

很多人一听到“记忆”，就觉得是“把聊天记录全部存下来”，这个理解太粗了。我实际用下来，WeKnora 这类系统把记忆分成了三个层次，分开处理才靠谱。

第一层是会话记忆，也就是当前这一轮对话的上下文。它解决的是“指代消解”问题：用户刚才提到“A 项目的预算”，下一句问“那截止时间呢”，系统要知道“那”指的是 A 项目。这一层实现最简单，把聊天历史拼进 prompt 就行，但要控制长度。

第二层是用户长期记忆，包括用户的称呼、偏好、常问的领域、对输出格式的偏好。比如有用户每次都要 Markdown 表格，长期记忆里会存一条“该用户偏好表格输出”，下次系统自动按表格生成。这一层我理解是独立存储的，通常放在一个单独的向量集合或键值库里。

第三层是业务记忆，这个比较高级，指的是把过去问答中产生的结论、中间结果、状态信息沉淀下来。比如用户上周要求在“华北区”的范围内做分析，这周再问相关问题，系统会记得这个范围条件。业务记忆的价值在于减少重复描述，让知识库真正像一个“懂业务的老同事”。

3.2 记忆是存在哪里的

从实现上看，会话记忆走的是“上下文窗口 + 摘要压缩”的路子。窗口内直接拼历史，等历史太长，系统会调用模型把前面的对话压缩成摘要，再把摘要放回上下文。这个机制的好处是省 token，坏处是摘要会丢失细节，所以 WeKnora 里一般可以配一个阈值，比如超过 20 轮就开启摘要压缩，或者用滑动窗口只保留最近 10 轮。

长期记忆和业务记忆则落地在向量库里。每个用户会有自己的“记忆集合”，系统在回答前先根据当前问题和用户 ID 去检索相关记忆片段，检索到的高相关记忆会作为额外的上下文注入 prompt。我记得在 WeKnora 的设置里，可以开一个“长期记忆增强”的开关，开启后系统会自动从对话中抽取值得长期保存的信息。这里有个关键点：它抽取的不是原始对话，而是结构化之后的“记忆元组”，比如“用户偏好=表格输出”。

3.3 我的记忆配置清单

如果你和我一样希望知识库在微信里不乱记、不忘事，下面这几个参数我强烈建议重点调：

• 会话窗口长度：不要贪多。微信对话场景通常一轮问题加一轮回答也就几百字，窗口设到 20 轮足够，多了反而稀释重点。
• 长期记忆抽取频率：默认可能是实时抽取，我建议改成对话结束再异步抽取，不然用户在连续追问时，系统把中间状态的对话也当成长期记忆存了，很容易污染。
• 记忆召回条数：默认可能带回 5 条记忆片段，太多了会让模型分不清哪条是当前对话的重点，我调到 3 条就够。
• 记忆时效：有些结论时间一长就过时了。WeKnora 里如果支持按时间衰减，建议把记忆召回的时间权重打开，越新的记忆权重越高。

3.4 接入记忆时的坑

记忆功能不是开了就万事大吉，我踩过三个实打实的坑。

第一个坑是记忆串台。最开始我在微信场景里用的是同一个机器人实例，结果两个同事同时问问题，A 的偏好被带到了 B 的回答里。这个问题根因是记忆没有按用户维度隔离。配置里需要把“用户 ID”作为记忆的 key，微信里的 user_id 必须从微信回调里取，而不是服务端自己生成。

第二个坑是记忆污染。用户偶尔随口说一句“这个项目好像不太行”，如果被当成长期结论写进记忆，后面所有涉及这个项目的回答都会被带偏。解决的思路是给记忆分等级：明确表示“记住”“以后都这样”这类才进入长期记忆，普通对话只进会话记忆。

第三个坑是记忆清除机制。测试阶段我反复给同一个用户灌数据，他的长期记忆里堆了一堆错乱结论，后面怎么问都不对。后来我在管理后台找到“编辑记忆”的功能，手动批量删掉了该用户的记忆。这里提醒一句：生产环境一定要在后台留出“用户记忆清理”的入口，否则出问题时只能手动连数据库删。

4. 给知识库接上“手脚”：工具调用从零到可用

4.1 Function Calling 到底是什么

工具调用的底层就是 Function Calling，也叫函数调用。你可以把它理解成“模型的问路机制”：模型在生成最终答案前，先判断自己缺什么信息，然后输出一段结构化的“调用请求”，而不是直接编一个答案。

举个例子，用户问“今天公司的销售总额是多少”。知识库里如果只有上个月的文档，模型没法直接回答，这时候它应该输出一个调用请求：调用query_sales_data函数，参数是{date: "today"}。系统收到这个请求后，真正去调用销售系统的 API，拿到结果，再把结果拼进上下文，让模型基于真实数据生成最终回答。

这个过程非常依赖两件事：一是模型本身要支持 Function Calling，二是函数描述要写得足够清楚。WeKnora v0.8.0 里的“工具管理”模块就是干这个的，你在里面注册一个工具，本质上就是写清楚这个工具叫什么、什么时候用、需要什么参数、返回什么结果。

4.2 注册一个工具的完整流程

我自己写的第一个工具是“查询订单状态”，走了完整流程之后才理解工具描述有多重要。

第一步，在 WeKnora 管理后台的“工具”页面，新建一个工具，填以下信息：

• 工具名称：英文，如query_order_status
• 工具描述：描述工具用途和适用场景，要写“当用户询问订单状态、物流信息、发货进度时使用”，描述越具体，模型越不容易选错工具。
• 参数定义：用 JSON Schema 描述参数。比如订单号是必填参数，类型是 string；查询日期是选填参数，类型是 string。参数定义一定要严格，因为模型会根据这个定义来生成参数值，如果参数名写错了，调用时就会报参数缺失。

第二步，在工具的实现地址或脚本里，写真正的执行逻辑。WeKnora 的工具执行通常支持 HTTP 回调，也就是系统把“工具名+参数”发给你配置的回调接口，你的接口执行完把结果返回。我的实现是一个 Python Flask 接口，收到参数后去查内部订单库，返回 JSON：

@app.route("/tools/query_order_status", methods=["POST"]) def query_order_status(): data = request.get_json() order_no = data.get("order_no") # 这里假设去查数据库 result = search_order_db(order_no) return jsonify({"status": result.status, "eta": result.eta})

第三步，回到 WeKnora 后台，把工具绑定到默认助手或某个技能包上。这里要注意，工具不是注册了就全局生效的，你得明确告诉系统“哪些场景可以用这个工具”。我的做法是建了一个order_assistant技能包，里面绑定了订单查询和物流查询两个工具，这样模型在回答订单相关问题时才会去调用。

4.3 一个和微信强相关的工具实战

既然标题里提到了微信，我就多说一个实战场景：我注册了一个“给用户发模板消息”的工具。用户直接在微信里对机器人说“帮我把今天的日报发给老张”，系统会先调用日报生成技能，拿到日报内容，再调用微信消息工具，把内容通过企业微信应用消息推送给指定的人。

这个工具的定义大概是这样：

• 工具名称：send_wecom_app_message
• 描述：当用户要求发送企业微信应用消息、通知、提醒时使用，参数包括接收人、消息内容、消息类型。
• 参数：user_ids（数组）、content（字符串）、msg_type（默认 text）。
• 实现：内部调用企业微信 API 的message/send接口。

这类工具最大的坑在权限：企业微信应用发送消息时，接收人必须是在应用的可见范围内，否则接口会报 60011 之类的错误码。所以注册工具之前，先要在企业微信管理后台把应用的可见范围配好，不然工具链条很容易断在最后一步。

4.4 工具调用失败怎么兜底

工具调用不会百分百成功。外部接口可能超时、参数可能传错、权限可能不够。我一般的兜底策略有三层。

第一层，工具内部保持简单，不做过重的业务逻辑。工具只负责“查数据、发消息”这种原子操作，复杂的流程放在技能包里串联。这样出问题时，问题定位会很容易。

第二层，超时控制。HTTP 回调的工具，我给每个工具设置了 15 秒的超时时间，超过就直接返回一个“工具超时”的错误。宁可让用户看到“查询超时，请稍后再试”，也不要让模型自己编一个结果来“圆场”。

第三层，异常信息回传。工具执行失败时，错误信息要原样返回给大模型，让模型知道发生了什么。比如“接口返回 401，权限不足”，模型可能会这样回答用户：“订单接口鉴权失败了，请联系管理员检查应用权限。”这比什么都不说强太多。

5. Skills 技能包：像装 App 一样扩充知识库能力

5.1 技能包到底是什么

如果说过往的 RAG 知识库是一个图书馆，技能包就是给这个图书馆配上不同工种的“员工”：客服、数据分析师、日报写手、设备排障员。每个技能包都包含“触发条件、处理流程、依赖工具、知识范围、输出规范”这几样东西。

我在 WeKnora v0.8.0 里最直观的感受是：技能包把“模型能力”和“业务逻辑”做了解耦。以前我想让机器人做“日报生成”，得在每次对话里反复强调“请根据今天的对话记录和工作日志生成格式如下的日报……”，现在只要把日报技能包配置好，模型在命中“日报生成”意图时，会自动按技能包里的提示词执行。

5.2 技能包的文件结构

WeKnora 的技能包我理解是一个目录或一个压缩包，里面带一个配置主文件、若干提示词模板和工具声明文件。以我做的“公众号文章采集技能包”为例，核心结构是这样：

skill-wechat-article/ ├── skill.yaml # 技能包配置：名称、描述、触发条件 ├── prompts/ │ ├── extract.md # 文章正文抽取的提示词模板 │ └── summarize.md # 摘要生成的提示词模板 ├── tools.yaml # 需要绑定的工具声明 └── knowledge.yaml # 关联的知识库范围

skill.yaml里最重要的字段是触发条件和描述。描述写得好，模型才能判断“这个技能包什么时候该出场”。我见过很多技能包不可用的原因就是描述太笼统，比如“用于处理文章”，模型根本不知道什么时候触发。我的写法是：

name: wechat_article_processor description: > 当用户提供微信公众号文章链接、要求解析文章内容、生成摘要、 提取要点或将文章保存到知识库时使用。 version: 1.0.0 tools: - fetch_url_content - write_to_knowledge_base

这样模型看到“把这篇公众号文章存到知识库里”这句话时，基本能稳定触发这个技能包。

5.3 自己写技能包的三个步骤

第一步，明确意图边界。你到底希望用户在什么情况下触发这个技能？边界越清楚，触发越准。不要做一个“什么都能干”的技能包，那是灾难。

第二步，圈定工具和知识。技能包需要哪些工具？需要查询哪些知识库？把依赖关系写清楚。如果技能包要调用外部 API，那对应的工具得先注册好。

第三步，写输出格式。这是最容易被忽略的。技能包不仅要告诉模型“做什么”，还要告诉模型“输出成什么样”。我的日报技能包输出格式就写得非常死板：标题、日期、核心数据、风险点、明日计划，每个字段都有固定要求，这样用户收到的每份日报格式都统一。

5.4 技能包和记忆、工具怎么配合

技能包不是孤立的，它会把记忆和工具串起来。拿“微信客服技能包”来说，它的流程是：先检索长期记忆，确认用户身份和历史问题；然后从知识库召回相关文档；如果需要实时数据，调用订单查询工具；最后按客服话术规范生成回复，并通过企业微信消息工具发出去。

这个链路能跑通，依赖的是 WeKnora 底层把“记忆检索、知识检索、工具调用、技能路由”整合到了一个请求流程里。我在管理后台看到的日志里，一次完整回答通常会有多个阶段：意图识别→技能匹配→记忆召回→知识召回→工具调用→最终生成。每一阶段都有日志，排错时非常有用。

6. 微信接入与落地：把知识库送到用户的对话列表里

6.1 微信生态接入方案的选型

微信生态里的接入入口很多，我强烈建议别碰个人微信的自动化方案，风险不可控，随时可能被封。合法合规的路径主要是三个：公众号/服务号、企业微信自建应用、微信客服。

公众号的优点是用户基数大、入口浅，缺点是接口能力相对受限，被动回复有 5 秒超时限制，要实现复杂的多轮对话得配合客服消息接口。企业微信自建应用应该是内部知识库助手最合适的形态：有完整的消息收发 API，支持应用消息主动推送，接收人范围可控，还能和内部通讯录打通。微信客服则适合对外客服场景，用户在你的小程序或App里直接发起咨询。

我的选择是企业微信自建应用，原因很简单：我们是内部知识库，用户就是公司同事，企业微信天然解决了身份认证的问题，不用再做一层账号体系。

6.2 服务器配置和消息收发

企业微信自建应用的接入，核心是配置“接收消息服务器”。在企业微信管理后台，进入应用详情，找到“接收消息”配置项，需要填三个东西：

• URL：你的 HTTPS 回调地址，比如https://your.domain.com/wecom/callback。
• Token：一个随机字符串，用来签名校验。
• EncodingAESKey：消息加解密密钥，企业微信提供了随机生成工具。

WeKnora 这边如果支持微信渠道插件，一般会自动生成一个回调地址和 Token，你只需要把两边配置对齐。如果不支持，就得自己写一个中转服务，把企业微信的消息格式转成 WeKnora 的对话接口格式。

我实际踩过一个坑：企业微信要求回调 URL 必须能在 5 秒内响应验证请求。我一开始把回调转发到 WeKnora 的重逻辑处理流程，结果验证请求超时，企业微信配置一直保存失败。解决办法是在回调服务里做两层：第一层直接响应企业微信的 URL 验证，第二层把真正的业务消息丢进队列异步处理。这样 URL 校验秒回，实际对话消息稍后处理也没问题。

6.3 微信对话机器人的交互设计

微信端对话和网页端对话体验差别很大，Web 端用户习惯多轮打字，微信端用户希望“发一条消息就有结果”。我在 WeKnora 的提示词里给模型加了几条微信场景规则：

• 回答尽量精炼，一般不超过 300 字。如果知识库答案太长，先给结论，再问“需要我展开哪个部分”。
• 把 Markdown 语法的使用降到最低，因为企业微信消息对 Markdown 支持有限。表格在消息端会变形，我一般要求模型输出纯文本，或者用逗号分隔。
• 遇到需要用户二选一的场景，明确列出选项编号，用户只需要回复“1”或“2”。这对后续意图识别很有帮助。

另外，微信消息还经常带图片或文件。我在 WeKnora 里配了文档解析通道，用户在微信里直接发一个 PDF 或 Word，系统会先下载文件，走解析流程后把内容写入一个“临时知识库”，然后回答用户“已收到，正在解析”。这个功能对移动办公场景非常有用。

6.4 微信对接时的鉴权细节：code 换 token

企业微信网页授权登录或小程序跳转时，经常会提到“code 换 token”这件事。简单说，用户在企业微信客户端里打开你的 H5 页面，企业微信会跳转到一个带上code参数的 URL，你的后端要用这个 code 去调用企业微信的接口，换取用户的身份信息，相当于用户 ID。

这个 code 是一次性的，有效期只有 5 分钟，而且只能用一次。我在对接 WeKnora 的登录鉴权时，写了一个接口：前端拿到 code 后传给后端，后端调用企业微信 APIauth/getuserinfo，通过 code 换取 userid，再用这个 userid 作为 WeKnora 记忆系统的用户 key。这样用户在微信端的所有对话，记忆都能按真实员工身份落库，换设备也不丢记忆。

6.5 微信接入和 Dify 流水线的对比

之前我在另一套系统里用 Dify 搭过知识库流水线，这里做个对比供大家参考。Dify 更适合做“可以看得见的流程编排”，节点拖拽、条件分支、人工审核都可以可视化配置，做复杂业务流很顺手。WeKnora 的强项则在于“看不见的运行时能力”：记忆自动管理、工具调度、技能路由，这些东西在界面里并不起眼，但对对话体验的提升是实打实的。

我现在是两条腿走路：Dify 负责做复杂的内部运营流，比如“工单自动分类并通知对应负责人”，需要人去审核确认的场景，Dify 的可视化更透明；WeKnora 负责做微信里的智能问答和个人AI助理，因为它的记忆和技能机制更适合“持续对话的贴身助理”这种形态。两个系统通过 API 互相调用，并不冲突。

7. 真实落地中的高发问题与排查清单

7.1 文档解析乱码与格式丢失

Word 和 PDF 解析是知识库构建里最让人头疼的一环。我测试过三类文档：Word 里如果有复杂表格，WeKnora 的默认解析器偶尔会把表格结构拆散，导致检索到的内容是一串没有意义的碎片；PDF 如果是扫描件，不走 OCR 的话，检索结果永远是空的。

解决办法分两层。第一层，配置解析流程时，优先用支持版面分析的模式，让系统先识别标题、段落、表格区域再切分。第二层，扫描版 PDF 必须在解析前加 OCR。我在生产环境的做法是先在外部用 OCR 工具把 PDF 转成文本再导入，宁可多一道预处理，也不依赖知识库自身的 OCR，因为效果和速度都不稳定。

7.2 向量检索召回为空或不准

召回为空最常见的两个原因：一是新导入的文档还没完成向量化，二是 embedding 模型本身拒绝了这个内容，比如空文档或纯图片。排查时先看后台的“文档状态”，确认每条文档处于“已向量化”状态。

召回不准则大概率是切分策略的问题。我一开始用固定 500 字切分，很多在语义上连贯的内容被硬切断了。后来改成让切分器尽量按标题、段落边界来切，片段控制在 800 字左右，边界的重叠设为 80 字。调整之后，召回命中率明显提升，特别是长文档里的关键结论，不容易再被切丢了。

7.3 工具调用超时或参数格式错误

工具调用的报错里，频率最高的是参数格式错误。大模型生成参数时，可能会把日期写成“今天”而不是具体的2025-06-15，也可能会把数组参数写成逗号分隔的字符串。解决思路有两个：一是在工具参数定义里把格式写死，比如format: date、type: array；二是在工具实现端做宽松解析，不匹配时自动转格式，而不是直接报错。

超时问题我遇到过更隐蔽的：企业微信发送消息接口偶尔会响应很慢，超过 15 秒后工具超时，但消息其实已经发出去了，结果用户收到两条同样的日报。这个问题的根因是接口不幂等，同样是重试导致的重复发送。解决方法是给每次请求生成一个唯一 request_id，企业微信接口支持幂等键的话必须用它，没有的话在工具里做一次“最近一次发送记录”的查重。

7.4 记忆串台与上下文超限

记忆串台我已经在前面细说了，这里补充一个上下文超限的排查思路。如果系统日志经常报context length exceeded，说明你的会话记忆加知识片段加系统提示词的总长度超过了模型的上下文窗口。我建议养成定期看 token 消耗的习惯，WeKnora 管理后台一般有每次请求的 token 统计，我对长对话场景设置了 15 轮自动压缩，同时把召回片段从 10 段降回 6 段，超限问题基本就消失了。

7.5 高发问题速查表

我把这阶段遇到的高频问题整理成了一张速查表，方便遇到问题时快速定位：

7.6 资源占用过高怎么定位

我自己用的是 16G 内存服务器，跑 Qdrant 向量库加 PostgreSQL 加两个 WeKnora 服务，空闲时内存占用大约 6G 到 7G。如果发现内存持续飙升，通常不是 WeKnora 本身的问题，而是文档解析并发太高。我在 docker compose 里限制了解析容器的 CPU 和内存，同时在后台把“最大并发解析数”从默认调低到 2，问题立刻缓解。

如果 CPU 占用高，十有八九是检索时向量计算压力大。建议在 Qdrant 里给向量字段建好索引，并且控制单次知识库检索的候选集数量，别把所有文档都拉进来算相似度。

结尾：一点真实体会

整个 WeKnora v0.8.0 落地下来，我最深的体会是：知识库工具正在从“回答问题的数据库”变成“能干活的工作伙伴”。记忆、工具调用、技能包这三样东西补齐后，知识库终于不仅仅是把资料堆在那里等人来问，而是能在微信这个日常场景里主动帮忙完成一些具体的事情。

最后分享一个小经验：无论是配置记忆、注册工具还是写技能包，都要从“一个真实的用户任务”出发，不要为了配置而配置。我一开始想把工具体系做得特别全，结果模型经常选错工具，反而拖垮了回答质量。后来我把工具收敛到和微信场景强相关的五六个，把每一个的描述和参数打磨到位，效果立刻改观。你要做的是选一个自己最头疼的重复性任务，先把那条链路打通，再慢慢往外扩。工具不在于多，在于每个都真的管用。

如果再往后走，我会试着把一套完整的设备报修流程做成一个独立的技能包，让用户在微信里说一句“设备报修”，系统能自动完成报修单创建、负责人通知、进度跟踪这几个动作。这个方向一旦跑通，知识库就不止是助手，而是真正嵌入业务流程的一环了。