1. 项目概述：为什么要在UE5里跑本地大模型？

如果你是一个UE5开发者，最近肯定没少被各种AI新闻刷屏。从ChatGPT的API到Claude、DeepSeek，再到各种开源的7B、13B模型，感觉不搞点AI，项目都少了点“未来感”。但直接调用云端API，延迟、费用、隐私都是问题，更别说在游戏运行时突然断网有多尴尬了。

所以，把大模型“塞”进游戏里，让它本地运行，就成了一个很自然的需求。想象一下：NPC能真正理解你的对话并生成动态剧情；游戏内的智能助手能根据你的操作实时提供攻略；甚至能根据玩家上传的截图，生成一段即兴的诗歌描述。这一切，不需要联网，就在你的电脑或玩家的电脑上实时发生。

Llama-Unreal这个插件，就是为此而生的。它把风靡开源社区的llama.cpp推理引擎，完整地打包成了一个UE5插件。这意味着，你可以在蓝图中直接调用本地的大语言模型（LLM），进行文本对话、图片理解（多模态）、甚至语音交互，还能玩转本地知识库（RAG）。它不是一个简单的API封装，而是把整个推理引擎、向量数据库、语音识别模块都集成到了虚幻引擎的生态里。

我花了大概两周时间，从零开始踩坑，终于在我的Windows开发机上，把一个7B参数的模型成功跑在了UE5编辑器里，并且实现了基础的对话和图片识别功能。整个过程，从模型下载、环境配置、插件集成到最终调通，遇到了不少官方文档没写的“坑”。这篇教程，就是把我趟过的路，一步步拆解给你看，目标是让你在2小时内，也能在UE5里看到第一个由本地模型生成的“Hello World”。

2. 核心准备：模型、插件与环境清单

在动手写第一行蓝图之前，准备工作至关重要。走错一步，可能就要花几个小时甚至一天去排查。我把需要准备的东西分成了三类：模型文件、插件本身和开发环境。

2.1 模型文件下载与选择

这是整个流程的“燃料”。llama.cpp使用一种名为GGUF的模型格式，它是专门为高效CPU/GPU推理优化的。你需要去Hugging Face这类模型仓库下载。

第一步：确定模型类型你需要根据想实现的功能，选择对应的模型：

1. 纯文本对话：选择任何标注为Chat或Instruct的模型。例如Qwen2.5-7B-Instruct、Llama-3.2-3B-Instruct。
2. 多模态（图片理解）：需要选择支持Vision的模型，并且必须同时下载对应的mmproj（多模态投影器）文件。例如Qwen2.5-Omni-7B-Instruct，就需要下载qwen2.5-omni-7b-instruct-q4_k_m.gguf和mmproj-qwen2.5-omni-7b-f16.gguf两个文件。
3. 嵌入模型（用于RAG）：选择专门的嵌入模型，如bge-small-en-v1.5、nomic-embed-text-v1.5。它们通常体积更小，专门用于将文本转换为向量。

第二步：选择量化等级GGUF模型文件名里通常带有q4_k_m、q8_0这样的后缀，这代表量化等级。简单理解：数字越小（如q2、q4），模型体积越小、运行速度越快，但精度损失越大，回答质量可能下降；数字越大（如q8、f16），质量越接近原版，但体积和内存占用也越大。

• 新手推荐：q4_k_m或q5_k_m。在质量和速度/显存占用上取得了很好的平衡。一个7B模型大约4-5GB。
• 显存充足（>8GB）：可以尝试q8_0以获得更好效果。
• 性能测试：可以先下个q2_k的超小模型，快速验证流程。

第三步：实际下载操作以Qwen2.5-7B-Instruct模型为例：

1. 打开Hugging Face，搜索Qwen2.5-7B-Instruct-GGUF。
2. 在文件列表里，找到类似qwen2.5-7b-instruct-q4_k_m.gguf的文件，点击下载。
3. 在你的项目目录下，创建一个专用文件夹来存放模型，例如：YourProject/Saved/Models/。把下载的.gguf文件放进去。
4. 重要提示：插件默认从Saved/Models文件夹的相对路径加载模型。你可以使用./模型文件名.gguf这样的路径。

实操心得：国内下载Hugging Face模型可能会非常慢甚至失败。有两个备选方案：一是使用一些国内镜像站；二是利用huggingface-cli工具，配合HF_ENDPOINT环境变量设置为国内镜像地址来下载。如果实在困难，可以先去一些国内网盘社区寻找网友分享的搬运版本。

2.2 插件获取与集成

Llama-Unreal插件托管在GitHub上。对于绝大多数Windows用户，我们不需要从源码编译，直接使用官方编译好的发布版即可，这是最省事的方法。

1. 访问发布页面：打开GitHub上的getnamo/Llama-Unreal仓库，切换到Releases标签页。

2. 选择对应版本：找到最新版本（例如v1.1.0 for UE5.7），在Assets下方，你会看到两个主要的压缩包：

   • Llama-Unreal-UEx.x-vx.x.x.7z：这个是我们需要的，它包含了编译好的二进制文件（DLL等）。
   • Source code (zip)：这是源码，除非你需要修改插件或为其他平台编译，否则不要下这个。

3. 集成到项目：

   • 解压下载的.7z文件，你会得到一个Plugins文件夹。
   • 打开你的UE5项目根目录（即.uproject文件所在的位置）。
   • 将解压出的Plugins文件夹整个复制到你的项目根目录。如果项目已有Plugins文件夹，就把Llama-Unreal插件目录合并进去。
   • 最终路径应该类似于：YourProject/Plugins/Llama-Unreal/。

4. 重启与编译：

   • 关闭UE5编辑器（如果开着）。
   • 右键点击你的.uproject文件，选择“Generate Visual Studio project files”。这一步会让UE5识别新插件。
   • 用Visual Studio打开生成的.sln解决方案文件，编译你的项目（通常编译“Development Editor”配置）。
   • 编译成功后，重新启动UE5编辑器。

验证插件是否加载：打开编辑器后，进入编辑(Edit) -> 插件(Plugins)，在搜索框输入Llama，你应该能看到Llama-Unreal插件，并且它应该处于**已启用(Enabled)**状态。

2.3 开发环境确认

确保你的系统环境满足要求，可以避免很多诡异的问题。

• 操作系统：Windows 10 或 11（64位）。本教程全程基于Windows。
• 虚幻引擎：UE 5.7 或更高版本。插件对版本有要求，请确保你的项目版本匹配。我使用的是UE5.7。
• Visual Studio：2022版本，并安装“使用C++的游戏开发”工作负载。这是编译UE5 C++项目的标配。
• 显卡驱动：更新到最新版本。如果你打算使用GPU加速（强烈推荐），确保你的NVIDIA或AMD显卡驱动是最新的。
• 磁盘空间：至少预留20GB空间，用于存放引擎、项目、插件和模型文件。

注意事项：你的UE5项目必须是C++项目。纯蓝图项目无法使用这个插件，因为插件包含原生C++代码，需要编译。如果你当前是蓝图项目，可以在编辑器内文件(File) -> 新建C++类(New C++ Class...)，随便创建一个类（例如一个空的Actor），UE5就会为你生成编译所需的文件，将项目转换为C++项目。

3. 插件核心模块与初次配置详解

插件成功加载后，我们得先搞清楚它提供了哪些“武器”。Llama-Unreal插件不是单一功能，它是一套工具集，主要包含以下几个核心模块，理解它们的分工能让后续开发事半功倍。

3.1 认识四大核心模块

1. LlamaCore（核心）：这是插件的心脏。提供了ULlamaComponent（组件）和ULlamaSubsystem（子系统），用于加载模型、进行对话、处理多模态输入（图/文）。我们绝大部分的基础交互都会通过它。
2. LlamaTools（工具集/RAG）：提供了本地检索增强生成（RAG）的全套工具。包括URagStore（存储库）、向量数据库、BM25关键词检索和混合检索器。如果你想让模型读取自定义的文档（如游戏世界观设定）并据此回答，就需要用它。
3. LlamaWhisper（语音识别）：集成了whisper.cpp，用于语音转文本（STT）。你可以用它捕获麦克风输入，转换成文字后再送给LlamaCore处理，实现语音对话。
4. 辅助组件：如ULlamaAudioCaptureComponent，专门处理麦克风捕获和语音活动检测（VAD），为LlamaWhisper或直接的多模态音频输入提供音频流。

对于入门，我们首先聚焦于LlamaCore。只要搞定了它，你就已经打开了本地AI对话的大门。

3.2 创建并配置你的第一个Llama组件

让我们在场景中实际创建一个能对话的AI实体。

1. 创建测试关卡：在内容浏览器中新建一个空白关卡，命名为BP_LLM_Test。
2. 放置一个空Actor：从放置面板拖一个Empty Actor到场景中，重命名为BP_AI_Agent。
3. 添加Llama组件：选中BP_AI_Agent，在细节（Details）面板点击添加组件(Add Component)，搜索并选择Llama Component。现在，这个Actor就具备了运行大模型的能力。
4. 关键参数配置：选中新添加的Llama组件，我们需要配置几个最关键的参数：
   • Model Params -> Path To Model：这是模型路径。点击输入框右侧的文件夹图标，浏览到你放在Saved/Models下的.gguf文件。或者直接输入相对路径，例如：./qwen2.5-7b-instruct-q4_k_m.gguf。注意：路径开头是./，表示相对于Saved/Models目录。
   • Model Params -> System Prompt：系统提示词。这是模型的“人格设定”或初始指令。例如，你可以输入“你是一个乐于助人的游戏内向导，请用简短、友好的语言回答玩家的问题。”
   • Model Params -> Max Context Length：上下文长度。默认4096，对于大多数7B模型够用。如果你的模型支持更长（如8K、32K），可以在这里修改，但要注意这会增加内存消耗。
   • Model Params -> GPU Layers：这是影响性能最关键参数之一。它表示有多少层神经网络被卸载到GPU运行。设为-1表示全部使用CPU（慢）；设为0表示尝试使用GPU但可能回退；设为一个大数（如99）会强制将所有能放的层都放到GPU上。对于有独立显卡的用户，务必将其设置为一个大于模型层数的值（例如99）以启用GPU加速。一个7B模型通常有30多层。
   • Advanced -> Sampling -> Temperature：温度，控制生成文本的随机性。值越低（如0.1）输出越确定、保守；值越高（如0.8）输出越有创意、随机。初次测试可以先用0.7。

3.3 编写第一个对话蓝图

配置好组件后，我们需要用蓝图来驱动它。思路是：游戏开始时加载模型，加载成功后，发送一条测试消息。

1. 打开Actor蓝图：双击BP_AI_Agent打开其蓝图图表。
2. 创建事件图表：确保你在事件图表(Event Graph)标签页。
3. 添加“事件开始运行(Event BeginPlay)”节点。
4. 加载模型：从Event BeginPlay节点拉出引线，搜索Load Model（属于Llama组件）。调用它。
5. 监听模型加载成功：我们需要知道模型什么时候加载完。在Llama组件的细节面板，找到事件（Events）部分，你会看到On Model Loaded。点击它旁边的绿色加号，这会在蓝图中自动创建一个自定义事件绑定。
6. 发送第一条消息：从自动生成的On Model Loaded事件节点拉出引线，搜索Insert Templated Prompt。这个节点用于发送格式化的对话消息。
   • Prompt：输入你想说的话，比如“你好，请介绍一下你自己。”。
   • Role：选择User，表示这是用户说的话。
   • b Generate Reply：勾选True，表示我们希望模型生成回复。
7. 接收回复：同样，在Llama组件的细节面板事件中，找到On Response Generated，点击旁边的加号创建绑定。这个事件会在模型生成完整回复后触发，并输出一个Response字符串。
8. 打印回复：从On Response Generated节点的Response引脚拉出引线，搜索Print String，连接。这样，模型的回复就会打印到屏幕和输出日志。

现在，你的蓝图逻辑应该类似这样：BeginPlay -> Load Model -> (成功) On Model Loaded -> Insert Templated Prompt -> (回复) On Response Generated -> Print String。

编译并运行：编译蓝图，回到关卡，点击播放。观察输出日志（Window -> Output Log）。如果一切顺利，你会先看到模型加载的日志，几秒到几十秒后（取决于模型大小和硬件），就能看到模型生成的自我介绍。

踩坑记录：第一次运行时，最常见的错误是Error Code 10: llama_model_load_from_file failed。这几乎总是模型路径错误导致的。请再次确认：

1. 路径是否正确，特别是./前缀。
2. 文件名是否完整，包括.gguf后缀。
3. 模型文件是否真的下载完整（可以检查文件大小）。
4. 如果路径包含中文或特殊字符，尝试将其移到全英文路径下。

4. 从基础对话到高级功能实战

当第一个“Hello World”跑通后，我们就可以探索插件更强大的功能了。这部分是教程的核心，我会带你实现多轮对话、流式输出、图片理解，并分享每一步的调试技巧。

4.1 实现连贯的多轮对话与历史管理

默认情况下，组件会维护一个对话历史（保存在KV缓存中）。这意味着你不需要手动拼接历史记录，模型能记住上下文。但我们需要了解如何操作这个历史。

基本的多轮对话：你只需要连续调用Insert Templated Prompt，模型就会基于之前的对话历史来生成回复。例如：

1. 用户：“今天的天气怎么样？”
2. 模型：“（假设今天是晴天）今天是晴天，气温适宜。”
3. 用户：“那我该穿什么衣服？”（模型会结合“晴天”这个上下文来回答）

历史管理操作：

• 重置上下文：调用Reset Context History。这会清空模型“记忆”中的所有对话历史，回到只有系统提示词的状态。适合开始一个全新的话题。
• 回滚对话：调用Rollback Context History By Messages，并传入一个数字（例如2）。这会删除最近N条消息对（一条用户消息+对应的助手回复）。比如，你觉得模型刚才的回答不好，可以回滚一步，重新提问。
• 移除最后一条助手回复：调用Remove Last Assistant Reply。这只会删除模型的上一条回复，但保留你的提问，方便你让模型重新生成。

蓝图实现示例：我们可以创建一个简单的交互界面。在关卡中放两个文本框（Editable Text）和一个按钮。一个文本框用于输入，另一个用于显示模型回复。按钮点击事件中，获取输入框文本，调用Insert Templated Prompt，然后将On Response Generated返回的文本设置到显示框。

4.2 启用流式输出与实时UI更新

默认的On Response Generated是在整个回复生成完毕后一次性触发。对于较长的回复，用户需要等待较长时间。流式输出可以逐词或逐句地显示回复，体验好很多。

1. 启用流式Token：在蓝图或代码中，监听On New Token Generated事件。这个事件在模型每生成一个Token（可以粗略理解为词或字）时触发，并返回这个Token的字符串。
2. 构建实时回复：在On New Token Generated事件中，将返回的Token字符串追加到一个显示字符串变量中，并实时更新UI（如文本框）。这样用户就能看到文字逐个出现的效果。
3. 启用分句输出：如果你觉得逐字输出太快，可以监听On Partial Generated事件。这个事件会在模型生成一个完整的句子（根据标点判断）时触发，返回一个更完整的片段，更新UI的节奏会更舒服。
4. 处理Markdown：如果模型回复包含Markdown格式（如粗体、斜体），可以监听On Markdown Partial Generated事件，它能提供带格式状态的文本片段，方便你进行富文本渲染。

性能提示：流式输出会频繁触发事件和UI更新。如果UI更新逻辑过于复杂，可能会影响生成速度。建议将文本追加操作放在Tick中由变量驱动，或者使用异步任务来减轻游戏线程负担。

4.3 集成多模态模型：让AI“看懂”图片

这是插件非常酷的功能。你需要一个支持视觉的多模态模型（如Qwen2.5-Omni）和对应的mmproj文件。

准备工作：

1. 下载视觉模型的两个GGUF文件：基础模型（如qwen2.5-omni-7b-instruct-q4_k_m.gguf）和投影器文件（如mmproj-qwen2.5-omni-7b-f16.gguf）。
2. 将这两个文件都放入Saved/Models/。
3. 在Llama组件的Model Params中，不仅要设置Path To Model，还必须设置Mmproj Path（例如./mmproj-qwen2.5-omni-7b-f16.gguf）。

发送图片提示的两种方式：

方式一：从纹理资产（UTexture2D）

1. 准备一张图片，导入到UE5内容浏览器，它会成为UTexture2D资产。关键点：纹理的像素格式必须是PF_B8G8R8A8。你可以在纹理资产的属性中查看和转换。
2. 在蓝图中，获取到这个纹理对象的引用。
3. 调用Insert Template Image Prompt节点。
   • Texture参数：传入你的纹理引用。
   • Prompt参数：输入你的问题，例如“请描述这张图片里的内容。”。
   • 其他参数与文本对话类似。

方式二：从磁盘文件路径（更高效）如果你不想把图片导入为UE资产，或者图片是动态生成的（如游戏截图），可以使用文件路径方式。

1. 确保图片文件（如JPG、PNG）存在于磁盘上。
2. 调用Insert Template Image Prompt From File节点。
   • Image Path参数：传入图片的绝对路径，例如“C:/Users/Name/Pictures/screenshot.png”。
   • 这种方式避免了GPU回读（readback），通常效率更高。

如何验证视觉功能已启用：在加载模型后（On Model Loaded事件之后），可以调用Is Multimodal Loaded和Supports Vision节点来检查。如果返回True，说明视觉模块加载成功。

实操心得：处理图片时，分辨率会影响处理的Token数量，从而影响速度和内存。插件内部会进行缩放处理，但传入过大图片（如4K）仍可能导致上下文溢出。建议先将图片缩放到合理尺寸（如512x512）再传入。另外，首次处理图片时，由于需要加载视觉编码器，可能会有几秒的延迟，属正常现象。

4.4 连接远程推理后端：作为OpenAI API的替代

插件不仅支持本地运行，还可以无缝切换到远程的、兼容OpenAI API的服务器。这对于调试、或者当本地机器性能不足时非常有用。

配置远程模式：

1. 确保你有一个正在运行的、兼容OpenAI API的LLM服务。例如：
   • llama.cpp自带的server（-server模式）
   • LM Studio（打开后启用“本地服务器”）
   • Ollama（运行ollama run后，其API默认在11434端口）
   • 当然，也可以是官方的OpenAI或Claude API端点（需要网络和API Key）。
2. 在Llama组件的Endpoint参数组中，设置Base Url为你的服务器地址，例如http://127.0.0.1:8080（llama.cpp server默认）或http://127.0.0.1:1234（LM Studio默认）。
3. 将b Use Remote参数设置为True。
4. 现在，当你调用Load Model时，插件会去探测远程服务器的/health和/props端点。成功后，后续所有的Insert Templated Prompt等请求都会发送到远程服务器。

动态切换的妙用：你可以在运行时通过Set Use Remote节点来切换本地和远程模式。插件内部会尝试智能地同步对话历史。例如，你可以在编辑器开发时使用远程高性能服务器快速迭代，打包发布时切换到本地轻量模型。

5. 性能调优、问题排查与进阶技巧

当功能都跑起来后，下一步就是让它跑得更快、更稳。这部分分享的都是在实际项目中积累的经验和遇到的坑。

5.1 GPU加速配置与显存管理

核心参数GPU Layers：这个值决定了有多少神经网络层在GPU上运行。设为-1全CPU，速度最慢但兼容性最好。设为0，插件会尝试自动分配，但可能不稳定。最佳实践是将其设置为一个明显大于模型层数的值，比如99。这样插件会尝试将所有层都加载到GPU。如果显存不足，加载会失败（Error Code 10），此时你需要减少这个数字，或者换用量化等级更低的模型。

如何知道模型有多少层？一个粗略的估计是：7B参数模型大约有30-35层，13B大约有40-45层。更准确的方法是使用llama.cpp的命令行工具llama-cli，加载模型时它会打印层数信息。

显存占用估算：

• 模型权重：一个q4_k_m的7B模型，权重文件约4-5GB。全部加载到GPU显存，就需要至少5GB。
• 上下文缓存（KV Cache）：这部分内存用于存储对话历史。由Max Context Length决定。长度越大，缓存越大。4096上下文对于7B模型可能需要额外几百MB到1GB显存。
• 运行时内存：推理过程本身也需要一些临时内存。

建议：对于拥有8GB显存的显卡（如RTX 4070），运行q4_k_m的7B模型并设置GPU Layers=99通常是可行的。如果遇到显存不足，可以尝试：

1. 降低GPU Layers，让一部分层留在CPU。
2. 换用更小的模型（如3B）或更低量化的模型（如q2_k）。
3. 减少Max Context Length。
4. 关闭一些不必要的后台应用，释放显存。

5.2 常见错误代码与解决方案速查表

在开发过程中，你一定会遇到各种错误。通过On Error事件可以捕获错误码和信息。以下是几个最常见错误及其解决方法：

调试心法：遇到错误时，第一件事是打开Output Log（输出日志），搜索Llama或错误码。插件会输出非常详细的日志，包括模型加载进度、层数、显存分配情况等，这是定位问题的第一手资料。

5.3 高级技巧：使用RAG构建游戏知识库

RAG（检索增强生成）可以让模型回答关于你特定游戏内容的问题，比如角色背景、物品描述、任务线索等。

快速上手URagStoreComponent：

1. 在Actor上添加一个Rag Store Component。
2. 配置两个模型：
   • Embedding Model Params.Path To Model：设置一个嵌入模型，如./bge-small-en-v1.5-q4_k_m.gguf。这个模型负责将文本转换为向量。
   • Answer Model Params.Path To Model：设置一个对话模型，如你之前用的./qwen2.5-7b-instruct-q4_k_m.gguf。这个模型负责生成最终答案。
3. 自动初始化：保持b Auto Initialize On Begin Play为True，游戏开始时它会自动加载这两个模型。
4. 注入知识：调用Ingest Text或Ingest File节点，将你的游戏文档（如.txt, .md文件）内容注入到知识库中。你可以一次性注入大量文本。
5. 提问：监听On Ask Response Generated事件，然后调用Ask Default节点并传入你的问题。RAG组件会自动从知识库中检索相关片段，组合成提示词，交给对话模型生成答案。

性能考虑：嵌入模型通常很小（几十到几百MB），加载很快。但检索过程涉及向量计算，如果知识库很大（数万条记录），实时检索可能会有延迟。建议在游戏加载时初始化并注入知识，游戏过程中进行检索。

5.4 打包与分发注意事项

当你开发完成，需要打包项目给其他人运行时，模型文件不会自动打包进游戏。你需要手动处理。

1. 模型文件作为额外资源：将你的.gguf模型文件视为游戏的外部资源。你可以选择让玩家自行下载，或者将其放在游戏安装目录的特定文件夹（例如GameName/Content/Models/）。
2. 修改模型加载路径：在打包版本中，不能使用相对于Saved/Models的路径了。你需要使用绝对路径，或者使用FPaths::ProjectContentDir()等API来构建指向游戏安装目录内资源的路径。
3. 首次运行检测：可以在游戏首次启动时，检查模型文件是否存在。如果不存在，引导玩家去指定位置下载或从游戏服务器后台下载。
4. 版本管理：模型文件很大，更新成本高。如果更新了模型，需要考虑如何让玩家平滑升级。

我个人在测试打包时，采用的方法是：在游戏可执行文件同级目录创建一个Models文件夹，将模型文件放进去。然后在蓝图中，使用FPaths::LaunchDir()来获取这个路径，并拼接上模型文件名。这样，只要玩家把模型文件放在正确位置，游戏就能找到它。

最后，本地大模型在UE5中的应用才刚刚开始，性能和体验还有很大优化空间。但它为游戏带来的可能性是巨大的——真正动态的叙事、个性化的交互、永不重复的对话内容。希望这篇教程能帮你跨出第一步，剩下的创意，就交给你的游戏了。如果在实际操作中遇到任何本文未覆盖的奇怪问题，不妨去插件的GitHub仓库的Issues页面看看，或者在其Discord社区提问，那里的开发者和用户都非常活跃。