模型 API 基础
调用模型与调用普通 HTTP 服务有相似之处:发送认证信息和请求,读取响应,处理失败。区别在于,模型返回的文本不是确定性的业务事实;HTTP 请求成功,也不代表内容可以直接采用。
本节使用 OpenAI Responses API 说明具体结构,核对日期为 2026-11-09。参数名称不能原样套用到所有提供商。
一次请求包含什么
最小文本请求可以发往 POST https://api.openai.com/v1/responses,使用 Bearer Token 认证。下面是请求体的示意结构,模型标识需要替换成账户中可用的实际值:
{
"model": "账户可用的模型标识",
"instructions": "把帖子概括为三个中文要点,不补充原文没有的事实。",
"input": "这里是待处理的帖子正文",
"max_output_tokens": 2048,
"store": false
}
这里的 instructions 表达应用要求,input 提供本次输入。用户提交的帖子属于待处理资料,不应获得修改应用规则的权限。文本与指令说明
Key、模型和配置放在哪里
API Key 留在服务端,通过环境变量或密钥管理注入。浏览器请求自己的后端,后端再访问模型;不要把服务 Key 写入前端构建产物、页面源码或仓库。
模型标识由后端配置决定。若让用户任意传入模型、输出上限或工具配置,就可能绕过应用的成本和能力边界。
Laravel 中可在 config/services.php 增加配置,在服务代码中用 config() 读取。部署时若使用配置缓存,修改环境变量后也要按项目流程更新缓存。Laravel 配置说明
store: false 用于控制本次响应的存储设置,不等于对数据保留或所有服务政策的完整承诺。真实数据能否发送,应核对所用服务的约定。
消息角色不是所有接口共用的字段模板
许多对话接口使用 user、assistant,以及 system 或 developer 等角色。user 表示用户输入,assistant 表示已有模型输出,高层角色用于应用指令;具体支持方式由接口和模型决定。
本章的最小示例使用 instructions 与文本 input,不混用其他端点的 messages 模板。需要多轮对话时,再按接口组织历史或会话状态;单次调用不会自动获得你数据库里的历史记录。
即使存在指令优先级,应用仍要通过权限检查、数据过滤和参数校验建立边界,不能把 Prompt 当作访问控制系统。
参数:先少用,再验证
| 参数或概念 | 本章的处理 |
|---|---|
| model | 通过服务端配置指定 |
| max_output_tokens | 示例设为 2048,作为输出预算上限 |
| stream | 非流式示例省略,流式示例设为 true |
| temperature / top_p | 不设统一默认,先核对模型支持 |
| stop | 不作为所有接口都可用的参数 |
输出上限不保证模型一定给出这么多内容。对推理模型,它还可能涵盖不可见的推理 Token;预算太小可能导致可见答案未生成就达到限制。Token 计数与上限
本教程的 2048 和超时时间都是教学设置,需根据模型与实测调整。若出现 incomplete,检查原因,不能通过忽略状态来“修好”接口。
怎样读取原始响应
Responses 的 output 是多种输出项的集合,可能包含推理、消息和工具相关项目。不要固定读取 output[0].content[0].text。部分 SDK 提供的 output_text 是便捷聚合属性,也不能直接当作所有原始 HTTP 响应都有的顶层字段。官方响应结构说明
对于本章只生成文本的任务,处理顺序是:检查 HTTP 状态;解析 JSON;确认响应完成;遍历 message 项里的 output_text;识别拒答和空文本;最后交给页面展示。
返回了文本,还要检查它是否忠于输入。通用 HTTP 成功、模型生成完成、业务结果合格,是三个不同层次。
留下必要的调用记录
建议记录应用任务 ID、模型标识、Prompt 版本、耗时、响应 ID、服务请求 ID、用量和失败类别。默认不记录 Key、完整帖子和完整响应,排障需要时再按数据要求处理。
服务请求 ID 用于追踪某次上游调用,不能充当业务幂等键。浏览器重发、队列重试和服务端重试之间,也需要明确谁负责控制次数。
下一节会把这些步骤落到一个 Laravel 服务中,先让一次非流式请求完整成功,再加入流式显示。
一站式AI产品经理入门指南
关于 LearnKu