游戏 AI / 系统课时
发出第一条结构化对话请求
发出第一条结构化对话请求
用一个可运行的 Python 脚本向 Responses API 发送 NPC 角色约束和玩家提问,随后读取完成状态、模型台词与 Token 用量。这样可以先验证最小请求和响应闭环,再接入游戏界面、记忆或任务系统。
学习目标
- 用不同消息角色区分 NPC 规则与玩家输入。
- 调用 Responses API 并从 SDK 响应中提取可显示的台词。
- 根据状态、异常和用量字段判断一次请求是否成功。
准备独立可运行的环境
需要 Python 3.10 或更新版本、可访问的 OpenAI API 项目及有效 API Key。本例使用官方 Python SDK,发送的是文本请求,不需要游戏引擎参与。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 侧存储该响应对象供后续检索;这不等于关闭所有平台数据保留策略,也不代替游戏后端自己的数据管理。
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> 均为动态占位,实际数值和标识会变化。
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 将已确认的结果表达为自然语言。