2.6 Completion API与ChatCompletion API差异对比与选型
一、两种API的定位
| API | 用途 | 输入格式 | 典型场景 |
|---|---|---|---|
| Completion | 单轮文本补全 | 纯文本prompt | 续写、补全 |
| ChatCompletion | 对话式补全 | messages数组 | 多轮对话、角色设定 |
《大模型应用开发极简入门》第2章「使用其他文本补全模型」专门讲解 Completion API（旧版） 用法与适用场景（单轮文本生成），并对比 ChatCompletion 与 Completion 的差异。本节与之一一对应，并给出可执行的迁移步骤与请求/响应对照表。
二、核心差异
| 维度 | Completion | ChatCompletion |
|---|---|---|
| 输入 | 纯文本字符串 | system/user/assistant消息 |
| 多轮 | 需手动拼接历史 | 原生支持 |
| 角色 | 无 | 支持system设定 |
| 推荐 | 逐步淘汰 | 当前主流 |
三、选型建议
优先使用ChatCompletion：支持多轮对话、角色设定、Function Calling，是当前OpenAI推荐的主流接口。Completion仅在对单轮纯文本补全有特殊需求时考虑。
3.1 与《大模型应用开发极简入门》第2.6节的对应
本书第2章「使用其他文本补全模型」专门讲解 Completion API（旧版） 的用法与适用场景（单轮文本生成），并对比 ChatCompletion 与 Completion 的差异。本节「两种 API 的定位」「核心差异」「选型建议」与之一一对应；后续的迁移指南与注意事项是书中「从 Completion 迁移到 ChatCompletion」的落地步骤。新项目一律使用 ChatCompletion，是书中与官方共同推荐的做法。
四、Completion API的遗留用法
4.1 基本格式
# Completion API（旧版，逐步淘汰）
response = client.completions.create(
model="text-davinci-003",
prompt="请翻译：Hello World",
max_tokens=100
)
text = response.choices[0].text
输入为纯文本字符串，无角色区分。多轮对话需手动拼接，如"用户：xxx\n助手：yyy\n用户：zzz\n助手："。
4.2 适用场景
仅在对单轮、纯文本补全有特殊需求，或维护旧系统时使用。新项目一律推荐ChatCompletion。
4.3 迁移指南
将prompt转为messages：若原prompt为"用户：A\n助手：B\n用户：C\n助手："，可拆分为[user:A, assistant:B, user:C]，最后一条user可为空或包含当前问题。若有「系统级」说明（如角色、规则），放入首条 {"role": "system", "content": "..."}。迁移后务必用相同用例回归测试，确认输出与行为一致再下线 Completion。
五、与《大模型应用开发极简入门》第2.6节的对应
本书第2章「使用其他文本补全模型」专门讲解 Completion API（旧版） 的用法与适用场景（单轮文本生成），并对比 ChatCompletion 与 Completion 的差异。本节与之一一对应：两种 API 的定位表对应「用途与典型场景」，核心差异表对应「输入格式、多轮、角色、推荐」；迁移指南对应书中「从 Completion 迁移到 ChatCompletion」的实践建议。新项目一律使用 ChatCompletion，是书中与官方共同推荐的做法。
六、ChatCompletion 相对 Completion 的优势总结
6.1 对话与角色
ChatCompletion 的 messages 支持 system / user / assistant 三种角色。system 用于设定身份与全局约束，user 表示用户输入，assistant 表示历史回复。Completion 仅支持单段 prompt 字符串，多轮需自行拼接，且无法显式区分「系统设定」与「用户/助手」，不利于复杂对话与安全策略。
6.2 多轮上下文
ChatCompletion 在一次请求中传入完整 messages 数组即可维持多轮上下文；Completion 需将历史对话拼成一段文本，易超出上下文窗口且格式不统一，维护成本高。
6.3 Function Calling 与扩展
当前 Function Calling（函数调用）仅支持 Chat Completion 类接口，用于在对话中调用外部工具。若业务需要工具调用、插件能力，必须使用 ChatCompletion，Completion 无法替代。
6.4 模型与版本
新模型（如 gpt-4、gpt-4-turbo、gpt-3.5-turbo）主要面向 Chat Completion；Completion 常用模型如 text-davinci-003 已逐步淡出。从生态与长期维护角度，选 ChatCompletion 更稳妥。
七、迁移时的注意事项
7.1 字段对应
Completion 的 response.choices[0].text 对应 ChatCompletion 的 response.choices[0].message.content。若有对 text 的引用，需改为 message.content。
7.2 停止序列与格式
若原 Completion 使用了 stop 等参数，在 ChatCompletion 中同样支持，可保留。输出格式若依赖「补全到某标记为止」，需在 ChatCompletion 的 system/user 中明确说明，或使用 stop 序列。
7.3 错误处理与重试
两种 API 的错误码与限流策略类似，迁移时可复用同一套重试与退避逻辑，仅将请求体从 prompt 改为 messages 即可。
九、Completion 仍在使用时的注意点
若因历史原因仍需保留 Completion 调用（如 text-davinci-003），需注意：（1）该模型系列可能逐步下线，需关注官方公告并规划迁移时间表；（2）新能力（如 Function Calling、更长上下文）仅面向 Chat 类模型开放，无法在 Completion 上使用；（3）计费与限流策略可能与 Chat 模型不同，需单独核算成本。书中第 2.6 节「使用其他文本补全模型」明确建议新项目使用 ChatCompletion，本节在对比与迁移之外，再次强调以 ChatCompletion 为首选，Completion 仅作兼容或过渡使用。
十、从 Completion 迁移到 ChatCompletion 的步骤小结
迁移可归纳为四步：（1）将单条 prompt 转为 messages，若原为多轮拼接文本，则按「用户/助手」交替拆成 user/assistant 消息；（2）将 response.choices[0].text 改为 response.choices[0].message.content；（3）若原用了 system 类指令，放入 messages 的首条 {"role": "system", "content": "..."}；（4）运行测试集或核心场景，确认输出与行为一致后再下线 Completion。书中「对比 ChatCompletion 与 Completion」的结论在本节已转化为可执行的迁移步骤与注意事项，便于旧项目平滑升级。
十一、小结
ChatCompletion 是当前开发的首选 API，支持多轮对话、角色设定、Function Calling。理解两者差异，有助于在迁移或兼容旧代码时做出正确选择。下一节将介绍 API 成本控制与重试机制。书中「使用其他文本补全模型」与「对比 ChatCompletion 与 Completion」的要点已全部体现在本节的表格、迁移指南与小结中。新项目一律采用 ChatCompletion 即可，无需再评估 Completion。
十二、Completion 与 ChatCompletion 的请求/响应结构对比
| 项目 | Completion | ChatCompletion |
|---|---|---|
| 请求入口 | client.completions.create | client.chat.completions.create |
| 输入 | prompt="..."（单字符串） | messages=[{role, content}, ...] |
| 输出取文 | response.choices[0].text | response.choices[0].message.content |
| 多轮 | 需将历史拼进 prompt | 直接传完整 messages |
| 角色 | 无 | system / user / assistant |
迁移时除替换 API 与字段外，还需将原 prompt 的「用户/助手」交替文本拆成多条 message，并视情况增加首条 system。书中第 2.6 节「使用其他文本补全模型」的对比在本节已转化为可直接执行的对照表与迁移步骤。
十三、与 2.5、2.7 节的配合
2.5 节多轮对话：多轮必须使用 ChatCompletion 的 messages，不能使用 Completion 的单 prompt。若你从零开发新项目，直接按 2.5 节用 ChatCompletion 即可，无需再学 Completion。2.7 节成本：ChatCompletion 与 Completion 的计费方式类似（按 Token），迁移后成本核算方式不变，仅需将 response.choices[0].message.content 的长度或 response.usage 纳入统计即可。书中「使用其他文本补全模型」与「对比 ChatCompletion 与 Completion」的结论在本节已全部可执行化，新项目一律采用 ChatCompletion。与 2.9 节的关系：Function Calling 仅支持 ChatCompletion 类接口，若业务需要工具调用或插件能力，必须使用 ChatCompletion，本节选型结论与 2.9 一致。迁移完成后，建议用相同用例做回归测试，确认输出与行为一致再下线 Completion 调用。
下一节预告：2.7 API成本控制与性能优化：Token计费与重试机制
