client.chat.completions.create 与 client.completions.create 有何区别及兼容性问题？

Question

常见问题：`client.chat.completions.create` 与 `client.completions.create` 是 OpenAI Python SDK 中两类不同接口，**本质不兼容**。前者用于 Chat 模型（如 `gpt-3.5-turbo`, `gpt-4`），接收 `messages` 列表（含 role/content 结构），支持多轮对话、系统提示和函数调用；后者仅适用于旧式 Completion 模型（如 `text-davinci-003`），输入为纯 `prompt` 字符串，无角色概念，已**自 2023 年底起被 OpenAI 官方弃用**。SDK v1.0+（2023年6月后）**完全移除了 `completions.create`**，调用将抛出 `AttributeError`。迁移时需重构输入格式、更新模型名，并注意 token 计算、流式响应（`stream=True`）及错误处理逻辑的差异。若项目仍依赖旧接口，必须降级 SDK 至 <1.0（不推荐，存在安全与功能风险），或全面适配 Chat 接口——这是当前唯一受支持且向后兼容的路径。

Answer 1

```html

一、现象层：典型报错与表征特征

开发者在升级 OpenAI Python SDK 至 v1.0+ 后，执行 client.completions.create(...) 时抛出：
AttributeError: 'OpenAI' object has no attribute 'completions'。该错误非代码逻辑错误，而是 SDK 架构级移除——completions 模块自 v1.0 起被彻底剥离。同时，旧式 prompt 字符串（如 "Translate to French: Hello world"）直接传入 chat.completions.create 将触发 ValidationError，因后者强制要求 messages: List[Dict[str, str]] 结构。

二、机制层：接口设计哲学的根本分野

• Chat 接口：面向对话智能体（Agent）范式，以 role（system/user/assistant）为语义锚点，天然支持上下文管理、工具调用（tools + tool_choice）、结构化响应（response_format={"type": "json_object"}）；
• Legacy Completions 接口：基于统计文本续写范式，仅接受扁平 prompt，无角色建模能力，无法表达“系统指令”与“用户意图”的分离，亦不支持函数调用等现代 LLM 工程能力。

二者底层协议、请求路由、tokenization 策略（如 Chat 模型使用 tiktoken 的 cl100k_base 编码器，而旧 Completion 模型多用 p50k_base）均不兼容。

三、迁移层：重构路径与关键转换对照表

维度	旧接口 completions.create	新接口 chat.completions.create
模型名	text-davinci-003, text-curie-001	gpt-3.5-turbo, gpt-4-turbo, gpt-4o
输入格式	{"prompt": "Summarize: ..."}	{"messages": [{"role":"user","content":"Summarize: ..."}]}
系统提示	需拼接进 prompt 字符串（易混淆）	独立 {"role":"system","content":"..."} 消息

四、工程层：流式响应与 Token 计算的差异实践

旧接口中 stream=True 返回 CompletionStream，逐 token 输出字符串；新接口返回 ChatCompletionChunk，需解析 delta.content 并累积，且首次 chunk 可能含 delta.role 或 delta.tool_calls。Token 计算亦不可复用：旧版用 tiktoken.get_encoding("p50k_base")，新版必须用 tiktoken.encoding_for_model("gpt-4o") —— 直接复用将导致计数偏差超 ±15%。

五、架构层：错误处理与可观测性升级

from openai import APIStatusError, APITimeoutError, RateLimitError

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Explain quantum entanglement"}],
        stream=True
    )
    for chunk in response:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
except RateLimitError as e:
    # 新 SDK 提供细粒度状态码（e.status_code == 429）
    log_rate_limit_violation(e.response.headers.get("x-ratelimit-limit"))
except APIStatusError as e:
    # 统一异常基类，覆盖 4xx/5xx 全量 HTTP 错误
    handle_openai_api_error(e)

六、演进层：为什么 Chat 接口是唯一可持续路径？

graph LR
A[OpenAI 战略聚焦] --> B[Agent 原生架构]
B --> C[所有新模型仅发布 Chat 版本]
C --> D[gpt-4o-mini, o1-preview, reasoning 系列均无 Completion 变体]
D --> E[API 网关层已废弃 /v1/completions 路由]
E --> F[2024 Q2 起，/v1/completions 返回 410 Gone]

官方文档明确标注：“All new models are chat-only. We recommend migrating all applications to the chat completions API.” 这不仅是兼容性问题，更是技术栈代际跃迁的强制信号。

```