OpenAI Chat API 参数完整中文指南

原创

xiaoHangXu

修改于 2025-09-08 17:46:10

23410

代码可运行

运行总次数：0

代码可运行

OpenAI Chat API 参数完整中文指南

本文档详细列出了OpenAI Chat API (https://api.openai.com/v1/chat/completions) 的所有请求参数，包括必需参数、可选参数和已弃用参数。对于每个参数，我们提供了详细的中文解释、使用场景建议、最佳实践和具体代码示例。

注意：OpenAI 正在推荐新项目尝试使用 Responses 功能，以利用最新的OpenAI平台特性。您可以比较 Chat Completions 与 Responses 的区别来决定选择，最新接口请访问：https://platform.openai.com/docs/api-reference/chat/create

API 端点

POST https://api.openai.com/v1/chat/completions

该API创建一个针对给定聊天对话的模型响应。参数支持可能因用于生成响应的模型而异，特别是对于较新的推理模型。下面特别注明了仅适用于推理模型的参数。

必需参数 (Required Parameters)

messages

类型: array
必需: 是
描述: 构成到目前为止对话的消息列表。根据使用的模型，支持不同的消息类型（模态），如文本、图像和音频。

基本文本对话示例

import openai

# 基本对话
messages = [
    {"role": "system", "content": "你是一个有用的AI助手。"},
    {"role": "user", "content": "你好，请介绍一下自己。"}
]

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=messages
)

多轮对话示例

# 多轮对话历史
messages = [
    {"role": "system", "content": "你是一个Python编程专家。"},
    {"role": "user", "content": "如何创建一个列表？"},
    {"role": "assistant", "content": "在Python中，你可以使用方括号[]来创建列表，例如：my_list = [1, 2, 3]"},
    {"role": "user", "content": "如何向列表添加元素？"}
]

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=messages
)

多模态输入示例（图像）

# 包含图像的消息
messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图片里有什么？"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://example.com/image.jpg"
                }
            }
        ]
    }
]

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=messages
)

model

类型: string
必需: 是
描述: 用于生成响应的模型ID，例如 gpt-4o 或 o3。OpenAI提供各种具有不同功能、性能特征和价格点的模型。

不同模型选择示例

# 使用GPT-4o进行复杂任务
response_gpt4 = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释量子计算的基本原理"}]
)

# 使用GPT-3.5-turbo进行简单任务
response_gpt35 = openai.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "今天天气怎么样？"}]
)

# 使用推理模型o3
response_o3 = openai.chat.completions.create(
    model="o3",
    messages=[{"role": "user", "content": "解决这个数学问题：2x + 5 = 15"}],
    reasoning_effort="high"  # 推理模型特有参数
)

可选参数 (Optional Parameters) <a id="可选参数-optional-parameters"></a>

audio

类型: object 或 null
默认值: 无
描述: 音频输出的参数。当请求音频输出且 modalities 包含 ["audio"] 时必需。

音频输出示例

# 生成音频响应
response = openai.chat.completions.create(
    model="gpt-4o-audio-preview",
    messages=[{"role": "user", "content": "请用温和的语调说'你好'"}],
    modalities=["text", "audio"],
    audio={
        "voice": "alloy",
        "format": "wav"
    }
)

frequency_penalty

类型: number 或 null
默认值: 0
范围: -2.0 到 2.0
描述: 正值会根据新生成的 token 在文本中的现有频率来惩罚它们，降低模型逐字重复同一行的可能性。

频率惩罚示例

# 创意写作 - 增加词汇多样性
creative_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一首关于春天的诗"}],
    frequency_penalty=0.7,  # 减少重复词汇
    temperature=0.8
)

# 技术文档 - 保持术语一致性
technical_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释API的工作原理"}],
    frequency_penalty=0.1,  # 允许技术术语重复
    temperature=0.3
)

# 解决重复问题
no_repeat_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "列出10个不同的编程语言"}],
    frequency_penalty=1.0  # 强烈避免重复
)

logit_bias

类型: map
默认值: null
范围: -100 到 100
描述: 修改指定 token 出现在完成中的可能性。

Token偏置示例

# 阻止特定词汇（假设token ID 50256代表某个不想要的词）
response_blocked = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个故事"}],
    logit_bias={"50256": -100}  # 完全阻止特定token
)

# 鼓励使用特定词汇
response_encouraged = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "描述一个产品"}],
    logit_bias={"12345": 50}  # 鼓励使用特定token
)

# 多个token控制
response_multi_bias = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一段代码"}],
    logit_bias={
        "1234": 20,   # 鼓励
        "5678": -50,  # 抑制
        "9012": -100  # 禁止
    }
)

logprobs

类型: boolean 或 null
默认值: false
描述: 是否返回输出 token 的对数概率。

对数概率示例

# 获取token概率信息
response_with_logprobs = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "天空是什么颜色？"}],
    logprobs=True,
    top_logprobs=5  # 返回每个位置前5个最可能的token
)

# 分析模型确定性
def analyze_model_confidence(response):
    if response.choices[0].logprobs:
        for token_info in response.choices[0].logprobs.content:
            print(f"Token: {token_info.token}")
            print(f"概率: {token_info.logprob}")
            print(f"前5个候选: {token_info.top_logprobs}")
            print("---")

analyze_model_confidence(response_with_logprobs)

max_completion_tokens

类型: integer 或 null
默认值: 无
描述: 可以为完成生成的 token 数量的上限，包括可见输出 token 和推理 token。

控制输出长度示例

# 短回复
short_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "简单解释什么是AI"}],
    max_completion_tokens=50
)

# 中等长度回复
medium_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "详细解释机器学习"}],
    max_completion_tokens=200
)

# 推理模型的token控制
reasoning_response = openai.chat.completions.create(
    model="o3",
    messages=[{"role": "user", "content": "解决复杂数学问题"}],
    max_completion_tokens=500,  # 包括推理token
    reasoning_effort="high"
)

metadata

类型: map
默认值: 无
限制: 最多16个键值对，键最长64字符，值最长512字符
描述: 可以附加到对象的键值对集合。

元数据示例

# 添加业务元数据
response_with_metadata = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "帮我写邮件"}],
    metadata={
        "user_id": "user_12345",
        "session_id": "session_abc789",
        "feature": "email_assistant",
        "version": "v1.2.0",
        "department": "marketing"
    }
)

# 用于A/B测试的元数据
ab_test_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "推荐产品"}],
    metadata={
        "experiment": "recommendation_v2",
        "variant": "control_group",
        "timestamp": "2024-01-15T10:30:00Z"
    }
)

modalities

类型: array 或 null
默认值: ["text"]
描述: 您希望模型生成的输出类型。

多模态输出示例

# 仅文本输出（默认）
text_only = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释概念"}],
    modalities=["text"]
)

# 文本和音频输出
text_audio = openai.chat.completions.create(
    model="gpt-4o-audio-preview",
    messages=[{"role": "user", "content": "朗读这段文字"}],
    modalities=["text", "audio"],
    audio={"voice": "nova"}
)

n

类型: integer 或 null
默认值: 1
描述: 为每个输入消息生成多少个聊天完成选项。

多选项生成示例

# 生成多个响应选项
multiple_responses = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "给我一个创意的产品名称"}],
    n=3,  # 生成3个不同的选项
    temperature=0.8
)

# 处理多个选项
for i, choice in enumerate(multiple_responses.choices):
    print(f"选项 {i+1}: {choice.message.content}")

# A/B测试不同响应
ab_test_responses = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个营销标语"}],
    n=5,
    temperature=0.7
)

parallel_tool_calls

类型: boolean
默认值: true
描述: 在工具使用期间是否启用并行函数调用。

并行工具调用示例

# 定义多个工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "城市名称"}
                },
                "required": ["location"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_news",
            "description": "获取新闻信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "category": {"type": "string", "description": "新闻类别"}
                },
                "required": ["category"]
            }
        }
    }
]

# 启用并行调用
parallel_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "请同时获取北京的天气和科技新闻"}],
    tools=tools,
    parallel_tool_calls=True  # 允许同时调用多个工具
)

# 禁用并行调用（串行执行）
serial_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "请获取天气然后获取新闻"}],
    tools=tools,
    parallel_tool_calls=False  # 工具将按顺序调用
)

prediction

类型: object
默认值: 无
描述: 预测输出的配置，当模型响应的大部分内容已知时，可以大大提高响应时间。

预测输出示例

# 文档编辑场景
prediction_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "请修改这个文档的第二段"}],
    prediction={
        "type": "content",
        "content": "这是一个关于AI的文档。[需要修改的段落]。这是结论部分。"
    }
)

# 代码补全场景
code_prediction = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "完成这个Python函数"}],
    prediction={
        "type": "content",
        "content": "def calculate_sum(a, b):\n    # 需要补全的部分\n    return result"
    }
)

presence_penalty

类型: number 或 null
默认值: 0
范围: -2.0 到 2.0
描述: 正值会根据新生成的token是否出现在文本中来惩罚它们，增加模型谈论新主题的可能性。

存在惩罚示例

# 鼓励探索新主题
new_topics_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一篇关于技术创新的文章"}],
    presence_penalty=0.8,  # 鼓励谈论新主题
    temperature=0.7
)

# 保持主题一致性
consistent_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "深入分析机器学习算法"}],
    presence_penalty=-0.3,  # 鼓励继续讨论相关主题
    temperature=0.5
)

# 创意写作中的主题多样性
creative_diversity = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个包含多个情节线的故事"}],
    presence_penalty=1.0,  # 最大化主题多样性
    frequency_penalty=0.5,  # 同时减少词汇重复
    temperature=0.8
)

prompt_cache_key

类型: string
默认值: 无
描述: OpenAI用于缓存类似请求的响应以优化缓存命中率。取代user字段。

缓存优化示例

# 使用缓存键优化性能
cached_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释Python基础语法"}],
    prompt_cache_key="python_basics_tutorial"
)

# 为不同用户组使用不同缓存键
def get_cached_response(user_type, content):
    cache_key = f"{user_type}_common_query"
    return openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": content}],
        prompt_cache_key=cache_key
    )

# 使用示例
beginner_response = get_cached_response("beginner", "什么是编程？")
advanced_response = get_cached_response("advanced", "解释设计模式")

reasoning_effort

类型: string 或 null
默认值: medium
描述: 约束推理模型在推理上的努力。目前支持的值有minimal、low、medium和high。
注意: 仅适用于推理模型（如o3和o4-mini）

推理努力示例

# 简单任务使用最小推理
simple_task = openai.chat.completions.create(
    model="o3",
    messages=[{"role": "user", "content": "2 + 2 等于多少？"}],
    reasoning_effort="minimal"  # 快速简单计算
)

# 复杂数学问题使用高推理
complex_math = openai.chat.completions.create(
    model="o3",
    messages=[{"role": "user", "content": "证明勾股定理"}],
    reasoning_effort="high"  # 需要详细推理过程
)

# 中等复杂度问题
medium_task = openai.chat.completions.create(
    model="o3",
    messages=[{"role": "user", "content": "分析这个商业案例的优缺点"}],
    reasoning_effort="medium"  # 平衡速度和质量
)

# 根据问题复杂度动态调整
def adaptive_reasoning(question, complexity_level):
    effort_mapping = {
        "simple": "minimal",
        "moderate": "low", 
        "complex": "medium",
        "very_complex": "high"
    }
    
    return openai.chat.completions.create(
        model="o3",
        messages=[{"role": "user", "content": question}],
        reasoning_effort=effort_mapping.get(complexity_level, "medium")
    )

response_format

类型: object
默认值: 无
描述: 指定模型必须输出的格式的对象。

结构化输出示例

# JSON对象格式
json_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "分析这个产品的特点"}],
    response_format={"type": "json_object"}
)

# JSON Schema格式（结构化输出）
schema_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "创建一个用户配置文件"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "user_profile",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "email": {"type": "string", "format": "email"},
                    "preferences": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["name", "email"]
            }
        }
    }
)

# 复杂数据结构示例
complex_schema = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "生成一个产品目录"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "product_catalog",
            "schema": {
                "type": "object",
                "properties": {
                    "products": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {"type": "string"},
                                "name": {"type": "string"},
                                "price": {"type": "number"},
                                "category": {"type": "string"},
                                "tags": {
                                    "type": "array",
                                    "items": {"type": "string"}
                                }
                            },
                            "required": ["id", "name", "price"]
                        }
                    }
                },
                "required": ["products"]
            }
        }
    }
)

safety_identifier

类型: string
默认值: 无
描述: 用于帮助检测可能违反OpenAI使用政策的应用程序用户的稳定标识符。

安全标识符示例

import hashlib

# 创建用户安全标识符
def create_safety_identifier(user_email):
    # 使用哈希保护用户隐私
    return hashlib.sha256(user_email.encode()).hexdigest()

# 使用安全标识符
user_email = "user@example.com"
safety_id = create_safety_identifier(user_email)

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "帮我写一篇文章"}],
    safety_identifier=safety_id
)

# 为不同应用场景创建标识符
class SafetyIdentifierManager:
    def __init__(self, app_name):
        self.app_name = app_name
    
    def create_identifier(self, user_id, session_id=None):
        base_string = f"{self.app_name}:{user_id}"
        if session_id:
            base_string += f":{session_id}"
        return hashlib.sha256(base_string.encode()).hexdigest()[:16]

# 使用示例
safety_manager = SafetyIdentifierManager("my_chat_app")
user_safety_id = safety_manager.create_identifier("user123", "session456")

safe_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "创建内容"}],
    safety_identifier=user_safety_id
)

service_tier

类型: string 或 null
默认值: auto
描述: 指定用于处理请求的处理类型。

服务层级示例

# 优先处理（低延迟）
priority_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "紧急：需要快速回复"}],
    service_tier="priority"
)

# 标准处理
standard_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "常规查询"}],
    service_tier="default"
)

# 灵活处理
flex_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "非紧急查询"}],
    service_tier="flex"
)

# 自动选择（推荐）
auto_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "普通查询"}],
    service_tier="auto"  # 让OpenAI根据项目设置自动选择
)

# 根据应用场景选择服务层级
def get_service_tier(urgency_level):
    tier_mapping = {
        "critical": "priority",
        "high": "default", 
        "normal": "auto",
        "low": "flex"
    }
    return tier_mapping.get(urgency_level, "auto")

# 使用示例
urgent_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "处理紧急情况"}],
    service_tier=get_service_tier("critical")
)

stop

类型: string / array / null
默认值: null
描述: 最多4个序列，API将在遇到这些序列时停止生成进一步的token。
注意: 不支持最新的推理模型o3和o4-mini

停止序列示例

# 单个停止词
single_stop = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "列出编程语言"}],
    stop="。"  # 在句号处停止
)

# 多个停止序列
multiple_stops = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个故事"}],
    stop=["结束", "完", "END", "\n\n"]  # 在任何这些序列处停止
)

# 格式化输出控制
formatted_output = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "生成代码示例"}],
    stop=["```", "---"]  # 在代码块或分隔符处停止
)

# 对话轮次控制
conversation_control = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "开始对话"}],
    stop=["用户:", "User:", "Q:"]  # 在下一个问题开始前停止
)

# 动态停止序列
def create_stop_sequences(content_type):
    stop_mapping = {
        "code": ["```", "---", "END"],
        "list": ["总结", "结论", "最后"],
        "story": ["结束", "完", "THE END"],
        "qa": ["下一个问题", "Q:", "问题:"]
    }
    return stop_mapping.get(content_type, None)

# 使用动态停止序列
code_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个Python函数"}],
    stop=create_stop_sequences("code")
)

store

类型: boolean 或 null
默认值: false
描述: 是否存储此聊天完成请求的输出，以用于模型蒸馏或评估产品。

数据存储示例

# 允许数据存储用于模型改进
store_enabled = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "这是非敏感的测试内容"}],
    store=True  # 允许OpenAI存储用于改进
)

# 禁用数据存储（敏感内容）
store_disabled = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "这是敏感的商业信息"}],
    store=False  # 不存储敏感数据
)

# 根据内容类型决定是否存储
def should_store_data(content_type, is_sensitive=False):
    if is_sensitive:
        return False
    
    # 非敏感的教育或测试内容可以存储
    allowed_types = ["educational", "testing", "examples"]
    return content_type in allowed_types

# 使用示例
educational_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释编程概念"}],
    store=should_store_data("educational", is_sensitive=False)
)

sensitive_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "分析公司财务数据"}],
    store=should_store_data("business", is_sensitive=True)
)

stream

类型: boolean 或 null
默认值: false
描述: 如果设置为true，模型响应数据将使用服务器发送事件流式传输到客户端。

流式响应示例

# 基本流式响应
def stream_response():
    stream = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "写一个长故事"}],
        stream=True
    )
    
    for chunk in stream:
        if chunk.choices[0].delta.content is not None:
            print(chunk.choices[0].delta.content, end="")

# 带错误处理的流式响应
def safe_stream_response():
    try:
        stream = openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "解释复杂概念"}],
            stream=True,
            stream_options={"include_usage": True}
        )
        
        full_response = ""
        for chunk in stream:
            if chunk.choices[0].delta.content is not None:
                content = chunk.choices[0].delta.content
                full_response += content
                print(content, end="", flush=True)
            
            # 检查是否完成
            if chunk.choices[0].finish_reason is not None:
                print(f"\n完成原因: {chunk.choices[0].finish_reason}")
                break
                
        return full_response
        
    except Exception as e:
        print(f"流式响应错误: {e}")
        return None

# 实时聊天应用示例
class StreamingChatBot:
    def __init__(self):
        self.conversation_history = []
    
    def add_message(self, role, content):
        self.conversation_history.append({"role": role, "content": content})
    
    def get_streaming_response(self, user_input):
        self.add_message("user", user_input)
        
        stream = openai.chat.completions.create(
            model="gpt-4o",
            messages=self.conversation_history,
            stream=True,
            temperature=0.7
        )
        
        assistant_response = ""
        for chunk in stream:
            if chunk.choices[0].delta.content is not None:
                content = chunk.choices[0].delta.content
                assistant_response += content
                yield content  # 实时返回内容片段
        
        # 将完整响应添加到历史
        self.add_message("assistant", assistant_response)

# 使用流式聊天机器人
chatbot = StreamingChatBot()
for content_chunk in chatbot.get_streaming_response("你好，请介绍自己"):
    print(content_chunk, end="", flush=True)

stream_options

类型: object 或 null
默认值: null
描述: 流式响应的选项。仅当stream设置为true时才设置此项。

流式选项示例

# 包含使用统计的流式响应
stream_with_usage = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一篇文章"}],
    stream=True,
    stream_options={"include_usage": True}
)

total_tokens = 0
for chunk in stream_with_usage:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")
    
    # 检查使用统计
    if hasattr(chunk, 'usage') and chunk.usage is not None:
        total_tokens = chunk.usage.total_tokens
        print(f"\n总token使用量: {total_tokens}")

# 高级流式处理
class AdvancedStreamProcessor:
    def __init__(self):
        self.buffer = ""
        self.word_count = 0
        self.token_count = 0
    
    def process_stream(self, messages, include_stats=True):
        stream = openai.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            stream=True,
            stream_options={"include_usage": include_stats}
        )
        
        for chunk in stream:
            # 处理内容
            if chunk.choices[0].delta.content is not None:
                content = chunk.choices[0].delta.content
                self.buffer += content
                self.word_count += len(content.split())
                
                # 实时显示统计
                if include_stats:
                    print(f"\r字数: {self.word_count}", end="")
                
                yield content
            
            # 处理完成信息
            if chunk.choices[0].finish_reason is not None:
                yield f"\n\n完成原因: {chunk.choices[0].finish_reason}"
            
            # 处理使用统计
            if hasattr(chunk, 'usage') and chunk.usage is not None:
                self.token_count = chunk.usage.total_tokens
                yield f"\nToken使用量: {self.token_count}"

# 使用高级流式处理器
processor = AdvancedStreamProcessor()
messages = [{"role": "user", "content": "写一个技术教程"}]

for output in processor.process_stream(messages):
    print(output, end="", flush=True)

temperature

类型: number 或 null
默认值: 1
范围: 0 到 2
描述: 要使用的采样温度，较高的值使输出更随机，较低的值使输出更集中和确定。

温度控制示例

# 低温度 - 确定性输出
deterministic_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "什么是Python？"}],
    temperature=0.1  # 非常确定的回答
)

# 中等温度 - 平衡输出
balanced_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个产品描述"}],
    temperature=0.7  # 平衡创意和准确性
)

# 高温度 - 创意输出
creative_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "创造一个新的超级英雄"}],
    temperature=1.2  # 高创意性
)

# 场景化温度设置
def get_temperature_for_task(task_type):
    temperature_mapping = {
        "factual_qa": 0.1,        # 事实问答需要准确性
        "code_generation": 0.2,   # 代码生成需要精确性
        "translation": 0.3,       # 翻译需要一致性
        "summarization": 0.4,     # 摘要需要平衡
        "general_chat": 0.7,      # 一般对话
        "creative_writing": 1.0,  # 创意写作
        "brainstorming": 1.3,     # 头脑风暴需要高创意
        "poetry": 1.5             # 诗歌创作需要最高创意
    }
    return temperature_mapping.get(task_type, 0.7)

# 使用场景化温度
def get_response_with_appropriate_temperature(content, task_type):
    temp = get_temperature_for_task(task_type)
    return openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": content}],
        temperature=temp
    )

# 示例使用
factual_response = get_response_with_appropriate_temperature(
    "地球的直径是多少？", "factual_qa"
)

creative_response = get_response_with_appropriate_temperature(
    "写一首关于未来的诗", "poetry"
)

# 温度对比实验
def temperature_comparison(prompt, temperatures=[0.1, 0.5, 1.0, 1.5]):
    results = {}
    for temp in temperatures:
        response = openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": prompt}],
            temperature=temp,
            max_completion_tokens=100
        )
        results[temp] = response.choices[0].message.content
    return results

# 比较不同温度的效果
comparison_results = temperature_comparison("描述一只猫")
for temp, content in comparison_results.items():
    print(f"温度 {temp}: {content[:100]}...")
    print("---")

tool_choice

类型: string 或 object
默认值: 当没有工具时为none，当存在工具时为auto
描述: 控制模型调用哪个（如果有）工具。

工具选择示例

# 定义工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "执行数学计算",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "数学表达式"}
                },
                "required": ["expression"]
            }
        }
    }
]

# 自动选择工具
auto_choice = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "北京今天天气怎么样？"}],
    tools=tools,
    tool_choice="auto"  # 让模型自动决定是否使用工具
)

# 强制使用特定工具
forced_tool = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "告诉我天气"}],
    tools=tools,
    tool_choice={
        "type": "function",
        "function": {"name": "get_weather"}
    }  # 强制使用天气工具
)

# 禁用所有工具
no_tools = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "北京天气怎么样？"}],
    tools=tools,
    tool_choice="none"  # 不使用任何工具，仅生成文本
)

# 要求必须使用工具
required_tool = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "帮我计算一些东西"}],
    tools=tools,
    tool_choice="required"  # 必须调用至少一个工具
)

# 智能工具选择
class SmartToolSelector:
    def __init__(self, tools):
        self.tools = tools
        self.tool_keywords = {
            "get_weather": ["天气", "温度", "下雨", "晴天", "weather"],
            "calculate": ["计算", "数学", "加", "减", "乘", "除", "calculate"]
        }
    
    def select_tool_choice(self, user_input):
        user_input_lower = user_input.lower()
        
        # 检查是否明确提到某个工具
        for tool_name, keywords in self.tool_keywords.items():
            if any(keyword in user_input_lower for keyword in keywords):
                return {
                    "type": "function",
                    "function": {"name": tool_name}
                }
        
        # 如果没有明确指向，让模型自动选择
        return "auto"
    
    def get_response(self, user_input):
        tool_choice = self.select_tool_choice(user_input)
        return openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": user_input}],
            tools=self.tools,
            tool_choice=tool_choice
        )

# 使用智能工具选择器
selector = SmartToolSelector(tools)
weather_response = selector.get_response("今天北京天气如何？")
math_response = selector.get_response("帮我计算 15 * 23")
general_response = selector.get_response("你好，请介绍自己")

tools

类型: array
默认值: 无
描述: 模型可能调用的一系列工具。您可以提供自定义工具或函数工具。

工具定义示例

# 基本工具定义
basic_tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "获取当前时间",
            "parameters": {
                "type": "object",
                "properties": {
                    "timezone": {
                        "type": "string",
                        "description": "时区，例如 'Asia/Shanghai'",
                        "default": "UTC"
                    }
                }
            }
        }
    }
]

# 复杂工具定义
advanced_tools = [
    {
        "type": "function",
        "function": {
            "name": "search_database",
            "description": "在数据库中搜索信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "搜索查询"
                    },
                    "table": {
                        "type": "string",
                        "enum": ["users", "products", "orders"],
                        "description": "要搜索的表"
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100,
                        "default": 10,
                        "description": "返回结果的最大数量"
                    },
                    "filters": {
                        "type": "object",
                        "properties": {
                            "date_range": {
                                "type": "object",
                                "properties": {
                                    "start": {"type": "string", "format": "date"},
                                    "end": {"type": "string", "format": "date"}
                                }
                            },
                            "status": {
                                "type": "string",
                                "enum": ["active", "inactive", "pending"]
                            }
                        }
                    }
                },
                "required": ["query", "table"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "send_email",
            "description": "发送电子邮件",
            "parameters": {
                "type": "object",
                "properties": {
                    "to": {
                        "type": "array",
                        "items": {"type": "string", "format": "email"},
                        "description": "收件人邮箱地址"
                    },
                    "subject": {
                        "type": "string",
                        "description": "邮件主题"
                    },
                    "body": {
                        "type": "string",
                        "description": "邮件正文"
                    },
                    "priority": {
                        "type": "string",
                        "enum": ["low", "normal", "high"],
                        "default": "normal"
                    }
                },
                "required": ["to", "subject", "body"]
            }
        }
    }
]

# 工具注册系统
class ToolRegistry:
    def __init__(self):
        self.tools = []
        self.implementations = {}
    
    def register_tool(self, tool_definition, implementation):
        self.tools.append(tool_definition)
        tool_name = tool_definition["function"]["name"]
        self.implementations[tool_name] = implementation
    
    def get_tools(self):
        return self.tools
    
    def execute_tool(self, tool_name, arguments):
        if tool_name in self.implementations:
            return self.implementations[tool_name](**arguments)
        else:
            raise ValueError(f"工具 {tool_name} 未注册")

# 注册工具实现
registry = ToolRegistry()

# 注册时间工具
def get_current_time(timezone="UTC"):
    from datetime import datetime
    import pytz
    tz = pytz.timezone(timezone)
    return datetime.now(tz).strftime("%Y-%m-%d %H:%M:%S %Z")

registry.register_tool(
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "获取当前时间",
            "parameters": {
                "type": "object",
                "properties": {
                    "timezone": {"type": "string", "default": "UTC"}
                }
            }
        }
    },
    get_current_time
)

# 注册计算工具
def calculate_expression(expression):
    try:
        # 安全的数学表达式计算
        import ast
        import operator
        
        operators = {
            ast.Add: operator.add,
            ast.Sub: operator.sub,
            ast.Mult: operator.mul,
            ast.Div: operator.truediv,
            ast.Pow: operator.pow,
            ast.USub: operator.neg,
        }
        
        def eval_expr(node):
            if isinstance(node, ast.Num):
                return node.n
            elif isinstance(node, ast.BinOp):
                return operators[type(node.op)](eval_expr(node.left), eval_expr(node.right))
            elif isinstance(node, ast.UnaryOp):
                return operators[type(node.op)](eval_expr(node.operand))
            else:
                raise TypeError(node)
        
        return eval_expr(ast.parse(expression, mode='eval').body)
    except:
        return "计算错误：无效的表达式"

registry.register_tool(
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "计算数学表达式",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {"type": "string", "description": "数学表达式"}
                },
                "required": ["expression"]
            }
        }
    },
    calculate_expression
)

# 使用工具注册系统
response_with_tools = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "现在几点了？请计算 25 * 4"}],
    tools=registry.get_tools(),
    tool_choice="auto"
)

# 处理工具调用
if response_with_tools.choices[0].message.tool_calls:
    for tool_call in response_with_tools.choices[0].message.tool_calls:
        tool_name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)
        result = registry.execute_tool(tool_name, arguments)
        print(f"工具 {tool_name} 执行结果: {result}")

# 动态工具生成
def create_api_tool(api_name, endpoint, method="GET", description=""):
    return {
        "type": "function",
        "function": {
            "name": f"call_{api_name}",
            "description": description or f"调用 {api_name} API",
            "parameters": {
                "type": "object",
                "properties": {
                    "endpoint": {"type": "string", "default": endpoint},
                    "method": {"type": "string", "default": method},
                    "params": {"type": "object", "description": "API参数"}
                }
            }
        }
    }

# 创建API工具集
api_tools = [
    create_api_tool("weather", "/api/weather", "GET", "获取天气信息"),
    create_api_tool("news", "/api/news", "GET", "获取新闻信息"),
    create_api_tool("translate", "/api/translate", "POST", "翻译文本")
]

# 使用API工具
api_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "获取最新新闻"}],
    tools=api_tools,
    tool_choice="auto"
)

top_logprobs

类型: integer 或 null
默认值: 无
范围: 0 到 20
描述: 指定在每个token位置返回最有可能的token数量，每个token都带有相关的对数概率。必须与logprobs=true一起使用。

Top对数概率示例

# 基本top_logprobs使用
response_with_top_logprobs = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "天空是什么颜色？"}],
    logprobs=True,
    top_logprobs=5  # 返回每个位置前5个最可能的token
)

# 分析token选择
def analyze_token_choices(response):
    if response.choices[0].logprobs:
        for i, token_info in enumerate(response.choices[0].logprobs.content):
            print(f"位置 {i}: '{token_info.token}'")
            print(f"  选中概率: {token_info.logprob:.4f}")
            print("  其他候选:")
            
            for alt in token_info.top_logprobs:
                print(f"    '{alt.token}': {alt.logprob:.4f}")
            print()

analyze_token_choices(response_with_top_logprobs)

# 模型确定性分析
def analyze_model_confidence(response):
    if not response.choices[0].logprobs:
        return None
    
    confidence_scores = []
    for token_info in response.choices[0].logprobs.content:
        # 计算选中token与次优选择的差距
        if len(token_info.top_logprobs) > 1:
            best_prob = token_info.logprob
            second_best = token_info.top_logprobs[1].logprob
            confidence = best_prob - second_best
            confidence_scores.append(confidence)
    
    avg_confidence = sum(confidence_scores) / len(confidence_scores) if confidence_scores else 0
    return {
        "average_confidence": avg_confidence,
        "confidence_scores": confidence_scores,
        "high_confidence_tokens": sum(1 for c in confidence_scores if c > 2.0),
        "low_confidence_tokens": sum(1 for c in confidence_scores if c < 0.5)
    }

# 创意vs确定性任务的对比
creative_task = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "创造一个新的超级英雄"}],
    logprobs=True,
    top_logprobs=5,
    temperature=0.8
)

factual_task = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "地球的直径是多少？"}],
    logprobs=True,
    top_logprobs=5,
    temperature=0.2
)

print("创意任务的确定性分析:")
creative_analysis = analyze_model_confidence(creative_task)
if creative_analysis:
    print(f"平均确定性: {creative_analysis['average_confidence']:.2f}")

print("\n事实任务的确定性分析:")
factual_analysis = analyze_model_confidence(factual_task)
if factual_analysis:
    print(f"平均确定性: {factual_analysis['average_confidence']:.2f}")

top_p

类型: number 或 null
默认值: 1
范围: 0 到 1
描述: 核采样的替代方法，模型考虑具有top_p概率质量的token的结果。

核采样示例

# 保守采样 - 高质量但可能缺乏创意
conservative_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个产品描述"}],
    top_p=0.1,  # 只考虑最可能的10%的token
    temperature=0.7
)

# 平衡采样 - 质量和多样性的平衡
balanced_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个产品描述"}],
    top_p=0.7,  # 考虑前70%概率质量的token
    temperature=0.7
)

# 开放采样 - 最大多样性
open_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一个产品描述"}],
    top_p=0.95,  # 考虑前95%概率质量的token
    temperature=0.7
)

# 场景化top_p设置
scenarios_top_p = {
    "technical_documentation": 0.3,  # 需要准确性
    "creative_writing": 0.8,         # 需要创意
    "code_generation": 0.5,          # 平衡准确性和灵活性
    "casual_conversation": 0.9,      # 自然多样性
    "formal_writing": 0.4,           # 正式且准确
    "brainstorming": 0.95            # 最大创意
}

def get_response_with_top_p(content, scenario):
    top_p = scenarios_top_p.get(scenario, 0.7)
    return openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": content}],
        top_p=top_p,
        temperature=0.7
    )

# 使用场景化设置
code_response = get_response_with_top_p("写一个快速排序算法", "code_generation")
creative_response = get_response_with_top_p("写一个科幻故事开头", "creative_writing")

verbosity

类型: string 或 null
默认值: medium
描述: 约束模型响应的详细程度。目前支持的值有low、medium和high。

详细程度控制示例

# 简洁回复
concise_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释什么是机器学习"}],
    verbosity="low"  # 简洁的解释
)

# 中等详细程度
medium_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释什么是机器学习"}],
    verbosity="medium"  # 平衡的解释
)

# 详细回复
detailed_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释什么是机器学习"}],
    verbosity="high"  # 详细的解释
)

# 根据用户需求调整详细程度
def get_verbosity_for_context(user_level, time_constraint):
    if time_constraint == "urgent":
        return "low"
    elif user_level == "beginner":
        return "high"  # 初学者需要详细解释
    elif user_level == "expert":
        return "low"   # 专家只需要要点
    else:
        return "medium"  # 默认中等详细程度

# 使用示例
beginner_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "什么是API？"}],
    verbosity=get_verbosity_for_context("beginner", "normal")
)

expert_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "解释REST API的最佳实践"}],
    verbosity=get_verbosity_for_context("expert", "normal")
)

web_search_options

类型: object
默认值: 无
描述: 此工具搜索网络以获取相关结果以用于响应。

网络搜索示例

# 基本网络搜索
web_search_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "最新的AI技术发展"}],
    web_search_options={
        "query": "latest AI technology developments 2024",
        "max_results": 5
    }
)

# 特定领域搜索
tech_search = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "分析当前的加密货币市场"}],
    web_search_options={
        "query": "cryptocurrency market analysis current trends",
        "domains": ["coindesk.com", "cointelegraph.com"],
        "language": "en"
    }
)

# 新闻搜索
news_search = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "今天有什么重要新闻？"}],
    web_search_options={
        "query": "breaking news today",
        "time_range": "24h",
        "source_type": "news"
    }
)

# 学术搜索
academic_search = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "机器学习的最新研究进展"}],
    web_search_options={
        "query": "machine learning research 2024",
        "source_type": "academic",
        "max_results": 10
    }
)

已弃用参数 (Deprecated Parameters)

function_call

类型: string 或 object
已弃用替代: tool_choice
描述: 控制模型调用哪个（如果有）函数。

迁移示例

# 旧方式（已弃用）
# old_response = openai.chat.completions.create(
#     model="gpt-4o",
#     messages=[{"role": "user", "content": "获取天气"}],
#     functions=[...],
#     function_call="auto"
# )

# 新方式（推荐）
new_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "获取天气"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取天气信息",
            "parameters": {...}
        }
    }],
    tool_choice="auto"  # 替代 function_call="auto"
)

# 强制调用特定函数的迁移
# 旧方式
# function_call={"name": "get_weather"}

# 新方式
tool_choice={
    "type": "function",
    "function": {"name": "get_weather"}
}

functions

类型: array
已弃用替代: tools
描述: 模型可能生成 JSON 输入的函数列表。

迁移示例

# 旧方式（已弃用）
# old_functions = [
#     {
#         "name": "get_weather",
#         "description": "获取天气信息",
#         "parameters": {
#             "type": "object",
#             "properties": {
#                 "location": {"type": "string"}
#             },
#             "required": ["location"]
#         }
#     }
# ]

# 新方式（推荐）
new_tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    }
]

# 使用新的tools参数
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "北京天气如何？"}],
    tools=new_tools,
    tool_choice="auto"
)

max_tokens

类型: integer 或 null
已弃用替代: max_completion_tokens
描述: 聊天完成中可以生成的最大 token 数量。
注意: 不兼容o系列模型

迁移示例

# 旧方式（已弃用，不兼容o系列模型）
# old_response = openai.chat.completions.create(
#     model="gpt-4o",
#     messages=[{"role": "user", "content": "写一篇文章"}],
#     max_tokens=500
# )

# 新方式（推荐，兼容所有模型）
new_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "写一篇文章"}],
    max_completion_tokens=500  # 替代 max_tokens
)

# 对于推理模型（如o3），必须使用新参数
reasoning_response = openai.chat.completions.create(
    model="o3",
    messages=[{"role": "user", "content": "解决复杂问题"}],
    max_completion_tokens=1000,  # 包括推理token
    reasoning_effort="high"
)

# 兼容性函数
def create_completion_with_token_limit(model, messages, token_limit, **kwargs):
    if model.startswith("o"):  # o系列模型
        return openai.chat.completions.create(
            model=model,
            messages=messages,
            max_completion_tokens=token_limit,
            **kwargs
        )
    else:  # 其他模型可以使用任一参数
        return openai.chat.completions.create(
            model=model,
            messages=messages,
            max_completion_tokens=token_limit,  # 推荐使用新参数
            **kwargs
        )

seed

类型: integer 或 null
已弃用替代: 无直接替代，但可使用 system_fingerprint 响应参数监控
描述: 此功能处于 Beta 阶段。用于尝试获得确定性的模型输出。

替代方案示例

# 旧方式（已弃用）
# old_response = openai.chat.completions.create(
#     model="gpt-4o",
#     messages=[{"role": "user", "content": "生成随机数"}],
#     seed=42
# )

# 新方式：使用其他参数组合获得更一致的输出
consistent_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "生成随机数"}],
    temperature=0.1,  # 低温度增加一致性
    top_p=0.1,        # 低top_p增加确定性
)

# 监控系统指纹以检测后端变化
def monitor_consistency(prompt, num_requests=3):
    responses = []
    fingerprints = []
    
    for i in range(num_requests):
        response = openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": prompt}],
            temperature=0.1
        )
        responses.append(response.choices[0].message.content)
        fingerprints.append(response.system_fingerprint)
    
    # 检查一致性
    unique_responses = set(responses)
    unique_fingerprints = set(fingerprints)
    
    return {
        "responses": responses,
        "unique_responses": len(unique_responses),
        "fingerprints": fingerprints,
        "unique_fingerprints": len(unique_fingerprints),
        "consistency_score": 1 - (len(unique_responses) - 1) / len(responses)
    }

# 使用一致性监控
consistency_report = monitor_consistency("什么是2+2？")
print(f"一致性得分: {consistency_report['consistency_score']:.2f}")

user

类型: string
已弃用替代: safety_identifier 和 prompt_cache_key
描述: 此字段被 safety_identifier 和 prompt_cache_key 替代。

迁移示例

import hashlib

# 旧方式（已弃用）
# old_response = openai.chat.completions.create(
#     model="gpt-4o",
#     messages=[{"role": "user", "content": "帮助内容"}],
#     user="user_12345"
# )

# 新方式：分别使用安全标识符和缓存键
def migrate_user_parameter(user_id, content_type="general"):
    # 创建安全标识符（用于滥用检测）
    safety_id = hashlib.sha256(f"app_name:{user_id}".encode()).hexdigest()[:16]
    
    # 创建缓存键（用于性能优化）
    cache_key = f"{content_type}_{hashlib.md5(user_id.encode()).hexdigest()[:8]}"
    
    return safety_id, cache_key

# 使用迁移后的参数
user_id = "user_12345"
safety_id, cache_key = migrate_user_parameter(user_id, "help_content")

new_response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "帮助内容"}],
    safety_identifier=safety_id,      # 替代user字段的安全功能
    prompt_cache_key=cache_key        # 替代user字段的缓存功能
)

# 批量迁移用户请求
class UserParameterMigrator:
    def __init__(self, app_name):
        self.app_name = app_name
    
    def create_identifiers(self, user_id, session_id=None):
        # 安全标识符
        base_string = f"{self.app_name}:{user_id}"
        safety_identifier = hashlib.sha256(base_string.encode()).hexdigest()[:16]
        
        # 缓存键
        cache_base = f"{user_id}"
        if session_id:
            cache_base += f":{session_id}"
        prompt_cache_key = hashlib.md5(cache_base.encode()).hexdigest()[:12]
        
        return safety_identifier, prompt_cache_key
    
    def create_completion(self, user_id, messages, session_id=None, **kwargs):
        safety_id, cache_key = self.create_identifiers(user_id, session_id)
        
        return openai.chat.completions.create(
            messages=messages,
            safety_identifier=safety_id,
            prompt_cache_key=cache_key,
            **kwargs
        )

# 使用迁移器
migrator = UserParameterMigrator("my_chat_app")
migrated_response = migrator.create_completion(
    user_id="user_12345",
    messages=[{"role": "user", "content": "你好"}],
    session_id="session_789",
    model="gpt-4o"
)

响应对象结构与参数说明

响应对象概述

响应对象包含生成的内容、使用统计、标识符和元数据等信息。根据请求设置（如流式传输或工具调用），响应格式可能有所不同。

聊天完成对象示例 (Chat Completion Object Example)

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello there, how can I help you today?"
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  },
  "system_fingerprint": "fp_44709d69a1"
}

详细响应参数说明

id

类型: string
描述: 聊天完成的唯一标识符。
用途: 用于跟踪、调试和引用特定的API响应。

object

类型: string
描述: 对象的类型，通常为 chat.completion。
用途: 用于确认返回的对象类型，便于客户端正确处理响应。

created

类型: integer
描述: 创建聊天完成的Unix时间戳（秒）。
用途: 记录响应生成的确切时间，可用于时间排序和日志记录。

model

类型: string
描述: 用于生成响应的模型ID（如 gpt-4o, gpt-3.5-turbo）。
用途: 确认实际用于处理请求的模型，尤其是当使用通用别名时。

choices

类型: array
描述: 聊天完成的选项列表。当请求中 n 大于1时，会包含多个选项。
用途: 提供一个或多个模型生成的响应变体。

choices[].index

类型: integer
描述: 选项在数组中的索引位置。
用途: 标识多个响应选项的顺序。

choices[].message

类型: object
描述: 模型生成的响应消息对象。
用途: 包含模型的实际输出内容，是响应的核心部分。

choices[].message.role

类型: string
描述: 消息的作者角色，通常为 assistant。
用途: 标识消息的发送者身份，用于构建对话历史。

choices[].message.content

类型: string 或 null
描述: 模型生成的文本内容。当使用工具调用时可能为 null。
用途: 包含模型的实际文本响应。

choices[].message.tool_calls

类型: array 或不存在
描述: 当模型决定调用工具时包含的工具调用信息。
用途: 提供模型请求执行的工具/函数调用的详细信息。

choices[].logprobs

类型: object 或 null
描述: 如果请求中 logprobs 为 true，则包含输出token的对数概率信息。
用途: 提供每个生成token的概率分布，用于研究或调试模型决策。

choices[].finish_reason

类型: string
描述: 模型停止生成token的原因。
可能的值:
- stop: 模型自然完成或遇到停止标记
- length: 达到最大token限制
- tool_calls: 模型决定调用工具
- content_filter: 内容被安全系统过滤
- function_call(已弃用): 模型决定调用函数
用途: 了解模型为何停止生成，特别是在截断情况下进行诊断。

usage

类型: object
描述: 提供有关请求和响应中使用的token数量的统计信息。
用途: 监控API使用量和成本估算。

usage.prompt_tokens

类型: integer
描述: 提示（输入）中使用的token数量。
用途: 跟踪输入消耗的token数量，用于成本计算。

usage.completion_tokens

类型: integer
描述: 完成（输出）中使用的token数量。
用途: 跟踪模型生成的token数量，用于成本计算。

usage.total_tokens

类型: integer
描述: 总共使用的token数量（提示+完成）。
用途: 跟踪总体token使用量，确保在限制范围内。

system_fingerprint

类型: string
描述: 系统指纹，用于监控后端变化。
用途: 检测OpenAI系统更新，可用于一致性监控。

流式响应示例

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{"content":" there!"},"finish_reason":null}]}
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-3.5-turbo-0613","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

流式响应处理注意事项

每个事件代表响应的一部分，需要在客户端累积以构建完整响应
delta 字段包含相对于前一个事件的增量更新
最后一个事件包含 finish_reason，表示流结束的原因
客户端需要实现服务器发送事件(SSE)处理逻辑
特定语言SDK通常提供流式处理的辅助函数

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

openapi

接口

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。