1. 创建 OpenAI Client 对象及参数说明

OpenAI 官方 SDK 采用 Client 对象 作为所有 API 调用的入口。

1.1 基本用法

from openai import OpenAI

client = OpenAI()

这是最常见的方式，SDK 会自动从环境变量中读取 OPENAI_API_KEY。

---

1.2 显式传参方式

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://api.openai.com/v1",
    timeout=30
)

参数说明

参数名	说明
api_key	OpenAI API Key，等同于鉴权凭证
base_url	API 服务地址，默认官方地址，私有化或代理时可修改
timeout	请求超时时间（秒）
default_headers	自定义请求头（如灰度标识、审计字段）
max_retries	请求失败自动重试次数

在企业或中台项目中，通常会封装 Client 为单例 Bean，统一管理。

---

2. chat.completions.create 调用及参数说明

对话模型通过 client.chat.completions.create 调用。

2.1 基础调用示例

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是一个后端开发助手"},
        {"role": "user", "content": "解释一下什么是幂等性"}
    ],
    temperature=0.7,
    max_tokens=512
)

---

2.2 核心参数详解

参数	说明
model	指定使用的模型
messages	对话上下文数组
temperature	随机性控制，值越大回答越发散
max_tokens	本次回复最大 token 数
top_p	nucleus sampling，通常与 temperature 二选一
stream	是否启用流式返回
stop	生成终止符

---

2.3 常用角色（role）说明

messages 是一个 有序数组，模型会严格按顺序理解上下文。

{
  "role": "user",
  "content": "xxx"
}

角色类型

role	作用
system	系统级指令，定义模型身份、行为边界
user	用户输入
assistant	模型历史回复（用于多轮对话）

示例：多轮对话上下文

messages = [
    {"role": "system", "content": "你是Java后端面试官"},
    {"role": "user", "content": "什么是线程池？"},
    {"role": "assistant", "content": "线程池用于复用线程..."},
    {"role": "user", "content": "说一下核心参数"}
]

关键点：

• system 并非必须，但强烈推荐
• 模型不会“记住历史”，上下文完全由 messages 决定

---

2.4 Response 对象完整结构说明

chat.completions.create 返回的是一个 结构化响应对象，而非纯字符串。

2.4.1 Response 示例结构（简化）

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "幂等性是指多次请求产生相同结果"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 18,
    "total_tokens": 50
  }
}

---

2.4.2 choices 字段

response.choices[0]

字段	说明
index	当前候选结果索引
message	模型生成的消息
finish_reason	生成结束原因

finish_reason 常见值

值	含义
stop	正常生成完成
length	达到 max_tokens
content_filter	内容被过滤

---

2.4.3 message 对象

response.choices[0].message

字段	说明
role	固定为 assistant
content	模型输出内容

获取最终文本：

text = response.choices[0].message.content

---

2.4.4 usage 字段（Token 统计）

response.usage

字段	说明
prompt_tokens	输入消耗
completion_tokens	输出消耗
total_tokens	总消耗

在计费、限流、上下文裁剪场景中非常关键。

3 两个示例：

3.1 ：

import os
from openai import OpenAI
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# 创建客户端
client = OpenAI(
    api_key=os.getenv('OPENAI_API_KEY'),
    base_url='https://api-inference.modelscope.cn/v1'
)


# 调用API - 添加 enable_thinking 参数
response = client.chat.completions.create(
    model='Qwen/Qwen3-8B',
    messages=[
        {"role": "system", "content": "你是AI助理，简要回答以下问题"},
        {"role": "user", "content": "小明有18条狗"},
        {"role": "assistant", "content": "好的"},
        {"role": "user", "content": "小明有17条猫"},
        {"role": "assistant", "content": "好的"},
        {"role": "user", "content": "小明有多少条宠物？"}
    ],
    stream=False,
    extra_body={  # ModelScope 特有的参数
        "enable_thinking": False
    }
)

# 输出结果
print("回答:", response.choices[0].message.content)
print("\n使用量统计:")
print(f"总token数: {response.usage.total_tokens}")
print(f"提示token数: {response.usage.prompt_tokens}")
print(f"完成token数: {response.usage.completion_tokens}")

3.2 多轮对话

实际开发中，应使用 LangChain 的 Memory 模块（如 ConversationBufferMemory）来智能管理上下文，而非手动拼接消息列表。它能自动处理 token 截断、对话摘要和持久化存储，避免上下文爆炸和效率问题，是生产环境的标准做法。

import os
from openai import OpenAI
from dotenv import load_dotenv

# 加载环境变量
load_dotenv()

# 创建客户端
client = OpenAI(
    api_key=os.getenv('OPENAI_API_KEY'),
    base_url='https://api-inference.modelscope.cn/v1'
)

my_message = [
    {"role": "system", "content": "你是一个Java后端面试官"}
]

while True:
    user_input = input("我：")
    my_message.append({"role": "user", "content": user_input})

    response = client.chat.completions.create(
        model="Qwen/Qwen3-8B",
        messages=my_message,
        stream=False,
        extra_body={  # ModelScope 特有的参数
            "enable_thinking": False
        }
    )

    reply = response.choices[0].message.content
    print("AI：", reply)
    print("token：",response.usage)

    my_message.append({"role": "assistant", "content": reply})