企业知识库 × 飞书机器人 —— 从 0 到 1 接入

4 阅读14分钟

企业知识库 × 飞书机器人 —— 从 0 到 1 接入

把一个本地跑的 LangGraph 企业知识库 RAG 系统,接上飞书机器人:员工在飞书里直接提问,机器人检索知识库后把答案回过来。本文讲清整条链路、每个文件和 SDK 各干什么,以及"为什么局域网就能跑、不需要公网域名"。

一、先想清楚:我们到底要做什么

假设你已经有一套企业知识库系统:文档入库、切分、向量化,员工提问时做混合召回、路由判断、大模型生成答案(本工程基于 FastAPI + LangGraph + ChromaDB,带 BM25 + 向量双路召回和置信度路由)。

现在的需求很朴素:不想再让人打开网页查资料,直接在日常用的飞书里问就行。

飞书机器人在这里只是一个薄适配层:

  • 接住飞书里发来的消息;
  • 把问题转给本地知识库的 /ask 接口;
  • 把知识库返回的答案,再发回飞书会话。

模型层、检索、权限隔离全部复用知识库本体,对接这一层不改模型逻辑。

二、为什么选飞书,而不是企业微信

接入 IM 客服有两种部署思路,我们的约束是:先在局域网内测通,以后再上云。

维度飞书企业微信
本地/局域网测试官方支持长连接(WebSocket),本地主动连飞书收事件,无需公网 IP、域名、可信证书、内网穿透回调强制公网 HTTPS + 可信证书 + 备案域名,本地联调必须先上穿透
上云后入口可继续用长连接,也可切 Webhook仍需公网 HTTPS 可信域名
对知识库的适配取文本 + 身份 → 调 /ask → 回传,模型层零改动同左,模型层零改动
身份体系飞书 open_id 直接复用知识库的顾客身份头,零账户成本userid 同构映射,成本相近

在"先局域网测、再上云"这个前提下,飞书的长连接把测试期的公网依赖降到了零,所以选飞书。

三、整体架构:一条消息的完整旅程

先放一张整体链路图:

飞书员工单聊机器人
   │  ① 消息经飞书云端
   ▼
飞书 wss 长连接(事件 im.message.receive_v1)
   ▼
feishu_kb_bot.py(本地独立进程,lark-oapi SDK)
   │  ② HTTP POST 本地知识库 /ask
   │     头 X-WX-OPENID = 飞书 open_id
   │     body { query, thread_id, mode }
   ▼
知识库本体 service/run_server.py(FastAPI,端口 8011)
   │  ③ 混合召回 → 路由 → 大模型生成 answer
   ▼
bot 调飞书"以机器人身份发消息"接口,把 answer 回给用户
   ▼
飞书云端推回员工手机/客户端

这里有一个反直觉但很关键的点:不是飞书云端主动来敲你电脑的门,而是你电脑上的 bot 进程主动向外拨出一条一直挂着的 WebSocket 连接,飞书云端顺着这条已经建好的连接把消息推回来。连接是"出向"的,所以不需要在路由器上开端口、不需要公网地址。

两条容易混淆的通道

飞书云端和 bot 之间其实是两条通道:

方向通道协议作用
飞书 → bot(下行收消息)wss://msg-frontier.feishu.cn/ws/v2WebSocket 长连接把 im.message.receive_v1 事件帧持续推下来
bot → 飞书(上行发消息)开放平台 REST 接口HTTPS POST换取访问凭证、调"发送消息"接口把答案回上去

两条都是电脑主动向外发起的:长连接负责"收",HTTPS REST 负责"发"。

一条消息的时序

  1. 员工在飞书客户端发消息,先到飞书云端;
  2. 云端判断这条消息属于哪个自建应用,找到该应用挂着的长连接;
  3. 云端通过 wss 把事件帧推给本地 bot;
  4. bot 解析出发送者 open_id、chat_id、消息文本;
  5. bot 起一个后台线程,调本地知识库 /ask;
  6. 知识库检索、路由、生成,返回 answer;
  7. bot 用应用凭证换 tenant_access_token,调飞书发消息接口,回写到对应会话;
  8. 云端再把这条消息推到员工客户端,用户看到回复。

耗时查询被甩到后台线程处理,是为了规避飞书事件 3 秒超时重试导致的重复回答。

bot 与知识库之间的接口约定

bot 调知识库只用一个接口 POST /ask,约定如下:

POST {KB_BASE_URL}/ask
Content-Type: application/json
X-WX-OPENID: <飞书 open_id>

{
  "query": "用户的问题",
  "thread_id": "feishu_{open_id}",
  "mode": "auto"
}
  • 身份头 X-WX-OPENID:把飞书 open_id 直接传进去,走知识库的公开库(全员可见)身份,零账户成本;
  • 会话隔离键 thread_id = feishu_{open_id}:每个飞书用户的多轮上下文各自独立,不串号;
  • 返回结构:answer(回复正文)、citations(参考来源)、confidence(置信度)、route(路由结果)、escalate_reason(转人工原因)等;bot 只把 answer 回给飞书,citations 打到终端日志备查。

知识库是本地自签 HTTPS,bot 调用时关闭了证书校验(仅局域网测试用;上云后换可信证书可去掉)。

四、工程里都有哪些文件,各自干什么

文件作用
feishu_kb_bot.py飞书长连接 bot 主脚本。内部分四块:handle_message 收事件、取 open_id/chat_id/文本并起后台线程;call_kb 调知识库 /ask、带身份头与会话隔离;reply 以机器人身份回文本消息;_worker 在后台线程里执行查询与回复
feishu_bot.env本地配置:飞书 App ID / Secret、知识库地址(含 Secret,不要提交仓库)
feishu_bot.env.example配置模板(占位值),换机或新环境时复制成 feishu_bot.env 照着填
start_bot.bat一键启动 bot:在工程根目录调用 .venv Python,-u 无缓冲输出
service/run_server.py知识库本体服务入口(FastAPI,监听 8011,自签 HTTPS)
service/kb_core.pyLangGraph 状态图、混合召回、会话持久化、置信度路由 / 人工闸核心
service/requirements.txtPython 依赖清单:知识库本体依赖 + 飞书 bot 依赖 lark-oapi
service/ui/admin.html知识库管理台页面

虚拟环境 .venv(Python 3.12.8)放在工程上级目录,工程内脚本统一用这个环境的解释器。bot 脚本依赖 requests、python-dotenv 和 lark-oapi;知识库本体依赖 FastAPI、LangGraph、ChromaDB、jieba、python-docx、openai 等(完整清单见 requirements.txt)。

bot 脚本内部是怎么分工的

feishu_kb_bot.py 本身不长,职责拆得很清楚:

  • handle_message(data):长连接事件回调。先判断消息类型,只处理 text,图片 / 语音 / 卡片直接忽略;从事件里取出发送者 open_id、会话 chat_id 和文本,空文本跳过;随后丢给后台线程,自己立刻返回,避免触发飞书 3 秒事件超时重试。
  • call_kb(query, open_id):拼出 thread_id = feishu_{open_id},向知识库 /ask 发 POST,带头 X-WX-OPENID;自签 HTTPS 关闭证书校验,超时 60 秒。返回的 answer 作为回复内容,citations(参考来源)只打到终端日志,不发给飞书用户,避免暴露机器化出处。
  • reply(chat_id, text):用机器人身份发一条文本消息,receive_id_type=chat_id,单聊和群聊都兼容。
  • _worker(...):后台守护线程,串行执行"调知识库 → 回消息",异常只记日志不崩溃。

五、飞书 SDK 到底帮我们做了什么

接入用的是官方 Python SDK lark-oapi。先回答一个常见疑问:是不是装了 SDK 才能和飞书通讯?

通讯的本质是"一条出向 WebSocket 长连接 + 应用凭证鉴权"。SDK 不是通讯本身,而是把这套协议细节封装好的工具。它替我们做了这些事:

  • 建连与握手:用 App ID / App Secret 完成 wss 拨号和鉴权,确认这条连接属于哪个合法应用;
  • 保活与重连:维持心跳,断线后自动重连;
  • 事件解析:把云端推下来的协议帧解析成结构化对象(如 P2ImMessageReceiveV1),再分发给我们注册的回调函数;
  • 发消息封装:封装"发送消息"REST 调用,并自动管理访问凭证的刷新。

对应到代码里就是这几处:

# 注册接收消息事件的回调
handler = (
    EventDispatcherHandler.builder("", "")
    .register_p2_im_message_receive_v1(handle_message)
    .build()
)

# 建立长连接
ws_client = WSClient(FEISHU_APP_ID, FEISHU_APP_SECRET, event_handler=handler)
ws_client.start()

# 以机器人身份发消息
send_client = lark.Client.builder() \
    .app_id(FEISHU_APP_ID) \
    .app_secret(FEISHU_APP_SECRET) \
    .build()

如果不装 SDK,理论上也能用 websockets 库手写握手、心跳、帧解析和重连,再用 requests 调 REST 接口;但要自己处理协议版本、加密、断线重连、凭证过期,成本高且容易踩坑。SDK 就是把这些标准化、省事而已。

六、从 0 到 1 接入步骤

6.1 先把知识库本体跑起来

接入前先确认三个前置条件:

  1. 知识库本体已在 https://127.0.0.1:8011 运行,健康检查通过;
  2. 本机能够出网访问飞书 wss(长连接是出向连接,不需要在路由器上开放入站端口,大多数公司局域网都满足);
  3. 已在飞书开放平台创建好企业自建应用(见 6.2)。

bot 是去调知识库的,所以知识库必须先在线:

cd D:\Work\langgraph\案例8.enterprise_kb\service
D:\Work\langgraph\.venv\Scripts\python.exe run_server.py

健康检查通过即可:

GET https://127.0.0.1:8011/health

返回 chat_available: true 说明模型和知识库就绪。(本工程是自签 HTTPS,调用时需跳过证书校验。)

6.2 飞书开放平台后台配置(一次性)

打开 飞书开放平台,用你装了飞书的同一账号登录,进入「开发者后台」。整个过程分六步:

① 创建企业自建应用

  • 在后台点「创建企业自建应用」;
  • 填写应用名称(本工程叫"AI 客服")、一句话描述,上传应用图标;
  • 创建完成后进入应用详情页。

长连接只支持企业自建应用,不支持商店应用。

② 记录凭证

在「凭证与基础信息」页记下 App ID 和 App Secret,后面填进本地 env。Secret 属敏感凭证,不要写进公开文章,也不要提交到代码仓库。

③ 添加机器人能力

在「应用能力」里确认已添加机器人;如果没有,先把机器人能力加上,否则应用无法收发消息。

④ 开通权限

在「权限管理」里开通以下 API 权限:

  • im:message.p2p_msg:readonly:读取用户发给机器人的单聊消息;
  • im:message.group_msg:readonly:群聊 @机器人才需要,可选;
  • im:message:send_as_bot:以机器人身份发消息。

⑤ 订阅事件

在「事件与回调」里:

  • 订阅方式选使用长连接接收事件;
  • 添加事件 im.message.receive_v1(接收消息 v2.0),应用身份订阅;
  • 长连接模式下 Verification Token、Encrypt Key 留空。

如果保存时提示需要长连接在线,可以先把 bot 跑起来建上连接,再回到后台保存事件订阅。

⑥ 创建版本并发布

权限、事件、机器人能力改完后,到「版本管理与发布」创建版本并发布,经企业管理员审核通过后线上才生效。后台改了配置但不发布,不会生效。

6.3 本地配置 env

在工程根目录写 feishu_bot.env:

FEISHU_APP_ID=cli_aa6d954d1178dc03
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # 应用密钥,属敏感凭证,公开文章中不写明文
KB_BASE_URL=https://127.0.0.1:8011
  • KB_BASE_URL 是知识库地址;同机部署用 127.0.0.1,跨机部署改成知识库所在机器的局域网 IP;
  • 后台如果重置过 Secret,这里要同步更新。

6.4 安装依赖

$py = "D:\Work\langgraph\.venv\Scripts\python.exe"
& $py -m pip install -r service\requirements.txt

requirements.txt 里分两组:

  • 知识库本体:fastapi、uvicorn、python-multipart、langgraph、langgraph-checkpoint-sqlite、chromadb、jieba、python-docx、openai、python-dotenv、requests;
  • 飞书 bot:lark-oapi,它会自带 websockets、pycryptodome、httpx、requests_toolbelt。

注意:飞书 SDK 这种第二方依赖一定要写进 requirements.txt。如果只在当时环境里手动装过,下次重建虚拟环境就会丢。

6.5 启动 bot

必须在工程根目录启动(脚本按相对路径读 feishu_bot.env)。建议用 -u 无缓冲启动,否则日志重定向到文件时会被 Python 块缓冲,长时间看不到输出。

cd D:\Work\langgraph\案例8.enterprise_kb
$env:PYTHONUNBUFFERED="1"
D:\Work\langgraph\.venv\Scripts\python.exe -u feishu_kb_bot.py

或者直接双击配套的 start_bot.bat。

需要后台常驻运行(隐藏窗口、日志落盘)时:

$dir = "D:\Work\langgraph\案例8.enterprise_kb"
$py  = "D:\Work\langgraph\.venv\Scripts\python.exe"
Start-Process -FilePath $py -ArgumentList "-u","feishu_kb_bot.py" `
  -WorkingDirectory $dir -WindowStyle Hidden `
  -RedirectStandardOutput "$dir\feishu_bot.log" `
  -RedirectStandardError  "$dir\feishu_bot.err.log"

启动成功的标志:日志里出现

[Lark] INFO connected to wss://msg-frontier.feishu.cn/...

看到这行,说明长连接已经建立、鉴权通过。如果在后台配置事件订阅时提示需要长连接在线,可以先把 bot 跑起来建上连接,再回到开放平台保存事件订阅。

6.6 验证闭环

按从内到外的顺序验证:

  1. 知识库健康:/health 返回 200,chat_available: true;
  2. bot 长连接:日志出现 connected to wss://...,无鉴权报错;
  3. 知识库 /ask 自测(不经过飞书,先确认本体能答):
$body = @{
    query     = "这款衣服有 M 码吗?什么时候补货?"
    thread_id = "feishu_diag_test"
    mode      = "auto"
} | ConvertTo-Json

Invoke-WebRequest "https://127.0.0.1:8011/ask" -Method POST -Body $body `
  -ContentType "application/json" `
  -Headers @{ "X-WX-OPENID" = "diag_openid_001" } `
  -SkipCertificateCheck
  1. 飞书端到端:单聊机器人发一条问题,能收到答案;bot 日志会打印对应的参考来源。

七、几个容易困惑的问题

手机不连 WiFi,用流量能在飞书里聊吗?

能。 飞书对话这条链路里,手机只跟飞书云端打交道,走手机自己的网络(WiFi 或 4G/5G 都行),并不直连你电脑。前提是电脑这一侧开机、bot 和知识库都在线、电脑能出网连上飞书。

要区分的是另一条路:如果用浏览器打开 https://172.17.16.46:8011/ui/chat.html 这种局域网地址的网页版知识库,那手机必须和电脑在同一 WiFi 才能访问;飞书机器人对话不受这个限制。

为什么这套不需要公网 IP、域名和备案证书?

因为消息接收走的是出向长连接:电脑主动连出去并挂着,飞书顺着这条连接把事件推回来,不需要飞书主动穿透内网找电脑,也就不需要入站端口、公网地址和可信证书。上云之后如果切到 Webhook 回调模式,才需要公网 HTTPS + 备案域名。

有没有单独的"API Key"?

飞书侧没有独立的 API Key 概念,鉴权用的就是应用凭证 App ID + App Secret:建长连接握手时校验一次,发消息时用它换 tenant_access_token。知识库侧也不校验 Key,靠 X-WX-OPENID 头区分用户身份。

不同员工的会话怎么隔离?

thread_id 拼成 feishu_{open_id},每个飞书用户的多轮上下文各自独立,不会串号。身份上,飞书 open_id 直接作为知识库的 X-WX-OPENID,走公开库(全员可见文档),零账户成本。

如果以后要按部门隔离(比如 HR 只能看 HR 文档):把 call_kb 里的 X-WX-OPENID 换成 Authorization: Bearer <知识库企业账户 token>,并为每个飞书 open_id 维护一张 open_id → 部门账户 的映射表即可,其余逻辑不变。

八、当前版本的边界

接入时需要知道这套实现目前做到哪一步、哪些还没做:

  • 只处理文本消息:图片、语音、交互卡片当前直接忽略,需要的话再在 handle_message 里扩展对应类型;
  • 多实例时消息随机分发:长连接模式下,如果同一应用挂了多个 bot 实例,事件只会随机分给其中一个客户端;单 bot 部署不受影响;
  • 公开库模式:所有飞书用户走全员可见文档,部门级隔离按第七节的方案后续补;
  • 知识库自签证书:本地联调关闭了证书校验,上云换可信证书后建议去掉 verify=False。

九、落地中值得记下的经验

  • 依赖一定要写进 requirements.txt:飞书 SDK 这种易被忽略的第二方依赖,如果只在当时的环境里手动装过,下次重建虚拟环境就会丢。
  • 启动加 -u:日志落盘时 Python 默认块缓冲,不加无缓冲参数会"看似没反应"。
  • 首次导入 SDK 可能较慢:机械盘/慢盘上加载整条依赖链要等一会儿,看到进程在、别当成卡死,等长连接日志出现即可。
  • 虚拟环境进程是父子一对:任务管理器里 .venv\Scripts\python.exe 父进程会派生一个系统解释器子进程实际干活,看到两个 python 不要误判成重复启动。

十、后续可以演进的方向

  • 上云常开:把 bot 脚本和知识库部署到一台常开服务器;长连接模式仍免公网域名和证书。
  • 会话存储换 Redis:当前用本地 SqliteSaver,多实例部署时可换成 Redis 后端。
  • 部门级知识隔离:补 open_id → 部门 映射,按部门返回对应文档。
  • 更多消息类型:当前只处理文本消息,图片、语音、卡片可按需扩展。

小结

整套接入的核心思路一句话:飞书侧负责把消息事件通过长连接送下来,本地 bot 做一层薄适配去调知识库,再把答案回写飞书。 真正的业务能力都在知识库本体,机器人这一层只做"翻译和转发"。选长连接,是为了让局域网测试零公网依赖;把依赖、配置、启动方式固化下来,换机重建时照着文档顺序起服务即可。