2. client.chat.completions.create 简单使用

client.chat.completions.create() 是 OpenAI Python SDK（v1.0+）中用于调用 ChatGPT 模型的核心方法。以下是该方法的 完整参数详解 和 使用示例：

---

一、基础必填参数

参数名	类型	必填	说明
model	str	✅	模型名称，如 "gpt-3.5-turbo"、"gpt-4-turbo"
messages	List[dict]	✅	对话消息列表，每条消息需包含 role 和 content（见下方消息格式）

📌 消息格式示例

messages = [
    {"role": "system", "content": "你是一个专业的翻译官"},  # 系统指令（可选）
    {"role": "user", "content": "将'Hello'翻译成中文"},    # 用户输入
    # 可包含历史消息 {"role": "assistant", "content": "你好"}
]

---

二、常用可选参数

参数名	类型	默认值	说明
max_tokens	int	inf	限制生成的最大token数（1个汉字≈1.3token）
temperature	float	1.0	控制随机性（0.0-2.0），值越低输出越确定
top_p	float	1.0	核采样概率（与temperature二选一）
n	int	1	生成几条候选回复
stop	List[str]	None	遇到指定字符串时停止生成（如 ["\n"]）
stream	bool	False	是否流式输出（逐字返回）
presence_penalty	float	0.0	惩罚重复话题（-2.0~2.0）
frequency_penalty	float	0.0	惩罚重复用词（-2.0~2.0）
seed	int	None	固定随机种子（确保相同输入输出一致）

---

三、高级参数

参数名	类型	适用场景
response_format	dict	强制返回JSON格式（如 {"type": "json_object"}）
tools / tool_choice	List	函数调用（Function Calling）
logprobs	bool	返回每个token的概率（调试用）
user	str	终端用户ID（用于滥用监控）

---

四、完整代码示例

1. 基础调用

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-3.5-turbo-0125",
    messages=[
        {"role": "system", "content": "你是一个幽默的助手"},
        {"role": "user", "content": "讲个程序员笑话"}
    ],
    max_tokens=100,
    temperature=0.7,
)
print(response.choices[0].message.content)

2. 流式输出（适合长文本）

response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[{"role": "user", "content": "用100字介绍AI"}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

3. 强制返回JSON

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "user", "content": "生成包含name和age的JSON，示例数据"}
    ],
    response_format={"type": "json_object"}  # 必须搭配system提示
)
print(response.choices[0].message.content)
# 输出示例: {"name": "张三", "age": 28}

4. 函数调用（Tools）

from openai.types.chat import ChatCompletionTool

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取城市天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"}
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "上海今天天气如何？"}],
    tools=tools,
    tool_choice="auto"  # 让模型决定是否调用函数
)
print(response.choices[0].message.tool_calls)

---

五、响应对象结构

返回的 response 包含以下关键属性：

response.id                  # 本次调用的唯一ID
response.choices[0].message  # 主要回复内容
response.usage               # token消耗统计

典型响应示例：

ChatCompletion(
    id="chatcmpl-xxx",
    choices=[
        ChatCompletionChoice(
            finish_reason="stop",
            index=0,
            message=ChatCompletionMessage(
                content="你好！我是AI助手。",
                role="assistant",
                tool_calls=None
            )
        )
    ],
    created=1710000000,
    model="gpt-3.5-turbo-0125",
    usage=CompletionUsage(
        prompt_tokens=10,
        completion_tokens=20,
        total_tokens=30
    )
)

---

六、注意事项

1. 模型兼容性
   • response_format 仅支持 gpt-3.5-turbo-0125 和 gpt-4-turbo 及以上版本
   • 函数调用需模型支持 tools 参数

2. 费用控制
   • 通过 max_tokens 限制生成长度
   • 监控 response.usage.total_tokens

3. 错误处理

   from openai import APIError
   
   try:
       response = client.chat.completions.create(...)
   except APIError as e:
       print(f"API错误: {e.status_code} - {e.message}")
   

---

掌握这些参数后，你可以精准控制AI的生成行为。建议从官方文档获取最新参数说明。