MaxKB工作流知识库：图片音频视频统一接入与问答实践

多模态知识库这件事，我是被实际需求逼着开始做的。最开始我的 MaxKB 知识库里全是 PDF、Word、TXT，文本问答跑得很顺，直到业务方丢过来一批产品界面截图、设备操作培训视频和现场会议录音，说"这些也要能查、能答"，我才意识到一个很现实的问题：很多关键业务知识根本不是文字，而是长在图片、音频、视频里的。纯文本知识库对这些内容基本是睁眼瞎，要么直接不识别，要么只抽取了文档里夹带的那点文字，丢掉了真正有价值的部分。后来我把 MaxKB 的工作流知识库完整用了一遍，把图、音、视三种模态统一收编到同一个库里，再通过工作流节点接进问答应用，才算真正把这块补上了。这篇内容会把整体思路、操作链路、参数配置和踩坑记录都整理出来，适合正在用 MaxKB、或是准备从纯文本 RAG 往多模态扩展的团队参考。

1. 先搞明白：多模态知识库到底解决什么问题

1.1 传统文本知识库的尴尬

我服务过的一个模拟项目里，知识库里有数百份设备操作手册，每一份手册里都有大量截图，标注了"点击右上角设置按钮""如下图红框所示"之类的关键信息。但是传统知识库在解析 PDF 时，只会把里面能提取到的文字抽出来，图片部分要么被丢弃，要么只留一个孤立的占位符。用户问"这个参数在哪里调整"，答案是能找到，但用户紧接着追问"界面上长什么样"，就完全没有内容可以回了。

音频和视频就更不用提了。传统知识库基本不支持直接上传 mp3、mp4 这类文件，就算勉强传上去，也没法做内容索引。但会议室、培训室、车间现场，恰恰是大量隐性经验产生的地方：老师傅的操作口述、项目复盘录音、新员工培训视频。这些内容如果进不了知识库，那整个问答系统覆盖的知识就是残缺的。

所以多模态知识库要解决的核心问题，不是"能不能上传"这种存储层面的事情，而是"能不能检索、能不能引用"。一张截图、一段录音，用户要的不是把原文件翻出来，而是让系统理解里面的内容，在问答中给出准确回复，并且顺带把对应的原始文件或片段指给他看。MaxKB 的工作流知识库正好把这条链路打通了。

1.2 工作流知识库的定位与其他类型有本质区别

MaxKB 的知识库其实分好几种，普通知识库适合直接做问答检索，返回的是命中的文本切片；而工作流知识库是专门为"应用工作流调用"设计的，它支持更丰富的文档类型，尤其是图片、音频、视频这类非文本文件，并且检索结果里可以携带结构化字段和原始文件引用信息。

换句话说，普通知识库回答问题的模式是"把命中的文本喂给大模型生成回答"；工作流知识库的玩法是"把命中的内容和对应的文件引用一起交给工作流，由工作流决定怎么展示、怎么加工"。对于多模态场景，这个差别是致命的。因为图片、音频、视频的价值在于它本身，而不是那一行提取出来的文字。用户在聊天界面里看到一段文字说"培训视频第 3 分钟讲的是安全帽佩戴规范"，远不如直接看到一个可播放的视频片段来得直观。

1.3 典型场景盘点：哪些业务内容最需要多模态

从我做过的实际需求来看，下面这几类场景对多模态知识库的需求最迫切。

这些场景有一个共同特点：答案的主体信息不在文字里，而在多媒体文件里，或者只有结合多媒体文件才能把问题讲清楚。纯文本方案解决不了，硬靠人工整理又费时费力。用工作流知识库把图、音、视统一管理起来，是投入产出比最高的做法。

2. 整体设计拆解：一条数据是怎么变成"知识"的

2.1 核心思路：文本化索引加原始文件引用

在做多模态知识库之前，我最困惑的一个问题是：大模型和向量检索本质上是处理文本的，图片和视频怎么参与相似度计算？难道真要跑一遍图像向量模型？实际操作下来，MaxKB 工作流知识库采用的是一个非常务实的思路，我把它总结成八个字：文本化索引、文件引用。

什么叫文本化索引？就是无论你丢进来的是图片、录音还是视频，系统都会先做内容提取——图片做 OCR 文字识别，音频做语音转写，视频先抽音轨再做转写——把非文本内容变成一段可以被分块、被向量化的文本。这样一来，向量检索、语义匹配这些成熟的技术就都能用上了。

但只提取文本还不够，否则和普通文本知识库没区别。所以要加第二层：文件引用。每一个文本分块都会绑定原始文件的 ID、路径或者访问地址。检索命中的时候，不仅返回命中的文本切片，还把对应的原始文件引用一起带出来。问答应用拿到这些引用，就能在回复里展示图片、播放视频片段。整个设计很像给一本书做索引目录，目录负责让你找到内容，书本身才是阅读对象。

2.2 三种模态的处理链路对比

图片、音频、视频虽然都归到多模态，但处理链路并不完全一样，拆开看更清楚。

图片的处理相对直接：上传后进入 OCR 解析，把图中出现的文字提取出来，再配合图片文件名、备注信息一起形成文本描述。如果图片本身是截图，OCR 效果通常很好；如果是一张产品实拍图，只有少量文字标识，那 OCR 只能提取出局部文字，这时候建议在上传时通过命名或备注补充描述信息，我的习惯是文件名就把画面内容写明白，比如"设备A电源指示灯故障状态.png"，检索效果会好很多。

音频的处理核心是语音转写。系统把音频文件送进 ASR 模型，生成带时间戳的转写文本，然后按时间窗口分块。带时间戳这个细节很关键，因为用户在问答中可能需要定位到"录音第几分钟说了什么"，时间戳就是定位的依据。没有时间戳的纯转写文本，分块后很难回溯源文件的具体位置。

视频是最复杂的，因为它同时包含画面和声音。工作流知识库的处理链路一般是：先抽取音轨，对声音部分做语音转写；画面部分则依赖关键帧抽取和 OCR 识别字幕或画面内文字。如果你手里的视频是培训录屏、操作演示，画面信息密度很高，建议在上传前做一点预处理，比如用剪辑工具导出关键截图作为补充材料；如果不做，纯靠音轨转写也能覆盖大部分问答需求，但会丢失操作步骤的可视化信息。

2.3 为什么选工作流知识库而不是普通知识库

我在搭建初期其实先试过普通知识库，踩了个不小的坑。普通知识库对多模态文件的支持很有限，就算上传进去了，问答时返回的也只有文本切片，原文件引用很难透传到应用端。这就导致用户问完问题得到一段文字回答，却看不到原始的图片或视频，体验非常割裂。

工作流知识库的定位决定了它天生适合这条路。在工作流里，知识库检索是一个独立节点，它接收用户问题，输出结构化结果，结果里既包含文本切片，又包含文件引用的元数据。后面的流程节点可以自由决定怎么用这些数据：可以拼进提示词让大模型总结，可以让大模型决定什么时候展示原图，也可以通过接口把文件地址返回给前端播放。每一步都是可编排的，而不是像普通知识库那样被固定死的问答逻辑。

另外，工作流知识库还有一个应用层的价值：它把图、音、视的解析能力封装成了标准接口，业务系统可以通过 API 自动向知识库投递素材。比如巡检系统每天产生大量现场照片，照片拍完自动进入知识库解析并索引，质检人员直接在内部问答应用里查询，不需要任何人工整理环节。这个扩展空间是普通知识库给不了的。

3. 实操过程：构建多模态知识库的完整步骤

3.1 第一步：准备材料与格式检查

动手之前，先把材料过一遍。我踩过最冤枉的坑，就是上传了一堆系统不支持的格式，解析全部失败，还以为是系统问题。以我实际使用的版本为例，图片类建议用 jpg、png、webp 这类常用格式；音频类用 mp3、wav、m4a 比较稳；视频类用 mp4、mov、webm。有些专业设备录出来的格式，比如某些工业相机的 raw、监控系统的私有格式，建议先用工具转成标准格式再上传。

文件大小也要留意。单个文件太大，解析时间会成倍增加，而且容易触发超时。我的经验是单文件尽量控制在 50MB 以内，超过的建议先切片。视频尤其要注意，一个 2 小时的培训视频动辄几个 GB，不切片直接传，大概率会解析失败。切片工具我用得最多的是 ffmpeg，命令行几秒钟就搞定，后面排查章节会给出具体命令。

上传之前给每个文件起一个好名字，这件事比想象中重要。文件名字会被当作元数据记录，检索的时候是重要的匹配维度。我见过有人全部用 "IMG_20240101.jpg" 这种默认名上传，结果 OCR 又提不出什么文字，整个文件在知识库里几乎等于隐形。

3.2 第二步：创建知识库与配置解析

在 MaxKB 控制台里进入知识库管理，点击创建，类型选择"工作流知识库"，然后填写名称和描述。名称建议体现业务域，比如"设备维修影像库""新员工培训资料库"，这样后续多个知识库并存的时候好区分，工作流里选库也不会选错。

创建之后的关键一步是解析配置。不同版本界面表述可能有差异，核心项基本是这几块：一是图片解析开关，对应 OCR 能力；二是音视频解析开关，对应 ASR 转写能力；三是语言设置，要跟素材实际使用的语言一致，中英混排的话尽量选择支持多语言的模型；四是转写输出格式，推荐保留时间戳。

解析配置完成后，直接进入上传页把准备好的文件批量拖进去。上传后系统会自动进入解析队列，可以在文件列表里看每一条的解析状态。多模态文件的解析比纯文本慢很多，耐心等一等。解析完成后，点击文件进去能看到提取出来的文本内容，我建议每上传完一批就抽查一次，确认 OCR 和转写结果不是一堆乱码。这个习惯能帮你第一时间发现模型选型问题，而不是等建完应用才发现答案质量一团糟。

3.3 第三步：配置向量化与索引模型

解析只是把非文本变成文本，接下来要做向量化，靠的是嵌入模型。MaxKB 支持配置不同的嵌入模型，可以是本地部署的开源模型，也可以是调用外部模型接口。选择标准第一是语言匹配度，处理中文内容就要选中文效果好的模型，通用英文模型处理中文会明显吃亏；第二是向量维度与索引规模，维度高代表信息粒度细，但存储和检索成本也高，业务量大时要权衡。

除了嵌入模型，排序模型也要关注。多模态知识库因为文件类型杂，命中的文本切片往往存在大量无关内容，比如一张截图的 OCR 结果可能只有几个词，视频转写可能包含很多口语填充词。如果用了粗排之后不做精排优化，返回给大模型的上下文会很脏。我在应用工作流里通常会配置一个 rerank 环节，或者在上层提示词里强调只参考与问题相关的片段。

分块策略方面，因为多模态内容不是连续的文章，分块不能照搬纯文本知识库那种固定字数切分。我的经验是：图片 OCR 文本本身短，不用再切，一个文件一条索引就够了；音频转写文本按时间段切，比如每 60 到 120 秒一块，重叠 10 到 15 秒避免切在句子中间；视频转写同理，但块大小可以结合章节信息调整，如果视频本身有章节，按章节切是最理想的。块太大，检索命中不精准；块太小，上下文信息不完整。多模态场景宁可在切块时多保留一点上下文，也别切得太碎。

3.4 第四步：接入应用工作流并测试召回

知识库建好，素材解析和向量化完成，下一步就是把它接到应用工作流里。在 MaxKB 中创建应用，类型选择"工作流应用"，然后进入画布编排。核心链路是这样：开始节点接收用户问题，知识库检索节点用这个问题去召回多模态知识库，召回的文本切片和文件引用进入提示词节点，拼装成带格式要求的上下文，最后交给大模型节点生成回答，再通过回复节点输出。

检索节点里要做两件事：一是选定刚才建好的工作流知识库，二是设定检索参数，包括召回条数、相似度阈值、是否启用重排序。召回条数我一般先设 5 条，相似度阈值设 0.5 左右，后续根据测试结果微调。阈值设太高容易召回不到东西，设太低又容易混入完全无关的内容。

提示词节点里，除了把检索结果塞进上下文，还要明确告诉大模型：当检索结果的元数据包含文件引用时，要在回答中主动给出文件标识或访问路径。一个简化的提示词模板大概长这样：

你是一个企业知识助手，请基于以下检索资料回答用户问题。 资料内容： {{knowledge_base_result}} 如果资料中带有文件引用信息，请在回答末尾以【相关文件】的形式列出。 请只依据资料回答，不要杜撰。 用户问题：{{question}}

模板里的两个变量，一个对应检索节点的输出，一个是用户输入。实际部署时变量名以你工作流里配置的字段为准。接好之后先跑几轮测试，拿真实业务问题去问，重点看两件事：一是文字回答是否准确，二是文件引用有没有正确输出。都通了，这个多模态知识库就算真正能用了。

3.5 重要：分块参数到底怎么调

好多人在多模态知识库里调参，还是沿用文本知识库的习惯，喜欢把分块长度设成统一的 512 或者 1024，结果效果飘忽不定。问题就出在模态差异上。

纯文本文档，每个分块都是完整句子的集合，长度统一是可接受的；但音频转写里天然包含大量停顿、语气词，按统一字符数切，很容易把一句完整的话拦腰截断。视频转写还要考虑时间戳的连续性，切碎了时间戳就乱了，用户拿到文本却定位不到视频位置。

我调参时的做法分三步。第一步，先按模态给文件分组，图片类不分块，音频视频类按时间切；第二步，用一批已知答案的测试问题跑一遍检索，看命中的切片是不是覆盖了答案；第三步，根据命中率微调重叠长度。一个比较省事的起点是：转写文本每块 90 秒，重叠 15 秒，召回条数 5。测出来的结果如果总是缺后半句，就把重叠加到 30 秒；如果命中但上下文冗余，就缩小到 60 秒。调参不是一步到位的事，记录每次改动和效果，比凭感觉乱调有效得多。

4. 踩坑实测：多模态知识库的高频问题与排查实录

4.1 图片 OCR 丢字、错字怎么办

图片 OCR 是第一个翻车现场。我拿一批产品说明书截图建库，建完发现问答里只要涉及具体参数，错误率就明显偏高。查了一下解析出来的文本，发现不少数字被识别错，比如把"100A"识别成"1004"。原因也很直白，原始截图分辨率不够，字边缘发虚，OCR 模型再强也架不住输入质量差。

解决办法分三层。第一层，从源头解决，尽量导出高分辨率截图，放大到文字清晰可读再上传；第二层，利用文件名的描述信息做辅助，遇到 OCR 完全失效的图，我就在文件名里把关键信息写全，这样至少检索时能靠文件名命中；第三层，在提示词里增加规则，要求大模型引用 OCR 文本时对数字类信息保持原文输出，不要自行解释。

还有一类坑是表格截图。OCR 把表格识别成乱七八糟的文本行，结构化信息全丢了。如果原文件是 Excel 或能导出表格，建议优先上传可解析的原始文档，而不是截图；如果只能截图像，那就别指望问答里能精确复述表格关系，检索时能定位到这张图就够了。

4.2 音频、视频转写的对齐与文件过大

音频转写最常见的问题有两个：口语词太多、时间戳对不齐。会议录音里全是"嗯""那个""就是说"，这些词会挤占向量空间，影响检索质量。我的处理方案是转写后在提示词里要求大模型忽略语气词，只提取核心信息；如果库规模大，也可以在预处理阶段做一次清洗，把高频语气词替换成空白。

文件过大导致的解析失败非常折磨人。一个 45 分钟的培训视频，MP4 格式将近 2GB，传到知识库里状态一直是解析中，最后超时失败。我以为是自己带宽问题，后来才发现是文件太大。用 ffmpeg 先抽音轨，可以把体积降一个量级：

# 从视频中抽取音轨，不重新编码，速度快 ffmpeg -i training.mp4 -vn -acodec copy training_audio.m4a # 如果视频太长，按每段30分钟切片 ffmpeg -i training.mp4 -f segment -segment_time 1800 -c copy training_part_%03d.mp4

抽完音轨、切完片再上传，解析成功率明显提升。视频画面信息仍然重要，所以我通常会配合前面说的，另外导出几张关键帧截图补进同一个知识库，检索时图文互补。

4.3 文件引用失效的排查

文件引用是多模态知识库的灵魂，也是出问题最多的地方。测试时经常遇到这种情况：回答里确实带了"相关文件"字段，但点进去打不开，或者图片裂了。查下来原因一般是三个。

第一个是文件路径变了。知识库里的文件在存储层有自己的位置，如果部署环境有迁移或者清理过存储目录，引用的地址就失效了。解决办法是检查部署环境的存储配置，确保文件目录不能被随意替换。第二个是访问地址没有正确配置，在多机部署或容器化部署时，文件服务对外地址可能与内部存储地址不一致，问答应用拿到的引用地址是内部地址，前端当然访问不到。第三个是文件被后续的清理策略误删，需要检查存储上的保留策略。

排查思路不复杂，拿到一条引用地址之后，先在服务器上直接访问一遍，确认地址本身是否能返回文件；如果能返回但前端打不开，就是跨域或鉴权问题；如果服务器上就访问不了，就往文件是否存在、路径是否变了这个方向查。按这个顺序排查，基本几分钟就能定位。

4.4 多模态知识库常见问题速查表

这张表是我自己调试时经常翻的，每次遇到问题先对着表看一遍省很多时间。多模态知识库的问题，绝大多数不是大模型能力问题，而是文件处理链路某个环节没对上。

5. 我的实测心得与后续扩展方向

把这套流程完整跑完之后，我最大的感受是：多模态知识库的质量上限，由素材质量决定，而不是由模型决定。高分辨率的截图、干净无噪音的录音、带章节的视频，建出来的库几乎不用怎么调参就能用；反过来，素材乱七八糟，配置调出花来也无济于事。所以我的建议是先花时间把文件规范定下来，再谈系统搭建。

另一个体会是，文件命名和元数据管理值得投入额外精力。多模态文件的自动解析能力再好，也比不上一个描述准确的文件名带来的检索提升。我现在建库之前都会跟资料管理员对齐命名规范，这比后期做任何优化都划算。

后续想更进一步的话，我计划做三个方向的事情：第一，给视频建立关键帧索引，也就是每隔一段时间抽取一帧画面做 OCR，这样用户问"某个画面出现在第几分钟"也能检索；第二，在问答环节引入多模态模型，让大模型直接看图判断，而不只依赖 OCR 文本，适合缺陷检测这类需要"看懂画面"的场景；第三，建立一套自动化评测集，拿固定的一百个业务问题定期回归测试，防止知识库更新后出现召回质量回退。这些方向现在都有相应的基础工具可以试，也是在多模态知识库这条路上继续深入时比较自然的延伸。