游戏 AI / 系统课时
配置密钥端点与开发日志
配置密钥端点与开发日志
先把 NPC 对话请求需要的凭据、API 入口、模型预算和日志级别集中配置到服务端。完成后可以在不发送真实对话的情况下检查启动条件,并保证密钥不会进入游戏客户端资源、代码仓库或开发日志。
学习目标
- 区分游戏客户端、后端和模型服务各自能接触的配置。
- 用环境变量设置 API 端点、模型与输出上限,并在启动时校验。
- 记录排障所需的元数据,不泄露凭据与玩家对话。
把密钥限制在服务端
在 Unity 或 Unreal 游戏中,玩家安装包、资源文件以及客户端脚本都可能被读取。客户端只把玩家发言和会话标识发给自己的游戏后端;后端从运行环境或密钥管理服务读取 OPENAI_API_KEY,再通过 HTTPS 调用模型接口。

配置端点与模型预算
本例使用 Python 后端和 OpenAI Responses API。以下环境变量中,OPENAI_API_KEY 与 OPENAI_BASE_URL 由官方 SDK 识别;NPC_ 前缀变量是我们自己的应用配置,必须由业务代码读取。
| 变量 | 开发示例 | 作用 |
|---|---|---|
OPENAI_API_KEY |
运行时输入 | 服务端凭据,不记录值 |
OPENAI_BASE_URL |
https://api.openai.com/v1 |
SDK 基础地址,不追加 /responses |
NPC_MODEL |
gpt-4.1-mini |
选用可访问的文本模型 |
NPC_MAX_OUTPUT_TOKENS |
160 |
短台词的输出上限 |
NPC_LOG_LEVEL |
INFO |
应用日志详细程度 |
在本机 Bash 终端执行;下面的密钥输入不回显。export 只对当前终端及其子进程生效,部署时改为服务端环境注入。
read -rsp "API Key: " OPENAI_API_KEY
export OPENAI_API_KEY
printf '\n'
export OPENAI_BASE_URL="https://api.openai.com/v1"
export NPC_MODEL="gpt-4.1-mini"
export NPC_MAX_OUTPUT_TOKENS="160"
export NPC_LOG_LEVEL="INFO"预期结果:终端提示输入密钥但不显示其内容;其余赋值命令不打印密钥。若使用 PowerShell,应通过该环境的安全凭据输入方式设置变量,而非直接复制 Bash 语法。
在启动时校验且避免泄密
将下面代码保存为 npc_config_check.py。它只检查密钥是否存在,不输出密钥正文;同时将 API 地址限制在示例使用的官方域名,拒绝空模型名和不合法的输出预算,避免密钥被误发到陌生主机。这里 32~4096 是项目约束,并非所有模型的通用限制。
import logging
import os
from urllib.parse import urlsplit
def main():
if not os.getenv("OPENAI_API_KEY", "").strip():
raise SystemExit("配置错误:缺少 OPENAI_API_KEY")
base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1").rstrip("/")
url = urlsplit(base_url)
# 只允许预期 API 地址,避免凭据被转发给陌生域名。
if ((url.scheme, url.netloc, url.path) !=
("https", "api.openai.com", "/v1") or url.query or url.fragment):
raise SystemExit("配置错误:API 基础地址不在允许列表")
model = os.getenv("NPC_MODEL", "gpt-4.1-mini").strip()
if not model:
raise SystemExit("配置错误:NPC_MODEL 不能为空")
try:
limit = int(os.getenv("NPC_MAX_OUTPUT_TOKENS", "160"))
except ValueError:
raise SystemExit("配置错误:输出上限必须为整数")
if not 32 <= limit <= 4096:
raise SystemExit("配置错误:输出上限超出项目允许范围")
level = os.getenv("NPC_LOG_LEVEL", "INFO").upper()
if level not in {"DEBUG", "INFO", "WARNING", "ERROR"}:
raise SystemExit("配置错误:无效日志级别")
logging.basicConfig(level=getattr(logging, level),
format="%(levelname)s %(message)s")
# 只暴露非敏感配置,绝不打印环境变量字典。
logging.info("npc.config ready model=%s host=%s max_tokens=%d key_loaded=yes",
model, url.hostname, limit)
if __name__ == "__main__":
main()预期结果:在上述 Bash 会话执行 python npc_config_check.py 后,终端出现以下日志;校验只证明配置格式正常,不代表已成功连接 API。
INFO npc.config ready model=gpt-4.1-mini host=api.openai.com max_tokens=160 key_loaded=yes设计能用于排障的开发日志
真实请求结束时记录 response_id、模型名、完成状态、耗时毫秒数、input_tokens 与 output_tokens;发生失败时记录 HTTP 状态码或异常类别。这样能区分认证失败、网络超时、模型生成不完整和 Token 成本异常。
不要直接记录 Authorization 头、完整请求对象、环境变量集合或玩家原文;尤其不要用 logging.debug(request_body) 作为临时排错手段。若报 401,检查服务端密钥及项目权限;若出现 404,核对基础地址与模型标识;若遇到 429,检查配额和速率限制,再考虑受控退避重试。
最后做一次负向验证:在单独终端不设置 OPENAI_API_KEY 运行检查脚本,应得到 配置错误:缺少 OPENAI_API_KEY。这说明错误在启动阶段就能被发现,而不会把敏感配置写入日志。