Amadeus的知识库 | OpenAI的API规范是啥来头？—— 集成大模型到项目中的必备通行证

一、引文相信每一个尝试做 AI 项目把大模型集成到自己项目中的开发者都一定听说过 OpenAI 的 API 规范。它就好比是大模型世界里面的普通话当开发者试图通过调用 API 完成与大模型的交互时通常都会遵循这一规范的请求格式来构建请求参数以及根据其响应格式来解析结果并且这一套规范在调用市面上的大部分的大模型 API 都是兼容的。那么这一规范究竟是什么呢里面到底蕴含哪些细节包括说在一个Java程序里面调用大模型的具体流程是什么要想知道答案我们可以继续看下去注意大模型 API 接口大致分为对话补全Chat Completions、嵌入Embeddings、微调Fine-tuning、图像生成Images、音频处理Audio这几种每一种接口的内部规范略有差异下面我们将会以最为常用的大模型 API 的事实标准—— OpenAI 的 Chat Completions API 作为示例刨析其中的具体细节。接口类型适用场景常用模型对话补全Chat Completions聊天机器人、内容生成gpt-3.5-turbo、gpt-4、gpt-4o嵌入Embeddings语义检索、向量数据库构建text-embedding-3-small、text-embedding-ada-002微调Fine-tuning自定义模型训练gpt-3.5-turbo-0125图像生成Images文生图、图生图dall-e-2、dall-e-3音频处理Audio语音转文字、文字转语音whisper-1、tts-1二、准备好你的BASE_URL和API_KEY我们在 Java 程序中调用大模型的第一步就是先确定你选择注册的 AI 模型服务平台的BASE_URL 和 API_KEY。以调用硅基流动平台的智谱GLM5为例复制 API 文档里面的POST请求就是BASE_URLAuthorization 里面的就是你的API_KEY在 API 密钥里面可以找到。三、构建请求体第二步就是构建请求参数OpenAI 的 API 规范对请求参数的格式进行了限定在这一小节我们就具体了解一下其中各个参数的具体含义和应用场景。1.参数总览curl https://api.openai.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $OPENAI_API_KEY \ -d { model: gpt-4-turbo, messages: [ { role: user, content: What\s the weather like in Boston today? 用户的问题 } ], tools: [ 用户提供工具集让模型来选择使用哪个可以解决用户的问题 { type: function, function: { name: get_current_weather, description: Get the current weather in a given location, parameters: { type: object, properties: { location: { type: string, description: The city and state, e.g. San Francisco, CA }, unit: { type: string, enum: [celsius, fahrenheit] } }, required: [location] } } } ], tool_choice: auto }观察上述 curl 命令一个功能强大的命令行工具可用于发送 HTTP/HTTPS 请求、下载文件、上传数据以及调试 API。它支持多种协议HTTP、HTTPS、FTP 等在开发、测试和运维中非常常用。我们可以发现除却刚刚的 BASE_URL 和 API_KEY 还有 model、messages、tools、tool_choice等等接下来我们就来具体讲解每一种常见参数包括其属性的含义。2.modelmodel 都是 string 类型且是必须具备的参数它代表调用的模型ID例如gpt-3.5-turbo、gpt-4o、gpt-4-turbo必须使用当前账号有权限的模型否则会返回404错误3.messagesmessage 细分的话可以分为四类 System message、User message、Assistant message、Tool message每种 message 的属性有所差别接下来分开进行讲解。1System messageSystem message 又称系统消息系统消息是用来定义模型的行为规则相当于给模型一份工作手册。模型会始终遵守系统消息中的指令。通常大家在借用 AI 背八股或者模拟面试时如果对大模型的回答效果不是很满意其实就可以上牛客或者直接找 AI 帮你写出一段对应场景下适合的 System message这样大模型就会严格按照这套行为规则回答你的问题效果通常都会比默认的 System message 要好出很多。一个完整的system message要是一个json对象包含以下字段content必须提供的string类型表示系统消息内容role必须提供的string类型表示该消息的角色对于system message应该是systemname可选的string类型表示对话参与者的名称。2User message用户消息就是用户的输入也就是用户问的问题。一个完整的User message是一个json对象包含以下字段content必须提供的string或array类型二选一表示user的消息内容为string类型时表示消息的文本内容为array类型时一般用于调用多模态模型用来包含多个内容部分的数组一般是一个文本内容的json对象和一个或多个图片内容的json对象。仅当使用 gpt-4-visual-preview 这样的多模态模型时才支持图像输入。具体字段如下文本内容部分是一个json对象type必须提供的string类型表示内容部分的类型一般是“text”text必须提供的string类型文字内容图片内容部分是一个json对象type必须提供的string类型表示内容部分的类型一般是image_urlimage_url必须提供的json对象类型字段有url必须提供的string类型图像的URL或Base64 编码的图像数据detail可选的string类型一般默认是“auto”role必须提供的string类型表示消息的角色对于user message应该是username可选的string类型表示对话参与者的名称3Assistant message助手消息是模型之前的回答。它的作用是构建多轮对话的上下文。一个完整的Assistant message是一个json对象包含以下字段content必须提供(指定tool_call时除外)的string类型表示大模型的回答role必须提供的string类型表示消息的角色对于assistant message应该是assistantname可选的string类型表示对话参与者的名称tool_calls可选的array类型大模型生成的工具调用例如函数调用。tool_calls数组的每个元素是一个json对象代表一个函数调用包含的字段有id必须提供的string类型表示函数调用的idtype必须提供的string类型表示工具调用的类型。目前仅支持“function”类型function必须提供的string类型表示模型针对工具调用为用户生成的函数说明即模型在特定任务和场景下下在用户提供的函数中会推断出应该使用哪一个函数以及函数的参数应该是什么。所以包括的字段有name必须提供的string类型要调用的函数的名称arguments必须提供的string类型表示调用函数所用的参数由模型以 JSON 格式生成(如{\n\location\: \Boston, MA\\n})。但是请注意模型并不总是生成有效的参数并且可能会产生未由函数定义的参数。在调用函数之前最好验证参数的准确性。4Tool message在讲最后一种消息类型前先给大家介绍下 Function Calling它可以让大模型通过调用工具扩展能力边界。一种常见的误解是所谓的 Function Calling 就是大模型自己调用工具这种想法是错误的大模型本身不会自己调用工具它只会告诉你的后端代码需要执行哪个工具然后由你的后端代码去执行这一工具再把返回结果传递给大模型拼凑上下文回答你的问题。具体过程如下Step 1用户询问天气案例—— messages 里面的User message携带用户问题tools 里面则是开发者事先给大模型准备好的工具它是一个列表里面存着各种各样的工具具体属性及含义后面在讲解 tools 这个参数时会再次讲解。curl https://api.openai.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $OPENAI_API_KEY \ -d { model: gpt-4-turbo, messages: [ { role: user, content: What\s the weather like in Boston today? 用户的问题 } ], tools: [ 用户提供工具集让模型来选择使用哪个可以解决用户的问题 { type: function, function: { name: get_current_weather, description: Get the current weather in a given location, parameters: { type: object, properties: { location: { type: string, description: The city and state, e.g. San Francisco, CA }, unit: { type: string, enum: [celsius, fahrenheit] } }, required: [location] } } } ], tool_choice: auto }Step 2大模型回答Step 1中的用户请求 —— 这是一个 OpenAI 的Chat Completions API的标准响应体格式在第四大节会讲到。关键看它 tool_calls 属性里面就是大模型根据用户问题还有事先准备的工具列表判断出来的你的后端代码需要调用的工具以及它的各种属性比如名字就是get_current_weather这就是一个标准的 JSON 格式字符串然后你的后端代码先把这个响应体解析再去调用这个函数。{ id: chatcmpl-abc123, object: chat.completion, created: 1699896916, model: gpt-3.5-turbo-0125, choices: [ { index: 0, message: { role: assistant, content: null, tool_calls: [大模型根据用户的问题和用户提供的工具集返回了可能有用的函数 { id: call_abc123, type: function, function: { name: get_current_weather, 用户可以在调用了该函数后在下一轮对话把该函数调用结果反馈给大模型 然后就可以得到一个最终的答复 arguments: {\n\location\: \Boston, MA\\n} } } ] }, logprobs: null, finish_reason: tool_calls } ], usage: { prompt_tokens: 82, completion_tokens: 17, total_tokens: 99 } }Step 3生成我们的 Tool message返回给大模型拼凑上下文 ——一个完整的Tool message是一个json对象。他的用处是在用户根据assistant的tool_calls内容调用了某个函数后用户可能还需要再把函数调用结果反馈给大模型让大模型根据函数调用结果给出最终的总结性的答复。tool message消息字段有content必须提供的string类型表示工具消息的内容一般是把函数调用的结果描述在这里role必须提供的string类型表示消息的角色对于tool message应该是tooltool_call_id必须提供的string类型表示本次消息是对哪个函数调用的结果反馈应该与 assistant message-tool_calls-id 对应4.tools可用工具列表定义模型可以调用的函数/工具规范每个工具包含type固定为function和function函数定义包含name、description、parameters列表中每个tool包含的字段有type必须提供的string类型工具的类型。目前仅支持函数“function”function必须提供的json对象类型表示函数的一些描述信息包括description可选的string类型是函数功能的描述模型使用它来选择何时以及如何调用该函数name必须提供的string类型是函数的名称。必须是 a-z、A-Z、0-9或包含下划线和破折号最大长度为 64parameters可选的json对象类型表示函数接受的参数描述为 JSON Schema 对象。不包含parameters字段是代表定义了一个带有空参数列表的函数5.tool_choice控制工具调用行为-none强制不调用工具-auto让模型自动选择是否调用工具 - 指定具体工具对象强制调用该工具6.stream是否启用流式响应默认false。设置为true时会通过SSE协议逐块返回结果适合需要打字机效果的场景7.top_p核采样参数取值范围0~1默认1。例如设置为0.1时只会从概率总和前10%的Token中采样和temperature建议只修改其中一个8.temperature采样温度取值范围0~2默认1。值越低输出越确定值越高输出越随机有创造性0表示完全确定性输出四、解析响应体1.参数总览{ id: chatcmpl-123, object: chat.completion, created: 1677652288, model: gpt-3.5-turbo-0125, system_fingerprint: fp_44709d6fcb, choices: [ { index: 0, message: { role: assistant, content: 你好有什么可以帮你的, tool_calls: [] }, logprobs: null, finish_reason: stop } ], usage: { prompt_tokens: 9, completion_tokens: 12, total_tokens: 21 } }2.id本次请求的唯一ID用于问题排查3.object固定为chat.completion标识响应类型4.created请求处理的时间戳秒级5.model实际使用的模型ID6.system_fingerprint模型后端版本标识相同值表示后端环境一致7.choice回复结果数组长度等于请求中设置的n值-index结果序号-messageAI回复的消息对象结构和请求中的message一致-finish_reason回复结束原因stop正常结束、length达到max_tokens限制、tool_calls调用工具、content_filter内容审核拦截8.usageToken消耗统计-prompt_tokens输入消息的Token数-completion_tokens输出回复的Token数-total_tokens总消耗Token数用于计费9.流式响应流式响应会返回多个SSE块每个块是一个JSON对象结构和非流式类似但choices[0].delta字段增量返回内容最后一块的finish_reason不为空表示结束最后会返回一个data: [DONE]标记。data: {id:chatcmpl-abc123,choices:[{index:0,delta:{role:assistant,content:},finish_reason:null}]} ​ data: {id:chatcmpl-abc123,choices:[{index:0,delta:{content:可以},finish_reason:null}]} ​ data: {id:chatcmpl-abc123,choices:[{index:0,delta:{content:的。},finish_reason:null}]} ​ data: {id:chatcmpl-abc123,choices:[{index:0,delta:{content:根据},finish_reason:null}]} ​ data: {id:chatcmpl-abc123,choices:[{index:0,delta:{content:退货},finish_reason:null}]} ​ data: {id:chatcmpl-abc123,choices:[{index:0,delta:{content:政策},finish_reason:null}]} ​ data: {id:chatcmpl-abc123,choices:[{index:0,delta:{},finish_reason:stop}]} ​ data: [DONE]五、总结这篇文章我们主要围绕OpenAI API接口展开讲解先梳理对话补全、嵌入、微调、图像生成、音频处理五类接口的适用场景与常用模型接着说明调用前需准备BASE_URL与API_KEY重点解析Chat Completions请求体核心参数包括model、messages各类角色消息、工具调用相关配置及stream、top_p、temperature等参数再介绍响应体字段含义与流式响应格式清晰展示从发起带工具的对话请求、模型返回函数调用指令到完成结果交互的完整流程。整体为开发者提供了OpenAI API从接口选型、请求构建到响应解析的实用入门指引。