模型 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 服务中,先让一次非流式请求完整成功,再加入流式显示。

本文章首发在 LearnKu.com 网站上。

上一篇 下一篇
讨论数量: 0
发起讨论 只看当前版本


暂无话题~