最近一周，我把一台装着算能1684x的机器和一台上线了腾讯开源RAG知识库weknora的服务器接在了一起，中间塞进一个qwen3-vl多模态模型，组了一套既能检索文档、又能“看图说话”的私有知识问答系统。整个折腾下来，最深的感受是：跑模型本身不难，难的是让知识库“查得准”、让模型“答得稳”、让两套系统在接口层面老老实实对齐。
这篇内容不打算写成官方文档的手把手翻译，而是把我在这套组合里的完整过程、关键决策和踩过的坑都记录下来。适合的对象是：手里正好有算能平台、准备做私有化知识问答、或者正在纠结RAG方案怎么选的人。如果你以为“部署个知识库再接个大模型”就是全部，那看完你会发现，真正的工程量在中间那条看不见的链路上。
1. 项目拆解：这套组合到底在解决什么问题
1.1 一句话看懂三者的分工
先说结论：weknora负责查，qwen3-vl负责答，1684x负责让这一切全都发生在内网。
算能1684x是一颗面向边缘与私有化部署的AI推理芯片，标称INT8算力在32TOPS附近，支持FP32、FP16、INT8多种精度，配套的SDK通常包含libsophon运行库、sophon-sail推理接口和TPU-MLIR模型编译工具链。对我来说，它最大的价值就是“在本地把模型推理成本压到接近零”，数据不出内网，也不依赖外部API。
qwen3-vl是多模态大模型，图片、表格截图、扫描文档都能作为输入。知识库场景里最麻烦的从来不是长文本，而是图表、截图、扫描件这类视觉信息，所以选它而不是纯文本模型，是为了让最后的问答环节具备真正的“看”能力。
weknora则是腾讯开源的知识库底座，它做的事情比普通向量检索更重一点，文档解析、切片、向量化、检索、知识图谱关系抽取都被包装成平台能力。这里我主要看重的是它的知识图谱能力——当问题和答案之间存在实体关系、同义概念、层级结构时，纯向量检索经常会漏，而图谱能把相邻关系补回来。
1.2 数据链路：从提问到答案的完整路径
整体链路是这样的：用户问题先进入检索层；weknora在知识库里做向量检索和图谱查询，返回一批候选片段；系统把候选片段整理成上下文；再带着上下文去请求运行在1684x上的qwen3-vl；模型生成答案后返回给用户。
如果提问涉及“某张故障截图”，检索阶段返回的不只是文字，而是图片的地址或文件路径。qwen3-vl的OpenAI兼容接口允许content里同时放文本和图片，我直接把图片URL或base64传进去，模型可以真正做到看着图回答。这是纯文本RAG做不到的。
这条链路里有一个很容易踩的误区：把生成和检索混在一起。很多人以为RAG就是把文档全部丢给模型，让模型“记住”。实际上模型上下文是有上限的，且直接塞原文会稀释注意力。weknora存在的意义就是先做一次“筛选”，把相关片段挑出来，再让qwen3-vl在精确的上下文里作答。
1.3 为什么不是“随便一个向量库 + 任意大模型”
我一开始也为省事想过：用一个开源向量数据库，把文档切片、embedding存进去，再调模型接口，不就完事了？真跑起来才发现，有几个问题不是简单方案能解决的。
第一是召回准确性。纯向量检索只做语义相似度匹配，对于专业领域的同义词、缩略语、上下级概念非常吃力。比如“温控模块”和“温度调节单元”在向量空间里可能离得不够近，但知识图谱里可能直接存在一条“同义/包含”关系。weknora这类带图谱的RAG平台，就是为了补这一段。
第二是运维成本。企业知识库是长期资产，涉及文档版本更新、权限管理、索引重建、检索效果评估。自己拿向量库拼，这些全得自己写；用weknora，至少平台层已经有了基础能力。
第三是多模态。我要做的不是纯文本问答，文档里的截图、表格、流程图为数不少。weknora负责把图片也纳入知识管理，qwen3-vl负责在生成阶段看图，两个能力对齐之后才能形成完整的“多模态RAG”。这也是我最终选择这套组合而不是“向量库+纯文本LLM”的关键原因。
2. 算能1684x侧：把qwen3-vl跑起来的实操要点
2.1 先摸清1684x的工具链边界
部署的第一步不是拉模型，而是先确认工具链能不能把模型“搬”到芯片上。1684x的官方推理生态基本围绕三块展开：libsophon负责板卡驱动与运行环境，sophon-sail是上层推理接口（C++和Python都有），TPU-MLIR负责把模型编译成bmodel格式。
所以动手前我先做了一次“可行性三问”：qwen3-vl对应的模型结构是否已有官方的bmodel或转换脚本；如果没有，能否用ONNX中间格式走TPU-MLIR；如果还是不行，是否有同架构的VL模型可以替代验证。实践下来，这三问基本能过滤掉90%的无效尝试。
这里要提醒一点：不要一上来就追求最新版本的工具链。设备上装的libsophon和TPU-MLIR版本必须匹配，混装很容易出现bmodel能编译但加载失败的情况。我建议把版本号固定，用官方提供的套件整体安装，而不是零散更新组件。
另外，如果qwen3-vl官方还没有给出针对1684x的模型文件，可以走移植路线：先用transformers从模型仓库拿权重，导出ONNX，再通过TPU-MLIR完成量化与编译。这条路有一定门槛，但对“新模型”来说是最常见的落地方式，至少我在处理同类模型时就是这么干的。
2.2 模型选型与量级估算
qwen3-vl不是单一体量，通常会有若干档位的参数版本。跑在1684x这种边缘芯片上，需要先做一次内存和算力预算。
一个简单的估算方法：FP16权重每10亿参数大约占2GB，INT8大约占1GB。以7B档位的模型为例，FP16需要约14GB，INT8约7GB。如果板卡内存或显存不算宽裕，优先考虑INT8甚至更低比特的量化方案。长上下文的KV Cache也要额外占空间，max_tokens设置得越大，显存占用越高。所以部署脚本里我一般先把max_tokens限制在512到1024，跑通后再逐步放大。
交互上建议先用最小输入做冒烟测试，比如单轮对话、短文本、无图片，确认输出正常后再逐步添加长文本和多图输入。这样定位问题容易很多，也避免把“上下文过长”和“模型转换失败”混在一起。
2.3 部署推理服务的通用步骤
我采用的方案是：本地先跑通模型，再用FastAPI封装成一个OpenAI兼容接口。这样weknora和Dify这类上游系统想要对接，几乎不需要改动业务代码，只需要把base_url指过来。
整个流程大概如下：
- 拉取qwen3-vl的权重文件，确认transformers依赖版本。
- 用脚本加载模型，先做一次纯文本测试，确认对话输出正常。
- 做一次带图片的测试，确认视觉编码器工作正常。
- 根据1684x工具链要求，把模型导出为ONNX，再用TPU-MLIR编译成bmodel，按需选择量化精度。
- 用sophon-sail写推理调用层，封装输入输出格式。
- 起一个FastAPI服务，暴露 /v1/chat/completions 和 /v1/models，兼容OpenAI格式。
接口层面我要特别强调消息结构。qwen3-vl是视觉语言模型，OpenAI风格的请求里，content是一个数组，可以同时包含文本块和图片块。图片块支持URL和base64两种传法。知识库场景工具内部调用时，我建议优先用base64，避免外部网络访问图片URL失败。
2.4 并发、显存与精度的经验
1684x的算力适合跑“几十亿参数加中小并发”的推理任务，不要把它当成数据中心卡来规划并发。我在部署时做了请求队列，控制同时推理的数量，宁可让单个请求排队，也不要并发打爆显存。队列配合简单的超时和重试，实测下来稳定性会好很多。
精度方面，如果知识问答对准确率要求高，建议优先INT8而不是更低比特。虽然低比特能塞下更大的模型，但在多模态场景里视觉特征经不起太大精度损耗，回答质量下降后排查起来更费劲。
还有一个容易被忽略的点：上下文长度。很多模型在长上下文下会出现“首token延迟明显变大”的情况。如果要处理很长的文档片段，我一般会把weknora返回的上下文控制在模型支持长度的一半以内，既降低显存压力，也减少模型注意力被无关内容稀释的风险。
3. weknora知识库本地部署与配置细节
3.1 部署前先理解weknora的架构
我理解weknora更像“企业知识库的操作系统”：前端管理界面负责索引可视化，后端API负责检索与接口服务，中间还有文档解析、向量化、知识图谱相关的组件。它跟单纯的开源向量数据库不一样，更像是一个完整的RAG平台。
部署之前先确认环境依赖：Docker和Docker Compose基本是标配；如果数据量小、单机跑，关系型数据库和向量存储都可以用内置或容器化的组件；如果数据量大，再考虑外置存储。先把架构搞清楚，后面调参数才不至于瞎猜。
在我的经验里，部署这类RAG平台最容易犯的错误，是没有先区分“数据存储”、“索引”、“检索服务”三件事。连数据库都没起来就急着上传文档肯定报错；索引和检索用的向量模型不一致，检索结果也会飘。
3.2 Docker Compose快速启动
如果官方提供了docker-compose文件，那是最省心的一条路。一般流程是：拉取源码或配置文件，复制一份.env.example为.env，设置好密钥、存储路径、数据库连接串等环境变量，然后执行 docker compose up -d，等服务健康检查通过。
需要替换的核心配置通常有三类：密钥类（JWT密钥、加密密钥），存储类（对象存储或本地路径），数据库类（数据库连接信息）。我习惯把所有密钥集中到一个.env文件里，不要散落在compose文件里，否则后续维护会很难受。
启动后先观察日志有没有报错，再访问管理界面做冒烟测试。如果页面能打开，创建一个空知识库并上传一份小文档，跑一遍“解析、切片、索引、检索”全流程。这一步通过，说明环境基本可用，可以开始正式迁移数据。
3.3 知识库初始化与OIDC配置
第一次创建知识库时，需要做两个关键决策：切片策略和向量模型。切片策略建议按业务内容调整，代码类知识用固定长度容易切断逻辑块，我一般优先按标题或段落切；官网类内容则可以按固定token长度。向量模型更关键，检索用的embedding模型必须和查询阶段保持一致，否则召回结果会非常随机。
如果weknora配置了OIDC，对接公司统一身份体系就很方便。OIDC配置里，issuer、client_id、client_secret、callback_url这几项基本绕不开。实际配置时经常出现回调地址对不上、scope缺了openid和profile之类的小问题，建议先开着debug日志看跳转流程。
有一点值得注意：OIDC只是登录层。知识库内部的权限控制是另一回事，比如哪些人能看哪些知识空间，仍然需要在weknora里单独配置。很多人以为接了OIDC就自动有了全部权限隔离，这是个误区。
3.4 把weknora接进Dify的常见玩法
如果你已经在用Dify编排Agent或者工作流，weknora完全可以作为Dify的知识检索节点或外部工具接入。反过来，Dify也能作为统一入口，把多路知识库、多个模型统一编排。
我在实际项目中两种方式都试过。如果只是“检索+生成”的简单问答，直接在weknora里配置qwen3-vl作为LLM endpoint即可，weknora自己就能完成RAG闭环；如果流程复杂，比如需要多轮追问、工具调用、人工审核，再把它接到Dify工作流里，模型提供商那里添加一个OpenAI兼容自定义服务，地址指向1684x上的推理服务。
这种“weknora管数据、Dify管流程、qwen3-vl管生成”的组合，好处是每个环节都能独立替换。哪怕以后模型换成新版本，或者知识库换成另一个平台，接口层不需要大改。
3.5 图片能不能进知识库
这是很多人在做多模态RAG时的困惑。先说结论：图片作为文件附件进知识库没问题，但要分清楚“能被存储”和“能被检索”是两回事。
常规RAG的索引都是基于文本的，图片本身不会参与向量匹配。如果上传一张没有任何文字描述的图片，检索阶段大概率找不到它。要让图片真的参与问答，通常有两条路：一是对图片做OCR或生成caption，把识别出来的文字和语义描述作为索引内容；二是保留图片文件本身，在生成阶段交给多模态模型看图。weknora负责第一件事，qwen3-vl负责第二件事，两条路都要走，才能形成完整的多模态RAG。
我在项目里的做法是：上传文档时尽量保留图片的上下文（图题、所在章节、周边文字），这样检索能命中“图片所在的语境”，再把图片文件本身传给qwen3-vl。单独一张“孤儿图片”在知识库里的价值很低，这也是我在整理语料时反复跟业务同事强调的。
4. 打通两者的RAG问答链路实现
4.1 两种对接方式怎么选
把weknora和qwen3-vl连起来，我在实践中走通了两条路。
第一种是在weknora管理后台配置自定义模型供应商，把OpenAI兼容的base_url指向1684x上的服务，然后在知识库问答页直接以qwen3-vl作为生成模型。优点是省事，知识库后台自带“检索-生成”闭环，不需要额外写编排代码。
第二种是自己写编排层：先调用weknora的检索API取回上下文，再调用qwen3-vl的chat接口完成生成。优点是可控，你可以自由控制召回数量、改写问题、注入提示词，甚至对检索结果做后处理。
我的建议是：先走第二种，哪怕只是一个小脚本。因为通过手动编排，你能清楚看到每次检索到底返回了什么、模型到底用了哪些内容，这对排查“回答不对”极有帮助。跑通之后再决定要不要切回第一种省事模式。
4.2 检索侧的查询改写与召回策略
RAG效果差，十有八九问题出在检索而不是生成。用户提问往往口语化，“报销单怎么填”和“费用报销流程”在字面上差了很远，向量模型不一定能兜住。这时可以在检索前加一个查询改写步骤，让qwen3-vl把原始问题扩写成更适合检索的关键词列表或子问题。
我实际用过的最简版本是：先给qwen3-vl一个系统提示，要求把用户问题改写成3个适合知识库检索的关键短语，只输出短语；然后把结果拼接起来，分别去weknora检索，最后合并去重。这个改动看似简单，但在我的场景里召回命中率提升非常明显。
召回策略上，我通常会先取top_k=10的向量结果，再叠加图谱关系扩展，最后按相关度重排。如果weknora支持自定义检索参数，建议把“只搜索某知识空间”这类限定也用上，避免跨领域干扰。上下文宁可少而精，也不要一股脑全部塞进去。
4.3 Prompt模板与上下文组织
一个好的RAG提示词，核心就一句话：让模型知道它只能依据给定资料回答，不能编造。我在模板里把引用编号也加了进去，要求模型在回答时标注参考自哪份资料，这样用户和运维都能追溯答案来源。
系统部分一般这样组织：说明身份；说明资料来自知识库，可能存在错误或过期；要求若资料不足以回答，必须老实说“资料不足”。用户部分则放问题本身，以及weknora返回的上下文片段。
上下文组织时，我会保留文档名、来源、页码这类元信息，让模型在回答末尾以[1][2]的形式给出引用。对于企业内部需要审慎控的场景，这点尤其重要，有依据的回答才敢给人看。
面对图片时，把图片和文字放在同一个content数组里，并提醒模型“回答问题时请结合图片内容”。如果不加这一句，部分模型会倾向于只读文字部分而忽略图片，白白浪费视觉能力。
4.4 图片与表格类知识的多模态生成
多模态RAG的生成阶段，最大的坑是“图拿了但没用上”。检索回来了图片路径，结果调qwen3-vl时只把文字塞进content，图片没有跟着传，模型自然只能盲猜。
我在接口层是这样处理的：weknora返回的每个chunk都带文件属性和可能的图片路径。如果一次问答涉及图片，先把图片读取成base64，再构造OpenAI格式的content数组，让图片块排在文字块之前，保证模型注意力先落在图上。图片比较大的话先做压缩，否则base64体积会占用上下文长度和传输带宽。
表格类知识同理。一张Excel截图的字段关系，如果只转成文字，行内信息容易丢；直接把截图传给qwen3-vl，让模型看行列结构，回答准确率明显更高。这也是我坚持用qwen3-vl而不是纯文本模型的原因。
4.5 效果评测与调优清单
连接打通之后，必须建立一套评测集。不用很复杂，20到30条覆盖典型业务问题和刁钻追问的测试集就够。我每次改动知识库、改提示词、换量化精度，都先跑到这套测试集里看效果，而不是靠一两次手工提问感觉“好像还行”。
调优的顺序建议是：先查检索召回是否正常，再查上下文是否被正确注入，最后再怀疑模型能力。很多问题表面上是“模型答错了”，实际是“该召回的内容根本没召回”。先看检索结果再谈生成，可以少走很多弯路。
我整理的几个关键调优点：top_k数量是否合适；检索结果有没有按相关性排序；上下文长度是否超过模型能力；提示词里是否明确禁止编造；图片是否真正传给了模型。按这个顺序逐项检查，大部分RAG效果问题都能定位。
5. 实操避坑：常见问题与排查实录
5.1 模型侧翻车现场
1684x上跑qwen3-vl，我遇到的最典型问题是“模型转换后输出不稳定”。一开始我怀疑量化精度，排查到最后才发现是分词器和权重版本不匹配。多模态模型对transformers等依赖的版本很敏感，导出ONNX前最好固定依赖版本，并记录导出环境信息。
第二个常踩的坑是“模型能加载但首token极慢”。这往往不是芯片算力不够，而是上下文长度已经接近上限，KV Cache开销巨大。我会把max_tokens调小，或者压缩weknora返回的上下文，问题立刻缓解。
第三个坑是图片传参格式不对。OpenAI接口里图片块的格式写错，模型根本不看图片，直接按文本处理。我在代码里加了格式校验，凡是content数组里字段名写错就立刻报错，比让用户看到“胡说八道”的答案强得多。
5.2 weknora侧翻车现场
weknora部署阶段最让人头疼的是“索引完成了但检索不到”。这种情况我遇到的九成都是因为向量模型不一致：上传文档索引用的是A模型，查询阶段配置的却是B模型，两个向量空间的数值根本没有可比性。建议把embedding模型的配置固化到知识库级别，别在全局随意切换。
还有一种情况是文档解析失败。PDF扫描件没有OCR，整篇都是图片，自然切不出任何文本。这个不是weknora的问题，而是语料质量的问题。我会在前期加一道预处理，把所有扫描件先跑一遍OCR，把识别文本和原PDF一起上传。
OIDC登录的坑也很多。常见的是回调地址没有配置成HTTPS，或者scope缺失，导致跳转登录后拿不到用户信息。遇到这类问题，我一般是先看weknora后端日志里的OIDC报错信息，再逐项核对issuer、client_id和callback_url，基本都能解决。
5.3 链路侧翻车现场
链路侧最容易出问题的点是“weknora返回了图片，但qwen3-vl读不到”。如果图片URL走的是内网地址，而qwen3-vl服务运行在没有路由的另一个网段，URL自然访问不了。我的对策是：统一走base64，不依赖URL跨网络访问。
另一个坑是“检索很慢，生成也慢，整体超时”。问题往往出在同步调用上。我会把检索和生成拆开，检索结果先缓存，模型服务加上并发限制。如果业务允许，给整个问答接口加一个异步任务机制，对用户体验会友好很多。
还有一个容易被忽略的问题：答案没有引用。用户看到一段没有来源的生成文本，信任度会很低。我在prompt里明确要求模型输出引用编号，并在后端校验答案中是否包含引用标记，没有的话自动重试一次。这招对内部系统的可信度提升立竿见影。
5.4 问题排查速查表
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 模型服务启动失败 | libsophon与TPU-MLIR版本不匹配 | 固定版本整体重装，检查驱动日志 |
| 输出乱码或重复 | 分词器版本与权重不一致 | 固定transformers版本，记录导出环境 |
| 首token延迟很高 | 上下文过长或KV Cache过大 | 调小max_tokens，压缩weknora返回上下文 |
| 检索结果为空 | 索引未完成或embedding不一致 | 查看索引状态，固化向量模型配置 |
| 检索到但回答不对 | 召回不相关或上下文被稀释 | 检查top_k与图谱扩展，先跑查询改写 |
| 图片没生效 | content数组格式错误或图片URL不可达 | 校验字段名，改用base64传图 |
| 整体超时 | 同步调用阻塞 | 拆检索与生成，加队列与异步任务 |
| OIDC登录失败 | 回调地址或scope配置错误 | 看后端日志，逐项核对OIDC配置 |
如果你也在折腾类似的组合，我的建议是：第一阶段先跑通最小闭环，哪怕只是十个文档加一个测试页面；第二阶段再投入时间优化召回和提示词；第三阶段才考虑并发、权限、监控这些生产级别的问题。别想着一步到位，把链路里的每一个环节都看明白，比堆配置有用得多。整套系统真正花时间的，永远不是把模型灌进芯片，而是“喂知识、测效果、调提示词”这个循环。
