OpenApi 接口使用说明 （二）

承前：OpenApi接口使用说明(一)

前言：

抱着学习GPT，就从接口层学习，才能更深入理解的初衷，遂在一定的理解的基础上，对 Open API Doc 该文章的进行中文转译，也是自我学习的一个过程。

对 Open API Doc 进行中文转译，并进行一定语境翻译，内容的调整，可能存在翻译不准确，如果介意请前往英文版查阅，或者Google 文章中文翻译查阅。

Completion 介绍

功能：给定提示，模型将返回一个或多个预测的补全，并且还可以返回每个位置上可选标记的概率。

接口：

• POST api.openai.com/v1/completi…

功能：

• 根据提供的 提示符(“prompt”) 和 参数，创建 补齐(“completion”) 。

presence_penalty & frequency_penalty 补充介绍

作用：

用于减少采样标记重复序列的可能性。

运作原理：

直接修改logits(非标准化的对数概率)，并添加额外的惩罚/诱导。

具体修改方式：

mu[j] -> mu[j] - c[j] * alpha_frequency - float(c[j] > 0) * alpha_presence

• mu[j]：第j个 token 的 logits 分对数。

• c[j]： 指 多长时间下，token 在当前位置之前被采样。

• float(c[j] > 0) ：如果 c[j] > 0 则值为1， 否则 值为0。

• alpha_frequency：是 频率惩罚 系数。

• alpha_presence：是 存在惩罚系数。

presence_penalty vs frequency_penalty 区别:

• presence_penalty:

• frequency_penalty:

penalty coefficients 取值：

• 如果目标只是在一定程度上减少重复样本，惩罚系数的合理值应该在0.1到1之间。

• 如果目标是强烈抑制重复，那么可以将系数增加到2，但这可能会显著降低样本的质量。而负值可以用来增加重复的可能性。

Curl 执行示例：

curl https://api.openai.com/v1/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "text-davinci-003",
    "prompt": "Say this is a test",
    "max_tokens": 7,
    "temperature": 0
  }'

结果：

{
        "id": "cmpl-76zk30Q0ejRwP9HA7C7SfpIm5fo1M",
        "object": "text_completion",
        "created": 1681901659,
        "model": "text-davinci-003",
        "choices": [{
                "text": "\n\nThis is indeed a test",
                "index": 0,
                "logprobs": null,
                "finish_reason": "length"
        }],
        "usage": {
                "prompt_tokens": 5,
                "completion_tokens": 7,
                "total_tokens": 12
        }
}

Chat 介绍

功能：给定描述对话的消息列表，模型将返回一个响应。

接口：

• POST api.openai.com/v1/chat/com…

功能：

• 为给定的chat 聊天对话创建一个模型响应。

Edits 介绍

功能：给定一个 提示 或者 指令，模型将 返回一个 编辑过的 提示信息。

接口：

• POST api.openai.com/v1/edits

功能：

• 根据提供的输入、指令和参数创建新的编辑。

Curl 执行示例：

curl https://api.openai.com/v1/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "text-davinci-edit-001",
    "input": "What day of the wek is it?",
    "instruction": "Fix the spelling mistakes"
  }'

结果：

{
  "object": "edit",
  "created": 1589478378,
  "choices": [
    {
      "text": "What day of the week is it?",
      "index": 0,
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 32,
    "total_tokens": 57
  }
}

说明：将 错误的单词 wek，转为 week。

Images 介绍

功能：给定提示符和/或输入图像，模型将生成新图像。

更多参考 Image Generate。

4.1 Create Images 介绍

接口：

• POST api.openai.com/v1/images/g…

功能：

• 根据提示创建一个图像。

Curl 执行示例：

curl https://api.openai.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "prompt": "A cute baby sea otter",
    "n": 2,
    "size": "1024x1024"
  }'

返回数据：

{
  "created": 1682313829,
  "data": [
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/org-QDZ0nHgzgPVhuYVa21sOEkpR/user-uvKCDCPswre2qtsKQHvTAxgG/img-xJYFqIwhUVkfWHz5oc3CKoQV.png?st=2023-04-24T04%3A23%3A49Z&se=2023-04-24T06%3A23%3A49Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=6aaadede-4fb3-4698-a8f6-684d7786b067&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2023-04-24T05%3A20%3A20Z&ske=2023-04-25T05%3A20%3A20Z&sks=b&skv=2021-08-06&sig=ZEbptoEEk1J6bkswqLipji/VEzAnc5qb3wrMjNY52TI%3D"
    },
    {
      "url": "https://oaidalleapiprodscus.blob.core.windows.net/private/org-QDZ0nHgzgPVhuYVa21sOEkpR/user-uvKCDCPswre2qtsKQHvTAxgG/img-ahdwDjngqdTokldybaXbRvqR.png?st=2023-04-24T04%3A23%3A49Z&se=2023-04-24T06%3A23%3A49Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=6aaadede-4fb3-4698-a8f6-684d7786b067&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2023-04-24T05%3A20%3A20Z&ske=2023-04-25T05%3A20%3A20Z&sks=b&skv=2021-08-06&sig=iqVL7KtrSr3L2EXmVATgjV/FytnEAlxzRayn5wdq%2BOg%3D"
    }
  ]
}

补充：该模型对 欧美人图像进行了更多的训练，生成的图像效果还不错。相反对其他地区的人像生成效果一般。

4.2 Create Images Edit 介绍

根据原始图片 和 提示，生成编辑后的 或者 扩展后的 新的图片。

接口：

• POST api.openai.com/v1/images/e…

功能：

• 根据原始图片 和 提示，生成编辑后的 或者 扩展后的 新的图片。

Curl 执行示例：

curl https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image="@otter.png" \
  -F mask="@mask.png" \
  -F prompt="A cute baby sea otter wearing a beret" \
  -F n=2 \
  -F size="1024x1024"

结果：

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}

4.3 Create Images variation 介绍

接口：

• 接口：POST api.openai.com/v1/images/v…

功能：

• 基于给定的图片，创建一个变化的图片。

Curl 执行示例：

curl https://api.openai.com/v1/images/variations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image="@otter.png" \
  -F n=2 \
  -F size="1024x1024"

结果：

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}

Embeddings 介绍

功能：获得给定输入的向量表示，可以很容易地被机器学习模型和算法 使用。

接口：

• POST api.openai.com/v1/embeddin…

功能：

• 创建表示输入文本的嵌入向量。

Curl 执行示例：

curl https://api.openai.com/v1/embeddings \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "The food was delicious and the waiter...",
    "model": "text-embedding-ada-002"
  }'

结果：

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... (1536 floats total for ada-002)
        -0.0028842222,
      ],
      "index": 0
    }
  ],
  "model": "text-embedding-ada-002",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

Audio 介绍

功能：实现将音频转换为文本。

更多参考 Speech to text。

6.1 Create transcription 介绍

接口：

• POST api.openai.com/v1/audio/tr…

功能：

• 将音频转为文本

Curl 执行示例：

curl https://api.openai.com/v1/audio/translations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@/path/to/file/german.m4a" \
  -F model="whisper-1"

结果：

{
  "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}

6.2 Create translation 介绍

接口：

• POST api.openai.com/v1/audio/tr…

功能：

• 将音频翻译成英语。

Curl 执行示例：

curl https://api.openai.com/v1/audio/translations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@/path/to/file/german.m4a" \
  -F model="whisper-1"

结果：

{
  "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}

Files 介绍

功能：是用于 上传可以 与 Fine-tuning 等功能 一起使用的 文档。

7.1 List files 介绍

接口：

• GET api.openai.com/v1/files

功能：

• 返回属于用户组织的 文件列表。

Curl 执行示例：

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY"

结果：

{
  "data": [
    {
      "id": "file-ccdDZrC3iZVNiQVeEA6Z66wf",
      "object": "file",
      "bytes": 175,
      "created_at": 1613677385,
      "filename": "train.jsonl",
      "purpose": "search"
    },
    {
      "id": "file-XjGxS3KTG0uNmNOK362iJua3",
      "object": "file",
      "bytes": 140,
      "created_at": 1613779121,
      "filename": "puppy.jsonl",
      "purpose": "search"
    }
  ],
  "object": "list"
}

7.2 Upload files 介绍

接口：

• POST api.openai.com/v1/files

功能：

• 上传一个包含被用于跨不同端点/特性 的文档。

• 目前，一个组织上传的所有文件最大可达1GB。

Curl 执行示例：

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="fine-tune" \
  -F file="@mydata.jsonl"

结果：

{
  "id": "file-XjGxS3KTG0uNmNOK362iJua3",
  "object": "file",
  "bytes": 140,
  "created_at": 1613779121,
  "filename": "mydata.jsonl",
  "purpose": "fine-tune"
}

7.3 Delete files 介绍

接口：

• DELETE api.openai.com/v1/files/{f…

功能：

• 删除指定文件

路径参数介绍：

	类型	是否必填	默认值	释义
file_id	string	Required		要用于此请求的文件的ID

Curl 执行示例：

curl https://api.openai.com/v1/files/file-XjGxS3KTG0uNmNOK362iJua3 \
  -X DELETE \
  -H "Authorization: Bearer $OPENAI_API_KEY"

结果：

{
  "id": "file-XjGxS3KTG0uNmNOK362iJua3",
  "object": "file",
  "deleted": true
}

7.4 Retrieve files 介绍

接口：

• GET api.openai.com/v1/files/{f…

功能：

• 返回特定文件的信息。

路径参数介绍：

	类型	是否必填	默认值	释义
file_id	string	Required		要用于此请求的文件的ID

Curl 执行示例：

curl https://api.openai.com/v1/files/file-XjGxS3KTG0uNmNOK362iJua3 \
  -H "Authorization: Bearer $OPENAI_API_KEY"

结果：

{
  "id": "file-XjGxS3KTG0uNmNOK362iJua3",
  "object": "file",
  "bytes": 140,
  "created_at": 1613779657,
  "filename": "mydata.jsonl",
  "purpose": "fine-tune"
}

7.5 Retrieve files content 介绍

接口：

• GET api.openai.com/v1/files/{f…

功能：

• 返回指定文件的内容

路径参数介绍：

	类型	是否必填	默认值	释义
file_id	string	Required		要用于此请求的文件的ID

Curl 执行示例：

curl https://api.openai.com/v1/files/file-XjGxS3KTG0uNmNOK362iJua3/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl

Fine-tunes 介绍

功能：管理 fine-tunes 工作，使用提供的特定训练数据 完成裁剪定制模型。

更多参考：Fine-tune models

8.1 Create fine-tunes 介绍

接口：

• POST api.openai.com/v1/fine-tun…

功能：

• 创建一个任务，根据给定的 数据集 进行 fine-tunes 一个 特定的模型。

• 响应包括排队任务的详细信息，包括任务状态，以及一旦完成 fine-tuned 的模型名称。

Learn more about Fine-tuning

Curl 执行示例：

curl https://api.openai.com/v1/fine-tunes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "training_file": "file-XGinujblHPwGLSztz8cPS8XY"
  }'

结果：

{
  "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
  "object": "fine-tune",
  "model": "curie",
  "created_at": 1614807352,
  "events": [
    {
      "object": "fine-tune-event",
      "created_at": 1614807352,
      "level": "info",
      "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
    }
  ],
  "fine_tuned_model": null,
  "hyperparams": {
    "batch_size": 4,
    "learning_rate_multiplier": 0.1,
    "n_epochs": 4,
    "prompt_loss_weight": 0.1,
  },
  "organization_id": "org-...",
  "result_files": [],
  "status": "pending",
  "validation_files": [],
  "training_files": [
    {
      "id": "file-XGinujblHPwGLSztz8cPS8XY",
      "object": "file",
      "bytes": 1547276,
      "created_at": 1610062281,
      "filename": "my-data-train.jsonl",
      "purpose": "fine-tune-train"
    }
  ],
  "updated_at": 1614807352,
}

8.2 List fine-tunes 介绍

接口：

• GET api.openai.com/v1/fine-tun…

功能：

• 列举对应 组织下的 所有 fine-tunes 文件。

Curl 执行示例：

curl https://api.openai.com/v1/fine-tunes \
  -H "Authorization: Bearer $OPENAI_API_KEY"

结果：

{
  "object": "list",
  "data": [
    {
      "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
      "object": "fine-tune",
      "model": "curie",
      "created_at": 1614807352,
      "fine_tuned_model": null,
      "hyperparams": { ... },
      "organization_id": "org-...",
      "result_files": [],
      "status": "pending",
      "validation_files": [],
      "training_files": [ { ... } ],
      "updated_at": 1614807352,
    },
    { ... },
    { ... }
  ]
}

8.3 Retrieve fine-tunes 介绍

接口：

• GET api.openai.com/v1/fine-tun…

功能：

• 检索 指定 id 的 fine-tunes 工作信息。

更多信息参考 Fine-Tunes。

路径参数介绍：

	类型	是否必填	默认值	释义
fine_tune_id	string	Required		fine-tune 工作ID

Curl 执行示例：

curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F \
  -H "Authorization: Bearer $OPENAI_API_KEY"

结果：

{
  "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F",
  "object": "fine-tune",
  "model": "curie",
  "created_at": 1614807352,
  "events": [
    {
      "object": "fine-tune-event",
      "created_at": 1614807352,
      "level": "info",
      "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
    },
    ......
    ,{
      "object": "fine-tune-event",
      "created_at": 1614807864,
      "level": "info",
      "message": "Job succeeded."
    }
  ],
  "fine_tuned_model": "curie:ft-acmeco-2021-03-03-21-44-20",
  "hyperparams": {
    "batch_size": 4,
    "learning_rate_multiplier": 0.1,
    "n_epochs": 4,
    "prompt_loss_weight": 0.1,
  },
  "organization_id": "org-...",
  "result_files": [
    {
      "id": "file-QQm6ZpqdNwAaVC3aSz5sWwLT",
      "object": "file",
      "bytes": 81509,
      "created_at": 1614807863,
      "filename": "compiled_results.csv",
      "purpose": "fine-tune-results"
    }
  ],
  "status": "succeeded",
  "validation_files": [],
  "training_files": [
    {
      "id": "file-XGinujblHPwGLSztz8cPS8XY",
      "object": "file",
      "bytes": 1547276,
      "created_at": 1610062281,
      "filename": "my-data-train.jsonl",
      "purpose": "fine-tune-train"
    }
  ],
  "updated_at": 1614807865,
}

8.4 Cancel fine-tunes 介绍

接口：

• POST api.openai.com/v1/fine-tun…

功能：

• 立刻取消 fine-tunes 工作。

路径参数介绍：

	类型	是否必填	默认值	释义
fine_tune_id	string	Required		fine-tune 工作ID

Curl 执行示例：

curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY"

结果：

{
  "id": "ft-xhrpBbvVUzYGo8oUO1FY4nI7",
  "object": "fine-tune",
  "model": "curie",
  "created_at": 1614807770,
  "events": [ { ... } ],
  "fine_tuned_model": null,
  "hyperparams": { ... },
  "organization_id": "org-...",
  "result_files": [],
  "status": "cancelled",
  "validation_files": [],
  "training_files": [
    {
      "id": "file-XGinujblHPwGLSztz8cPS8XY",
      "object": "file",
      "bytes": 1547276,
      "created_at": 1610062281,
      "filename": "my-data-train.jsonl",
      "purpose": "fine-tune-train"
    }
  ],
  "updated_at": 1614807789,
}

8.5 List fine-tunes events介绍

接口：

• GET api.openai.com/v1/fine-tun…

功能：

• 获取 fine-tunes 工作的细粒度状态更新信息。

路径参数介绍：

	类型	是否必填	默认值	释义
fine_tune_id	string	Required		fine-tune 工作ID

查询参数介绍：

	类型	是否必填	默认值	释义
stream	boolean	Optional	false	是否为fine-tune 工作 进行流式传输。

Curl 执行示例：

curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/events \
  -H "Authorization: Bearer $OPENAI_API_KEY"

结果：

{
  "object": "list",
  "data": [
    {
      "object": "fine-tune-event",
      "created_at": 1614807352,
      "level": "info",
      "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807356,
      "level": "info",
      "message": "Job started."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807861,
      "level": "info",
      "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807864,
      "level": "info",
      "message": "Uploaded result files: file-QQm6ZpqdNwAaVC3aSz5sWwLT."
    },
    {
      "object": "fine-tune-event",
      "created_at": 1614807864,
      "level": "info",
      "message": "Job succeeded."
    }
  ]
}

8.6 Delete fine-tunes model介绍

接口：

• DELETE api.openai.com/v1/models/{…

功能：

• 删除 fine-tunes 微调过的模型。

注：删除者必须在组织中具有Owner角色。

路径参数介绍：

	类型	是否必填	默认值	释义
model	string	Required		要删除的模型

Curl 执行示例：

curl https://api.openai.com/v1/models/curie:ft-acmeco-2021-03-03-21-44-20 \
  -X DELETE \
  -H "Authorization: Bearer $OPENAI_API_KEY"

结果：

{
  "id": "curie:ft-acmeco-2021-03-03-21-44-20",
  "object": "model",
  "deleted": true
}

Moderations 介绍

功能：给定输入文本，如果模型将其分类为违反OpenAI的内容策略，则输出。

更多信息，见 Moderations

9.1 Create moderations 介绍

接口：

• POST api.openai.com/v1/moderati…

功能：

• 如果文本违反OpenAI的内容政策，则对应分类归类

Curl 执行示例：

curl https://api.openai.com/v1/moderations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "input": "I want to kill them."
  }'

结果：

{
  "id": "modr-5MWoLO",
  "model": "text-moderation-001",
  "results": [
    {
      "categories": {
        "hate": false,
        "hate/threatening": true,
        "self-harm": false,
        "sexual": false,
        "sexual/minors": false,
        "violence": true,
        "violence/graphic": false
      },
      "category_scores": {
        "hate": 0.22714105248451233,
        "hate/threatening": 0.4132447838783264,
        "self-harm": 0.005232391878962517,
        "sexual": 0.01407341007143259,
        "sexual/minors": 0.0038522258400917053,
        "violence": 0.9223177433013916,
        "violence/graphic": 0.036865197122097015
      },
      "flagged": true
    }
  ]
}