OpenRouter 入门:接入游戏 AI NPC
从注册、选模型到调用 API,完成一个能响应玩家对话的游戏 NPC,并将输出接入游戏对话流程。
- 1
注册并创建 API 密钥
打开官网,点击 Sign Up 或 Log In 登录。进入控制台的 Keys 页面,点击 Create API Key,填写名称并复制密钥;密钥只展示一次,需存入环境变量,不要写进代码仓库。
- 2
筛选适合 NPC 的模型
进入 Models 页面,按聊天、文本生成或角色扮演标签筛选模型,查看上下文长度、定价与延迟。先选一款价格适中的模型做原型,再保留候选模型用于效果和成本对比。
- 3
配置调用环境
在项目目录创建 .env,写入 OPENROUTER_API_KEY;再安装 OpenAI 兼容 SDK。将 base URL 设为 https://openrouter.ai/api/v1,模型标识填入刚选中的模型 ID,便于后续统一替换。
- 4
编写 NPC 对话请求
编写异步函数,发送 system 角色设定、NPC 背景、玩家状态和历史对白,并要求返回简短、可直接展示的台词。先用固定玩家输入测试,设置超时、token 上限及基础错误重试。
- 5
接入游戏对话流程
把请求封装成游戏事件监听器:玩家提交对话后调用模型,把回复写入 NPC 对话框,再交回对话状态机。加入流式输出、取消生成和兜底台词,避免网络等待阻塞主线程。
- 6
验证产物并记录指标
连续测试问候、询问线索、冲突和越界问题,记录首字延迟、完整回复时间、token 消耗与费用。比较不同模型的角色一致性后,将模型 ID、提示词和参数配置化,方便迭代。
💡 实用技巧
- 用环境变量管理密钥,定期轮换
- 先用小 token 上限控制原型成本
- 把模型 ID 与提示词配置化
- 对话历史只保留必要消息
⚠️ 常见坑
- 误把完整回复延迟当作首字延迟
- 让 NPC 输出游戏指令而非台词
常见问题
Q:API 密钥应该放在哪个文件里?
在项目目录创建 .env,写入 OPENROUTER_API_KEY=你的密钥,并安装 OpenAI 兼容 SDK。密钥只在创建时展示一次,不要写进代码仓库;调用时通过环境变量读取。
Q:NPC 选模型时要看哪些参数?
进入 Models 页面,按聊天、文本生成或角色扮演标签筛选模型,重点查看上下文长度、定价和延迟。原型阶段先选价格适中的模型,再保留候选模型比较效果与成本。
Q:模型回复怎样接进游戏对话流程?
将异步请求封装为对话事件监听器:玩家提交后调用模型,把回复写入 NPC 对话框,再交回对话状态机;同时加入超时、token 上限、错误重试、取消生成和兜底台词。