项目复盘 · 企业微信智能客服「阿全」

阿全知识助手全链路沉淀

这不是单次 VR 一体机模块更新的复盘，而是一次把阿全从知识策划、产品线架构、视频素材、企业微信客服链路、测试发布到后续运维完整梳理清楚的沉淀。VR 99 模块更新只是其中一个可复用案例。

时间：2026-07-07 范围：VR一体机 / PCVR / 视频链接 / 企业微信客服线上状态：服务 active，健康检查 ok

一、知识版图：阿全不是单一模块库

阿全服务的是宇见希行 VR 安全培训业务，核心不是“问答机器人”，而是面向销售咨询的知识助手。它需要同时理解产品线差异、模块目录、行业组合、演示视频、FAQ 和人工转接边界。

99VR 一体机新版模块

176PCVR 模块总数

76线上视频索引

2线上 Chroma collection

知识域	用途	关键边界
VR 一体机	回答一体机软件、模块清单、安全月套餐、适用场景。	新版以 Word 文档为权威来源，当前是 99 模块、13 类别、5 套餐。
PCVR	回答 PC VR 软件版、行业包、场馆型培训、高画质和外设联动需求。	PCVR 是独立产品线，不能和 VR 一体机模块数量混算。
安全体感设备	回答实体安全体验设备、训练装置、硬件组合。	不要让旧首页里的 VR 模块摘要误归入体感设备。
视频素材	客户要看效果、演示、场景时，回复短链视频。	目前微信客服侧只主动承诺 VR 一体机演示视频，PCVR 视频要谨慎处理。
企业微信客服流程	接收消息、同步客服会话、AI 回复、转人工、结束会话、满意度评价。	客服状态为人工接入或会话关闭时，AI 不应越权回复。
工厂专属知识库	复用同一套客服框架服务其他客户，例如盈峰工具。	通过独立 collection 和 prompt 隔离，不能串用 VR 知识。

这次漏写的根因：我把 HTML 标题和内容收窄成“VR 一体机更新复盘”，没有按“整个知识助手”来总结，所以 PCVR、视频链接、客服链路这些真实组成部分没有展开。正确口径应是全景架构，VR 99 模块是案例。

二、整体架构：消息、检索、生成、媒体四层协同

阿全的架构可以拆成四层：企业微信消息层负责接入与状态管理，知识层负责结构化和向量检索，生成层负责组织自然语言，媒体层负责把视频与图片以微信可点开的方式附到回复里。

企业微信接入层

main.py 处理普通 webhook、微信客服 kf/sync_msg、客服事件、会话状态、转人工、二维码和满意度菜单。Webhook 快速返回，实际处理放后台任务，避免企业微信超时。

知识检索层

knowledge/ingest.py 负责文档、网页、视频转录、汇总文本入库；knowledge/retriever.py 用 BGE embedding 检索 ChromaDB，并把 type=summary 的 chunk 排到前面。

回答生成层

agent/chat.py 用 DeepSeek 生成适合微信聊天的回复。系统提示明确区分 VR 一体机、PCVR、安全体感设备、培训管理软件，并约束不说“根据知识库”。

媒体短链层

视频 URL 存在 Chroma metadata 中，启动时构建 video_id -> full_url 内存索引。回复时把长视频链接转成 https://wecom.yjxxdesign.com/v/Sxx，由 /v/{id} 302 跳转。

三、检索设计：产品线分流比“多塞资料”更重要

阿全最容易出错的地方，不是资料少，而是相似主题太多：VR 一体机里有高处坠落，PCVR 也有高处坠落；一体机有消防逃生，PCVR 也可能有消防场景。检索结构必须让模型先知道产品线，再看具体模块。

VR 一体机

适合企业安全教育、新员工培训、班组轮训和安全月活动。新版结构是 99 模块、13 类别、5 套餐。入库粒度包括总览、数量问答、分类明细、单模块详情和安全月套餐。

PCVR

适合对画面、沉浸感、多人轮训、外设联动和复杂事故推演要求更高的场馆。当前文本源显示 176 模块、15 分类方向，入库脚本会抓取 PCVR 页面或整页清单作为 PCVR 产品线摘要。

安全体感设备

回答实体模拟设备和训练装置，不应混入 VR 模块数量。旧首页抓取曾把“85项实景模拟”误带进体感设备摘要，本次发布已在线上清掉同类冲突。

工厂专属知识

盈峰工具使用 factory_yingfeng_tools collection 和独立 prompt，只回答该工厂产品。这个机制证明阿全架构可复用，但必须保持知识域隔离。

chunk 策略

chunk 类型	解决的问题	适用示例
产品线总览	先告诉模型这是 VR 一体机、PCVR 还是体感设备。	“VR一体机和PCVR有什么区别？”
数量问答	让“有多少个模块”这种泛问稳定命中总数。	“VR一体机现在几个模块？”
分类明细	支持列表型、类别型咨询。	“触电类有哪些？”“消防专项有哪些？”
单模块详情	支持精确模块名检索，尤其是新模块和长名称。	“HID电箱断路器短路打火是什么？”
媒体 metadata	检索命中内容后附带相关视频或图片。	“有汽车吊倾覆演示视频吗？”

四、视频链接体系：素材不是附件，是销售对话的一部分

阿全的视频体系有两个目标：让客户在微信里点开就能看效果，同时避免每次回复都塞视频。代码里明确只有客户问“VR视频、想看效果、看视频、演示、场景、怎么操作”等语境时，才更积极地附带演示视频。

视频入库

scripts/transcribe_video.py 可把视频转录文本和视频 URL 一起写入知识库。视频 URL 存在 metadata 的 video_url 字段里。

启动索引

服务启动时扫描 Chroma metadata，把 S21-攀爬坠落.mp4 或 S47 起重作业十不吊下.mp4 解析成视频 ID 和中文名。线上当前视频索引是 76 条。

短链输出

客户看到的是 https://wecom.yjxxdesign.com/v/S21 这样的短链，不是 COS 或 R2 长链接。短链路由再 302 跳转到真实视频地址。

回复策略

VR 一体机可以主动推荐代表性视频，例如“汽车吊倾覆”。PCVR 视频目前不在微信客服侧承诺提供，避免把没有准备好的素材说满。

视频回复形态：
攀爬坠落：https://wecom.yjxxdesign.com/v/S21

短链路由：
GET /v/{id} -> 从 _VIDEO_INDEX 查 full_url -> 302 Redirect

五、客服链路：AI 回复必须服从会话状态

企业微信客服不是普通聊天窗口，它有会话状态、人工接入、事件通知、菜单消息和会话结束。阿全的稳定性来自两个原则：Webhook 快速确认，业务处理异步执行；AI 只在允许回复的状态下介入。

环节	实现要点	风险控制
消息接入	企业微信回调只通知，实际文本通过 `kf/sync_msg` 拉取。	消息 ID 去重，避免重复回复。
AI 回复	检索命中后调用 DeepSeek，结合上下文历史生成自然回复。	答不上触发转人工或扫码菜单，不编造价格、库存和承诺。
人工接入	会话进入人工状态后，AI 不继续插话。	客户选择继续向 AI 提问时，再恢复 AI 接待。
多客服隔离	不同 open_kfid 映射不同 scope 和 collection。	盈峰工具等工厂客服禁止串用 VR 知识。
服务发布	systemd 管理 `wecom-ai`，FastAPI 监听 `127.0.0.1:8000`。	发布前备份 Chroma，发布后检查 health 和日志。

六、测试与发布：从真实问法和线上约束反推流程

测试不能只看“文件已入库”。这类知识助手要测四件事：检索首屏是否拿到正确产品线，旧知识是否残留，视频短链是否可索引，客服服务是否健康。

测试项	本次验证	沉淀规则
VR 数量问法	“VR一体机现在有多少个模块？”首条命中 99 模块、13 类别。	数量问法需要单独短摘要，不要只靠长总览。
新增模块问法	“HID电箱断路器短路打火”命中 NO.95 单模块详情。	新增长名称必须做单模块 chunk。
套餐问法	“安全月工厂套餐推荐哪些模块？”命中安全月套餐推荐。	销售组合要单独建 chunk，不要散在模块表里。
旧知识冲突	线上旧“85项/85个”残留清零。	发布前后都要 grep/扫描冲突词。
视频索引	线上 `/health` 显示视频索引 76 条。	视频是检索 metadata，不是正文里手工拼链接。

发布中的真实约束

远端服务器无法访问 HuggingFace，直接运行 SentenceTransformer("BAAI/bge-small-zh-v1.5") 会尝试联网并失败。所以最终采用“本地生成并验证 embeddings，线上局部 upsert”的方式发布 VR chunk，避免覆盖远端其他 collection 和新增知识。

线上发布后校验：
knowledge_base total = 283
L1-VR一体机 chunk = 115
旧 85 项残留 = 0
服务状态 = active
健康检查 = ok
视频索引 = 76

七、可复用清单：下一次更新照这个走

策划

确认权威来源、保留策略和必须变准的问法。
明确产品线边界，尤其是 VR 一体机与 PCVR 不混算。
把视频素材视为知识资产的一部分，而不是最后附加物。

架构

原始文档、结构化源、向量库分层。
按产品线、类别、模块、套餐、视频 metadata 组织 chunk。
多客服/多客户用独立 collection 和 prompt 隔离。

实施

从文档抽取 JSON，再由脚本生成检索 chunk。
保留单模块详情，补数量问答和套餐摘要。
清理旧官网、旧 FAQ、误分类摘要中的冲突事实。

测试

用真实销售问法测试检索首屏。
检查视频索引、短链、health 和 systemd 日志。
移动端 HTML 必须检查 390px 无横向撑屏。

下一步建议

把这套经验固化成三个脚本：知识源抽取脚本、离线 embedding 导出/导入脚本、冲突词扫描脚本。这样以后更新 PCVR 模块、视频素材、FAQ 或新客户知识库时，就不需要临场拆流程。

全景范围：VR一体机、PCVR、视频、客服链路交付形态：单文件 HTML 阅读优先：桌面与移动端