游戏 AI / 系统课时

发出第一条结构化对话请求

发出第一条结构化对话请求

用一个可运行的 Python 脚本向 Responses API 发送 NPC 角色约束和玩家提问,随后读取完成状态、模型台词与 Token 用量。这样可以先验证最小请求和响应闭环,再接入游戏界面、记忆或任务系统。

学习目标

  • 用不同消息角色区分 NPC 规则与玩家输入。
  • 调用 Responses API 并从 SDK 响应中提取可显示的台词。
  • 根据状态、异常和用量字段判断一次请求是否成功。

准备独立可运行的环境

需要 Python 3.10 或更新版本、可访问的 OpenAI API 项目及有效 API Key。本例使用官方 Python SDK,发送的是文本请求,不需要游戏引擎参与。Bash 中运行以下命令;密钥会以隐藏输入方式读取到当前进程环境。

bash
python -m pip install openai
read -rsp "API Key: " OPENAI_API_KEY
export OPENAI_API_KEY
printf '\n'

预期结果:安装命令提示安装成功或依赖已满足,输入密钥时字符不回显。若 SDK 已安装,依赖版本可能与新装环境不同;团队项目应锁定经测试的依赖版本。

用角色字段构造最小请求

保存为 npc_first_reply.py。developer 负责服务端设定的 NPC 身份与回答范围,user 承载玩家本轮问题。max_output_tokens 限制生成预算;store=False 表示不在 API 侧存储该响应对象供后续检索;这不等于关闭所有平台数据保留策略,也不代替游戏后端自己的数据管理。

python
import os
from openai import APIConnectionError, APIStatusError, APITimeoutError, OpenAI

def main():
    # 显式关闭自动重试,让第一次联调的失败原因更清楚。
    client = OpenAI(timeout=20.0, max_retries=0)
    try:
        response = client.responses.create(
            model=os.getenv("NPC_MODEL", "gpt-4.1-mini"),
            input=[
                {
                    "role": "developer",
                    "content": (
                        "你是港口守卫阿岚。已知规则:没有通行证不得进入港口。"
                        "只用简体中文回答,每次最多50字。"
                        "不得宣布已修改玩家金币、背包或任务状态。"
                    ),
                },
                {"role": "user", "content": "我没有通行证,能进港口吗?"},
            ],
            max_output_tokens=int(os.getenv("NPC_MAX_OUTPUT_TOKENS", "160")),
            store=False,
        )
    except APIStatusError as exc:
        print("http_status:", exc.status_code)
        return
    except (APITimeoutError, APIConnectionError) as exc:
        print("network_error:", type(exc).__name__)
        return

    print("status:", response.status)
    if response.status != "completed":
        print("result: incomplete_or_failed")
        return
    # output_text 汇总文本项,避免假定 output[0] 就是台词。
    reply = response.output_text.strip()
    if not reply:
        print("result: empty_text")
        return
    print("npc:", reply)
    usage = response.usage
    if usage is not None:
        print(f"tokens: input={usage.input_tokens} "
              f"output={usage.output_tokens} total={usage.total_tokens}")
    else:
        print("tokens: unavailable")
    print("response_id:", response.id)

if __name__ == "__main__":
    main()

预期输出:执行 python npc_first_reply.py 后,正常完成时可见如下结构。台词由模型生成,并非固定字串;<TOKEN_COUNT>、<ID> 均为动态占位,实际数值和标识会变化。

text
status: completed
npc: <NPC台词>
tokens: input=<TOKEN_COUNT> output=<TOKEN_COUNT> total=<TOKEN_COUNT>
response_id: <ID>

逐项核对响应

成功调用代表 HTTP 请求通过,但还要核对响应内的 status 是否为 completed。只有状态完成、output_text 非空,才能把台词交给游戏 UI;incomplete 或 failed 不应伪装成正常 NPC 回答。output 可能包含不同类型的项,不能假设第一项总是文本消息。

usage.input_tokens、usage.output_tokens 和 usage.total_tokens 用于统计单轮成本;若 usage 不可用,应保留缺失标记而不是写 0。response.id 可用于服务端追踪,但玩家界面通常不需要展示它。

排查第一次失败

观察到的结果 排查方向
http_status: 401 检查后端是否加载正确密钥
http_status: 404 核对模型标识与 API 基础地址
http_status: 429 检查限额、配额及请求频率
network_error: APITimeoutError 核对网络、超时预算,必要时重试
result: empty_text 检查模型输出类型及请求约束

此脚本只生成候选台词:即使模型说“你可以通行”,也不能据此修改玩家通行权限。实际项目应由游戏服务器读取任务与物品状态,独立决定玩家能否通行,再由 NPC 将已确认的结果表达为自然语言。

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

目录与阅读设置

阅读设置

17

记录一个想法

发出第一条结构化对话请求

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

登录哪都通