跳到主要内容

概述

Runtime Local LLM Documentation

Runtime Local LLM 是一款完全在设备上运行大型语言模型的插件，基于 llama.cpp 实现，运行时无需网络连接。它支持 GGUF 模型文件，并提供完整的蓝图 API，用于加载模型、发送消息以及逐 token 接收响应，所有操作均在后台线程中执行，并通过游戏线程回调处理。

该插件支持 Windows、Mac、Linux、Android（包括 Meta Quest 及其他基于 Android 的平台）以及 iOS。

主要功能​

  • 完全离线推理：运行时无需云服务或API密钥
  • GGUF模型支持：加载任意GGUF格式的模型（Llama、Mistral、Phi、Gemma、Qwen等）
  • 最新的llama.cpp：在Fab上定期更新以紧跟llama.cpp的发布节奏，确保始终支持最新的GGUF模型格式
  • GPU加速：在Windows和Linux上使用Vulkan，在Mac和iOS上使用Metal，在Android和Meta Quest上使用CPU及内部指令集
  • 多种模型加载方式：
    • 从本地文件路径加载
    • 按模型名称加载（蓝图中的下拉选择）
    • 从URL下载并自动加载
    • 仅下载用于预缓存模型
  • 逐令牌流式输出：实时接收每个生成的令牌，实现即时显示
  • 异步蓝图节点：包含输出委托的节点，用于加载、发送消息和下载
  • 可配置推理参数：温度、Top-P、Top-K、重复惩罚、GPU层卸载、上下文大小、随机种子、线程数和系统提示
  • 对话管理：支持多轮对话，具备上下文重置、保存/加载到磁盘、内存快照以及长对话自动摘要功能
  • 编辑器模型管理器：在项目设置中直接浏览、下载、导入、删除和测试模型
  • 跨平台打包：通过NonUFS暂存方式将模型随项目一同发布

工作原理​

  1. 在编辑器中管理模型：使用插件设置面板浏览预定义模型目录、下载模型，或导入您自己的GGUF文件
  2. 在运行时加载模型：调用加载函数（按文件、名称、URL或元数据），并传入推理参数
  3. 发送消息：将用户消息传递给LLM实例；模型生成响应时，令牌会通过委托流式返回
  4. 使用响应：在聊天界面中显示令牌、驱动NPC对话、生成动态内容，或将其输入其他系统

所有推理均在专用后台线程上运行。回调（令牌生成、完成、错误）在游戏线程上触发，因此您可以安全地从中更新 UI 和游戏状态。

常见使用场景​

  • 游戏内聊天机器人与助手：问答、帮助系统、动态教程
  • NPC对话：利用对话快照实现具有持久性角色记忆的交互式NPC
  • 长时角色扮演与叙事系统：自动摘要功能可将持续数小时的对话控制在上下文限制内，同时保留关键信息
  • 程序化内容生成：即时生成任务描述、物品背景故事、对话树
  • 离线优先应用：无需网络连接即可实现LLM功能的任何场景

模型存储与打包​

模型以 .gguf 文件形式存储在项目目录的 Content/RuntimeLocalLLM/Models 文件夹中。该插件会自动配置要复制的附加非资产目录（DirectoriesToAlwaysStageAsNonUFS），确保模型文件随打包项目一同发布，并在运行时通过标准文件输入/输出保持可访问性。

每个模型还附带一个 .json 侧边文件，用于存储其元数据（显示名称、系列、变体、描述、参数数量）。

支持的模型​

该插件支持任何GGUF格式的模型。编辑器提供热门预定义模型目录，支持一键下载，同时您也可以导入任意自定义GGUF文件。常见的模型系列包括：

  • Llama（Meta）— 1B、3B、8B 及更大参数
  • Mistral / Mixtral — 7B 及更大参数
  • Phi（微软）— 2B、3B、4B
  • Gemma（谷歌）— 2B、7B
  • Qwen（阿里巴巴）— 1.5B、7B 及更大参数
  • TinyLlama — 1.1B
  • 以及更多社区模型

量化​

模型提供多种量化级别，在质量、大小和速度之间进行权衡：

量化质量Size速度
Q2_K更低最小最快
Q4_K_MGood中等Fast
Q5_K_M更好更大中等
Q8_0High大更慢
F16 / F32最高最大最慢

对于移动设备和VR设备，建议使用紧凑型模型（1B–3B参数）配合较小的量化级别（Q2_K至Q4_K_M）。对于桌面设备，可根据可用RAM及CPU/GPU资源选择更大的模型和更高的量化级别。

其他资源​

Join our Discord
online · support