OpenAI API 参数 #
参数概览 #
Chat Completions API 提供了丰富的参数来控制模型的行为和输出。理解这些参数对于获得理想的输出结果至关重要。
text
┌─────────────────────────────────────────────────────────────┐
│ 参数分类 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 核心参数 │
│ ├── model 使用的模型 │
│ ├── messages 对话消息列表 │
│ └── stream 是否流式输出 │
│ │
│ 输出控制 │
│ ├── temperature 随机性控制 │
│ ├── top_p 核采样参数 │
│ ├── max_tokens 最大输出长度 │
│ ├── stop 停止序列 │
│ └── response_format 输出格式 │
│ │
│ 惩罚参数 │
│ ├── frequency_penalty 频率惩罚 │
│ └── presence_penalty 存在惩罚 │
│ │
│ 高级参数 │
│ ├── seed 随机种子 │
│ ├── logit_bias Token 偏置 │
│ ├── user 用户标识 │
│ └── n 生成数量 │
│ │
└─────────────────────────────────────────────────────────────┘
核心参数 #
model（模型选择） #
text
┌─────────────────────────────────────────────────────────────┐
│ model 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：指定要使用的模型 │
│ 类型：string │
│ 必填：是 │
│ │
│ 常用值： │
│ ───────────────────────────────────────────────────────── │
│ gpt-4o 最新旗舰，多模态，速度快 │
│ gpt-4o-mini 轻量级，成本低 │
│ gpt-4-turbo 强大推理能力 │
│ gpt-3.5-turbo 经济实惠 │
│ o1 深度推理 │
│ o1-mini 轻量推理 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "你好"}]
)
messages（消息列表） #
text
┌─────────────────────────────────────────────────────────────┐
│ messages 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：对话消息数组 │
│ 类型：array │
│ 必填：是 │
│ │
│ 消息格式： │
│ { │
│ "role": "system|user|assistant|tool", │
│ "content": "消息内容" │
│ } │
│ │
│ 角色说明： │
│ ───────────────────────────────────────────────────────── │
│ system 设置 AI 行为和角色 │
│ user 用户输入 │
│ assistant AI 回复 │
│ tool 工具返回结果 │
│ │
└─────────────────────────────────────────────────────────────┘
python
messages = [
{"role": "system", "content": "你是一个助手。"},
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "你好！"},
{"role": "user", "content": "今天天气如何？"}
]
stream（流式输出） #
text
┌─────────────────────────────────────────────────────────────┐
│ stream 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：是否以流式方式返回响应 │
│ 类型：boolean │
│ 默认：false │
│ │
│ true 逐块返回，实时显示 │
│ false 完整返回，等待时间长 │
│ │
│ 适用场景： │
│ ───────────────────────────────────────────────────────── │
│ true 聊天界面、实时显示、长文本 │
│ false 批处理、API 调用、短文本 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "写一个故事"}],
stream=True
)
for chunk in response:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
输出控制参数 #
temperature（温度） #
text
┌─────────────────────────────────────────────────────────────┐
│ temperature 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：控制输出的随机性 │
│ 类型：number │
│ 范围：0 - 2 │
│ 默认：1 │
│ │
│ 值的含义： │
│ ───────────────────────────────────────────────────────── │
│ 0 完全确定性，每次输出相同 │
│ 0.3 低随机性，更聚焦、更一致 │
│ 0.7 中等随机性，平衡创造性和一致性 │
│ 1.0 默认值，标准随机性 │
│ 1.5 高随机性，更有创意、更多样 │
│ 2.0 最高随机性，可能产生意外结果 │
│ │
└─────────────────────────────────────────────────────────────┘
低温度示例（确定性任务） #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "将以下英文翻译成中文：Hello World"}
],
temperature=0
)
print(response.choices[0].message.content)
高温度示例（创意任务） #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "写一个关于机器人的创意故事"}
],
temperature=1.5
)
print(response.choices[0].message.content)
温度对比 #
python
prompt = "用一个词描述春天"
for temp in [0, 0.5, 1.0, 1.5]:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": prompt}],
temperature=temp
)
print(f"temperature={temp}: {response.choices[0].message.content}")
top_p（核采样） #
text
┌─────────────────────────────────────────────────────────────┐
│ top_p 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：核采样参数，控制候选词的范围 │
│ 类型：number │
│ 范围：0 - 1 │
│ 默认：1 │
│ │
│ 原理： │
│ ───────────────────────────────────────────────────────── │
│ 模型按概率排序所有可能的下一个词 │
│ 只从累积概率达到 top_p 的词中选择 │
│ │
│ 值的含义： │
│ ───────────────────────────────────────────────────────── │
│ 0.1 只从概率最高的 10% 词中选择 │
│ 0.5 从概率最高的 50% 词中选择 │
│ 0.9 从概率最高的 90% 词中选择 │
│ 1.0 从所有词中选择（默认） │
│ │
│ 建议： │
│ ───────────────────────────────────────────────────────── │
│ 通常只调整 temperature 或 top_p 其中之一 │
│ 不要同时调整两个参数 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "写一首关于春天的诗"}
],
top_p=0.9
)
max_tokens（最大输出长度） #
text
┌─────────────────────────────────────────────────────────────┐
│ max_tokens 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：限制生成的最大 Token 数量 │
│ 类型：integer │
│ 范围：1 - 模型上下文限制 │
│ │
│ 注意事项： │
│ ───────────────────────────────────────────────────────── │
│ 这是输出 Token 的上限，不是输入 │
│ 输入 + 输出 不能超过模型上下文限制 │
│ 如果达到限制，finish_reason 会是 "length" │
│ │
│ 模型上下文限制： │
│ ───────────────────────────────────────────────────────── │
│ gpt-4o 128,000 tokens │
│ gpt-4o-mini 128,000 tokens │
│ gpt-4-turbo 128,000 tokens │
│ gpt-3.5-turbo 16,385 tokens │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "写一篇关于人工智能的长文"}
],
max_tokens=500
)
print(f"生成内容: {response.choices[0].message.content}")
print(f"结束原因: {response.choices[0].finish_reason}")
print(f"输出 Token: {response.usage.completion_tokens}")
stop（停止序列） #
text
┌─────────────────────────────────────────────────────────────┐
│ stop 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：遇到指定序列时停止生成 │
│ 类型：string 或 array │
│ 最多：4 个停止序列 │
│ │
│ 使用场景： │
│ ───────────────────────────────────────────────────────── │
│ 控制输出格式 │
│ 限制输出长度 │
│ 在特定标记处停止 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "列出三种水果，用逗号分隔"}
],
stop=["。", "\n"]
)
print(response.choices[0].message.content)
response_format（输出格式） #
text
┌─────────────────────────────────────────────────────────────┐
│ response_format 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：指定输出格式 │
│ 类型：object │
│ │
│ 可选值： │
│ ───────────────────────────────────────────────────────── │
│ {"type": "text"} 默认，普通文本 │
│ {"type": "json_object"} JSON 格式 │
│ {"type": "json_schema"} JSON Schema（结构化） │
│ │
│ 注意： │
│ ───────────────────────────────────────────────────────── │
│ 使用 json_object 时，系统提示中应要求 JSON 输出 │
│ json_schema 需要提供具体的 schema 定义 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{
"role": "system",
"content": "你是一个数据提取助手。以 JSON 格式返回结果。"
},
{
"role": "user",
"content": "提取：张三，28岁，北京"
}
],
response_format={"type": "json_object"}
)
import json
data = json.loads(response.choices[0].message.content)
print(json.dumps(data, indent=2, ensure_ascii=False))
惩罚参数 #
frequency_penalty（频率惩罚） #
text
┌─────────────────────────────────────────────────────────────┐
│ frequency_penalty 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：根据词在文本中的出现频率进行惩罚 │
│ 类型：number │
│ 范围：-2.0 - 2.0 │
│ 默认：0 │
│ │
│ 原理： │
│ ───────────────────────────────────────────────────────── │
│ 正值：降低重复词的概率 │
│ 负值：增加重复词的概率 │
│ 惩罚与词的出现次数成正比 │
│ │
│ 值的含义： │
│ ───────────────────────────────────────────────────────── │
│ -2.0 鼓励重复 │
│ 0 不惩罚（默认） │
│ 0.5 轻微惩罚重复 │
│ 1.0 中等惩罚重复 │
│ 2.0 强烈惩罚重复 │
│ │
│ 适用场景： │
│ ───────────────────────────────────────────────────────── │
│ 正值：减少重复内容，使输出更多样 │
│ 负值：需要强调某些内容时 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "写一篇关于人工智能的文章"}
],
frequency_penalty=0.8
)
presence_penalty（存在惩罚） #
text
┌─────────────────────────────────────────────────────────────┐
│ presence_penalty 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：根据词是否出现进行惩罚 │
│ 类型：number │
│ 范围：-2.0 - 2.0 │
│ 默认：0 │
│ │
│ 与 frequency_penalty 的区别： │
│ ───────────────────────────────────────────────────────── │
│ frequency_penalty：惩罚与出现次数成正比 │
│ presence_penalty：只要出现就惩罚，不关心次数 │
│ │
│ 值的含义： │
│ ───────────────────────────────────────────────────────── │
│ 正值：鼓励谈论新话题 │
│ 负值：鼓励重复已提及的内容 │
│ │
│ 适用场景： │
│ ───────────────────────────────────────────────────────── │
│ 正值：需要广泛覆盖话题时 │
│ 负值：需要深入讨论某话题时 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "讨论人工智能的各个方面"}
],
presence_penalty=0.6
)
惩罚参数组合使用 #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "写一篇关于机器学习的文章"}
],
frequency_penalty=0.5,
presence_penalty=0.5
)
高级参数 #
seed（随机种子） #
text
┌─────────────────────────────────────────────────────────────┐
│ seed 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：设置随机种子以获得可重复的输出 │
│ 类型：integer │
│ │
│ 用途： │
│ ───────────────────────────────────────────────────────── │
│ 调试和测试 │
│ 需要可重复结果的场景 │
│ │
│ 注意： │
│ ───────────────────────────────────────────────────────── │
│ 相同 seed + 相同输入 ≈ 相同输出 │
│ 但不保证完全相同（系统因素） │
│ │
└─────────────────────────────────────────────────────────────┘
python
for seed in [42, 42, 100]:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "生成一个随机数"}
],
seed=seed,
temperature=0
)
print(f"seed={seed}: {response.choices[0].message.content}")
logit_bias（Token 偏置） #
text
┌─────────────────────────────────────────────────────────────┐
│ logit_bias 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：调整特定 Token 的生成概率 │
│ 类型：object │
│ 格式：{token_id: bias_value} │
│ │
│ 偏置值范围：-100 到 100 │
│ ───────────────────────────────────────────────────────── │
│ -100 完全禁止该 Token │
│ 负值 降低该 Token 的概率 │
│ 0 无影响 │
│ 正值 增加该 Token 的概率 │
│ 100 强制选择该 Token │
│ │
│ 使用场景： │
│ ───────────────────────────────────────────────────────── │
│ 禁止某些词汇 │
│ 增加特定词汇的出现概率 │
│ │
└─────────────────────────────────────────────────────────────┘
python
import tiktoken
enc = tiktoken.encoding_for_model("gpt-4o-mini")
word = "AI"
token_id = enc.encode(word)[0]
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "什么是人工智能？"}
],
logit_bias={token_id: 5}
)
n（生成数量） #
text
┌─────────────────────────────────────────────────────────────┐
│ n 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：生成多个回复选项 │
│ 类型：integer │
│ 默认：1 │
│ │
│ 注意： │
│ ───────────────────────────────────────────────────────── │
│ 会消耗更多的 Token │
│ 返回的 choices 数组会有多个元素 │
│ │
│ 使用场景： │
│ ───────────────────────────────────────────────────────── │
│ 需要多个选项供用户选择 │
│ A/B 测试 │
│ 创意生成 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "给一个科技公司起名"}
],
n=3,
temperature=1.0
)
for i, choice in enumerate(response.choices):
print(f"选项 {i+1}: {choice.message.content}")
user（用户标识） #
text
┌─────────────────────────────────────────────────────────────┐
│ user 参数 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 描述：标识最终用户，用于监控和检测滥用 │
│ 类型：string │
│ │
│ 用途： │
│ ───────────────────────────────────────────────────────── │
│ 追踪用户行为 │
│ 检测滥用行为 │
│ 分析使用模式 │
│ │
│ 建议： │
│ ───────────────────────────────────────────────────────── │
│ 使用用户 ID 或唯一标识符 │
│ 不要使用敏感信息 │
│ │
└─────────────────────────────────────────────────────────────┘
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "你好"}
],
user="user-12345"
)
参数组合示例 #
精确模式（翻译、分类） #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "将以下文本翻译成英文：你好世界"}
],
temperature=0,
top_p=1,
frequency_penalty=0,
presence_penalty=0
)
创意模式（写作、头脑风暴） #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "写一个科幻故事的开头"}
],
temperature=1.2,
top_p=0.9,
frequency_penalty=0.5,
presence_penalty=0.5
)
平衡模式（问答、解释） #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "解释什么是机器学习"}
],
temperature=0.7,
top_p=0.9,
frequency_penalty=0.2,
presence_penalty=0.2
)
结构化输出模式 #
python
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{
"role": "system",
"content": "提取信息并以 JSON 格式返回。"
},
{
"role": "user",
"content": "张三，28岁，软件工程师，北京"
}
],
temperature=0,
response_format={"type": "json_object"}
)
参数调优建议 #
根据任务类型选择参数 #
text
┌─────────────────────────────────────────────────────────────┐
│ 任务类型参数建议 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 翻译任务 │
│ ───────────────────────────────────────────────────────── │
│ temperature: 0 │
│ top_p: 1 │
│ frequency_penalty: 0 │
│ presence_penalty: 0 │
│ │
│ 代码生成 │
│ ───────────────────────────────────────────────────────── │
│ temperature: 0 - 0.3 │
│ top_p: 0.9 │
│ frequency_penalty: 0 │
│ presence_penalty: 0 │
│ │
│ 创意写作 │
│ ───────────────────────────────────────────────────────── │
│ temperature: 0.8 - 1.2 │
│ top_p: 0.9 │
│ frequency_penalty: 0.3 - 0.5 │
│ presence_penalty: 0.3 - 0.5 │
│ │
│ 问答/解释 │
│ ───────────────────────────────────────────────────────── │
│ temperature: 0.5 - 0.7 │
│ top_p: 0.9 │
│ frequency_penalty: 0.2 │
│ presence_penalty: 0.2 │
│ │
│ 头脑风暴 │
│ ───────────────────────────────────────────────────────── │
│ temperature: 1.0 - 1.5 │
│ top_p: 0.9 │
│ frequency_penalty: 0.5 - 0.8 │
│ presence_penalty: 0.5 - 0.8 │
│ │
└─────────────────────────────────────────────────────────────┘
下一步 #
现在你已经掌握了 OpenAI API 的各种参数，接下来学习 流式响应，了解如何实现实时输出的效果！
最后更新：2026-03-29