如何在 Godot 4 中运行本地 LLM
在 Godot 4 中运行本地 LLM:用 Ollama 提供模型服务,通过 HTTPRequest 从 GDScript 调用,保存聊天历史,并了解本地模型对玩家的成本。
Sercan AltundasFounder of Neocortex
· 阅读约 8 分钟

在 Godot 中本地运行语言模型,意味着你的 NPC 无需联网,也不会按每条消息计费。最简单的方案是 Ollama(它在你自己的机器上提供开放模型服务)加上 Godot 内置的 HTTPRequest 节点。本指南将用 GDScript 构建一个本地 NPC 对话,然后介绍向玩家交付本地模型时真正涉及的内容。
在本地运行模型的两种方式
- 本地服务器,例如 Ollama,与游戏并行运行,并通过 HTTP 进行回应。设置简单,非常适合原型开发,但每位玩家都需要安装它。
- 游戏内置模型,通过嵌入 llama.cpp 的 GDExtension 实现,例如开源插件 NobodyWho。玩家无需额外安装任何东西,但模型会随你的游戏一起发布,并运行在他们的硬件上。
本指南使用 Ollama,因为它只需十分钟即可上手,而且对于任何 HTTP 模型服务器来说,GDScript 的思路都是相同的。
第一步:用 Ollama 运行模型
安装 Ollama,然后下载一个小型模型,并在终端中进行测试。几十亿参数的小模型在普通游戏 GPU 上响应很快,对于测试对话来说已经绰绰有余。Ollama 运行期间会监听 http://localhost:11434。
第二步:从 GDScript 调用它
将一个 HTTPRequest 节点添加为你 NPC 的子节点,然后挂载以下脚本。它会保存对话历史,使模型知道之前说过什么:
extends Node
@onready var http: HTTPRequest = $HTTPRequest
var history: Array = [
{"role": "system", "content": "You are Brannoch, a gruff village blacksmith. Answer in one or two sentences."}
]
func _ready() -> void:
http.request_completed.connect(_on_request_completed)
func ask(player_line: String) -> void:
history.append({"role": "user", "content": player_line})
var body := JSON.stringify({"model": "MODEL_NAME", "messages": history, "stream": false})
http.request("http://localhost:11434/api/chat", ["Content-Type: application/json"], HTTPClient.METHOD_POST, body)
func _on_request_completed(result: int, code: int, _headers: PackedStringArray, body: PackedByteArray) -> void:
if result != HTTPRequest.RESULT_SUCCESS or code != 200:
push_warning("Local model request failed: %d" % code)
return
var reply: Dictionary = JSON.parse_string(body.get_string_from_utf8())["message"]
history.append(reply)
print(reply["content"]) # show it in your dialogue UI将 MODEL_NAME 替换为你下载的模型,然后调用 ask("Is the north road safe?"),Brannoch 就会在你自己的机器上回答。一个 HTTPRequest 一次只能处理一个请求,因此请等待回复之后再发送下一句台词。
第三步:让它更像一个角色
原始模型只是一个聊天机器人。要把它变成 NPC,你还需要:
- 更精简的系统提示词: 角色想要什么,不知道什么,说话方式如何。参见如何赋予 NPC 独特的性格。
- 修剪历史记录: 历史会随着每句台词增长,回答所需的时间也会随之增加。只保留系统提示词以及最近的几轮对话。
- 游戏上下文: 在玩家的消息之前,添加一句简短的说明,描述刚刚发生了什么("The player returned the stolen hammer.")。
本地模型对玩家的成本
本地推理把成本从服务器账单转移到了玩家的硬件上:
- 内存。 模型与你的游戏共享 GPU。在我们自己的设备端运行时上,3B 模型大约需要 3 GB 显存,2B 模型则低于 1 GB。
- 下载大小。 模型会为你的游戏增加数 GB 的体积。
- 质量。 小模型知识较少,也更容易偏离角色设定。
- 平台。 网页导出版本和大多数手机都无法很好地运行它们。
它还需要你自己构建什么
本地模型只提供文本。游戏角色通常还需要更多:
- 语音: 为玩家提供语音识别,为回复提供文字转语音,并结合流式传输以保持等待时间较短。参见AI NPC 语音流程是如何工作的。
- 情绪与动作: 通过提示词要求结构化输出,并可靠地解析它。
- 玩家施压时保持角色设定。 参见如何让 AI NPC 保持角色。
Godot 中的云端方案
当你需要的是一个角色,而不仅仅是一个聊天机器人时,Neocortex Godot SDK 会在云端运行角色,因此玩家无需安装任何东西,也不需要占用 GPU。你在浏览器编辑器中设计角色的性格、知识库、语音和动作,SDK 则在 GDScript 中为你提供语音输入和输出、每句台词的情绪,以及以数据形式返回的动作。具体的操作步骤见如何在 Godot 4 中添加 AI NPC 对话。
需要在生产环境中进行设备端推理的工作室,可以与我们洽谈设备端运行时,该运行时以 Custom 套餐的形式提供:在笔记本 RTX 3080 上,它的首个 token 在 0.06 秒内返回,约一秒后即可开始说话。联系我们规划相关方案。
下一步
关于延迟的权衡,请阅读如何让 AI NPC 语音在一秒内回复。对于 Unity,同一主题在如何在 Unity 游戏中本地运行 LLM中有所介绍。所有教程都收录在构建 AI NPC 指南中。
常见问题
如何在 Godot 中运行本地 LLM?
用 Ollama 在你的机器上运行模型,然后使用 HTTPRequest 节点从 GDScript 调用它的本地 HTTP API。它可以离线工作,并且每条消息都不产生费用,因此是原型化 NPC 对话的好方法。
我可以发布使用 Ollama 的游戏吗?
只有当每位玩家都安装了 Ollama 并下载了模型时才可以,而很少有人会这样做。已发布的游戏要么把模型打包进构建中,要么使用 Neocortex 这类云服务,后者无需玩家机器上做任何准备。
NPC 能使用多大的本地模型?
几十亿参数的模型可以在普通游戏 GPU 上运行。在我们自己的设备端运行时上,3B 模型大约需要 3 GB 显存。更大的模型能给出更好的回答,但需要多得多的内存。
Godot 中的本地 LLM 支持语音吗?
它本身不支持:你需要分别添加语音识别和文字转语音。Neocortex Godot SDK 则在云端运行角色,为其提供语音输入和输出、情绪及动作。






