当前位置：首页 > news >正文

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

news 来源：原创 2025/4/30 7:52:57

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
    )
)

六、注意事项

模型兼容性
• response_format 仅支持 gpt-3.5-turbo-0125 和 gpt-4-turbo 及以上版本
• 函数调用需模型支持 tools 参数
费用控制
• 通过 max_tokens 限制生成长度
• 监控 response.usage.total_tokens

错误处理

from openai import APIError

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