Openai 参数调用

一、核心参数（几乎必填）

参数	类型	必填	说明
Model	string	✅	模型名称，如 "gpt-4o"、"deepseek-v4-flash"
Messages	[]ChatCompletionMessage	✅	对话消息列表，包含 Role（system/user/assistant/tool）和 Content
Stream	bool		true 逐 token 输出（打字机效果），false 一次性返回完整结果

Messages 的四种 Role

Role	用途	示例
system	设定 AI 的行为、角色、规则	“你是一个 SQL 助手”
user	用户输入	“帮我写个查询”
assistant	AI 的回复（多轮对话时需要把历史回答放进来）	上一轮的回复内容；或 tool_calls 表示要调用工具
tool	工具调用的返回结果	{"tables": [...]}，须配合 tool_call_id

---

二、生成控制参数

参数	类型	默认值	说明
Temperature	float32	1	随机性。0~2，越低越确定，越高越有创意。⚠ 与 TopP 不要同时设
TopP	float32	1	核采样。只考虑概率累积到 TopP 的 token。0~1。是 Temperature 的替代方案
MaxTokens	int	-	输出最大 token 数（旧版参数）
MaxCompletionTokens	int	-	输出最大 token 数（新版，推荐用这个）
N	int	1	生成 N 个候选回复（一次请求返回多条答案）
Stop	[]string	-	停止词。输出碰到这些字符串立刻停，最多设 4 个
Seed	*int	-	随机种子。相同 seed + 相同参数 → 可复现输出

三、输出格式控制

参数	类型	说明
ResponseFormat	*ChatCompletionResponseFormat	控制输出格式： {"type": "text"} — 普通文本 {"type": "json_object"} — 强制 JSON {"type": "json_schema", "json_schema": {...}} — 按 Schema 输出

// 示例：按指定 Schema 输出
ResponseFormat: &openai.ChatCompletionResponseFormat{
    Type: openai.ChatCompletionResponseFormatTypeJSONSchema,
    JSONSchema: &openai.ChatCompletionResponseFormatJSONSchema{
        Name: "user_info",
        Strict: true,
        Schema: jsonSchema{...},
    },
}

四、重复度控制

参数	类型	范围	说明
PresencePenalty	float32	-2 ~ 2	话题新颖性惩罚。值越高越倾向于聊新话题
FrequencyPenalty	float32	-2 ~ 2	词汇重复度惩罚。值越高越禁用重复词汇
LogitBias	map[string]int	-100 ~ 100	Token 概率偏置。对特定 token 加权或抑制（如 -100 禁止某词出现）

五、工具/函数调用参数

参数	类型	说明
Tools	[]Tool	定义模型可调用的工具列表，每个 Tool 包含 Type(“function”) + Function(Name/Description/Parameters)
ToolChoice	特殊类型	控制工具调用行为：nil/"auto" 模型自己判断（默认）；"none" 禁用工具；"required" 强制调用；{"type":"function","function":{"name":"xxx"}} 强制调用指定工具
ParallelToolCalls	*bool	是否允许并行调用多个工具。设为 false 禁止
Functions	[]FunctionDefinition	⛔ 已废弃，用 Tools 替代
FunctionCall	-	⛔ 已废弃，用 ToolChoice 替代

ToolChoice 四种模式

nil / "auto"  →  模型自己判断要不要调工具（默认，最常用）
"none"        →  禁止调用任何工具
"required"    →  强制必须调用工具
{"type":"function","function":{"name":"xxx"}}  →  强制调用指定工具

六、流式输出选项

参数	类型	说明
StreamOptions	*StreamOptions	流式输出附加选项。IncludeUsage: true 可在流式返回中获取 token 用量

StreamOptions: &openai.StreamOptions{
    IncludeUsage: true, // 流式输出也返回 usage 统计
}

七、高级参数

参数	类型	说明
Prediction	*Prediction	预测输出。提前告知模型期望的回复内容，匹配时复用（省钱+加速），不匹配不影响结果
ReasoningEffort	string	推理力度（o 系列模型专用）。"low" / "medium" / "high"
Store	bool	是否将请求存储到 OpenAI 持久化存储中
ServiceTier	string	服务层级。"default" 或 "flex"（flex 更便宜但可能排队）
Verbosity	string	输出详细度。"low" / "medium" / "high"

八、身份与标注参数

参数	类型	说明
User	string	用户标识，用于 OpenAI 滥用检测
Metadata	map[string]string	自定义标签（最多 16 组键值对），方便后台分类筛选
SafetyIdentifier	string	安全标识符，内容审查相关

九、日志与调试参数

参数	类型	说明
LogProbs	bool	是否返回每个 token 的对数概率
TopLogProbs	int	配合 LogProbs，返回每个位置概率最高的几个 token（0~20）

十、扩展参数

参数	类型	说明
ChatTemplateKwargs	map[string]any	传给聊天模板的额外参数，针对特定开源模型
ChatCompletionRequestExtensions	struct	扩展字段，各平台/模型的自定义配置

---

快速参考：最小有效请求

resp, err := client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
    Model: "deepseek-v4-flash",
    Messages: []openai.ChatCompletionMessage{
        {Role: openai.ChatMessageRoleUser, Content: "Hello!"},
    },
})

快速参考：带工具调用的请求

resp, err := client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
    Model:  "deepseek-v4-flash",
    Messages: msgs,
    // 定义工具
    Tools: []openai.Tool{{
        Type: openai.ToolTypeFunction,
        Function: &openai.FunctionDefinition{
            Name:        "get_weather",
            Description: "获取指定城市的天气",
            Parameters:  "jsonSchema"
        }
    }},
    ToolChoice: "auto", // 默认就是 auto，不写也行
})