流式响应API接入最佳实践

背景介绍

基于AI大模型能力构建的API常需要使用流式响应提供服务，一方面流式响应API允许系统在处理请求时实时传输数据，用户可以在模型生成输出的同时开始接收结果，从而减少了等待时间，提高了交互效率。另一方面流式响应可以优化用户体验，尤其是在需要实时反馈的应用场景中。例如在对话系统或者在线客服中，用户能够即时看到模型的应答部分，有助于提升交互的自然性和连贯性。

云市场已支持流式响应API的接入和商业化，用户订阅后以流式响应的方式进行API调试和使用。本文会主要介绍流式响应API相比于普通API在接入过程中的一些注意事项和最佳实践。

在API网关发布流式响应API的注意事项

1. 在网关发布API分组时，参照支持流式数据传输（SSE）文档，为流式响应API所在的API分组勾选支持流式数据传输的数据传输设置。

2. 在网关发布API时，根据需要在API 网关正确设置API后端响应的超时时间（不设置一般默认为10秒），防止因为后端响应时间过长而导致请求超时报错。

API调试对流式响应的支持

云市场商品详情页API调试功能已支持了流式响应API，对于符合Server-Sent Events协议规范的API返回值，API调试工具会在调用结果Tab展示流式结果，SSE响应中最新的事件结果会追加展示在调试结果中，直到响应结束。

最佳实践

1. 符合Server-Sent Events标准

API输出应符合Server-Sent Events协议规范，HTTP响应使用Content-Type: text/event-stream作为响应的内容类型；数据格式上SSE 数据由一系列以 data: 开头的行组成。每条消息以两个换行符结束。每条消息可以包括多个数据行和一些其他可选的字段，如 id（事件 ID）和 event（事件类型）。一个简单的符合SSE规范的响应示例如下：

HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

id: 1
event: message
data: 这是第一条消息
data: 这是同一条消息的续行

id: 2
event: message
data: 这是第二条消息

2. 增量结果合并返回

AI大模型应用场景下，大模型生成回答是一个逐字逐句生成的过程，随着输出token的增加，通过SSE事件返回时可以在每次返回的新消息中包含前一条消息的内容，格式化为一个包含历史信息的完整数据结构，这将有助于接收方在解析消息时，快速获取所需的上下文信息。