![文章封面](https://developer.qcloudimg.com/http-save/yehe-11715263/e75fd099fb517f26248031b732905511.png)

**简介：先分清模型 API 与普通 HTTP 接口的区别，再看 Chat Completions 和 Responses 两种接口形态、messages 的角色分工和输出项**

## 从模型 API 到可控的 Agent Harness

**简介：不是「会调模型」，而是让模型调用成为可替换、可校验、可恢复的工程能力**

-   传统 HTTP API vs LLM API

![传统 HTTP 接口与 LLM 接口对比](https://developer.qcloudimg.com/http-save/yehe-11715263/e48284037e4395a7a007f18c38f1f786.png)

-   两者的本质区别
    -   传统 HTTP：请求确定，响应可预测
    -   LLM：请求是上下文，响应是概率生成
        -   返回的是「概率最大的下一段文本」
        -   **同样的输入，可以得到不同的输出**
    -   所以在把 Agent Loop 跑起来之前，先要解决更基础的问题：如何稳定调用模型
-   统一模型调用服务要具备的六项能力

| 能力 | 要点 |
| --- | --- |
| **理解 Chat / Responses API 结构** | 识别请求字段、消息角色与响应体的来源，不靠记忆调用姿势 |
| **理解三大采样参数边界** | `temperature`、`top_p`、`max_tokens` 各控制什么，不被「调大温度」误解 |
| **管理 Token 与 Context Window** | 喂「足够且必要」的上下文，不把全部历史塞进 prompt |
| **建立 Structured Output 契约** | JSON Schema / Pydantic / 原生结构化输出，从「看起来像 JSON」到业务可校验 |
| **分类处理调用失败** | 超时、限流、过载、拒答、截断、格式错，不同失败对应不同处置 |
| **切换至少两个模型 Adapter** | 不改 Loop 就能换模型，关键能力可路由、可回放、可回归 |

-   验收标准
    -   不是「能跑通示例」
    -   **同类请求可回归 · 失败可定位 · 模型可替换 · 输出可校验**

## AI 写代码，工程师还负责什么

**简介：生成候选结果交给模型，让候选结果在系统中可用仍由工程师定义**

-   职责重新划分（不是分工对立）
    -   模型：在给定上下文中生成候选结果
        -   写一段文本、生成一段代码、提出一种修改路径
    -   工程师：让候选结果在系统中可用
        -   目标可验收 · 约束可执行 · 失败可定位 · 变更可回滚
-   必须由工程师指定的五件事

| 工程师必须指定 | 不能交给模型决定的原因 |
| --- | --- |
| **任务目标** | 「写代码」不等于可验收的修改范围，模型不知道这个 PR 要不要附带测试 |
| **上下文** | 模型不知道当前仓库、约束、依赖和已发生的历史决策 |
| **输出契约** | 自然语言不能安全地驱动程序分支或工具调用，必须有结构化约束 |
| **权限与预算** | 模型不能决定自己能花多少钱、能改哪些文件，必须由系统授权 |
| **失败边界** | 模型不知道何时重试、何时降级或必须停止，这是工程师的设计责任 |

-   **编码可以交给 AI；目标、上下文和边界必须由工程师定义**

## 输入输出是 Agent 工程的起点

**简介：输入是一次受控请求，输出是系统下一步行动的依据**

![受控请求与下一步行动](https://developer.qcloudimg.com/http-save/yehe-11715263/a3580ff4021b04c793a5cc47d9b68d00.png)

-   输入不是一句 Prompt，而是一次受控请求
    -   指令：系统规则与任务目标
    -   上下文：代码、文件摘要、历史消息、工具结果
    -   参数：随机性、输出预算、模型能力
-   输出不是一段文本，而是下一步行动的依据
    -   展示给用户、写库、调工具、改文件，还是进入下一轮 Loop，都由输出决定
-   **输入定义可做什么，输出定义系统如何行动**
    -   两件事都在 Harness 内部显式声明，而不是默认靠字符串解析
    -   Harness 把「请求—响应」当成可工程化的对象；SDK 只是请求的载体

## Chat Completions 与 Responses

**简介：不是新旧替代，而是两种不同的心智模型**

| 维度 | Chat Completions | Responses |
| --- | --- | --- |
| 心智模型 | 围绕 messages 的请求—响应 | 面向输出项的统一接口 |
| 输入 | `messages` 数组 | 文本、图片、文件、检索结果可同时传入，统一 item 化 |
| 输出 | 一段文本 | 一组输出项：`message` / `function_call` / `reasoning` / `refusal` |
| 生态 | OpenAI Compatible 协议、第三方代理、本地推理服务都默认支持 | 新 Agent / Codex 首选 |
| 适合 | 多供应商统一接入，大多数模型都能保证的稳定形态 | 需要丰富 Agent 语义的新建应用 |

-   **工程选型：兼容层以 Chat 为基线，需要丰富 Agent 语义时再研究 Responses**
-   第一次调用：Chat Completions
    -   用 OpenAI Compatible SDK 调用 DeepSeek V4 Flash，关注请求形状与响应字段来源

```python
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[
        # system：不可随意覆盖的全局契约
        {"role": "system", "content": "你是代码审查助手。"},
        {"role": "user", "content": "检查这段 Python 是否有空指针风险。"},
    ],
    max_tokens=600,
)

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

-   关键点
    -   请求是 messages 数组：保持 role 与 content 来源可识别，这是后续裁剪、审计、重放的前提
    -   响应取值路径：先读 `choices`，再读 `message`，最后才是 `content`
        -   这是响应的「唯一可信入口」
    -   关键不是 SDK，而是接下来要封装的输入、输出和错误边界
    -   模型名与能力以控制台当前提供的为准

## 消息不是聊天记录，而是运行时上下文

**简介：每一种 role 都承担一种工程职责，混进 user 字符串是埋雷的第一步**

| role | 工程含义 |
| --- | --- |
| `system` | 不可随意覆盖的**全局行为契约**，模型的角色、能力边界和保守度都从这里开始 |
| `user` | 用户目标、输入数据与约束，是唯一面向模型的「用户输入」位置 |
| `assistant` | 模型已经做出的决定，支持**多轮连续性**，下一轮前的状态、修订、撤回都靠它保留 |
| `tool` | **外部世界的观察结果**，必须可追溯；工具是模型的「传感器」，决定它下一步能看见什么 |

-   反例与正解
    -   **反例：把系统规则、用户输入、工具结果、历史结论拼成一大段字符串**
        -   无法裁剪 · 无法审计 · 无法重放 · 无法证明「模型知道什么」
    -   正解：保留来源、role 与顺序，让 Harness 能够裁剪、审计与重放
-   **messages 是运行时状态数组，不是 UI 上的对话流**

## Agent 需要「输出项」而不仅是文本

**简介：Agent 关注的不是「模型说了什么」，而是「系统下一步要处理什么」**

```python
response = client.responses.create(
    model="deepseek-v4-flash",
    input=[
        {"role": "user", "content": "为 login 函数生成测试边界。"},
    ],
)

for item in response.output:
    print(item.type, item)
```

-   输出项类型

| 输出项 | 含义 |
| --- | --- |
| `message` | 可展示的回答 |
| `function_call` | 待执行的工具请求 |
| `reasoning` | 推理项 |
| `refusal` | 拒答 |

-   核心认识
    -   **模型输出是运行时事件，不是只能 print() 的字符串**
    -   把模型当成事件源，而不是 chat 对象；Tool Use 与 Loop 后续都会消费这些输出项
    -   判断标准：Loop 是否需要根据输出决定下一步
        -   是 → 用输出项
        -   否 → 纯文本即可

## 面试/考试记忆点

-   **LLM API 的请求是上下文、响应是概率生成，同样的输入可能得到不同输出**
-   编码可以交给 AI，任务目标、上下文、输出契约、权限预算、失败边界必须由工程师定义
-   一次模型调用的输入 = 指令 + 上下文 + 参数，输出是系统下一步行动的依据
-   Chat Completions 是多供应商兼容的稳定基线；Responses 面向输出项，适合需要丰富 Agent 语义的场景
-   Chat Completions 的响应取值路径是 `choices[0].message.content`
-   四种 role：system 是全局契约，user 是用户输入，assistant 是模型已做的决定，tool 是外部观察结果
-   messages 是运行时状态数组，不能把规则、输入、工具结果拼成一个大字符串
-   Responses 的输出项有 message、function\_call、reasoning、refusal，Loop 据此决定下一步

文章封面 简介：先分清模型 API 与普通 HTTP 接口的区别，再看 Chat Completions 和 Responses 两种接口形态、messages 的角色分工和输出项 从模型 API 到可控的 Agent Harness 简介：不是「会调模型」，而是让模型调用成为可替换、可校验、可恢复的工程能力 传统 HTTP API vs LLM API 传统 HTTP 接口与 LLM 接口对比 

Chat Completions 与 Responses API

人工智能

本文系统解析LLM API与普通HTTP接口的本质区别，深入对比Chat Completions与Responses两种接口形态，详解messages角色分工与输出项类型。重点阐述统一模型调用服务需具备的六项能力，以及工程师在AI编程中的核心职责边界，帮助读者构建可控、可校验、可替换的Agent工程能力。

DeepSeek

路由

Python

Agent

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Chat Completions 与 Responses API-腾讯云开发者社区-腾讯云

Chat Completions 与 Responses API

Chat Completions 与 Responses API

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐