llama.jar

llama.jar 🦙

llama.jar 是一个轻量级、高性能的 Minecraft 模组，通过 llama.cpp 将本地大语言模型直接集成到 Minecraft 中。

完全离线运行于你自己的硬件上，无需 API 密钥、订阅费用，也没有任何外部网络请求。

[!WARNING] 此为 Alpha 版本，尚未在所有环境中充分测试。请谨慎使用，如遇任何错误或问题，请务必报告。

---

主要特性

• 离线本地 LLM 推理：直接在 Minecraft 进程内运行你喜爱的开源模型（如 LLaMA-3、Qwen-2.5、Phi-3、Mistral 等）。
• 硬件加速与 GPU 支持：支持多核 CPU 执行，并可通过 GPU 卸载（CUDA、Metal、OpenCL/CLBlast）实现硬件加速生成。支持多 GPU 配置。
• 内置游戏集成：使用游戏内命令实时向加载的模型发送提示，或监听交互。
• 模组开发库：完全架构为库模组。你可以在自己的自定义模组中导入 llama.jar，轻松添加 AI 驱动的 NPC、动态任务生成或智能自动助手。
• 广泛版本兼容性：支持 Forge 和 Fabric 平台，涵盖多个 Minecraft 版本：
  • 1.20.1
  • 1.21.1
  • 1.21.11

---

如何设置

1. 下载模组：下载与你使用的模组加载器（Forge 或 Fabric）和 Minecraft 版本对应的正确 jar 文件。
2. 添加 GGUF 模型：下载任意 GGUF 格式模型（例如 llama-3-8b-instruct.Q4_K_M.gguf 或更小的模型如 qwen-2.5-1.5b-instruct），将 .gguf 文件放入 .minecraft/models/ 文件夹。
3. 启动 Minecraft：模组将在启动时自动设置工作区。

---

游戏内命令

使用命令权限管理模型并即时运行提示：

• /model list — 列出 models/ 目录下所有可用的 GGUF 文件。
• /model load <文件名> — 将选中的模型加载到内存中。
• /model status — 显示当前活动模型的信息。
• /llama <提示> — 向加载的模型提交提示，并将输出直接流式传输到聊天栏。
• /llama stop — 立即停止当前文本生成。

---

配置

公共配置文件（llamajar-common.toml 或 llamajar.json）会在你的 config 目录中生成。你可以调整性能参数：

• modelName — 启动时自动加载的 GGUF 模型名称（留空则手动加载）。
• systemPrompt — 设置默认系统提示，以自定义模型行为、个性或指南（留空则无系统提示）。
• gpuLayers — 卸载到 GPU 的模型层数（越高意味着将更多计算卸载到 GPU 显存）。
• threads — 分配给模型推理的 CPU 线程数（默认匹配 CPU 物理核心数）。
• contextLength — 对话的最大上下文窗口大小（以 token 计）。

---

开发者集成（库模组用法）

要将 llama.jar 作为你自己的 AI 模组的基础，请将其添加到你的开发环境中。

Gradle 设置

repositories {
    mavenLocal() // 在本地发布 llama.jar 后
}

dependencies {
    // 用于 Fabric 开发
    modImplementation "com.popr4x.llamajar:llamajar-fabric-1.20.1:alpha-1.0"
    
    // 用于 Forge 开发
    implementation "com.popr4x.llamajar:llamajar-forge-1.20.1:alpha-1.0"
}

在 Java 中访问 llama.cpp 上下文

import com.llamajar.LlamaJar;
import de.kherud.llama.LlamaModel;
import de.kherud.llama.LlamaIterator;

// 检查模型是否已加载
if (LlamaJar.isModelLoaded()) {
    LlamaModel model = LlamaJar.getModel();
    // 执行自定义推理、注册自定义监听器或管理模型状态
}

---

许可证

本项目采用 AGPLv3 许可证。底层使用了 llama.cpp 和 de.kherud:llama 提供的 Java JNI 绑定，后者基于 Apache-2.0 许可证。