高效办公的小叮当做Unity里的AI功能做到后期，几乎所有人都会撞上同一个问题：本地模型能聊了，但聊的内容一问三不知。尤其当你想让NPC记住世界观、让助手按照自家产品文档回答问题的时候，光靠调prompt是没用的。这个系列前面几篇聊了不少LLMUnity集成时的坑，这篇专门把知识库配置和使用这件事从头到尾捋一遍——包括我在编辑器、Android真机上实际跑通后踩到的那些文档里根本不会写的细节。
LLMUnity本身是个在Unity内跑本地大模型的方案，数据不出设备，隐私好控制，离线也能用。但本地模型有个天然短板：训练数据是通用的，它不知道你的游戏世界观、不知道你项目里的专有名词。知识库功能本质上就是把外部文档切成碎片、向量化、存起来，每次提问时先检索相关段落，再拼进上下文让模型参考。这就是RAG（检索增强生成），也是目前给本地模型补业务知识最实用的一条路，既不用做成本高昂的微调，又能随时更新内容。
这篇文章不是从零教你API怎么调，而是围绕“为什么你的知识库不生效”“为什么检索结果不对”“Build到真机后为什么加载不出来”这类实际现象来写。适合已经被LLMUnity的对话功能折磨过一遍、现在正想给它接知识库的开发者。如果你刚下载插件还没跑通，建议先看前面的配置文章，把基础对话跑通再进这一篇，否则排查问题时变量太多，不好定位。
1. 先搞懂LLMUnity知识库的工作链路，后面才不会被现象误导
我在群里见过不少朋友问“文件也放进去了，参数也开了，模型就是不按知识库回答”。这种问题一大半是因为对知识库的内部顺序没概念。LLMUnity的知识库功能不是简单地把整个文档塞给模型，它走的是完整RAG链路：文本导入、切片、向量化（Embedding）、存储、检索、再拼进Prompt。每一步都可能出错，而且越靠前的环节出错，后面看起来就越像“模型不行”。
1.1 文本导入和向量化：不是把文档“传”给模型，而是把文字切碎后编码
很多第一次接触知识库的Unity开发者，最大的误解在于“把文档放进去就等于模型读过了”。其实模型没有“读”这个动作。LLMUnity的做法是——先配置一个轻量的Embedding模型，把文档里的文本块转成一串高维向量，向量里包含语义信息。用户提问时，系统把问题也转成向量，然后在库里找和问题向量最接近的文本块，把这些文本块拼到Prompt里，再交给真正的大模型做生成。
这个过程里Embedding模型和对话模型是两套东西。我在实际项目里遇到过一种很典型的错误：只配了对话模型，没配Embedding模型，然后知识库功能怎么开都报错。LLMUnity在启用知识库功能时，需要额外下载一个Embedding模型（常见方案是类似all-MiniLM-L6-v2这类轻量模型）。如果下载超时或者模型文件不完整，后续所有知识库操作都会失败，而且报错信息有时候很误导——它可能只提示“Failed to load knowledge base”，不会明确说Embedding模型缺了。
注意：LLMUnity不同版本里知识库功能的入口长得不一样。有的版本在窗口里可以直接配置Embedding模型下载链接，有的版本需要手动在代码里指定模型文件路径。如果你打开界面没看到对应选项，先翻一下当前版本包里的README或者Demo场景，别拿旧版教程硬套新版界面。
我自己的经验是：先把Embedding模型单独下载好，确认它确实是能独立加载的，再去配知识库。具体判断方法是日志里能不能看到Embedding模型加载完成的输出，不同版本的输出标志不同，但关键特征是“模型已就绪”这一类输出。如果看不到，就不要往下进行，不然后面每一步报错你都会误以为是知识库文件的问题。
1.2 知识库文件存储格式：Editor下正常不代表打包后正常
LLMUnity的知识库在编辑器里通常会把向量数据持久化保存下来（比如生成对应后缀的文件，有的版本是.mdf，有的版本是Unity原生的Asset格式）。这样做的目的是避免每次启动都重新对整篇文档做Embedding——那玩意儿在CPU上跑起来是真的慢。
但“持久化”三个字恰恰是埋坑的地方。你在编辑器里Add文本、生成知识库，向量数据很可能被写进了工程路径下某个Asset文件里。但当你打成Android包，这个文件是否被打进包、运行时能否写入，完全是另一回事。我经常看到有人编辑器里一切正常，一上真机就报找不到知识库，查来查去发现是持久化文件压根没进最终包。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 配置知识库前必须检查的依赖和路径问题
2.1 LLMUnity版本和API差异：先确认你的接口长什么样
LLMUnity这插件迭代速度很快，早期版本和当前版本在知识库接口上变化不小。早期版本里你可能会看到类似AddToKnowledgeBase(string document)这样的方法，而在较新的Client接口里，直接调用方法传字符串的方式可能已经变了。我强烈建议你不要只看网上的历史代码，先打开工程里Plugins或Scripts目录下的源码，搜索“Knowledge”关键字，把你当前版本的接口看清楚。
为什么要强调这一步？因为我在项目里遇到过：代码是按网上教程写的，理论上没有任何问题，但运行时就告诉你LlmKnowledgeBase不存在，或者在调用时抛TypeLoadException。最后发现是教程基于的版本跟Unity包管理器的版本不是同一代，有些类已经被移进内部命名空间了。
经验：接这种快速迭代的开源插件，第一件事不是找教程，而是在本地代码里搜索对应关键字确认API存在。教程只能帮你建立概念模型，API签名一定要以你当前包里的代码为准。
2.2 Embedding模型的一顿折腾：下载超时、二进制校验、到底放哪个目录
配置LLMUnity知识库时，需要准备两类模型：一类是对话模型，一类是Embedding模型。对话模型可能你已经通过界面下载器搞定了，但Embedding模型很多人没注意到。有的版本会在模型下载界面内置一个单独的Embedding模型选项，有的版本需要你自己下载好后放到指定目录，然后在代码里指定路径。如果Embedding模型没就绪，你在构建知识库时点击提交没有任何反应，或者控制台报DLL相关的异常。
另外要注意：Embedding模型和对话模型体积差很多。Embedding模型通常很小，几十MB级别，下载应该很快。如果你发现下载速度异常或者老是在某个百分比卡住，可以试试离线方式——从模型托管平台手动下载对应GGUF或其他格式文件，然后放进Unity工程里，再用代码指定路径加载。手动放置文件时，要尤其注意Unity会怎么处理这个文件：放在StreamingAssets下能保证原封不动进包并可用路径访问，但如果你放在Resources下或者普通文件夹下，打包时文件可能不会被携带，或者路径完全对不上，加载就会失败。
真机上路径问题更隐蔽。Unity在不同平台上获取路径的方式不同：编辑器下Application.streamingAssetsPath指向工程目录里的StreamingAssets文件夹，Android上这同一个API指向APK压缩包内的位置——它不是一个普通可读的文件系统路径，直接拿来当普通文件路径传给LLMUnity，实际读取时就会出现“路径找到但文件打不开”。如果你在移动端用知识库，最稳的办法还是想办法把它放到可写目录，比如Application.persistentDataPath下面，但也要考虑首次启动时文件拷贝消耗的时间。
2.3 Unity编辑器里跑LLMUnity：主线程卡死和资源释放问题
LLMUnity的知识库索引构建通常是在客户端调用后进行的。如果你文档很长，构建向量索引就可能比较耗时。有些版本是在主线程上同步等待，于是你会在编辑器里看到界面整个卡住几十秒甚至更久，像是在“无响应”。这不是死机，是Embedding过程没有及时让出主线程。若是小文档还好，大文档会让人误判崩溃。
另一个相关问题是：如果在构建过程中你强行停止播放模式，或者脚本里重复调用了添加知识库的接口，有概率出现DLL层面的崩溃，这种崩溃往往没有C#堆栈，只有在Editor日志里有原生层的报错。遇到这种莫名其妙的原生崩溃，优先考虑是不是“上一次构建还没结束又开始了下一次”。
我在跑这个功能时的习惯是：构建知识库不放在Start里直接做，而是单独做一个初始化流程，给加载进度留出日志输出，期间也避免用户触发其他调用。如果界面允许，放在异步流程里并在UI上给出进度反馈。对用户而言，一个能看见“正在构建知识库索引 45%”的界面，比看似卡死的界面要友好一百倍。
3. 完整的配置流程：从创建知识库到检索生效的每一步
这里我按自己在工程里的实际做法写一套可复制的步骤。具体方法名可能在不同版本有差异，但流程骨架通用。你在操作时如果发现某个按钮或类名对不上，就回头按第2.1节的方法在当前版本代码里搜一下。
3.1 准备文档数据：结构比格式更值钱
你需要先确定知识来源。LLMUnity许多版本支持传文本内容，但不管是文件还是字符串，内容碎片化整理得好不好直接影响后续效果。我踩过的坑是：把一整个几十页的Word文档转成TXT丢进去，结果检索效果惨不忍睹，因为分块器不知道在哪里断句合理，经常把不相关的内容切成一块，或者把一个完整概念拦腰截断。
建议你在喂给知识库前，先把文档做成结构清晰的Markdown或纯文本，章节之间用明确分隔。比如：
- 文档标题
- 一级小节标题（##）
- 具体条目
这样分块时，切出来的块内容语义更完整。如果是问答对，就一条条隔开；如果是操作手册，就把独立的操作流程单独成段，不要跟其他流程混在一个段落里。虽然LLMUnity的切片逻辑会自行处理，但输入的组织程度高一些，切片结果会好不少。
实操提示：不要直接把PDF作为知识库原始内容往里塞。PDF里经常有分栏、页眉页脚、文字乱序，切出来经常是碎句子。先转成TXT或Markdown文本清洗一遍，才值得进知识库。
3.2 加载并构建知识库：一个稳妥的调用顺序
在UI层面，通常会有个知识库管理区域，可以新建、导入文本、构建索引、保存。整个过程可分三步：
- 创建知识库对象并指定名称，有些版本是点击某个按钮后生成一个资源文件。
- 向知识库添加内容（添加文件或手动传文本）。
- 执行索引构建，等向量化完成再保存。
调用层面，你在代码里需要遵循类似顺序：先初始化LLM核心，确认对话模型就绪，再配置Embedding模型，然后调用创建或加载知识库的接口，之后才能做添加或查询。如果你还没等对话模型完全就绪就开始加知识库，很可能出现“工作线程还没准备好，数据就来了”导致内容丢失。
构建完成后，一定要验证一次。验证方式最简单的是尝试检索一句和你文档内容非常相关的话，看返回的知识条目是否包含正确片段。而不是直接跑去问大模型。因为如果这个环节就没检索出东西，后面生成环节无论你怎么调Prompt都白搭。
3.3 在运行时把检索结果和对话串起来
检索本身只是拿到相关文本片段，真正让知识库影响对话，还需要让LLM在生成时带上检索内容。很多教程会告诉你，知识库里的内容会自动拼入System Prompt或用户消息前缀。但你最好打开Debug，实际看一眼最终发送给模型的Prompt里有没有包含文档片段，因为我在某几个版本里遇见过——知识库本身构建成功，检索也有结果，但对话接口没有把检索结果拼进去，导致问什么都像是没看到知识库一样。
具体做法是先看插件自带Demo是怎么把知识库和对话关联的。有些版本是通过初始化LlmClient时启用知识库选项，这样每次对话都会自动做检索；有些版本需要你手动在对话消息前插入检索结果文本。
我个人的建议是：初期调试阶段，把知识库检索和对话拆开测试。先单独验证检索模块能返回文档片段，再验证对话模型能正常对话，最后才验证两者联动。如果联动后回答不引用文档，优先怀疑Prompt拼接逻辑，而不是模型本身能力问题。
4. 常见问题排查：从现象反推根因，少走弯路
没有哪套配置是第一次就能完美的，下面按我实际遇到的高频现象整理排查思路。
4.1 Prompt被拼上了文档内容，但回答依然不用知识库内容
这个现象最让人抓狂。文档检索出来是准的，模型也确实收到了文档片段，但回答起来依然像失忆一样，或者只是生硬地把文档原文复制出来。我排查后的结论大致有三类原因：
第一，文档片段混在Prompt的最末尾，前面历史对话太长，模型注意力分配不过来，等于被早期指令淹没。处理方法：把知识库检索片段放在Prompt靠前位置，并且用清晰标记包裹，比如“以下是参考资料”。
第二，检索出来的片段本身就答非所问。比如文档里关于某个问题的描述分散在多个段落，TopK只取了一个不完整段落，模型信息不够。这种情况要加大检索数量，或者提高相关性阈值。
第三，模型本身指令跟随能力弱。LLMUnity可加载的模型有大有小，如果你为了性能选了很小的模型，它可能连“请根据参考资料回答”这种指令都跟不稳，这时候怎么调格式都白搭。只有换稍微大一点的模型，或精简Prompt指令。
4.2 检索返回的K值、相似度阈值怎么设才合理
知识库效果难调，多数不是模型问题而是检索参数问题。排名靠前的相关片段数和最低相似度阈值是两个可以调节的旋钮。
如果K值太小，比如只取1个片段，遇到需要综合多处信息的提问就回答不全；如果K值太大，比如TopK等于20，又会引入大量无关片段，把真正相关信息挤到边缘。
我一般是先按3到5起步，再根据文档块的平均长度来调整。如果每个块很短（一两句话），K值适当加大；如果每块就是一大段，K值就要缩小。相似度阈值设置则看你对自己的数据噪声容忍度：文档很规范，阈值可以设高一点，保证出来的是高相关片段；文档本身很杂，阈值就得调低一些，宁多勿缺。
经验：如果怎么调都不太对，回到文档内容本身思考。知识库检索的边界在于——如果文档原文里根本没有能回答这个问题的独立段落，再好的检索和模型也答不出来。能在文档里找到明确匹配的表述，才谈得上效果好坏。
4.3 Android真机打不开知识库：打包路径和首帧时序的问题
这个问题我花了一整天才定位。原因是编辑器环境走的是编辑器路径，能直接读写工程文件没问题；但到了手机上，你要把你的知识库文件放到一个应用可访问的位置，并且要让加载逻辑发生在文件确实存在之后。
如果文件只是放在Assets目录下某个普通文件夹里，Build时文件可能不会打成包。解决方法是把知识库文件或源文档放到StreamingAssets下。可如果你生成的是某个AssetDatabase管理的资源，打包后运行时按运行时路径去取是取不到这个“编辑器专用路径”的，需要在打包前用编辑器脚本把知识库内容转成运行时能读取的格式并传入目标平台。
另一种我遇到过的崩溃是：知识库加载代码在场景加载早期执行，而模型初始化还没完成，导致某些原生层句柄为空。真机上这类报错没有详细C#堆栈，只有类似“null pointer”的信息。这种情况要在初始化流程中保证顺序：LLM核心完全就绪后，再加载知识库。如果没有明确的“初始化完成”事件，可以加个协程等待，间隔几帧确认模型状态就绪后再调知识库接口。
4.4 中文语境下的知识库效果差如何补救
LLMUnity支持的知识库核心是向量检索。嵌入模型对中文理解能力参差不齐——如果用的是为一个西语/英语为主的预训练Embedding模型，对中文的语义区分会很粗糙，“刺客”和“侠客”这类词可能被编码得很接近甚至相同，检索准确性就不好保证。
遇到这种情况有几个补救手段：一是把中文文档里容易混淆的概念通过改写变成更明确的表述，比如少用模糊指代；二是调整分块粒度，中文按语义段落分比按固定字符硬切会好很多；三是检索失败时增加Query改写或同义词扩展——比如把用户问题里的简体转繁体、把简称扩成全称再检索；再有就是选用本身支持多语言的Embedding模型，实际操作需要在模型仓库里找合适文件替换，并且验证中文句子的检索效果。
5. 实测后的一些调优心得：让知识库更“聪明”一点
把知识库跑通之后，更值得花时间的是提升它的可用性。几个我在实际项目中反复调的效果因素供你参考。
5.1 先给自己做一套小小的评测集合
所谓“好用”，不能靠感觉。我在项目里会抽出20到30个用户最容易问的问题，这些问题又细分为三类：文档直接有答案、文档多段综合才能答、文档完全没有答案。每次改动分块策略或检索参数后，拿这30个问题过一遍，记录其中有多少个回答正确、有多少个检索命中但不回答、有多少个强行编造，跑完后看数据向哪边偏移。
这套评测集不用多高大上，就是纯文本问题列表加期望的文档来源。每次版本迭代跑一遍，能省下大量“凭感觉调参，调完又觉得好像更差了”的时间。RAG项目本身并没有银弹，经常就是一个参数对你这批数据效果更好，对另一批数据就不行。
5.2 用户的问法和文档里的说法不一致，怎么办
文档里写的是“角色阵营”，用户开口问的是“这个NPC跟谁是敌对关系”。如果没有任何改写，检索就找不到准确片段。有些LLMUnity的示例里会把用户原始问题直接拿去检索。为了提升命中，进入知识库检索前先做一个简单的手工预处理：把常见问法映射成文档里的标准说法。
比如我维护了一张映射表：
| 用户口语化提问 | 转换成检索词 |
|---|---|
| 这个角色跟谁打架最多 | 敌对关系阵营 |
| 武器强化材料哪里找 | 强化材料掉落来源 |
| 能不能复活 | 死亡惩罚与复活机制 |
如果不想维护这种人工映射，也可以把多组问法同时拿去检索，比如问句的关键词扩展成三四个近义表达，再合并检索结果后去重。这一步投入小，效果却很明显。
5.3 多轮对话时的检索范围处理
很多人第一次接入知识库时，只把用户当前一句话拿去做检索。可实际对话里，用户经常说“那这个呢”“换成另外一种呢”。这类代词直接把上一句给吞了，单独拿出来检索肯定是空的。我会在项目里保留一个简短的最近两轮对话记录，当检测到当前问题缺少主语或明显是代词开头时，把上一轮用户问题作为补充检索条件再查一遍。
还要注意不要把检索片段和历史对话无脑叠加在一起送进模型。上下文长度有上限，塞太多低价值内容反而降低回答质量。参考片段剪到能回答问题的最低数量为佳。
5.4 什么时候该更新知识库，什么时候该换模型
文档内容变了，知识库需要重新构建索引，不是简单地删除旧文件重来一遍就行。如果原文档只是小改，有些版本支持增量或重载；如果大改，最好重新构建，避免旧向量残留在库里，检索到过时内容比检索不到更麻烦。
模型不是越大越好，得考虑你目标设备端的显存和内存限制。项目验证阶段我建议先用精度尚可、速度能接受的模型跑通链路；链路稳定后再根据设备能力换更强的模型。但换对话模型时相关知识检索参数一般不用大动，因为Embedding模型没有换的话，检索向量空间还是一样的。
6. 最后的额外提醒
LLMUnity是个还在快速演进的开源方案，配置知识库时如果发现某个“现象”网上没人提及，先不要怀疑是自己学得不对，很可能是你当前版本的处理方式或文档说明有滞后。我遇到过Embedding模型下载地址过期导致构建到一半失败的情况，解决办法也很直接：去模型托管站点搜对应模型文件，手动下载再改配置文件路径即可。
按我个人经验，这一套知识库链路跑通后最值得做的，不是继续堆更多文档内容，而是反反复复检验“每个问题是否都能检索到正确来源”。一个只有三五十条高质量词条并能准确检索回复的知识库，远比塞了几千条杂七杂八内容但说话驴唇不对马嘴的知识库有价值得多。你的Unity项目如果只是想做个能陪着玩家对话的AI，知识库里每个词条都认真组织到位，比单纯追求“数据量大”要实用得多。多在人话到文档语言之间做翻译的工作，比多写几十段配置代码有用得多。