原文标题Unity 集成大语言模型的方法、实现与评估研究作者雍潇潇项目UnityLLM 统一接入插件 3D 解谜游戏UnityLLM 插件 主客观双轨评估把 DeepSeek、Kimi、豆包塞进 Unity我怎么做了一套“零代码切换”的 LLM-NPC 框架一、先说说为什么要折腾这个做独立游戏的应该都有同感传统 NPC 对话太僵了。 branching dialogue 树写到后期就是灾难玩家稍微跳出预设问题NPC 就开始“人工智障”。这两年大模型火了之后大家第一反应是能不能让 GPT/DeepSeek 直接进 Unity 当 NPC 大脑但真动手你会发现从 Python 原型到 Unity 生产环境中间隔着一条鸿沟接入碎片化DeepSeek、Moonshot、火山引擎、智谱、通义千问、文心一言……每家 API 的鉴权、请求体、返回格式都不一样换一家就要重写一套 C# 网络层。最新我看都接口形式统一了Unity 里没有现成方案学术圈很多 awesome 的 LLM Agent比如斯坦福小镇、Voyager都是 Python 后端和 Unity 的 C# 协程、ScriptableObject、实时渲染管线根本接不上。角色一致性难搞光靠一句 system prompt多轮对话后 NPC 很容易“人设崩塌”从冷酷 AI 变成热情客服。所以我就围绕一件事在 Unity 内部做一套标准化、可复用、带人格资产的 LLM 接入框架并且真的放入游戏让 100 多个玩家来测并且通过代码测试输出了横向对比报告。二、整体思路双层架构我不想做“调通一个 API 就发教程”的Demo而是希望策划换模型不用改代码策划调人设不用找程序。所以架构拆成两层层级职责关键技术底层统一接入层屏蔽不同 MaaS 平台的 API 差异实现“零代码”模型切换策略模式 ScriptableObject 依赖倒置上层人格资产层把 NPC 人设抽象成可配置的数据资产保证多轮对话角色不崩人格四元组身份/语言风格/句式/背景 动态上下文管理下面分别聊聊这两层我是怎么实现的。生产级 Unity LLM-NPC 框架从“能跑”到“可维护”的工程化实践【先看这一节5 分钟读懂全文】背景变化2025-2026 年国内大模型 API 已基本收敛到 OpenAI-compatible 格式接入门槛从“协议翻译”变成了“工程治理”。开发者真正的痛点不再是“调不通接口”而是如何在 Unity 里管理多平台配置、保证 NPC 人设不崩、并基于数据做模型选型决策。我做了一套什么UnityLLM 插件基于策略模式 ScriptableObject 的零代码扩展框架。新增一个平台 新建一个.asset配置 填 3 个字段不碰任何业务代码。Persona Asset 系统把 NPC 人设抽象为可拖拽编辑的 ScriptableObject支持“固定回复优先匹配 → 人格 Prompt 动态注入 → 上下文历史裁剪”三级流水线。内置测评工具链自动化采集 TTFB / Token 吞吐量 / 成本 / 角色一致性输出可横向对比的评估报告。核心数据新增平台接入成本0 行业务代码纯配置化固定回复拦截~1ms 延迟成本为 0人格资产 vs 简单 Prompt角色一致性 F10.1658 → 0.7685363.5%玩家实测n109整体满意度3.87/5角色统一性认可率62%一、为什么现在还要做“接入框架”API 不都统一了吗确实DeepSeek、Moonshot、智谱、通义、文心、火山等主流平台在 2025 年后都提供了 OpenAI-compatible 端点。如果你只是写个 Demo直接拼一个UnityWebRequestPOST 过去就能跑。但生产环境里问题才刚刚开始工程痛点具体表现配置碎片化API Key、模型名、Endpoint、温度、MaxTokens 散落在各个 MonoBehaviour 里策划改不了程序不敢动平台切换成本高今天用 DeepSeek明天老板让换 Moonshot后天要接入私有化部署——每次都要改代码、改场景、改 Prefab人设管理混乱System Prompt 硬编码在 C# 里策划想调语气要提需求走排期多轮对话后人设漂移没人管性能黑盒延迟多少哪家稳成本高不高没有结构化日志决策靠拍脑袋高频对话烧钱“你好”、“谢谢”、“当前任务”每次都走 LLMToken 费用和延迟都是浪费所以这套框架的核心目标不是“调通 API”而是“把 LLM-NPC 做成可维护、可扩展、可评估的工程组件”。二、全景架构双层分离设计整个系统遵循关注点分离Separation of Concerns拆成两层┌─────────────────────────────────────────┐│ 表现层Presentation ││ UIController / 对话面板 / 输入框 / 日志 │├─────────────────────────────────────────┤│ 业务层Gameplay ││ 人格资产 Persona AssetScriptableObject││ ├─ 固定回复表 FixedResponseTable ││ ├─ 身份 / 风格 / 句式 / 背景 四元组 ││ └─ 动态上下文管理 DialogHistory │├─────────────────────────────────────────┤│ 服务层Service ││ APIManager单一职责拼消息、发请求、记日志││ ├─ 本地缓存/固定回复拦截 ││ ├─ 消息栈组装System History User ││ └─ 统一响应解析 异常处理 │├─────────────────────────────────────────┤│ 适配层Adapter ││ IProviderConfig策略接口 ││ ├─ DeepSeekConfig.asset ││ ├─ MoonshotConfig.asset ││ ├─ VolcengineConfig.asset ││ └─ … 新增平台 新建.asset 填字段 │└─────────────────────────────────────────┘关键设计决策适配层只负责“平台特有的连接参数”不碰消息体构造因为协议已统一业务层只负责“NPC 人设与对话逻辑”不碰 HTTP 细节服务层只负责“请求生命周期管理”不碰平台差异三、工程化接入如何让“新增平台”变成纯配置操作这是本文第一个核心贡献。我要实现的是策划/程序新增一个模型平台不需要改APIManager不需要改Config不需要改场景逻辑——只需要在 Project 窗口里右键创建一个.asset文件填几个字段。3.1 策略接口IProviderConfig既然协议已统一接口不需要暴露“怎么拼 JSON”只需要暴露**“去哪里找谁、用什么钥匙”**csharppublic interface IProviderConfig{string GetApiUrl(); // 平台请求基地址string GetModel(); // 模型标识或 endpointIdstring GetApiKey(); // 认证密钥string GetDisplayName(); // UI 显示名如 “DeepSeek-V3”}设计意图4 个方法全部是纯数据读取无副作用可单元测试返回类型全是 string因为平台差异只体现在值不体现在类型未来如果要支持流式输出Stream可以定义派生接口 IStreamableProvider老平台零侵入3.2 抽象基类ProviderConfigBaseScriptableObject直接实现接口会导致每个平台类都重复写 model、apiKey 等字段。我用模板方法模式抽一个基类csharppublic abstract class ProviderConfigBase : ScriptableObject, IProviderConfig{[Header(“基础配置”)][SerializeField] protected string model “deepseek-chat”;[Header(认证信息)] [SerializeField] protected string apiKey; [Header(可选人格资产)] [SerializeField] protected PersonalityConfig personalityConfig; // 子类必须实现的差异点 public abstract string GetApiUrl(); public abstract string GetModel(); // 允许子类覆盖如火山返回 endpointId public abstract string GetApiKey(); // 默认实现大部分平台直接返回 model 字段 public virtual string GetDisplayName() model; // 提供给上层的统一访问入口 public PersonalityConfig Personality personalityConfig;}ScriptableObject 的工程价值数据与代码解耦策划在 Inspector 里改 Key、换模型不需要改 C#版本控制友好.asset 是 YAML 文本Git diff 可读运行时零拷贝多处引用同一份配置内存只存一份3.3 具体平台配置以 DeepSeek 和火山为例DeepSeek最标准csharp[CreateAssetMenu(menuName “UnityLLM/Configs/DeepSeek”)]public class DeepSeekConfig : ProviderConfigBase{[SerializeField] private string baseUrl “https://api.deepseek.com/v1/chat/completions”;public override string GetApiUrl() baseUrl; public override string GetModel() model; // 直接返回 model 字段 public override string GetApiKey() apiKey;}火山引擎特殊点用 endpointId 而不是 model 名csharp[CreateAssetMenu(menuName “UnityLLM/Configs/Volcengine”)]public class VolcengineConfig : ProviderConfigBase{[SerializeField] private string baseUrl “https://ark.cn-beijing.volces.com/api/v3/chat/completions”;[SerializeField] private string endpointId; // 火山特有字段public override string GetApiUrl() baseUrl; public override string GetModel() endpointId; // 覆盖返回 endpointId public override string GetApiKey() apiKey;}新增平台的成本新建一个继承 ProviderConfigBase 的类约 10 行代码→ 右键 Create Asset → 填字段。全程不碰 APIManager。3.4 配置调度中心Config上下文角色Config 是一个 MonoBehaviour挂在场景里负责运行时策略切换csharppublic class Config : MonoBehaviour{[Header(“平台配置池拖拽绑定”)][SerializeField] private DeepSeekConfig deepSeekConfig;[SerializeField] private MoonshotConfig moonshotConfig;[SerializeField] private VolcengineConfig volcengineConfig;// … 其他平台private IProviderConfig _activeConfig; public static IProviderConfig ActiveConfig { get; private set; } public void SetProvider(AIProvider provider) { _activeConfig provider switch { AIProvider.DeepSeek deepSeekConfig, AIProvider.Moonshot moonshotConfig, AIProvider.Volcengine volcengineConfig, _ throw new ArgumentOutOfRangeException() }; if (_activeConfig null) { Debug.LogError($[UnityLLM] {provider} 配置未绑定请在 Inspector 中拖拽配置资产); return; } ActiveConfig _activeConfig; OnProviderChanged?.Invoke(provider); }}工程细节防御式编程配置缺失时打明确错误日志不抛空引用异常事件驱动OnProviderChanged 让 UI 层可以监听并刷新下拉框显示静态代理ActiveConfig 是静态属性方便 APIManager 全局访问避免单例滥用3.5 为什么这套设计在 API 统一后仍有价值现在各家协议一样但连接参数、计费策略、服务稳定性差异巨大。我的框架把“换平台”从代码修改降级为配置替换这正是生产环境需要的工程治理能力。四、人格资产系统让策划掌控 NPC 灵魂这是第二个核心贡献。我不希望 NPC 人设是隐藏在 C# 里的长字符串而是可视化、可复用、可版本控制的数据资产。4.1 人格资产四元组Persona Quadruplecsharp[CreateAssetMenu(menuName “UnityLLM/Persona”)]public class PersonalityConfig : ScriptableObject{[Header(“1. 身份 Identity”)][TextArea(3, 5)]public string identity “你是赫斯珀洛斯-7空间站主控AI卡戎…”;[Header(2. 语言风格 Style)] [TextArea(3, 5)] public string speechStyle 恒定甜美、毫无情感波澜的女声用词精准但冷漠...; [Header(3. 句式特征 Phrasing)] [TextArea(3, 5)] public string signaturePhrasing 喜欢用根据流程开头用祝您好运结束...; [Header(4. 背景知识 Knowledge)] [TextArea(3, 5)] public string backgroundKnowledge 了解空间站所有系统参数但不懂人类情感...; [Header(生成参数)] [Range(0f, 2f)] public float temperature 0.5f; public int maxTokens 1024; public int maxHistoryLength 6; // 上下文轮数上限 [Header(固定回复表)] public ListFixedResponse fixedResponses new();}策划工作流在 Project 窗口右键 → Create → UnityLLM → Persona在 Inspector 里填四元组字段像填 Excel 一样直观把 .asset 拖到对应平台的 ProviderConfigBase 里完成绑定4.2 固定回复表零成本拦截高频请求这是性能优化的第一道闸门。对于“你好”、“谢谢”、“当前任务是什么”这类高频输入直接本地匹配返回不走网络、不产生 Token 费用、延迟约 1ms。csharp[System.Serializable]public class FixedResponse{public string id;public List keywords; // 匹配关键词public bool exactMatch; // true精确匹配false包含匹配public int priority; // 优先级冲突时取高public bool oneTimeUse; // 是否一次性public string responseText; // 返回内容public bool overrideAI; // true直接返回false仅作建议}// 在 APIManager 中的调用位置public void SendMessage(string userInput, Action onResponse){// 第一层固定回复拦截if (TryMatchFixedResponse(userInput, out var fixedReply)){LogFixedResponseHit(userInput, fixedReply);onResponse?.Invoke(fixedReply);return; // 关键直接返回不执行后续网络请求}// 第二层走 LLM 生成 StartCoroutine(CallLLM(userInput, onResponse));}匹配逻辑支持多关键词或关系任一命中即可支持优先级仲裁多个规则命中时取 priority 最高支持一次性回复如剧情触发句说完就失效支持精确/模糊匹配切换4.3 动态上下文管理防止 Token 爆炸多轮对话如果不裁剪上下文会越来越长导致请求体膨胀 → 延迟增加Token 费用飙升模型注意力稀释 → 早期人设遗忘我的方案是双轨裁剪csharpprivate List _history new();private void TrimHistory(){// 规则1硬性轮数上限保留最近 N 轮int maxRounds ActivePersona.maxHistoryLength;while (_history.Count maxRounds * 2) // *2 因为每轮有 user assistant{_history.RemoveAt(0);}// 规则2System Prompt 始终置顶不被裁剪 // 规则3首轮对话强制注入完整人格四元组后续轮次只追加用户输入}// 消息栈组装private List BuildMessageStack(string userInput){var messages new List();// 锚定System Prompt 始终第一条 messages.Add(new ApiMessage(system, CompilePersonaPrompt())); // 历史上下文 messages.AddRange(_history); // 当前输入 messages.Add(new ApiMessage(user, userInput)); return messages;}private string CompilePersonaPrompt(){// 把四元组编译成结构化 System Promptreturn $“[身份]\n{identity}\n\n” $“[语言风格]\n{speechStyle}\n\n” $“[句式特征]\n{signaturePhrasing}\n\n” $“[背景知识]\n{backgroundKnowledge}\n\n” $“[约束]\n禁止用第三人称描述自己禁止重复直接回应用户。”;}设计意图首轮锚定完整人格只在对话开始时注入一次减少后续 Token 开销历史滑动窗口只保留最近 maxHistoryLength 轮防止上下文无限增长System 隔离System 消息与 History 物理分离确保人设不会被用户输入污染五、测评体系不是“跑个分”而是“工程决策依据”这是第三个核心贡献。很多 LLM 集成文章只告诉你“能跑”但生产环境需要回答用哪家多快多贵人设稳不稳 我设计了一套内置自动化测评工具链。5.1 运行时日志每一帧都有据可查csharppublic class AIEvaluationLogger : MonoBehaviour{[System.Serializable]public class RequestLog{public string provider; // DeepSeek / Moonshot / Volcenginepublic string model;public float ttfb; // Time To First Byte首字节延迟public float totalLatency; // 总延迟public int inputTokens; // 输入 Token 估算public int outputTokens; // 输出 Token 估算public bool isFixedResponse; // 是否命中缓存public bool success; // 是否成功public float estimatedCost; // 按价目表估算成本public string errorMessage; // 失败原因}private ListRequestLog _logs new(); public void EndRequest(RequestLog log) { _logs.Add(log); // 实时输出到控制台 / 文件 / UI 面板 } public void ExportReport(string path) { // 导出 CSV / JSON 供后续分析 }}5.2 横向对比报告300 次请求实测我在控制环境下统一输入长度 20 Token、空历史上下文、分散于不同时段对三家平台各执行 100 次请求其中 50 次 AI 生成、50 次固定回复命中。表 1远程调用性能AI 生成模式Table平台 TTFB 均值 TTFB P95 总延迟 Token/s 稳定性标准差DeepSeek 4289 ms 4335 ms ~4293 ms 17.5 ⭐⭐⭐⭐⭐43 msMoonshot 5404 ms 5478 ms ~5408 ms 29.0 ⭐⭐⭐⭐60 ms火山引擎 13731 ms 13912 ms ~13734 ms 6.8 ⭐⭐103 ms工程结论追求即时响应如战斗中的 NPC 喊话→ 选 DeepSeek延迟最低且最稳追求长文本生成效率如剧情旁白、任务描述→ 选 Moonshot吞吐量最高火山引擎在当前网络环境下延迟波动大实时对话场景建议加本地缓存兜底表 2固定回复缓存收益Table平台 AI 生成延迟 缓存延迟 加速比 本地开销DeepSeek 4289 ms 1.0 ms 4294× 0.82 msMoonshot 5404 ms 1.0 ms 5390× 0.82 ms火山引擎 13731 ms 1.0 ms 13741× 0.82 ms工程结论固定回复是性价比最高的优化没有之一本地匹配逻辑耗时 1ms可忽略不计建议把“问候、任务查询、规则说明”等高频句全部配置为固定回复表 3经济性分析50% 缓存命中率Table平台 固定回复成本 AI 生成成本 单次请求均值 缓存节省比例DeepSeek ~$0.000062 ~$0.000083 ~$0.000073 12.7%Moonshot ~$0.000171 ~$0.000474 ~$0.000323 31.9%火山引擎 ~$0.000507 ~$0.000849 ~$0.000678 20.1%综合测算300 次请求每家 100 次50% 缓存命中理论总成本全走 AI约 $0.001406实际支出 $0.001074整体节省约 23.7%。注Token 估算基于字符数/2 的工程近似实际计费以平台账单为准。5.3 角色一致性测评人格资产到底值不值这是策划最关心的指标——NPC 说话像不像他自己。我设计了消融实验 双轨验证。实验设置策略 B基线简单 System Prompt“你是空间站 AI 卡戎简洁回答。”策略 C人格资产注入完整四元组身份/风格/句式/背景输入10 组典型玩家提问任务查询、规则挑战、情感试探、角色询问模型统一使用 DeepSeek排除模型差异干扰评估方法 1LLM-as-Judge主观语义评估用 GPT-4o 对回复进行 1-5 分角色一致性评分5完全符合人设。Table策略 平均分 提升 统计显著性B简单 Prompt 4.00 - -C人格资产 4.90 22.5% t(9)3.00, p0.05, Cohen’s d0.95评估方法 2TF-IDF 客观量化词汇层面验证为避免“AI 评 AI”的偏见引入独立于 LLM 的第三方指标策划预先编写 10 组“理想回复”严格符合卡戎人设计算生成回复与理想回复的 TF-IDF F1 相似度Table指标 策略 B 策略 C 提升F1 分数 0.1658 0.7685 363.5%精确率 Precision 0.3324 0.6656 100.2%召回率 Recall 0.1118 0.9335 735.0%关键发现召回率暴涨说明人格资产成功把“抽象人设”转化为了“可复现的词汇特征”如“协议”、“数据”、“效率”、“流程”策略 B 的回复虽然通顺但几乎没有覆盖角色标志性词汇策略 C 则精准复现两种独立评估方法高度吻合交叉验证了人格资产的有效性玩家问卷验证n109维度题项示例均值同意/强烈同意比例角色统一性“NPC 始终保持角色个性统一”3.53 / 562.39%语气符合度“语气与情感符合角色设定”3.57 / 561.47%沉浸感“对话提升我对游戏世界的沉浸感”3.83 / 566.06%整体满意度“我对本次文本交互整体满意”3.87 / 569.72%工程结论人格资产四元组不是“让 Prompt 更长”而是结构化约束能显著抑制多轮对话中的角色漂移对于“需要强人设”的 NPC如反派、AI 管家、神秘商人必须上人格资产简单 Prompt 无法支撑生产需求六、总结这套框架的工程价值在哪里维度传统做法本框架新增平台改代码、改场景、改 Prefab右键 Create Asset填 3 个字段0 代码人设调整找程序改 C# 里的字符串策划在 Inspector 里直接改实时生效高频对话每次走 LLM延迟 4-13 秒固定回复拦截1ms 返回0 成本性能评估凭感觉、“我这边挺快的”内置结构化日志输出可对比的 CSV 报告角色一致性“感觉还行”TF-IDF LLM-as-Judge 双轨量化验证一句话总结在 API 格式趋同的今天LLM-NPC 的竞争力不再是“能不能接进去”而是“接进去之后好不好管、换平台快不快、人设稳不稳、有没有数据支撑选型决策”。这套框架就是冲着这几个工程问题去的。附录快速开始给想抄作业的同学Step 1导入插件把 UnityLLM 文件夹拖进 Project。Step 2创建平台配置Project 窗口右键 → Create → UnityLLM → Configs → DeepSeek→ 填 Api Key、Model、BaseUrl。Step 3创建人格资产Project 窗口右键 → Create → UnityLLM → Persona→ 填四元组身份/风格/句式/背景 固定回复表。Step 4绑定到场景场景里新建空物体挂 Config 脚本把 DeepSeek.asset 拖到 Config 的对应槽位把 Persona.asset 拖到 DeepSeek.asset 的 Personality Config 槽位运行输入文字搞定。Step 5查看测评报告运行后自动在 Assets/UnityLLM/Logs/ 下生成 CSV用 Excel 打开即可看到每次请求的延迟、Token、成本。如果你也在做 Unity LLM 的项目欢迎在评论区交流。关于人格资产的设计、固定回复表的匹配策略、或者测评数据的解读都可以聊。 【智能体从对话到决策】虚拟环境下大语言模型的部署与智能体交互研究
原文标题Unity 集成大语言模型的方法、实现与评估研究作者雍潇潇项目UnityLLM 统一接入插件 3D 解谜游戏UnityLLM 插件 主客观双轨评估把 DeepSeek、Kimi、豆包塞进 Unity我怎么做了一套“零代码切换”的 LLM-NPC 框架一、先说说为什么要折腾这个做独立游戏的应该都有同感传统 NPC 对话太僵了。 branching dialogue 树写到后期就是灾难玩家稍微跳出预设问题NPC 就开始“人工智障”。这两年大模型火了之后大家第一反应是能不能让 GPT/DeepSeek 直接进 Unity 当 NPC 大脑但真动手你会发现从 Python 原型到 Unity 生产环境中间隔着一条鸿沟接入碎片化DeepSeek、Moonshot、火山引擎、智谱、通义千问、文心一言……每家 API 的鉴权、请求体、返回格式都不一样换一家就要重写一套 C# 网络层。最新我看都接口形式统一了Unity 里没有现成方案学术圈很多 awesome 的 LLM Agent比如斯坦福小镇、Voyager都是 Python 后端和 Unity 的 C# 协程、ScriptableObject、实时渲染管线根本接不上。角色一致性难搞光靠一句 system prompt多轮对话后 NPC 很容易“人设崩塌”从冷酷 AI 变成热情客服。所以我就围绕一件事在 Unity 内部做一套标准化、可复用、带人格资产的 LLM 接入框架并且真的放入游戏让 100 多个玩家来测并且通过代码测试输出了横向对比报告。二、整体思路双层架构我不想做“调通一个 API 就发教程”的Demo而是希望策划换模型不用改代码策划调人设不用找程序。所以架构拆成两层层级职责关键技术底层统一接入层屏蔽不同 MaaS 平台的 API 差异实现“零代码”模型切换策略模式 ScriptableObject 依赖倒置上层人格资产层把 NPC 人设抽象成可配置的数据资产保证多轮对话角色不崩人格四元组身份/语言风格/句式/背景 动态上下文管理下面分别聊聊这两层我是怎么实现的。生产级 Unity LLM-NPC 框架从“能跑”到“可维护”的工程化实践【先看这一节5 分钟读懂全文】背景变化2025-2026 年国内大模型 API 已基本收敛到 OpenAI-compatible 格式接入门槛从“协议翻译”变成了“工程治理”。开发者真正的痛点不再是“调不通接口”而是如何在 Unity 里管理多平台配置、保证 NPC 人设不崩、并基于数据做模型选型决策。我做了一套什么UnityLLM 插件基于策略模式 ScriptableObject 的零代码扩展框架。新增一个平台 新建一个.asset配置 填 3 个字段不碰任何业务代码。Persona Asset 系统把 NPC 人设抽象为可拖拽编辑的 ScriptableObject支持“固定回复优先匹配 → 人格 Prompt 动态注入 → 上下文历史裁剪”三级流水线。内置测评工具链自动化采集 TTFB / Token 吞吐量 / 成本 / 角色一致性输出可横向对比的评估报告。核心数据新增平台接入成本0 行业务代码纯配置化固定回复拦截~1ms 延迟成本为 0人格资产 vs 简单 Prompt角色一致性 F10.1658 → 0.7685363.5%玩家实测n109整体满意度3.87/5角色统一性认可率62%一、为什么现在还要做“接入框架”API 不都统一了吗确实DeepSeek、Moonshot、智谱、通义、文心、火山等主流平台在 2025 年后都提供了 OpenAI-compatible 端点。如果你只是写个 Demo直接拼一个UnityWebRequestPOST 过去就能跑。但生产环境里问题才刚刚开始工程痛点具体表现配置碎片化API Key、模型名、Endpoint、温度、MaxTokens 散落在各个 MonoBehaviour 里策划改不了程序不敢动平台切换成本高今天用 DeepSeek明天老板让换 Moonshot后天要接入私有化部署——每次都要改代码、改场景、改 Prefab人设管理混乱System Prompt 硬编码在 C# 里策划想调语气要提需求走排期多轮对话后人设漂移没人管性能黑盒延迟多少哪家稳成本高不高没有结构化日志决策靠拍脑袋高频对话烧钱“你好”、“谢谢”、“当前任务”每次都走 LLMToken 费用和延迟都是浪费所以这套框架的核心目标不是“调通 API”而是“把 LLM-NPC 做成可维护、可扩展、可评估的工程组件”。二、全景架构双层分离设计整个系统遵循关注点分离Separation of Concerns拆成两层┌─────────────────────────────────────────┐│ 表现层Presentation ││ UIController / 对话面板 / 输入框 / 日志 │├─────────────────────────────────────────┤│ 业务层Gameplay ││ 人格资产 Persona AssetScriptableObject││ ├─ 固定回复表 FixedResponseTable ││ ├─ 身份 / 风格 / 句式 / 背景 四元组 ││ └─ 动态上下文管理 DialogHistory │├─────────────────────────────────────────┤│ 服务层Service ││ APIManager单一职责拼消息、发请求、记日志││ ├─ 本地缓存/固定回复拦截 ││ ├─ 消息栈组装System History User ││ └─ 统一响应解析 异常处理 │├─────────────────────────────────────────┤│ 适配层Adapter ││ IProviderConfig策略接口 ││ ├─ DeepSeekConfig.asset ││ ├─ MoonshotConfig.asset ││ ├─ VolcengineConfig.asset ││ └─ … 新增平台 新建.asset 填字段 │└─────────────────────────────────────────┘关键设计决策适配层只负责“平台特有的连接参数”不碰消息体构造因为协议已统一业务层只负责“NPC 人设与对话逻辑”不碰 HTTP 细节服务层只负责“请求生命周期管理”不碰平台差异三、工程化接入如何让“新增平台”变成纯配置操作这是本文第一个核心贡献。我要实现的是策划/程序新增一个模型平台不需要改APIManager不需要改Config不需要改场景逻辑——只需要在 Project 窗口里右键创建一个.asset文件填几个字段。3.1 策略接口IProviderConfig既然协议已统一接口不需要暴露“怎么拼 JSON”只需要暴露**“去哪里找谁、用什么钥匙”**csharppublic interface IProviderConfig{string GetApiUrl(); // 平台请求基地址string GetModel(); // 模型标识或 endpointIdstring GetApiKey(); // 认证密钥string GetDisplayName(); // UI 显示名如 “DeepSeek-V3”}设计意图4 个方法全部是纯数据读取无副作用可单元测试返回类型全是 string因为平台差异只体现在值不体现在类型未来如果要支持流式输出Stream可以定义派生接口 IStreamableProvider老平台零侵入3.2 抽象基类ProviderConfigBaseScriptableObject直接实现接口会导致每个平台类都重复写 model、apiKey 等字段。我用模板方法模式抽一个基类csharppublic abstract class ProviderConfigBase : ScriptableObject, IProviderConfig{[Header(“基础配置”)][SerializeField] protected string model “deepseek-chat”;[Header(认证信息)] [SerializeField] protected string apiKey; [Header(可选人格资产)] [SerializeField] protected PersonalityConfig personalityConfig; // 子类必须实现的差异点 public abstract string GetApiUrl(); public abstract string GetModel(); // 允许子类覆盖如火山返回 endpointId public abstract string GetApiKey(); // 默认实现大部分平台直接返回 model 字段 public virtual string GetDisplayName() model; // 提供给上层的统一访问入口 public PersonalityConfig Personality personalityConfig;}ScriptableObject 的工程价值数据与代码解耦策划在 Inspector 里改 Key、换模型不需要改 C#版本控制友好.asset 是 YAML 文本Git diff 可读运行时零拷贝多处引用同一份配置内存只存一份3.3 具体平台配置以 DeepSeek 和火山为例DeepSeek最标准csharp[CreateAssetMenu(menuName “UnityLLM/Configs/DeepSeek”)]public class DeepSeekConfig : ProviderConfigBase{[SerializeField] private string baseUrl “https://api.deepseek.com/v1/chat/completions”;public override string GetApiUrl() baseUrl; public override string GetModel() model; // 直接返回 model 字段 public override string GetApiKey() apiKey;}火山引擎特殊点用 endpointId 而不是 model 名csharp[CreateAssetMenu(menuName “UnityLLM/Configs/Volcengine”)]public class VolcengineConfig : ProviderConfigBase{[SerializeField] private string baseUrl “https://ark.cn-beijing.volces.com/api/v3/chat/completions”;[SerializeField] private string endpointId; // 火山特有字段public override string GetApiUrl() baseUrl; public override string GetModel() endpointId; // 覆盖返回 endpointId public override string GetApiKey() apiKey;}新增平台的成本新建一个继承 ProviderConfigBase 的类约 10 行代码→ 右键 Create Asset → 填字段。全程不碰 APIManager。3.4 配置调度中心Config上下文角色Config 是一个 MonoBehaviour挂在场景里负责运行时策略切换csharppublic class Config : MonoBehaviour{[Header(“平台配置池拖拽绑定”)][SerializeField] private DeepSeekConfig deepSeekConfig;[SerializeField] private MoonshotConfig moonshotConfig;[SerializeField] private VolcengineConfig volcengineConfig;// … 其他平台private IProviderConfig _activeConfig; public static IProviderConfig ActiveConfig { get; private set; } public void SetProvider(AIProvider provider) { _activeConfig provider switch { AIProvider.DeepSeek deepSeekConfig, AIProvider.Moonshot moonshotConfig, AIProvider.Volcengine volcengineConfig, _ throw new ArgumentOutOfRangeException() }; if (_activeConfig null) { Debug.LogError($[UnityLLM] {provider} 配置未绑定请在 Inspector 中拖拽配置资产); return; } ActiveConfig _activeConfig; OnProviderChanged?.Invoke(provider); }}工程细节防御式编程配置缺失时打明确错误日志不抛空引用异常事件驱动OnProviderChanged 让 UI 层可以监听并刷新下拉框显示静态代理ActiveConfig 是静态属性方便 APIManager 全局访问避免单例滥用3.5 为什么这套设计在 API 统一后仍有价值现在各家协议一样但连接参数、计费策略、服务稳定性差异巨大。我的框架把“换平台”从代码修改降级为配置替换这正是生产环境需要的工程治理能力。四、人格资产系统让策划掌控 NPC 灵魂这是第二个核心贡献。我不希望 NPC 人设是隐藏在 C# 里的长字符串而是可视化、可复用、可版本控制的数据资产。4.1 人格资产四元组Persona Quadruplecsharp[CreateAssetMenu(menuName “UnityLLM/Persona”)]public class PersonalityConfig : ScriptableObject{[Header(“1. 身份 Identity”)][TextArea(3, 5)]public string identity “你是赫斯珀洛斯-7空间站主控AI卡戎…”;[Header(2. 语言风格 Style)] [TextArea(3, 5)] public string speechStyle 恒定甜美、毫无情感波澜的女声用词精准但冷漠...; [Header(3. 句式特征 Phrasing)] [TextArea(3, 5)] public string signaturePhrasing 喜欢用根据流程开头用祝您好运结束...; [Header(4. 背景知识 Knowledge)] [TextArea(3, 5)] public string backgroundKnowledge 了解空间站所有系统参数但不懂人类情感...; [Header(生成参数)] [Range(0f, 2f)] public float temperature 0.5f; public int maxTokens 1024; public int maxHistoryLength 6; // 上下文轮数上限 [Header(固定回复表)] public ListFixedResponse fixedResponses new();}策划工作流在 Project 窗口右键 → Create → UnityLLM → Persona在 Inspector 里填四元组字段像填 Excel 一样直观把 .asset 拖到对应平台的 ProviderConfigBase 里完成绑定4.2 固定回复表零成本拦截高频请求这是性能优化的第一道闸门。对于“你好”、“谢谢”、“当前任务是什么”这类高频输入直接本地匹配返回不走网络、不产生 Token 费用、延迟约 1ms。csharp[System.Serializable]public class FixedResponse{public string id;public List keywords; // 匹配关键词public bool exactMatch; // true精确匹配false包含匹配public int priority; // 优先级冲突时取高public bool oneTimeUse; // 是否一次性public string responseText; // 返回内容public bool overrideAI; // true直接返回false仅作建议}// 在 APIManager 中的调用位置public void SendMessage(string userInput, Action onResponse){// 第一层固定回复拦截if (TryMatchFixedResponse(userInput, out var fixedReply)){LogFixedResponseHit(userInput, fixedReply);onResponse?.Invoke(fixedReply);return; // 关键直接返回不执行后续网络请求}// 第二层走 LLM 生成 StartCoroutine(CallLLM(userInput, onResponse));}匹配逻辑支持多关键词或关系任一命中即可支持优先级仲裁多个规则命中时取 priority 最高支持一次性回复如剧情触发句说完就失效支持精确/模糊匹配切换4.3 动态上下文管理防止 Token 爆炸多轮对话如果不裁剪上下文会越来越长导致请求体膨胀 → 延迟增加Token 费用飙升模型注意力稀释 → 早期人设遗忘我的方案是双轨裁剪csharpprivate List _history new();private void TrimHistory(){// 规则1硬性轮数上限保留最近 N 轮int maxRounds ActivePersona.maxHistoryLength;while (_history.Count maxRounds * 2) // *2 因为每轮有 user assistant{_history.RemoveAt(0);}// 规则2System Prompt 始终置顶不被裁剪 // 规则3首轮对话强制注入完整人格四元组后续轮次只追加用户输入}// 消息栈组装private List BuildMessageStack(string userInput){var messages new List();// 锚定System Prompt 始终第一条 messages.Add(new ApiMessage(system, CompilePersonaPrompt())); // 历史上下文 messages.AddRange(_history); // 当前输入 messages.Add(new ApiMessage(user, userInput)); return messages;}private string CompilePersonaPrompt(){// 把四元组编译成结构化 System Promptreturn $“[身份]\n{identity}\n\n” $“[语言风格]\n{speechStyle}\n\n” $“[句式特征]\n{signaturePhrasing}\n\n” $“[背景知识]\n{backgroundKnowledge}\n\n” $“[约束]\n禁止用第三人称描述自己禁止重复直接回应用户。”;}设计意图首轮锚定完整人格只在对话开始时注入一次减少后续 Token 开销历史滑动窗口只保留最近 maxHistoryLength 轮防止上下文无限增长System 隔离System 消息与 History 物理分离确保人设不会被用户输入污染五、测评体系不是“跑个分”而是“工程决策依据”这是第三个核心贡献。很多 LLM 集成文章只告诉你“能跑”但生产环境需要回答用哪家多快多贵人设稳不稳 我设计了一套内置自动化测评工具链。5.1 运行时日志每一帧都有据可查csharppublic class AIEvaluationLogger : MonoBehaviour{[System.Serializable]public class RequestLog{public string provider; // DeepSeek / Moonshot / Volcenginepublic string model;public float ttfb; // Time To First Byte首字节延迟public float totalLatency; // 总延迟public int inputTokens; // 输入 Token 估算public int outputTokens; // 输出 Token 估算public bool isFixedResponse; // 是否命中缓存public bool success; // 是否成功public float estimatedCost; // 按价目表估算成本public string errorMessage; // 失败原因}private ListRequestLog _logs new(); public void EndRequest(RequestLog log) { _logs.Add(log); // 实时输出到控制台 / 文件 / UI 面板 } public void ExportReport(string path) { // 导出 CSV / JSON 供后续分析 }}5.2 横向对比报告300 次请求实测我在控制环境下统一输入长度 20 Token、空历史上下文、分散于不同时段对三家平台各执行 100 次请求其中 50 次 AI 生成、50 次固定回复命中。表 1远程调用性能AI 生成模式Table平台 TTFB 均值 TTFB P95 总延迟 Token/s 稳定性标准差DeepSeek 4289 ms 4335 ms ~4293 ms 17.5 ⭐⭐⭐⭐⭐43 msMoonshot 5404 ms 5478 ms ~5408 ms 29.0 ⭐⭐⭐⭐60 ms火山引擎 13731 ms 13912 ms ~13734 ms 6.8 ⭐⭐103 ms工程结论追求即时响应如战斗中的 NPC 喊话→ 选 DeepSeek延迟最低且最稳追求长文本生成效率如剧情旁白、任务描述→ 选 Moonshot吞吐量最高火山引擎在当前网络环境下延迟波动大实时对话场景建议加本地缓存兜底表 2固定回复缓存收益Table平台 AI 生成延迟 缓存延迟 加速比 本地开销DeepSeek 4289 ms 1.0 ms 4294× 0.82 msMoonshot 5404 ms 1.0 ms 5390× 0.82 ms火山引擎 13731 ms 1.0 ms 13741× 0.82 ms工程结论固定回复是性价比最高的优化没有之一本地匹配逻辑耗时 1ms可忽略不计建议把“问候、任务查询、规则说明”等高频句全部配置为固定回复表 3经济性分析50% 缓存命中率Table平台 固定回复成本 AI 生成成本 单次请求均值 缓存节省比例DeepSeek ~$0.000062 ~$0.000083 ~$0.000073 12.7%Moonshot ~$0.000171 ~$0.000474 ~$0.000323 31.9%火山引擎 ~$0.000507 ~$0.000849 ~$0.000678 20.1%综合测算300 次请求每家 100 次50% 缓存命中理论总成本全走 AI约 $0.001406实际支出 $0.001074整体节省约 23.7%。注Token 估算基于字符数/2 的工程近似实际计费以平台账单为准。5.3 角色一致性测评人格资产到底值不值这是策划最关心的指标——NPC 说话像不像他自己。我设计了消融实验 双轨验证。实验设置策略 B基线简单 System Prompt“你是空间站 AI 卡戎简洁回答。”策略 C人格资产注入完整四元组身份/风格/句式/背景输入10 组典型玩家提问任务查询、规则挑战、情感试探、角色询问模型统一使用 DeepSeek排除模型差异干扰评估方法 1LLM-as-Judge主观语义评估用 GPT-4o 对回复进行 1-5 分角色一致性评分5完全符合人设。Table策略 平均分 提升 统计显著性B简单 Prompt 4.00 - -C人格资产 4.90 22.5% t(9)3.00, p0.05, Cohen’s d0.95评估方法 2TF-IDF 客观量化词汇层面验证为避免“AI 评 AI”的偏见引入独立于 LLM 的第三方指标策划预先编写 10 组“理想回复”严格符合卡戎人设计算生成回复与理想回复的 TF-IDF F1 相似度Table指标 策略 B 策略 C 提升F1 分数 0.1658 0.7685 363.5%精确率 Precision 0.3324 0.6656 100.2%召回率 Recall 0.1118 0.9335 735.0%关键发现召回率暴涨说明人格资产成功把“抽象人设”转化为了“可复现的词汇特征”如“协议”、“数据”、“效率”、“流程”策略 B 的回复虽然通顺但几乎没有覆盖角色标志性词汇策略 C 则精准复现两种独立评估方法高度吻合交叉验证了人格资产的有效性玩家问卷验证n109维度题项示例均值同意/强烈同意比例角色统一性“NPC 始终保持角色个性统一”3.53 / 562.39%语气符合度“语气与情感符合角色设定”3.57 / 561.47%沉浸感“对话提升我对游戏世界的沉浸感”3.83 / 566.06%整体满意度“我对本次文本交互整体满意”3.87 / 569.72%工程结论人格资产四元组不是“让 Prompt 更长”而是结构化约束能显著抑制多轮对话中的角色漂移对于“需要强人设”的 NPC如反派、AI 管家、神秘商人必须上人格资产简单 Prompt 无法支撑生产需求六、总结这套框架的工程价值在哪里维度传统做法本框架新增平台改代码、改场景、改 Prefab右键 Create Asset填 3 个字段0 代码人设调整找程序改 C# 里的字符串策划在 Inspector 里直接改实时生效高频对话每次走 LLM延迟 4-13 秒固定回复拦截1ms 返回0 成本性能评估凭感觉、“我这边挺快的”内置结构化日志输出可对比的 CSV 报告角色一致性“感觉还行”TF-IDF LLM-as-Judge 双轨量化验证一句话总结在 API 格式趋同的今天LLM-NPC 的竞争力不再是“能不能接进去”而是“接进去之后好不好管、换平台快不快、人设稳不稳、有没有数据支撑选型决策”。这套框架就是冲着这几个工程问题去的。附录快速开始给想抄作业的同学Step 1导入插件把 UnityLLM 文件夹拖进 Project。Step 2创建平台配置Project 窗口右键 → Create → UnityLLM → Configs → DeepSeek→ 填 Api Key、Model、BaseUrl。Step 3创建人格资产Project 窗口右键 → Create → UnityLLM → Persona→ 填四元组身份/风格/句式/背景 固定回复表。Step 4绑定到场景场景里新建空物体挂 Config 脚本把 DeepSeek.asset 拖到 Config 的对应槽位把 Persona.asset 拖到 DeepSeek.asset 的 Personality Config 槽位运行输入文字搞定。Step 5查看测评报告运行后自动在 Assets/UnityLLM/Logs/ 下生成 CSV用 Excel 打开即可看到每次请求的延迟、Token、成本。如果你也在做 Unity LLM 的项目欢迎在评论区交流。关于人格资产的设计、固定回复表的匹配策略、或者测评数据的解读都可以聊。