游戏 AI / 系统课时
给生成请求统一加一层服务封装
给生成请求统一加一层服务封装
当 NPC、任务系统都直接拼接模型请求时,协议处理、超时、错误转换和输出校验会迅速重复。本篇把这些职责收进统一服务层,让游戏业务只关心“要什么内容”和“如何使用结果”。
学习目标
- 理解模型客户端、内容服务与游戏业务之间的职责边界
- 用 Python 实现一个可复用的生成服务封装
- 让 NPC 与任务系统共享同一套请求、错误和结果处理逻辑
为什么要分出服务层
直接在业务代码里调用模型,最初看起来最快,但很容易形成多个版本的调用逻辑。NPC 系统可能自己处理提示词,任务系统自己设置超时,商店系统又单独解析响应;模型协议一旦变化,就需要逐处修改。
更稳妥的结构是让游戏业务只提交领域需要的信息,由内容服务统一负责请求模型,再把稳定的数据结构返回给上层。这样模型供应商和具体协议都被隔离在边界内。

三层职责怎么划分
游戏业务调用层知道自己要完成什么,例如“生成酒馆老板对玩家当前选择的回应”,但不应知道 HTTP 请求格式、模型名称或鉴权细节。
内容服务层负责稳定的业务接口。它可以把角色状态、任务目标和玩家输入整理成统一请求,同时集中处理超时、重试边界、响应解析和失败降级。
模型客户端层只解决模型协议问题,例如发送请求、接收响应和映射供应商字段。将来替换模型服务时,优先修改这一层,而不是修改 NPC 和任务代码。
一个最小的封装实现
下面用 Python 展示三层结构。示例中的模型客户端使用本地假实现,重点验证封装边界,不依赖具体模型供应商 SDK。
from dataclasses import dataclass
@dataclass
class GameContext:
role: str
player_input: str
goal: str
class ModelClient:
def generate(self, prompt: str) -> str:
# 模拟真实模型客户端;生产环境可在此替换具体 SDK 调用。
return f"围绕{prompt}生成一句简短台词"
class ContentService:
def __init__(self, client: ModelClient):
self.client = client
def generate_npc_reply(self, context: GameContext) -> str:
prompt = (
f"角色={context.role}; "
f"玩家输入={context.player_input}; "
f"目标={context.goal}"
)
result = self.client.generate(prompt)
if not result.strip():
raise ValueError("model returned empty content")
return result.strip()
def main() -> None:
service = ContentService(ModelClient())
context = GameContext(
role="酒馆老板",
player_input="有没有去北门的路?",
goal="给出与任务相关的简短回应",
)
print(service.generate_npc_reply(context))
if __name__ == "__main__":
main()预期输出
围绕角色=酒馆老板; 玩家输入=有没有去北门的路?; 目标=给出与任务相关的简短回应生成一句简短台词这里真正值得保留的不是字符串拼接,而是 ContentService 的边界:NPC 业务只依赖 generate_npc_reply(),模型客户端如何发送请求可以独立变化。生产代码还可以在这一层增加超时、结构化输出校验和统一日志。
让不同系统共享同一入口
NPC 和任务系统不应该分别实现一套模型调用。它们可以共享同一个 ContentService,只是调用不同的领域方法,或者传入不同的内容类型。
例如,NPC 系统请求的是对话回复,任务系统请求的是任务描述。两者都经过同一套客户端和公共错误处理,因此模型地址、认证方式、超时策略等不会散落在业务代码中。
封装边界的几个关键点
不要让服务层把所有游戏逻辑都吞进去。像“任务是否完成”“玩家是否有资格领取奖励”这类规则仍然应该由游戏领域代码决定;内容服务只负责生成和规范化内容。
同时,模型输出也不应原样扩散到多个系统。服务层可以把供应商响应转换成游戏内部稳定的数据,例如 text、content_type、request_id。这样供应商字段变化时,只需要在边界内适配。
最终的调用关系应保持简单:业务提出内容需求,服务层统一编排,客户端处理模型协议。这个边界一旦稳定,后续加入缓存、监控或模型切换时,改动范围也会明显缩小。