【AI大模型第7集】大模型调用OpenAI client.chat.completions.create核心参数详解_chatcompletioncreateparams.responseformat

技术文档

文章目录

一、必填参数
- 1. `model`
- 2. `messages`
二、常用可选参数
- 1. `temperature`
- 2. `top_p`
- 3. `max_tokens`
- 4. `n`
- 5. `stop`
- 6. `stream`
- 7. `presence_penalty` / `frequency_penalty`
三、高级参数
- 1. `logit_bias`
- 2. `tool_calls` / `tool_choice`
- 3. `response_format`
- 4. `user`
- 5. `seed`
- 6. `image_url` 嵌套参数（图像分析）
四、参数 `messages` 详细介绍
- 1. `messages` 的基本结构
- 2. 角色 (`role`) 的作用
- 3. `content` 的高级用法
- 4. `messages` 的构建规则
- 5. `messages` 的内部处理机制
- 6. `messages` 的常见错误与解决方案
五、核心参数使用建议
六、示例代码
- 1. 基础调用
- 2. 流式输出
- 3. 图像分析
- 4. 工具调用
七、总结

OpenAI API 是由 OpenAI 公司开发，为 LLM 开发人员提供的一个简单接口。通过此 API 能在应用程序中方便地调用 OpenAI 提供的大模型基础能力。 OpenAI 的API协议已成为 LLM 领域的标准。

Python 是 OpenAI 的官方主要语言，OpenAI 官方提供了 Python SDK 的五大核心接口：ChatCompletion（多轮对话）、Completion（单轮文本补全）、Embedding（文本向量化）、Audio（语音识别与翻译）和 Image（图像生成与编辑）。

ChatCompletion 接口用于生成“多轮对话”的 AI 回复，是构建聊天机器人、智能助理等对话系统的核心。与传统的 Completion 接口不同，ChatCompletion 接口支持消息列表（包含角色和内容），能够保持对话上下文，多轮交互时模型可以“记住”之前的对话内容。例如，我们可以用它实现类似 ChatGPT 的聊天，或者让模型扮演某个角色进行问答。开发者可以通过设定系统消息来规定 AI 的行为，通过多轮 user/assistant 消息实现上下文相关的对话。在 SDK v1.5.0 中，通过 client.chat.completions.create() 方法调用该接口。

以下是 OpenAI client.chat.completions.create() 方法核心参数的详细介绍：

一、必填参数

1. `model`

作用：指定使用的模型名称（如 qwen-plus、gpt-4、gpt-4o 等）。
类型：字符串。
示例：
```
model=\"qwen-plus\"
```
说明：
- 模型选择需根据任务需求（如对话、图像理解、工具调用等）。
- 新模型（如 gpt-4o）支持更复杂的任务（如图像分析）。

2. `messages`

作用：对话历史及角色定义。
类型：字典列表，每个字典包含：
- role：角色类型（system、user、assistant、tool）。
- content：消息内容（或工具调用的 tool_call_id）。
- name（可选）：参与者名称。
- tool_calls（可选）：模型请求调用工具时使用。

示例：

messages = [ {\"role\": \"system\", \"content\": \"你是一个翻译官\"}, {\"role\": \"user\", \"content\": \"我喜欢学习人工智能\"}, {\"role\": \"assistant\", \"content\": \"I like studying AI.\"}]

说明：
- system 消息用于定义模型行为（如角色设定，后面会详细介绍）。
- 支持多轮对话，需包含完整历史。
- 图像分析需嵌套 image_url 字典（见下方高级参数）。

二、常用可选参数

1. `temperature`

作用：控制输出的随机性，取值范围： [0, 2)（默认值 1）。

示例：

temperature=0.7 # 适度随机temperature=0.2 # 高确定性（事实性问题）temperature=1.5 # 高创造性（故事生成）

说明：
- 值越高，输出的更随机多样；值越低，输出的更确定。
- 与 top_p 二选一，避免同时设置。

2. `top_p`

作用：核采样概率（Nucleus Sampling），控制模型输出的多样性，取值范围：（0,1.0]（默认值 1）。

示例：

top_p=0.9 # 仅考虑前90%概率的 token

说明：
- 值越高，输出的更随机多样；值越低，输出的更确定。
- 与 temperature 功能类似，但基于概率质量。

3. `max_tokens`

作用：限制生成内容的最大 token 数（默认无限制）。

示例：

max_tokens=100 # 最多生成100个 token

说明：
- 受模型上下文长度限制（如 gpt-3.5-turbo 最大 4096 tokens）。
- 超出模型限制会导致错误。

4. `n`

作用：生成多个结果的数量（默认值 1）。
示例：
```
n=3 # 生成3个不同的结果
```
说明：
- 会增加 token 消耗，需谨慎使用。

5. `stop`

作用：设置停止词，遇到即终止生成。

示例：

stop=[\"。\", \"？\"] # 遇到句号或问号时停止stop=[\"\\n\\n\"] # 遇到两行空格时停止

说明：
- 使用stop参数后，当模型生成的文本即将包含指定的字符串或token_id时，将自动停止生成。
- stop为array类型时，不可以将token_id和字符串同时作为元素输入，比如不可以指定stop为[“你好”,104307]。

6. `stream`

作用：是否启用流式传输（逐步返回结果，默认 False）。
示例：
```
stream=True # 流式返回
```
说明：
- false：模型生成完所有内容后一次性返回结果。
- true：边生成边输出，即每生成一部分内容就立即输出一个片段（chunk）。您需要实时地逐个读取这些片段以获得完整的结果。
- 适合实时应用（如聊天机器人）、需处理流式响应的逐块数据。

7. `presence_penalty` / `frequency_penalty`

作用：惩罚重复内容，用来控制模型输出的内容重复度，取值范围：[-2.0, 2.0]。

示例：

presence_penalty=1.0 # 减少重复主题frequency_penalty=0.5 # 减少重复 token

说明：
- presence_penalty：惩罚新主题的重复。
- frequency_penalty：惩罚 token 的频率。
- 正数会减少重复度，负数会增加重复度。如果参数值是正数，模型将对目前文本中已存在的Token施加一个惩罚值（惩罚值与文本出现的次数无关），减少这些Token重复出现的几率，从而减少内容重复度，增加用词多样性。

三、高级参数

1. `logit_bias`

作用：调整特定 token 的生成概率（字典形式）。

示例：

logit_bias={1234: 2.0} # 增加 token ID 1234 的权重

2. `tool_calls` / `tool_choice`

作用：调用外部工具或函数。

示例：

tool_calls=[{ \"name\": \"get_weather\", \"parameters\": {\"city\": \"string\"}, \"description\": \"获取天气信息\"}]tool_choice=\"auto\" # 默认值为 \"auto\"，表示由大模型自动决定是否调用工具。值为 \"null\" 时，则强制大模型不调用工具。

3. `response_format`

作用：强制返回特定格式（如 JSON）。

示例：

response_format={\"type\": \"json_object\"}

说明：
- 可选值：{“type”: “text”}或{“type”: “json_object”}。设置为{“type”: “json_object”}时会输出标准格式的JSON字符串。
- 如果指定该参数为{“type”: “json_object”}，您需要在 System Message 或 User Message 中指引模型输出 JSON 格式，如：“请按照json格式输出。”

4. `user`

作用：终端用户标识符（用于监测滥用行为）。
示例：
```
user=\"user_12345\"
```

5. `seed`

作用：固定随机种子（确保相同输入输出一致），取值范围：0~231−1。。
示例：
```
seed=42
```
说明：
- 设置seed参数会使文本生成过程更具有确定性，通常用于使模型每次运行的结果一致。
- 在每次模型调用时传入相同的seed值（由您指定），并保持其他参数不变，模型将尽可能返回相同的结果。

6. `image_url` 嵌套参数（图像分析）

作用：支持图像输入（需模型支持，如 gpt-4o）。

示例：

messages = [ { \"role\": \"user\", \"content\": [ {\"type\": \"text\", \"text\": \"这是第一张图片：\"}, { \"type\": \"image_url\", \"image_url\": {  \"url\": \"https://example.com/image1.jpg\",  \"detail\": \"high\" # 可选属性，控制图像清晰度 } }, {\"type\": \"text\", \"text\": \"请解析这张图。\"} ] }]

四、参数 `messages` 详细介绍

1. `messages` 的基本结构

messages 是一个字典列表（List[Dict]），每个字典表示一条消息，包含以下字段：

字段名类型是否必需说明 role 字符串必需消息的角色，可选值：
system（系统指令）
user（用户输入）
assistant（模型回复）
tool（工具调用）
tool_call（调用工具时的请求）
tool_response（调用工具后的响应） content 字符串/列表必需消息内容。如果是文本，直接传字符串；如果包含图像、音频等模态内容，传列表嵌套字典（如 {\"type\": \"image_url\", \"image_url\": {...}}）。 name 字符串可选参与者名称（如用户昵称），用于标识消息来源。 tool_call 字典可选模型请求调用工具时使用，包含工具名称和参数（见下方工具调用示例）。 tool_response 字典可选工具调用后的响应内容（如返回数据）。

2. 角色 (`role`) 的作用

system
- 作用：定义模型的行为或角色（如助手职责、语言风格、约束条件）。
- 示例：
```
{\"role\": \"system\", \"content\": \"你是一个幽默的助手，需要用俏皮话回答用户问题。\"}
```
- 适用场景：设定模型的初始行为、限制输出范围（如禁止敏感内容）、强制格式（如 JSON 输出）。
user
- 作用：用户输入的内容。
- 示例：
```
{\"role\": \"user\", \"content\": \"帮我写一首关于秋天的诗。\"}
```
- 适用场景：用户提问、指令或上下文补充。
assistant
- 作用：模型的回复内容。
- 示例：
```
{\"role\": \"assistant\", \"content\": \"秋风送爽叶纷飞，金桂飘香满园醉。\"}
```
- 适用场景：记录模型的输出，用于后续对话的上下文。

tool / tool_call / tool_response

作用：支持模型调用外部工具（如数据库查询、天气 API）。

示例：

# 模型请求调用工具{\"role\": \"assistant\", \"tool_call\": { \"name\": \"get_weather\", \"parameters\": {\"city\": \"北京\"}}}# 工具返回结果{\"role\": \"tool\", \"content\": {\"temperature\": \"20°C\", \"condition\": \"晴\"}}

3. `content` 的高级用法

文本内容

直接传字符串：

{\"role\": \"user\", \"content\": \"你好！\"}

多模态内容（图像、音频）

需使用列表嵌套字典，指定模态类型：

messages = [ { \"role\": \"user\", \"content\": [ {\"type\": \"text\", \"text\": \"这是第一张图片：\"}, { \"type\": \"image_url\", \"image_url\": {  \"url\": \"https://example.com/image.jpg\",  \"detail\": \"high\" # 控制图像解析质量（low/high） } }, {\"type\": \"text\", \"text\": \"请解析这张图。\"} ] }]

要求：模型需支持多模态功能（如 gpt-4o）。

工具调用的参数

若 role 为 assistant，且需要调用工具，需在 tool_call 中传参数：

{\"role\": \"assistant\", \"tool_call\": { \"name\": \"search_wikipedia\", \"parameters\": {\"query\": \"量子力学\"}}}

4. `messages` 的构建规则

顺序要求

对话历史必须按时间顺序排列（先 system，再 user 和 assistant 交替）。

示例：

messages = [ {\"role\": \"system\", \"content\": \"你是一个翻译官\"}, {\"role\": \"user\", \"content\": \"Hello, how are you?\"}, {\"role\": \"assistant\", \"content\": \"你好，最近怎么样？\"}, {\"role\": \"user\", \"content\": \"I\'m fine, thanks!\"}]

上下文长度限制
- 总 token 数不能超过模型的最大上下文长度（如 gpt-3.5-turbo 最大 4096 tokens）。
- 建议保留关键历史信息，避免冗余。
系统消息的特殊作用
- system 消息会直接影响模型的行为，建议在对话开始时设置。
- 示例：强制输出 JSON 格式：
```
{\"role\": \"system\", \"content\": \"请以 JSON 格式输出结果。\"}
```

5. `messages` 的内部处理机制

当 messages 列表传递给大模型时，OpenAI 的API会做如下处理：

逐条解释每条消息：每条消息由 role 和 content 组成，API会跟进 role 的类型赋予不同的权重或作用。例如：system 定义模型行为，user 是用户的输入，assistant 是模型的响应。
生成一段内部结构化数据：这些数据被编码为 token（模型可以理解的格式），并跟进顺序被输入到模型中。
保留层次化信息：比如 role 信息不会被简单的丢失，而是作为上下文的提示存在，影响生成过程。

实际上 OpenAI API 会为每条消息标记 role 和 content，例如：
- system 的内容被视为对整个对话的指导信息，模型优先根据他定义的规则回应。
- user 的内容会触发生成逻辑，模型会跟进前面的上下文回答。
- assistant 的内容用于帮助模型了解之前的对话背景，让响应更加符合用户期望。

6. `messages` 的常见错误与解决方案

错误：缺少 role 或 content
- 原因：未正确构造字典。
- 解决：确保每条消息都包含 role 和 content。
错误：tool_call 参数缺失
- 原因：模型请求调用工具时未提供 tool_call。
- 解决：在 assistant 消息中添加 tool_call 字段。
错误：多模态内容格式错误
- 原因：未按规范嵌套字典。
- 解决：参考多模态示例的结构。

五、核心参数使用建议

控制成本：
- 优先使用低价模型（如 gpt-3.5-turbo）。
- 限制 max_tokens 和 n。
优化质量：
- 事实性问题：temperature=0.2。
- 创意生成：temperature=0.8。
- 多样性需求：top_p=0.9。
流式响应：
- 实时场景启用 stream=True。
避免重复：
- 使用 presence_penalty 和 frequency_penalty。
图像分析：
- 使用 image_url 参数嵌套图像链接（需模型支持）。

六、示例代码

1. 基础调用

import osfrom openai import OpenAIclient = OpenAI( # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key=\"sk-xxx\", api_key=os.getenv(\"DASHSCOPE_API_KEY\"), base_url=\"https://dashscope.aliyuncs.com/compatible-mode/v1\",)completion = client.chat.completions.create( # 模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models model=\"qwen-plus\", messages=[ {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"}, {\"role\": \"user\", \"content\": \"你是谁？\"}, ], # Qwen3模型通过enable_thinking参数控制思考过程（开源版默认True，商业版默认False） # 使用Qwen3开源版模型时，若未启用流式输出，请将下行取消注释，否则会报错 # extra_body={\"enable_thinking\": False},)print(completion.model_dump_json())

2. 流式输出

import osfrom openai import OpenAIclient = OpenAI( # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key=\"sk-xxx\", api_key=os.getenv(\"DASHSCOPE_API_KEY\"), base_url=\"https://dashscope.aliyuncs.com/compatible-mode/v1\",)completion = client.chat.completions.create( model=\"qwen-plus\", # 此处以qwen-plus为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models messages=[{\'role\': \'system\', \'content\': \'You are a helpful assistant.\'}, {\'role\': \'user\', \'content\': \'你是谁？\'}], stream=True, stream_options={\"include_usage\": True} )for chunk in completion: print(chunk.model_dump_json())

3. 图像分析

import osfrom openai import OpenAIclient = OpenAI( # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key=\"sk-xxx\", api_key=os.getenv(\"DASHSCOPE_API_KEY\"), base_url=\"https://dashscope.aliyuncs.com/compatible-mode/v1\",)completion = client.chat.completions.create( model=\"qwen-vl-plus\", # 此处以qwen-vl-plus为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models messages=[{\"role\": \"user\",\"content\": [{\"type\": \"image_url\",\"image_url\": {\"url\": \"https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg\"}},{\"type\": \"text\",\"text\": \"这是什么\"}]}] )print(completion.model_dump_json())

4. 工具调用

import osfrom openai import OpenAIclient = OpenAI( # 若没有配置环境变量，请用百炼API Key将下行替换为：api_key=\"sk-xxx\", api_key=os.getenv(\"DASHSCOPE_API_KEY\"), base_url=\"https://dashscope.aliyuncs.com/compatible-mode/v1\", # 填写DashScope SDK的base_url)tools = [ # 工具1 获取当前时刻的时间 { \"type\": \"function\", \"function\": { \"name\": \"get_current_time\", \"description\": \"当你想知道现在的时间时非常有用。\", \"parameters\": {} # 因为获取当前时间无需输入参数，因此parameters为空字典 } }, # 工具2 获取指定城市的天气 { \"type\": \"function\", \"function\": { \"name\": \"get_current_weather\", \"description\": \"当你想查询指定城市的天气时非常有用。\", \"parameters\": {  \"type\": \"object\", \"properties\": {  # 查询天气时需要提供位置，因此参数设置为location  \"location\": { \"type\": \"string\", \"description\": \"城市或县区，比如北京市、杭州市、余杭区等。\"  } }, \"required\": [\"location\"] } } }]messages = [{\"role\": \"user\", \"content\": \"杭州天气怎么样\"}]completion = client.chat.completions.create( model=\"qwen-plus\", # 此处以qwen-plus为例，可按需更换模型名称。模型列表：https://help.aliyun.com/zh/model-studio/getting-started/models messages=messages, tools=tools)print(completion.model_dump_json())

七、总结

在实际项目中，无论你是在开发客服助手、文案生成系统、知识库搜索引擎，还是构建多模态 Agent，理解并掌握这些参数的调优技巧，是将大模型从“能跑”到“好用”的关键一步。

【AI大模型第7集】大模型调用OpenAI client.chat.completions.create核心参数详解_chatcompletioncreateparams.responseformat

文章目录

一、必填参数

1. `model`

2. `messages`

二、常用可选参数

1. `temperature`

2. `top_p`

3. `max_tokens`

4. `n`

5. `stop`

6. `stream`

7. `presence_penalty` / `frequency_penalty`

三、高级参数

1. `logit_bias`

2. `tool_calls` / `tool_choice`

3. `response_format`

4. `user`

5. `seed`

6. `image_url` 嵌套参数（图像分析）

四、参数 `messages` 详细介绍

1. `messages` 的基本结构

2. 角色 (`role`) 的作用

3. `content` 的高级用法

4. `messages` 的构建规则

5. `messages` 的内部处理机制

6. `messages` 的常见错误与解决方案

五、核心参数使用建议

六、示例代码

1. 基础调用

2. 流式输出

3. 图像分析

4. 工具调用

七、总结

公告

DeepSeek全套部署资料免费下载

免费可商用字体批量下载

标签

【AI大模型第7集】大模型调用OpenAI client.chat.completions.create核心参数详解_chatcompletioncreateparams.responseformat

文章目录

一、必填参数

1. model

2. messages

二、常用可选参数

1. temperature

2. top_p

3. max_tokens

4. n

5. stop

6. stream

7. presence_penalty / frequency_penalty

三、高级参数

1. logit_bias

2. tool_calls / tool_choice

3. response_format

4. user

5. seed

6. image_url 嵌套参数（图像分析）

四、参数 messages 详细介绍

1. messages 的基本结构

2. 角色 (role) 的作用

3. content 的高级用法

4. messages 的构建规则

5. messages 的内部处理机制

6. messages 的常见错误与解决方案

五、核心参数使用建议

六、示例代码

1. 基础调用

2. 流式输出

3. 图像分析

4. 工具调用

七、总结

相关问题

公告

DeepSeek全套部署资料免费下载

免费可商用字体批量下载

标签

1. `model`

2. `messages`

1. `temperature`

2. `top_p`

3. `max_tokens`

4. `n`

5. `stop`

6. `stream`

7. `presence_penalty` / `frequency_penalty`

1. `logit_bias`

2. `tool_calls` / `tool_choice`

3. `response_format`

4. `user`

5. `seed`

6. `image_url` 嵌套参数（图像分析）

四、参数 `messages` 详细介绍

1. `messages` 的基本结构

2. 角色 (`role`) 的作用

3. `content` 的高级用法

4. `messages` 的构建规则

5. `messages` 的内部处理机制

6. `messages` 的常见错误与解决方案