跳到主要内容

概述

Runtime Local LLM Documentation

Runtime Local LLM 是一个完全在设备上运行大型语言模型的插件，基于 llama.cpp，在运行时无需互联网连接。它支持 GGUF 模型文件，并提供了完整的 Blueprint API 用于加载模型、发送消息以及接收逐令牌响应，所有操作都在后台线程上执行，并通过游戏线程回调。

该插件支持 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 加内联函数
  • 多种模型加载方式：
    • 从本地文件路径加载
    • 按模型名称加载（在 Blueprint 中下拉选择）
    • 从 URL 下载并自动加载
    • 仅下载以进行模型预缓存
  • 逐令牌流式传输：在生成每个令牌时实时接收，用于实时显示
  • 异步 Blueprint 节点：带有输出委托的节点，用于加载、发送消息和下载
  • 可配置的推理参数：Temperature、Top-P、Top-K、repeat penalty、GPU 层卸载、上下文大小、种子、线程数和系统提示
  • 对话上下文管理：支持多轮对话，并支持上下文重置
  • 编辑器模型管理器：直接在项目设置中浏览、下载、导入、删除和测试模型
  • 跨平台打包：通过 NonUFS 暂存，模型文件随您的项目一起发布

工作原理​

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

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

模型存储与打包​

模型以 .gguf 文件形式存储在项目的 Content/RuntimeLocalLLM/Models 目录中。该插件会自动配置 Additional Non-Asset Directories To Copy (DirectoriesToAlwaysStageAsNonUFS)，以便模型文件随打包项目一起发布，并在运行时通过标准文件 I/O 保持可访问。

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

支持的模型​

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

  • Llama（Meta） — 1B、3B、8B 及更大
  • Mistral / Mixtral — 7B 及更大
  • Phi（Microsoft） — 2B、3B、4B
  • Gemma（Google） — 2B、7B
  • Qwen（Alibaba） — 1.5B、7B 及更大
  • TinyLlama — 1.1B
  • 以及更多社区模型

量化​

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

量化质量大小速度
Q2_K较低最小最快
Q4_K_M良好中等快
Q5_K_M较好较大中等
Q8_0高大较慢
F16 / F32最高最大最慢

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

其他资源​

Join our Discord
online · support