企业知识库 × 飞书机器人 ------ 从 0 到 1 接入
把一个本地跑的 LangGraph 企业知识库 RAG 系统,接上飞书机器人:员工在飞书里直接提问,机器人检索知识库后把答案回过来。本文讲清整条链路、每个文件和 SDK 各干什么,以及"为什么局域网就能跑、不需要公网域名"。
一、先想清楚:我们到底要做什么
假设你已经有一套企业知识库系统:文档入库、切分、向量化,员工提问时做混合召回、路由判断、大模型生成答案(本工程基于 FastAPI + LangGraph + ChromaDB,带 BM25 + 向量双路召回和置信度路由)。
现在的需求很朴素:不想再让人打开网页查资料,直接在日常用的飞书里问就行。
飞书机器人在这里只是一个薄适配层:
- 接住飞书里发来的消息;
- 把问题转给本地知识库的
/ask接口; - 把知识库返回的答案,再发回飞书会话。
模型层、检索、权限隔离全部复用知识库本体,对接这一层不改模型逻辑。
二、为什么选飞书,而不是企业微信
接入 IM 客服有两种部署思路,我们的约束是:先在局域网内测通,以后再上云。
| 维度 | 飞书 | 企业微信 |
|---|---|---|
| 本地/局域网测试 | 官方支持长连接(WebSocket),本地主动连飞书收事件,无需公网 IP、域名、可信证书、内网穿透 | 回调强制公网 HTTPS + 可信证书 + 备案域名,本地联调必须先上穿透 |
| 上云后入口 | 可继续用长连接,也可切 Webhook | 仍需公网 HTTPS 可信域名 |
| 对知识库的适配 | 取文本 + 身份 → 调 /ask → 回传,模型层零改动 |
同左,模型层零改动 |
| 身份体系 | 飞书 open_id 直接复用知识库的顾客身份头,零账户成本 |
userid 同构映射,成本相近 |
在"先局域网测、再上云"这个前提下,飞书的长连接把测试期的公网依赖降到了零,所以选飞书。
三、整体架构:一条消息的完整旅程
先放一张整体链路图:
bash
飞书员工单聊机器人
│ ① 消息经飞书云端
▼
飞书 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/v2 |
WebSocket 长连接 | 把 im.message.receive_v1 事件帧持续推下来 |
| bot → 飞书(上行发消息) | 开放平台 REST 接口 | HTTPS POST | 换取访问凭证、调"发送消息"接口把答案回上去 |
两条都是电脑主动向外发起的:长连接负责"收",HTTPS REST 负责"发"。
一条消息的时序
- 员工在飞书客户端发消息,先到飞书云端;
- 云端判断这条消息属于哪个自建应用,找到该应用挂着的长连接;
- 云端通过 wss 把事件帧推给本地 bot;
- bot 解析出发送者
open_id、chat_id、消息文本; - bot 起一个后台线程,调本地知识库
/ask; - 知识库检索、路由、生成,返回
answer; - bot 用应用凭证换
tenant_access_token,调飞书发消息接口,回写到对应会话; - 云端再把这条消息推到员工客户端,用户看到回复。
耗时查询被甩到后台线程处理,是为了规避飞书事件 3 秒超时重试导致的重复回答。
bot 与知识库之间的接口约定
bot 调知识库只用一个接口 POST /ask,约定如下:
http
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.py |
LangGraph 状态图、混合召回、会话持久化、置信度路由 / 人工闸核心 |
service/requirements.txt |
Python 依赖清单:知识库本体依赖 + 飞书 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 调用,并自动管理访问凭证的刷新。
对应到代码里就是这几处:
python
# 注册接收消息事件的回调
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 先把知识库本体跑起来
接入前先确认三个前置条件:
- 知识库本体已在
https://127.0.0.1:8011运行,健康检查通过; - 本机能够出网访问飞书 wss(长连接是出向连接,不需要在路由器上开放入站端口,大多数公司局域网都满足);
- 已在飞书开放平台创建好企业自建应用(见 6.2)。
bot 是去调知识库的,所以知识库必须先在线:
powershell
cd D:\Work\langgraph\案例8.enterprise_kb\service
D:\Work\langgraph\.venv\Scripts\python.exe run_server.py
健康检查通过即可:
arduino
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:
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 安装依赖
powershell
$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 块缓冲,长时间看不到输出。
powershell
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。
需要后台常驻运行(隐藏窗口、日志落盘)时:
powershell
$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"
启动成功的标志:日志里出现
arduino
[Lark] INFO connected to wss://msg-frontier.feishu.cn/...
看到这行,说明长连接已经建立、鉴权通过。如果在后台配置事件订阅时提示需要长连接在线,可以先把 bot 跑起来建上连接,再回到开放平台保存事件订阅。
6.6 验证闭环
按从内到外的顺序验证:
- 知识库健康 :
/health返回 200,chat_available: true; - bot 长连接 :日志出现
connected to wss://...,无鉴权报错; - 知识库
/ask自测(不经过飞书,先确认本体能答):
powershell
$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
- 飞书端到端:单聊机器人发一条问题,能收到答案;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 做一层薄适配去调知识库,再把答案回写飞书。 真正的业务能力都在知识库本体,机器人这一层只做"翻译和转发"。选长连接,是为了让局域网测试零公网依赖;把依赖、配置、启动方式固化下来,换机重建时照着文档顺序起服务即可。