游戏 AI / 系统课时
让模型只返回游戏需要的 JSON
让模型只返回游戏需要的 JSON
本篇解决模型返回一大段自然语言,游戏却只需要少量结构化字段的问题。完成后,你可以定义稳定的数据契约、校验模型结果,并把合法 JSON 直接映射为游戏对象。
学习目标
- 设计只包含游戏必需字段的 JSON 数据契约
- 使用严格校验阻止缺字段、错类型和越界数据进入游戏逻辑
- 区分模型生成、数据校验与游戏对象映射三个阶段
先把自然语言改成数据契约
游戏运行时真正需要的是可消费的数据,而不是“这个 NPC 看起来很生气”这样的描述。例如任务系统可能只需要 id、type、text 和 difficulty。字段越少,解析、版本管理和失败处理越简单。

推荐先写契约,再写提示词。以任务卡为例,可以约定 type 只能是固定枚举,difficulty 必须是整数,text 必须是非空字符串。模型即使表达能力很强,也不能代替这些运行时约束。
提示词只负责约束语义
提示词应该明确告诉模型“只能返回对象”“不要解释”“字段含义是什么”。但不要把提示词当成唯一防线,因为模型输出仍可能出现额外字段、数字类型错误或非法枚举值。
你正在为游戏任务系统生成一条任务。
只返回 JSON 对象,不要 Markdown,不要解释文字。
字段必须且只能包含:
id:字符串,任务唯一标识。
type:只能是 "collect"、"defeat"、"escort"。
text:非空字符串,玩家可直接看到的任务文本。
difficulty:1 到 5 的整数。预期结果
{"id":"quest-1042","type":"collect","text":"收集 3 枚古代水晶","difficulty":2}校验通过后再创建游戏对象
下面的示例不依赖任何模型厂商 SDK,而是模拟“模型已经返回字符串”这一边界。这样可以单独验证游戏侧最关键的安全边界:先解析,再校验,最后映射。
interface QuestData {
id: string;
type: "collect" | "defeat" | "escort";
text: string;
difficulty: number;
}
function parseQuest(raw: string): QuestData {
const value: unknown = JSON.parse(raw);
if (typeof value !== "object" || value === null || Array.isArray(value)) {
throw new Error("quest must be a JSON object");
}
const data = value as Record<string, unknown>;
const allowedTypes = new Set(["collect", "defeat", "escort"]);
if (typeof data.id !== "string" || data.id.length === 0) {
throw new Error("invalid id");
}
if (typeof data.type !== "string" || !allowedTypes.has(data.type)) {
throw new Error("invalid type");
}
if (typeof data.text !== "string" || data.text.trim() === "") {
throw new Error("invalid text");
}
if (!Number.isInteger(data.difficulty) || data.difficulty < 1 || data.difficulty > 5) {
throw new Error("invalid difficulty");
}
// 明确映射字段,避免把模型返回的未知字段直接带进游戏对象。
return {
id: data.id,
type: data.type as QuestData["type"],
text: data.text,
difficulty: data.difficulty,
};
}
const raw = '{"id":"quest-1042","type":"collect","text":"收集 3 枚古代水晶","difficulty":2}';
const quest = parseQuest(raw);
console.log(quest.id, quest.type, quest.difficulty);预期输出
quest-1042 collect 2实际接入模型时,可以在服务端或支持结构化输出的模型调用层继续使用同一份数据契约;游戏侧仍应保留校验,因为接口版本、提示词或模型行为变化都可能产生异常数据。
不要让额外字段直接进入运行时
常见错误是解析后直接把整个对象交给游戏实体。这样模型一旦返回 comment、mood 或其他字段,运行时的数据结构就会悄悄膨胀。更稳妥的方式是建立显式 DTO,只复制游戏真正使用的字段。
还要决定失败策略。无法解析 JSON、字段校验失败或数值越界时,不应继续创建任务;可以记录原始响应供排查,并返回一个可识别的失败状态。对于实时游戏,宁可丢弃一条不合法生成结果,也不要让坏数据进入状态更新链路。
只要把模型当成“不完全可信的数据生产者”,再用固定契约和运行时校验把边界封住,生成内容就能从自然语言输出转换成稳定的游戏数据入口。