上个月有同事在群里问“公司最新的报销流程去哪看”群里没人立刻回答。这很正常——文档散落在飞书云文档、本地共享盘、项目 Wiki 里真要搜起来比翻聊天记录还痛苦。我的做法是用自己的 AI 智能体工作台 WorkBuddy把飞书机器人和本地部署的 RAGFlow 知识库串成一条问答链路以后这种问题机器人直接回答答案背后有真实文档支撑。整个过程从环境准备到调通用了大概三天其中一半时间花在踩坑上。这篇文章就是一份保姆级实战记录每一步怎么做、为什么这么做、哪些地方容易翻车我全给你讲清楚。1. 链路设计与选型思路1.1 链路全貌谁在做什么先给你一张整体地图免得后面迷失方向。用户打开飞书在群里 机器人输入一句“最新的报销流程是什么”。这条消息先到达飞书开放平台平台再把事件内容通过回调推送到你的服务地址。那个服务地址由 WorkBuddy 智能体技能托管技能收到消息后先做合法性校验然后提取出文本内容构造一个检索请求发给本地 RAGFlow。RAGFlow 在本地知识库里做向量检索和全文检索把最相关的几个文档片段返回。WorkBuddy 拿到这些片段后把它们交给大模型整理成一段通顺、可读的回答最后通过飞书发送消息 API 把答案发回群里。整个链路分工非常清晰飞书负责对话入口WorkBuddy 负责编排和动作执行RAGFlow 负责知识检索。用户只感知到一个机器人背后细节完全透明。这也是我推荐这种拆法的原因——每个环节都有成熟组件不需要重复造轮子。1.2 为什么选 RAGFlow WorkBuddy 组合很多朋友第一反应是“用 Dify 不行吗”或者“我直接写个 Python 服务不就行了”。都行但各有取舍。我从选型阶段对比过一轮直接给你看结论对比项RAGFlowDify手写脚本文档解析能力强PDF 表格、扫描件、复杂版式都能处理中等普通文档没问题弱基本靠你自己写知识库检索向量 全文混合检索召回质量高有基础 RAG 能力自己拼装智能体/技能管理无专注知识库完整 Workflow 编排无部署复杂度中高高低适用场景私有化知识问答底座完整 Agent 应用极限定制我当时的核心诉求有三个文档必须留在内网、需要一个可维护的“消息处理器”而不是完整聊天应用、文档解析质量要高。RAGFlow 在这三个维度上刚好全中。WorkBuddy 的“技能Skill”机制则解决了工程化问题——把回调服务、HTTP 工具、提示词模板封装成一个技能日志、重试、配置统一管理比手写几份脚本扔在服务器上要清晰得多。另外强调一句文档解析质量是知识库召回效果的上限。你再怎么调提示词如果入库时文档被切得七零八落后面检索就是神仙难救。这也是我坚持用 RAGFlow 而不是随便搭个本地向量库的原因。2. 环境准备三件套安装与初始化2.1 RAGFlow 本地部署与初始化先聊硬件。RAGFlow 官方建议 CPU 至少 8 核、内存 16G 以上、磁盘 50G 以上。这是合理底线尤其是你要跑索引构建任务的时候。我用的是一台 16 核 32G 的旧服务器跑起来比较从容。如果你的机器只有 8G 内存建议先降级到小知识库测试否则容器很容易被 OOM 杀掉。部署方式很简单Docker 一条龙。git clone https://github.com/infiniflow/ragflow.git cd ragflow/docker cp .env.example .env # 按需修改端口映射和相关配置 docker compose up -d等容器全部 up 起来浏览器打开http://服务器IP首次登录默认账号是admin首次登录后会强制改密码。进去之后第一步先配置模型提供商。这一块有两个方向服务器能访问外网直接填一个在线 API比如硅基流动、OpenAI 兼容接口或者 DeepSeek 的 API Key配一个嵌入模型加一个对话模型即可。完全内网环境嵌入模型建议本地部署bge-m3这类开源模型对话模型至少要 7B~14B 参数级别显存 24G 起步否则推理速度会让你怀疑人生。配置好模型后就可以创建知识库并上传文档了。这个环节我在后面第三节详细展开因为解析策略直接影响检索效果。2.2 飞书机器人创建与事件订阅飞书这边的操作大部分人应该都熟我快速过一遍关键点。登录飞书开放平台创建“企业自建应用”添加“机器人”能力。然后进入“事件与回调”订阅im.message.receive_v1事件也就是“接收消息”事件。这里要拿到三个核心凭证App ID、App Secret、Verification Token。如果你想加密事件内容还可以开 Encrypt Key但复杂度会明显上升开发阶段不建议开。飞书回调有一个硬性要求回调地址必须是 HTTPS。这个 HTTPS 不一定非得是公网域名只要能被飞书服务器稳定访问就行。开发阶段我用一台带公网 IP 的临时服务器部署调试通过后再迁回公司内网。如果你手头没有公网服务器本地机器开个 HTTPS 内网映射工具也能顶一阵但不建议作为长期方案稳定性没保障。还有一件特别容易被忽略的事自建应用要“发布版本”后才对组织成员生效。开发调试时你可以用测试企业但正式上线一定要走完创建版本、提交发布、审核通过的流程不然其他同事根本看不到机器人。2.3 WorkBuddy 安装与基础设置WorkBuddy 装起来没什么难度Windows、macOS、Linux 都有客户端下载安装包一路下一步就行。不过有一点特别值得说WorkBuddy 会把技能运行时、日志、缓存写进系统盘默认目录。长期跑知识库问答临时文件会越来越多C 盘紧张的话建议在设置里把缓存目录改到数据盘比如D:\workbuddy_cache。这个操作不影响任何技能运行纯粹是把存储压力从系统盘转移走。装好之后我建了一个技能项目取名叫feishu_rag_bridge。这里解释一下我对“技能”的理解你可以把它看成一个可执行的说明书里面包含触发条件、运行工具、提示词模板和回调端点定义。我们后面所有核心逻辑都会写在这个技能里。WorkBuddy 的好处是技能执行过程的每一步都有日志排查问题比裸脚本舒服太多了。2.4 网络与回调地址打通这条链路最容易被忽视的就是网络连通性。飞书回调要访问你的服务你的服务要访问 RAGFlow 和飞书 API三个方向都不能断。我当时遇到过一个诡异问题RAGFlow 部署在内网飞书回调落在公网服务器内网服务器访问不了 RAGFlow 的 API因为 RAGFlow 在另一个网段的 Docker 容器里。解决思路很简单要么把三个服务放在同一个网络环境要么通过网关/路由把网络打通。这里不涉及特别复杂的技术就是要提前把架构图画清楚飞书服务器 → 你的公网入口 → 内网转发 → WorkBuddy 技能服务 → RAGFlow 容器。每一跳都要能通再往下走才有意义。3. 核心链路实现与全流程跑通3.1 知识库文档入库与解析策略RAGFlow 知识库的解析能力是它最大的卖点但前提是你得把参数配对。我先创建一个知识库然后批量上传公司制度、项目文档、FAQ 等文件。支持格式很全PDF、DOCX、Markdown、TXT、HTML、XLSX 都能处理。Chunk 参数我建议这样配置Chunk 大小256~512 token取 256 更精准512 上下文更完整。我做问答场景选了 384平衡了召回精准度和上下文完整性。Chunk 重叠32~64 token防止关键句子被切断。我选 64因为公司文档里很多结论性表述跨段。检索模式混合检索向量 全文。纯向量检索对口语化提问不太友好混合模式能把关键词命中的结果也捞进来。开启“引用”元数据这样回答的时候能知道答案来自哪个文档飞书回复时可以带上来源可信度高很多。上传文档后RAGFlow 会自动触发解析。这里注意一个状态问题文档列表里每个文件都有状态字段只有状态变成“完成”并且索引构建成功检索才能命中。我第一次测试时没注意状态好几个文档还在“解析中”就把问题抛上去了结果检索结果为空差点误判成代码问题。另外特别提醒Excel 表格建议把每一行或每一块区域存成独立 chunk否则整张表被揉进一个 chunk 里检索关键词时很难精准命中行级信息。RAGFlow 对表格的处理在开源方案里算好的但入库前把表头和样例数据整理干净效果会再上一个台阶。3.2 WorkBuddy 技能飞书事件接收与校验技能里我写了一个 Flask HTTP 服务专门接收飞书事件回调。飞书在验证回调地址时会发送一个url_verification请求里面带challenge字段你的服务必须原样返回challenge才能通过验证。这是新手第一个坑一定要先处理。from flask import Flask, request, jsonify import os app Flask(__name__) VERIFICATION_TOKEN os.getenv(FEISHU_VERIFICATION_TOKEN) app.route(/feishu/webhook, methods[POST]) def feishu_webhook(): data request.get_json() # 飞书验证回调地址时必须原样返回 challenge if data.get(type) url_verification: return jsonify({challenge: data[challenge]}) # 校验 Verification Token header_token data.get(header, {}).get(token, ) if header_token ! VERIFICATION_TOKEN: return jsonify({code: 1, msg: invalid token}) # 事件处理提取消息文本 event data.get(event, {}) message_type event.get(message_type) if message_type ! text: return jsonify({code: 0, msg: ignore}) content json.loads(event.get(message, {}).get(content, {})) question content.get(text, ) # 触发后续检索和回复逻辑 handle_question(question, event.get(sender, {}).get(sender_id, {})) return jsonify({code: 0})这段代码是整个链路的入口。注意它没有处理加密模式所以前面建议你别开 Encrypt Key。校验逻辑看起来简单但在飞书自定义应用里Verification Token 是事件订阅的标配少校验一步就会被攻击者伪造消息塞进来。3.3 WorkBuddy 技能查询 RAGFlow 并生成回答收到问题文本后下一步是调 RAGFlow 的检索接口。第一步要先在 RAGFlow 里生成一个 API Key位置在个人头像菜单的“API”管理里。然后构造检索请求。curl -X POST http://ragflow_host/api/v1/retrieval \ -H Authorization: Bearer your_api_key \ -H Content-Type: application/json \ -d { question: 最新的报销流程是什么, dataset_ids: [dataset_id], top_k: 8 }RAGFlow 返回的结果里面会带多个 chunk每个 chunk 有content、doc_name等字段。这时候千万别把 chunk 原文直接甩给用户而是要做“先检索后生成”。我给大模型的定义是这样的你是公司内部知识助手。请严格基于下面的知识库资料回答用户问题。 如果资料不足以回答直接回复“知识库中未找到相关信息”不要编造。 资料 {chunks} 用户问题{question}这里有一个易错点dataset_ids填错会导致检索不到。你可以通过 RAGFlow 的列表接口查知识库 ID不要靠肉眼从 URL 猜URL 里的那串才是真正的 ID。检索返回后我取 top 3~5 条最高分片段拼进提示词太多反而会让模型注意力分散。拼好提示词后调用对话模型接口生成最终答案然后再调飞书消息发送 API 回传给用户。发送消息需要先拿tenant_access_tokencurl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \ -H Content-Type: application/json \ -d {app_id: APP_ID, app_secret: APP_SECRET}拿到 token 之后curl -X POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_typeopen_id \ -H Authorization: Bearer tenant_access_token \ -H Content-Type: application/json \ -d { receive_id: open_id, msg_type: text, content: {\text\: \根据知识库检索报销流程如下...\} }这套动作串起来就是一个完整的“收到消息→查库→回答”闭环。整个过程在 WorkBuddy 技能里都有日志每次调用哪个接口、耗时多久、返回了什么一目了然。调试效率比黑盒脚本高太多了。3.4 端到端测试与效果调优链路通了之后第一件事先跑一遍冒烟测试在飞书群里 机器人问一个知识库里肯定有的问题比如“请假需要提前几天”。如果回复正常再问一个知识库里没有的问题看它会不会老实说“未找到”而不是胡编。调优的时候我重点盯三个指标检索召回质量如果回答引用了错误文档优先检查 chunk 参数调小 chunk 大小或者换混合检索里的权重。RAGFlow 的检索参数面板可以直接调不用改代码。响应速度飞书回调接口对超时敏感如果整个流程超过 5 秒用户体感就很差。我的优化做法是把 LLM 超时时间设成 15 秒如果模型响应慢先返回一句“正在查询请稍候”然后再异步补发结果。这个体验细节很加分。答案格式如果发现模型总爱堆一大段话可以在提示词里加一句“控制在 200 字以内”。有些读者会问这样会不会丢失细节其实知识库问答要的是“快、准、稳”细节靠后续追问补而不是第一次回答就铺满全文。4. 踩坑实录这些问题我全替你趟过了4.1 回调 Challenge 校验失败飞书初始化回调地址时会向你的 HTTPS 地址发一个url_verification请求。如果你没有在代码里优先判断这个 type 并返回challenge飞书会提示“地址验证失败”。我当时在这个坑里卡了半小时后来把请求体打出来才发现原来回调验证和我后面处理事件用的是同一个接口只是载荷类型不一样。解决办法就是上面代码里那三行if判断。4.2 RAGFlow 返回空结果这个问题最迷惑因为接口返回正常但结果列表是空的。排查后发现是知识库文档没有完成索引构建。RAGFlow 上传文档后会异步解析解析完还需要建立索引两个状态都完成后才能检索。如果你在文档列表里看到状态是“解析中”或“未建立索引”先等一会再测或者手动触发“建立索引”任务。别急着怀疑代码先查数据状态。4.3 飞书机器人的消息频率限制机器人频繁发消息会触发飞书的频率限制错误码大概长这样9499或1000001之类。虽然我知道账号不敏感但频率限制是真实存在的。解决方案是对发送接口做重试 退避第一次失败等 1 秒再失败等 3 秒最长等待 10 秒后放弃。另外如果收到用户的连续多条消息可以做一个简单的去重避免每一条都触发完整流程。批量导入文档后不要立刻并行测试几十个问题容易把自己限流别问我怎么知道的。4.4 本地模型显存与性能权衡在内网环境部署本地大模型确实省心不用把文档送到外部但显存占用和推理速度成了一道坎。我一开始用了一个较大的模型结果单次检索生成的回答要等 40 秒飞书早就超时了。后面换成了 7B 量化版本虽然回答没之前华丽但 3~5 秒出结果实用性大增。嵌入模型也要注意如果bge-m3跑不动可以换更小的向量模型代价是召回准确率略有下降。这里给个实用建议并不是所有场景都需要本地生成模型。如果只是做内部问答而且文档敏感度没那么高嵌入模型可以本地跑对话模型用在线 API混合搭配能省不少资源。如果文档确实高度敏感那双本地部署没得商量预算和硬件都得跟上。4.5 常见问题速查表现象大概率原因解法飞书回调查验失败没处理 url_verification 的 challenge优先返回 challenge 字段消息回调收到了但没回复Verification Token 校验失败检查 header.token 与后台配置是否一致检索结果为空文档未完成解析/索引查看 RAGFlow 文档状态手动建立索引RAGFlow 接口 401API Key 错误或过期重新生成 API Key飞书回复超时整个链路处理超过 5 秒拆分异步任务先回复“处理中”回答内容张冠李戴Chunk 太大或重叠不足调小 chunk增加重叠 token机器人发消息报频率限制单日调用量过高加重试退避逻辑降低测试频率表格文件无法问答飞书消息事件只拿到“文件”类型下载文件后走解析流程或引导用户发文本5. 这些事做安全做扩展5.1 权限隔离与审计链路能跑通只是第一步上生产前权限和审计一定要做。飞书自建应用在“权限管理”里可以限制应用可见范围只对指定部门或群组开放避免全公司都来调这个机器人。RAGFlow 的 API Key 只放在环境变量里不要写进代码仓库也不要出现在飞书消息日志中。审计日志建议做成结构化每次用户提问、检索命中的文档、生成答案、发送状态都记录一条日志。这样一旦出现问题可以回溯是哪份文档命中导致错误回答。我当时用 WorkBuddy 技能自带的日志做了基础版本后续如果要更严格可以接一个日志系统或者简单落库按人和时间来查。5.2 后续扩展从单链路到多技能这条链路跑顺之后你会发现“飞书机器人 本地知识库”这个模式能复制到很多场景。比如我可以再加一个文档定时同步技能每晚会自动扫描某个共享目录把新增文件上传到 RAGFlow 并触发重建索引这样知识库内容始终和最新文档同步不用人工入库。RAGFlow 也支持多知识库我打算按部门拆知识库在 WorkBuddy 里写一个路由逻辑根据用户提问自动选知识库准确性还能再提高一截。另一个很值得做的方向是“多模型路由”简单问题用便宜的小模型复杂问题再切大模型。这样既不牺牲质量又能控制成本。我个人在实际操作中的体会是这种“机器人 知识库”的链路真正难的从来不是技术本身而是文档质量和工程细节。文档没整理好再强的组件也白搭回调校验、限流、状态检查这些细节才是决定你是在“写玩具”还是“造工具”的分水岭。先把一条链路跑透再考虑花活这才是最稳的路径。