游戏 AI / 系统课时

配置密钥端点与开发日志

配置密钥端点与开发日志

先把 NPC 对话请求需要的凭据、API 入口、模型预算和日志级别集中配置到服务端。完成后可以在不发送真实对话的情况下检查启动条件,并保证密钥不会进入游戏客户端资源、代码仓库或开发日志。

学习目标

  • 区分游戏客户端、后端和模型服务各自能接触的配置。
  • 用环境变量设置 API 端点、模型与输出上限,并在启动时校验。
  • 记录排障所需的元数据,不泄露凭据与玩家对话。

把密钥限制在服务端

在 Unity 或 Unreal 游戏中,玩家安装包、资源文件以及客户端脚本都可能被读取。客户端只把玩家发言和会话标识发给自己的游戏后端;后端从运行环境或密钥管理服务读取 OPENAI_API_KEY,再通过 HTTPS 调用模型接口。

NPC 对话的密钥边界与安全日志数据流

配置端点与模型预算

本例使用 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 只对当前终端及其子进程生效,部署时改为服务端环境注入。

bash
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 是项目约束,并非所有模型的通用限制。

python
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。

text
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。这说明错误在启动阶段就能被发现,而不会把敏感配置写入日志。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置密钥端点与开发日志

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

登录哪都通