openai.Completion.create 接口参数说明

引言：对于接口，不了解参数含义，就不知道它能咋用？而了解参数的含义最好有例子，基于这个认知，整理了OpenAI几个主要API的接口参数说明。

OpenAI的completions接口是一种自然语言处理API，可用于各种文本生成任务，例如：

• 文本摘要：给定一篇文章，生成一个简短的摘要。
• 语言翻译：将一种语言的文本翻译成另一种语言的文本。
• 文章生成：生成一篇文章，可以用于自动写作、内容创作等领域。
• 问答系统：回答用户提出的问题，可以用于智能客服、知识库等领域。
• 自动化写作：自动生成各种类型的文本，例如广告文案、新闻报道、小说等。
• ...

本文是Completion接口的参数说明和例子，官方文档看：https://platform.openai.com/docs/api-reference/completions

下面是一个简单的http请求例子

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
  }'

参数 model

要使用的模型，可以通过下面脚本来获得可用的模型：

import os
import openai
openai.api_key = os.getenv("OPENAI_API_KEY")
openai.Model.list()

各个模型的说明看：
https://platform.openai.com/docs/models/overview

参数 prompt

你的提问，或者说得到回答结果的提示文本。
可以是字符串或数组。

下面是用数组的一个例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = ["The following is a conversation between two friends, John and Sarah.",
          "John: Hi Sarah, how are you doing today?",
          "Sarah: I'm doing great, thanks for asking. How about you?",
          "John: I'm doing pretty well too. So, did you hear about the new restaurant that just opened up downtown?"]

response = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=1,
    stop=None,
    temperature=0.5,
)

print(response.choices[0].text)

在这个示例中，我们传递一个包含四个句子的数组作为prompt。这个prompt表示一个关于两个朋友之间的对话，他们谈论了新开张的餐厅。我们使用了Davinci模型进行生成，生成的结果将包含最多50个tokens。其他参数使用了默认值。

OpenAI的completions接口的计费方式是基于生成的tokens数目的。使用数组方式和不使用数组方式的收费方式是相同的，都是按照生成的tokens数目计费。

不过，使用数组方式可以使得我们更加方便地将一个文本片段分成多个段落或句子，这样可以更好地控制生成的文本的结构和内容。同时，使用数组方式还可以使得我们更加灵活地在prompt中添加或删除特定的句子，以便进行实验和测试。

因此，在实际应用中，使用数组方式可能更加方便和实用。

参数 suffix 后缀

完成生成文本后的后缀字符串，默认为空。

参数suffix用于在模型生成的文本之后添加一段固定的后缀。这可以用来添加一些额外的文本或标记，例如表示文本结束的符号。

以下是使用suffix参数的示例：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The quick brown fox jumps over the lazy dog."
suffix = "The end of the story."

response = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=1,
    stop=None,
    temperature=0.5,
    suffix=suffix
)

print(response.choices[0].text)

最终生成的文本将类似于以下内容：

The quick brown fox jumps over the lazy dog. The end of the story.

请注意，suffix 参数仅在生成文本的长度不超过 max_tokens 时才会生效。如果生成文本的长度达到了 max_tokens，API 将返回生成文本并停止生成，无论是否提供 suffix 。

参数 max_tokens

生成结果时的最大token数，默认值为16。
不能超过模型的上下文长度(大多数模型的上下文长度为 2048 个token。)，可以把结果内容复制到 OpenAI Tokenizer 来了解 tokens 的计数方式。

以下是使用max_tokens参数的示例：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The quick brown fox jumps over the lazy dog."

response = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=10,
    n=1,
    stop=None,
    temperature=0.5,
)

print(response.choices[0].text)

在这个示例中，模型将生成一个包含最多10个tokens的文本，因此最终生成的文本将非常短。可能的结果包括单个单词或短语，例如“fox jumps”或“the quick brown”。

总之，通过控制max_tokens参数，我们可以控制模型生成的文本长度，以便生成符合我们需求的文本结果。

需要注意的是，生成的文本长度过长可能会影响API的响应时间和计费。

参数 temperature

参数temperature用于调整模型生成文本时的创造性程度。

• 较高的temperature将使模型更有可能生成新颖、独特的文本，
• 而较低的温度则更有可能生成常见或常规的文本。

例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The quick brown fox jumps over the lazy dog."

response = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=1,
    stop=None,
    temperature=0.9,
)

print(response.choices[0].text)

在这个示例中，模型将生成一个包含最多50个tokens的文本，并尝试以较高的创造性程度生成文本。这可能会导致模型生成非常新颖和独特的文本，例如以下可能的结果：

The quick brown fox dances over the lazy dog and sings a happy tune. The dog is not impressed, but the fox is having a great time.

参数 top_p

top_p参数用于控制模型生成文本时，选择下一个单词的概率分布的范围。具体来说，当使用top_p参数时，模型将考虑累积概率分布中概率之和最大的最小集合中的所有单词，并在其中选择下一个单词。

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "What is the meaning of life?"
model = "text-davinci-002"
response = openai.Completion.create(
    engine=model,
    prompt=prompt,
    max_tokens=50,
    top_p=0.5,
    n=1,
    stop=None,
)
print(response.choices[0].text)

在上面的代码中，我们使用了text-davinci-002模型生成了一个关于“生命的意义”的短文本，使用了top_p参数，值为0.5。这个参数控制着OpenAI生成文本的多样性，具体来说，它表示从概率分布中选取的概率质量值之和达到0.5时停止，生成的文本就是这个分布下的采样结果。

与之类似的另一个参数是temperature，它也可以控制生成文本的多样性。不同的是，temperature是一个正实数，它用来缩放模型生成的原始概率分布。具体来说，当temperature较低时，生成的文本更加保守、可预测，当temperature较高时，生成的文本更加随机、多样。

下面是对比top_p和temperature两个参数的表格，以及它们适用的场景：

参数	top_p	temperature
作用	控制生成文本的多样性，选择概率质量值之和达到top_p的概率分布采样结果	缩放模型生成的原始概率分布，控制生成文本的多样性
适用场景	- 当需要生成较为可控、可预测的文本时 - 当需要生成语法正确、含义明确的文本时 - 当需要保留模型生成文本的局部结构时	- 当需要生成多样、创新的文本时 - 当需要避免生成重复或过度拟合的文本时 - 当需要让模型在新领域的表现更加灵活、泛化能力更强时

总的来说，top_p适用于需要控制模型生成文本多样性的场景，可以让生成的文本保持一定的可控性，适用于需要保留一些局部结构的场景。而temperature适用于需要生成更加多样、创新的文本，可以让生成的文本更具随机性，适用于需要在新领域进行探索的场景。

参数 n

n这个参数控制了API返回的候选文本的数量，即API会生成多少个可能的文本选项供用户选择。

注意：由于此参数会生成许多，因此它会快速消耗token配额，请谨慎使用。

下面是一个例子，使用OpenAI的API来生成一个文本片段，其中n设置为3：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The quick brown fox"
model = "text-davinci-002"
completions = openai.Completion.create(
    engine=model,
    prompt=prompt,
    max_tokens=20,
    n=3,
    temperature=0.5
)

for choice in completions.choices:
    print(choice.text)

在这个例子中，API将返回三个可能的文本选项，我们可以通过遍历completions.choices来获取它们。
可能的输出结果如下：

The quick brown fox jumps over the lazy dog.
The quick brown fox is always looking for new challenges.
The quick brown fox is known for its speed and agility.

参数 best_of

best_of参数用于指定多个生成器对同一个prompt文本进行生成，并从中选择最好的结果返回。

下面是一个使用best_of参数的例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The meaning of life is"
completions = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=3,
    best_of=2,
)

text = completions.choices[0].text.strip()

print(f"Generated Text: {text}")

在这个例子中，n=3告诉生成器生成3个文本结果，best_of=2告诉生成器从这3个结果中选择2个最好的结果返回。

这里的“最好的结果”是指根据模型得分排序而来的，模型得分越高的结果排名越靠前。

通过使用best_of参数，可以提高生成文本的质量和一致性，从而减少生成文本中可能存在的错误和不自然之处。

然而需要注意的是，使用best_of参数会增加 API 调用的计算量和时间，因为每个请求都需要生成多个文本并选择最好的结果。因此，在实际使用中需要根据需求和计算资源来选择是否使用该参数。

参数 stream

默认false,是否流式传输回部分进度。

参数stream可以在请求生成文本时控制文本是否以流的形式返回。下面是一个使用stream参数的例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "I am feeling very"
response = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    temperature=0.7,
    stream=True
)

for chunk in response:
    text = chunk["text"]
    print(text)

使用stream参数的好处在于，它允许我们按需生成文本，而不需要等到整个文本都生成完毕。这对于处理大型文本生成任务来说非常有用，因为它可以降低内存占用和网络带宽使用，并且可以更快地获得部分结果。

参数 frequency_penalty

参数frequency_penalty可以在生成文本时控制模型是否应该生成高频词汇。

下面我们用例子来测试不同取值的结果：

import openai
openai.api_key = secrets["api_key"]

prompt = "The quick brown"
response = openai.Completion.create(
    engine="text-davinci-002",
    prompt=prompt,
    max_tokens=20,
    temperature=0.7,
    frequency_penalty=1 # 我们这里测试分别取值 0 、0.5 、 1 三个情况
)

text = response.choices[0].text
print(text)

输出结果

• frequency_penalty 参数被设置为0， ，表示完全忽略单词的出现频率。这将导致模型更有可能生成一些常见的单词。输出结果： fox jumped over the lazy dog.
• frequency_penalty参数被设置为0.5，表示模型更有可能避免生成常见的单词。输出结果： fox was running across the forest.
• frequency_penalty 参数被设置为1，表示模型完全避免生成常见的单词。输出结果： dog was running across the field.

这个例子中的生成结果中避免了常见的单词"quick"和"brown"。这可能会使生成的文本更加多样化，但也可能导致生成的文本难以理解或不符合预期。

参数 presence_penalty

表示惩罚那些在生成文本中频繁出现的单词或短语。

它跟frequency_penalty的区别如下：

	frequency_penalty	presence_penalty
适用范围	表示惩罚那些在训练数据中出现频率较高的单词或短语。	表示惩罚那些在生成文本中频繁出现的单词或短语。
设置高的值时	当frequency_penalty设置为较高的值时，生成文本会更加多样化，避免出现过于常见的单词或短语。	当presence_penalty设置为较高的值时，生成文本会更加多样化，避免出现重复的内容。
设置低的值时	当frequency_penalty设置为较低的值时，生成文本可能会出现更多的常见单词或短语。	而当presence_penalty设置为较低的值时，生成文本可能会出现更多的重复内容。

我们使用OpenAI Completion API生成了一段长度为200的文本，这段文本是根据“我想写一篇关于一个鬼屋的故事”的前缀自动生成的。我们将presence_penalty和frequency_penalty参数都设置为0.6，这意味着我们想要生成的文本不会出现过于频繁或者过于常见的单词或短语。

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "I want to generate a story about a haunted house."
model = "text-davinci-002"
presence_penalty = 0.6
frequency_penalty = 0.6
temperature = 0.7

response = openai.Completion.create(
    engine=model,
    prompt=prompt,
    max_tokens=200,
    n=1,
    presence_penalty=presence_penalty,
    frequency_penalty=frequency_penalty,
    temperature=temperature
)

print(response.choices[0].text)

最终，我们得到了以下输出结果：

The old house on the hill had always been shrouded in mystery. Its dark, looming presence seemed to cast a shadow over the entire town, and nobody ever dared to venture inside. But one Halloween night, a group of teenagers decided to take the ultimate risk and explore the haunted house.

As they approached the front door, they could hear strange noises coming from inside. The creaking of floorboards, the rustling of curtains, and the howling of the wind all seemed to blend together in an eerie symphony. But the teenagers were determined to uncover the secrets of the haunted house, so they pushed open the door and stepped inside.

As they made their way through the dark, cobweb-covered corridors, they encountered all sorts of spooky sights. Ghostly apparitions floated through the air, strange symbols were etched into the walls, and a faint, otherworldly glow emanated from every corner. But the teenagers pressed on, driven by curiosity and a thirst for adventure.

Finally, they reached the heart of the haunted house:

在OpenAI Completion API中，presence_penalty和frequency_penalty参数的取值范围均为0到1之间的实数。当参数值越高时，惩罚力度就越大，生成文本的多样性也就越高；当参数值越低时，惩罚力度就越小，生成文本的多样性也就越低。一般来说，推荐使用默认值（即0）或者接近默认值的参数值，以保证生成的文本质量和多样性的平衡。

参数 stop

stop参数用于指定在生成文本时停止生成的条件，当生成文本中包含指定的字符串或达到指定的最大生成长度时，生成过程会自动停止。

下面是一个使用stop参数的例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The meaning of life is"
completions = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=1,
    stop=["."],
)

message = completions.choices[0].text.strip()
print(message)

在这个例子中，stop=["."]告诉生成器当生成的文本中包含句号时停止生成，生成器会在生成文本中第一次出现句号的位置停止。

当stop参数包含多个值时，只要满足其中任意一个条件，生成器就会停止生成。

除了字符串之外，stop参数还可以接受一个整数，表示生成文本的最大长度。例如，stop=100表示当生成文本的长度达到100个token时停止生成。

参数 logprobs

logprobs参数用于返回每个生成token的概率值（log-softmax）和其对应的token。

下面是一个使用logprobs参数的例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The meaning of life is"
completions = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=1,
    logprobs=10,
)

text = completions.choices[0].text.strip()
logprobs = completions.choices[0].logprobs.token_logprobs
tokens = logprobs.keys()
probs = logprobs.values()

for token, prob in zip(tokens, probs):
    print(f"Token: {token}, Log Probability: {prob}")

在这个例子中，logprobs=10告诉生成器返回生成文本中前10个token的概率值和对应的token。

logprobs返回的结果是一个字典，其中每个键表示一个token，每个值表示该token的log概率值。

通过使用logprobs参数，可以更加细致地控制文本生成过程，例如可以根据每个token的概率值来选择生成文本的下一个token，或者对生成文本的可解释性进行分析等。

参数 echo

echo参数用于将输入的prompt文本作为生成结果的一部分返回，这可以用于将输入的上下文与生成的文本结果组合在一起，增强文本的可读性和可解释性。

下面是一个使用echo参数的例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The meaning of life is"
completions = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=1,
    echo=True,
)

text = completions.choices[0].text.strip()
echo = completions.choices[0].echo

print(f"Generated Text: {text}")
print(f"Input Prompt: {echo}")

在这个例子中，echo=True告诉生成器将输入的prompt文本作为生成结果的一部分返回。echo返回的结果是一个字符串，表示输入的prompt文本。

通过使用echo参数，可以将生成的文本结果与输入的上下文结合在一起，增强文本的可读性和可解释性。例如，当生成的文本用于回答问题时，将输入的问题作为生成结果的一部分返回，可以让用户更加清楚地理解回答的内容与输入问题之间的关系。

根据 OpenAI API 的定价规则，使用 echo 参数不会产生额外的费用。也就是说，在使用 OpenAI 的 Completions API 时，将 echo 参数设置为 True 不会增加 API 调用的计费成本。

参数 logit_bias

logit_bias参数用于对生成器的输出结果进行偏置，以使生成的文本更加符合特定的条件或偏好。

具体来说，该参数将文本生成器的输出偏向于某些给定的单词或短语，从而使生成文本更加贴合这些条件。

下面是一个使用logit_bias参数的例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The meaning of life is"
completions = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=1,
    logit_bias={"life": 10, "love": 5},
)

text = completions.choices[0].text.strip()

print(f"Generated Text: {text}")

在这个例子中，logit_bias参数指定了两个单词和对应的偏置值。其中，"life": 10表示对“life”这个词进行10个单位的偏置，"love": 5表示对“love”这个词进行5个单位的偏置。

通过使用logit_bias参数，可以对生成的文本结果进行精细调整，从而更好地满足特定的需求或条件。例如，当需要生成与“生命”或“爱情”相关的文本时，可以使用logit_bias参数来使生成的文本更加倾向于这些主题，从而增加文本的相关性和准确性。

需要注意的是，logit_bias参数需要使用正确的权重值来指定偏置。过高或过低的权重值可能会导致生成的文本不符合预期或不自然。在使用logit_bias参数时，建议对权重值进行适当的调整和测试，以达到最佳的效果。

参数 user

user参数用于指定一个用户 ID，以使 API 可以根据用户的历史数据和偏好来生成文本。

下面是一个使用user参数的例子：

import openai
openai.api_key = "YOUR_API_KEY"

prompt = "The meaning of life is"
completions = openai.Completion.create(
    engine="davinci",
    prompt=prompt,
    max_tokens=50,
    n=1,
    user="user-123",
)

text = completions.choices[0].text.strip()

print(f"Generated Text: {text}")

在这个例子中，user参数指定了一个用户 ID 为“user-123”。这意味着生成器将根据这个用户的历史数据和偏好来生成文本，从而使生成文本更加符合用户的需求和偏好。

通过使用user参数，可以使生成的文本更加个性化和针对性，从而更好地满足用户的需求和期望。例如，当需要为某个特定用户生成文本时，可以使用该参数来使生成的文本更加符合该用户的个性、爱好和口味，从而增加用户的满意度和参与度。

需要注意的是，user参数需要在用户的历史数据和偏好已经存储到 OpenAI 平台上后才能使用。如果用户是第一次使用 OpenAI 的服务，那么该参数可能会无效，因为系统还没有足够的数据来为其生成个性化的文本。

总结

以上每个例子绝大多数是通过下面的Prompt在ChatGPT上获得，并适当调整的。

请给个OpenAI的completions接口参数***使用的例子，并解释

请给个OpenAI的completions接口参数 presence_penalty 和 frequency_penalty 这两个参数有啥区别？请用例子和输出结果来解释。

OpenAI的completions接口提供了高质量的自然语言处理服务，是通用人工智能的最基础文本处理服务，可以提高客户的生产力和改善客户的体验。