【API 设计之道】10 面向 AI 的 API：长耗时任务 (LRO) 与流式响应

大家好，我是Tony Bai。

欢迎来到我们的专栏 《API 设计之道：从设计模式到 Gin 工程化实现》的第十讲，也是我们微专栏的收官之战。

在过去的几年里，后端开发面临的最大挑战，从"高并发"变成了"高延迟"。

随着 ChatGPT 和各类大模型的爆发，我们越来越多地需要设计与 AI 交互的 API。这类业务有一个显著特征：慢。

• 生成一张 4K 图片，可能需要 15 秒。

• 处理一个长文档摘要，可能需要 40 秒。

• 微调一个模型，可能需要几小时。

如果你依然使用传统的同步 Request-Response 模式：

// 传统的同步调用
func GenerateText(c *gin.Context) {
    result := CallLLM() // 这里阻塞了 60 秒
    c.JSON(200, result)
}

你会遇到灾难性的后果：

1. 网关超时：Nginx 或 Load Balancer 通常默认 60 秒超时，直接切断连接，客户端收到 504 Gateway Timeout。

2. 资源锁死：Gin 的 Goroutine 被长期占用，无法释放，导致服务吞吐量暴跌。

3. 用户体验极差：用户盯着屏幕转圈圈，不知道还要等多久，甚至怀疑系统挂了。

面对 AI 时代的 API 设计挑战，我们需要引入两套重量级的架构模式：长耗时操作 (Long-running Operations, LRO) 和 流式响应 (Streaming)。

今天，我们将在 Gin 中实现这两种模式，让你的 API 能够优雅地驾驭"慢"业务。

模式一：长耗时操作 (LRO) 与 轮询

对于那些不需要实时反馈 ，或者耗时极长（分钟级以上） 的任务（如视频转码、模型训练），最标准的做法是 "异步创建 + 状态轮询"。