游戏 AI / 系统课时

给生成请求统一加一层服务封装

给生成请求统一加一层服务封装

当 NPC、任务系统都直接拼接模型请求时,协议处理、超时、错误转换和输出校验会迅速重复。本篇把这些职责收进统一服务层,让游戏业务只关心“要什么内容”和“如何使用结果”。

学习目标

  • 理解模型客户端、内容服务与游戏业务之间的职责边界
  • 用 Python 实现一个可复用的生成服务封装
  • 让 NPC 与任务系统共享同一套请求、错误和结果处理逻辑

为什么要分出服务层

直接在业务代码里调用模型,最初看起来最快,但很容易形成多个版本的调用逻辑。NPC 系统可能自己处理提示词,任务系统自己设置超时,商店系统又单独解析响应;模型协议一旦变化,就需要逐处修改。

更稳妥的结构是让游戏业务只提交领域需要的信息,由内容服务统一负责请求模型,再把稳定的数据结构返回给上层。这样模型供应商和具体协议都被隔离在边界内。

模型客户端、内容服务与游戏业务的分层关系

三层职责怎么划分

游戏业务调用层知道自己要完成什么,例如“生成酒馆老板对玩家当前选择的回应”,但不应知道 HTTP 请求格式、模型名称或鉴权细节。

内容服务层负责稳定的业务接口。它可以把角色状态、任务目标和玩家输入整理成统一请求,同时集中处理超时、重试边界、响应解析和失败降级。

模型客户端层只解决模型协议问题,例如发送请求、接收响应和映射供应商字段。将来替换模型服务时,优先修改这一层,而不是修改 NPC 和任务代码。

一个最小的封装实现

下面用 Python 展示三层结构。示例中的模型客户端使用本地假实现,重点验证封装边界,不依赖具体模型供应商 SDK。

python
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()

预期输出

text
围绕角色=酒馆老板; 玩家输入=有没有去北门的路?; 目标=给出与任务相关的简短回应生成一句简短台词

这里真正值得保留的不是字符串拼接,而是 ContentService 的边界:NPC 业务只依赖 generate_npc_reply(),模型客户端如何发送请求可以独立变化。生产代码还可以在这一层增加超时、结构化输出校验和统一日志。

让不同系统共享同一入口

NPC 和任务系统不应该分别实现一套模型调用。它们可以共享同一个 ContentService,只是调用不同的领域方法,或者传入不同的内容类型。

例如,NPC 系统请求的是对话回复,任务系统请求的是任务描述。两者都经过同一套客户端和公共错误处理,因此模型地址、认证方式、超时策略等不会散落在业务代码中。

封装边界的几个关键点

不要让服务层把所有游戏逻辑都吞进去。像“任务是否完成”“玩家是否有资格领取奖励”这类规则仍然应该由游戏领域代码决定;内容服务只负责生成和规范化内容。

同时,模型输出也不应原样扩散到多个系统。服务层可以把供应商响应转换成游戏内部稳定的数据,例如 text、content_type、request_id。这样供应商字段变化时,只需要在边界内适配。

最终的调用关系应保持简单:业务提出内容需求,服务层统一编排,客户端处理模型协议。这个边界一旦稳定,后续加入缓存、监控或模型切换时,改动范围也会明显缩小。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

给生成请求统一加一层服务封装

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通