2、OpenAI API标准接口剖析

好，咱们进入正题。这一章我打算把OpenAI API的底裤扒干净——请求长什么样、响应怎么解析、认证怎么搞、还有那几个最常用的端点。说白了，你只要搞懂了这套标准，后面适配Ollama就是照葫芦画瓢。

2.1 认证方式：API Key的江湖规矩

OpenAI的认证方式其实特别简单——就是API Key。每次请求都得在HTTP头里带上它。我个人习惯用环境变量来管理，而不是硬编码在代码里。

# 请求头示例
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

嗯，这里要注意一点：API Key是有权限范围的。我在项目中遇到过有人把只读Key拿去写数据，结果403报错半天找不出原因。说白了，Key分两种：

• 可写Key：能调所有端点，包括创建模型、微调等
• 只读Key：只能查模型列表、看用量统计

2.2 请求格式：JSON是唯一通行证

所有请求都是POST，数据格式是JSON。我刚开始接触时觉得这设计挺优雅的——一个JSON搞定所有参数，不用搞什么表单提交。

拿最常用的chat/completions端点举例：

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "system", "content": "你是一个AI助手"},
    {"role": "user", "content": "你好，今天天气怎么样？"}
  ],
  "temperature": 0.7,
  "max_tokens": 100,
  "stream": false
}

这里有几个关键字段，我挑重要的说：

• model：模型名称，必填。你想想看，不告诉它用哪个模型，它怎么干活？
• messages：对话历史，是个数组。每个元素有role和content两个字段。role可以是system、user、assistant。
• temperature：控制随机性，0到2之间。0就是每次都选最可能的词，2就是放飞自我。
• max_tokens：最大输出长度。我建议别设太大，不然响应慢还费钱。
• stream：是否流式输出。设为true的话，响应会像打字机一样一个字一个字蹦出来。

2.3 响应格式：读懂AI的回复

响应也是JSON格式。你拿到手后，主要关注几个字段就行：

{
  "id": "chatcmpl-123456789",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！今天天气不错，适合出门走走。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 15,
    "total_tokens": 35
  }
}

我重点解释几个：

• choices：这是核心。里面是个数组，每个元素是一次生成结果。通常只有一个，除非你设了n参数。
• finish_reason：为什么停止生成。stop表示正常结束，length表示达到max_tokens上限，content_filter表示内容被过滤了。
• usage：计费信息。prompt_tokens是你输入的字数，completion_tokens是AI输出的字数。嗯，钱就是这么算的。

2.4 常用端点：三个核心接口

OpenAI的端点其实不少，但日常开发中，90%的情况只用这三个：

端点	方法	用途	我常用的场景
/v1/chat/completions	POST	对话生成	聊天机器人、文本生成
/v1/embeddings	POST	文本向量化	语义搜索、知识库
/v1/models	GET	获取模型列表	检查可用模型

2.4.1 chat/completions：最常用的对话接口

这个端点我几乎天天用。它支持多轮对话，你只要把历史消息都塞进messages数组就行。我做过一个客服系统，就是把用户和AI的对话历史全部传进去，效果出奇的好。

流式输出这块我要多说一句。如果你做的是实时对话应用，一定要用stream模式。响应会变成一行一行的数据流：

data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
data: {"choices":[{"delta":{"content":"！"}}]}
data: [DONE]

你想想看，用户打字时看到AI一个字一个字蹦出来，体验感直接拉满。

2.4.2 embeddings：把文字变成数字

这个端点说白了就是把文本转成向量。我做过一个知识库搜索系统，就是把文档全部转成向量存起来，用户提问时也转成向量，然后算相似度。效果比传统关键词搜索好太多了。

{
  "input": "今天天气怎么样？",
  "model": "text-embedding-ada-002"
}

返回的向量是一个浮点数数组，长度通常是1536。嗯，这个数字你记一下，后面适配Ollama时会用到。

2.4.3 models：看看有哪些模型可用

这个端点最简单，就是个GET请求。返回当前账号下可用的模型列表。我每次部署新环境时，第一件事就是调这个接口，确认模型是不是加载好了。

GET /v1/models

{
  "data": [
    {"id": "gpt-3.5-turbo", "object": "model", "created": 1677610602},
    {"id": "gpt-4", "object": "model", "created": 1687882411}
  ]
}

2.5 知识体系总览

下面这张图是我自己画的，把这一章的核心内容串起来了。你一看就明白各个部分的关系：

这张图从下往上看：认证是基础，请求是输入，端点是路由，响应是输出。你只要把这四层搞明白，OpenAI API就算入门了。

---

公众号:蓝海资料掘金营，微信deep3321