[智能体-99]：openAI API参数全解

下面以最新 Chat Completions APIv1/2026为核心把所有参数按「必填→核心生成控制→采样→惩罚→格式 / 工具→高级 / 推理→流式→多模态→废弃」分组逐条讲清作用、取值范围、默认值、典型用法与避坑。基于 OpenAI 官方文档 2026‑05 最新实践含 gpt‑4o/4o‑mini/3.5‑turbo 通用参数一、必选参数缺一不可1.model字符串作用指定模型版本常用值gpt-4o最新多模态最强gpt-4o-mini轻量、低成本、快gpt-4-turbo长上下文 128kgpt-3.5-turbo性价比之王示例model: gpt-4o2.messages数组作用对话历史 / 输入上下文结构每一条是{role: ..., content: ...}rolesystem人设、user用户、assistant历史回复content文本 / 多模态内容图文混合示例jsonmessages: [ {role: system, content: 你是资深架构师}, {role: user, content: 解释一下混合AI} ]二、核心生成控制最常用3.max_completion_tokens整数推荐作用最大输出 token 数含思考 可见输出范围1模型上限如 gpt‑4o 128k默认无上限受模型总上下文限制替代旧参数max_tokens已逐步废弃场景控长度、防超长、控成本示例max_completion_tokens: 10244.n整数作用生成n 个独立候选回复范围116默认1计费按所有 n 的总 token 计费场景多方案对比、创意发散示例n: 35.stream布尔作用流式输出SSE逐字返回默认false一次性返回完整结果场景聊天界面实时打字、降低感知延迟配合stream_options见下文示例stream: true6.stop字符串 / 数组作用遇到指定停止符立即终止生成示例stop: [\n\n, ###]场景固定格式生成如 JSON、Markdown 区块三、采样策略控制 “创造性”二选一即可7.temperature浮点数作用随机性 / 发散度范围0.02.0默认1.00.0最确定、最保守、重复度高适合代码 / 数学0.7平衡日常对话1.5最发散、创意、不稳定写诗 / 故事最佳实践temperature 与 top_p只调一个8.top_p浮点数Nucleus Sampling作用按概率累积采样只从前 p% 概率的 token 里选范围0.01.0默认1.0全概率示例top_p0.9→ 只从累计概率前 90% 的候选里选特点比 temperature 更 “智能”保留高质量候选9.top_k整数部分模型支持作用只从概率最高的 k 个 token里选范围1100默认无限制场景极端控发散少用四、重复度惩罚防啰嗦 / 重复10.presence_penalty浮点数作用惩罚出现过的 token鼓励引入新话题范围-2.02.0默认0正数抑制重复、鼓励拓展负数鼓励重复、保守场景长对话、避免循环11.frequency_penalty浮点数作用按出现频率惩罚抑制高频词重复范围-2.02.0默认0区别presence 是否出现过frequency 出现次数场景文案写作、避免用词单调五、格式与工具调用结构化输出 / 函数调用12.response_format对象作用强制输出格式JSON / 文本类型{type: text}默认{type: json_object}强制合法 JSON示例jsonresponse_format: {type: json_object}场景API 交互、结构化数据抽取13.tools数组作用函数调用 / 工具能力联网、代码、自定义工具结构JSON Schema 描述工具示例jsontools: [ { type: function, function: { name: search, description: 联网搜索, parameters: {query: {type: string}} } } ]14.tool_choice字符串 / 对象作用强制 / 自动选择工具可选auto默认、none、{type:function,function:{name:xxx}}六、高级 / 推理模型专属gpt‑4o/5 系列15.reasoning_effort字符串推理模型专用作用思考深度控制推理算力可选low/medium/high默认medium场景复杂数学、多步骤推理 →high快答 →low16.logprobs整数作用返回每个 token 的对数概率用于置信度评估范围020示例logprobs: 5→ 每个位置返回前 5 个候选概率17.logit_bias对象作用手动干预 token 概率强制出现 / 禁止某些词格式{token_id: bias(-100~100)}示例禁止 “废话”{1234: -100}18.store布尔作用是否存储本次对话用于模型蒸馏 / 评估默认false19.metadata对象作用自定义标签用于后台筛选 / 统计示例{project: hybrid-ai, env: prod}七、流式输出配套20.stream_options对象streamtrue 时有效jsonstream_options: { include_usage: true, // 最后返回 token 用量 include_obfuscation: false }八、多模态参数gpt‑4o 专属21.modalities数组作用生成文本 / 音频示例[text, audio]22.audio对象作用音频输出参数如语音人声音色九、废弃 / 旧参数不要再用max_tokens→ 替换为max_completion_tokensbest_of→ 服务端多候选再选最优与stream不兼容废弃十、常用参数组合直接复制可用1精准 / 代码 / 数学json{ model: gpt-4o, temperature: 0.1, top_p: 0.95, max_completion_tokens: 2048, frequency_penalty: 0.2 }2创意 / 文案 / 故事json{ model: gpt-4o, temperature: 1.2, top_p: 0.9, presence_penalty: 0.5 }3结构化 JSON 输出json{ model: gpt-4o, response_format: {type: json_object}, temperature: 0.3 }十一、参数速查表精简版参数作用关键范围默认model模型选择gpt‑4o/3.5‑turbo必选messages对话上下文数组必选temperature随机性021.0top_p核采样011.0max_completion_tokens最大输出长度1128k不限n候选数1161stream流式输出true/falsefalsepresence_penalty新话题鼓励-220frequency_penalty高频抑制-220response_format输出格式text/json_objecttext