加载中
加载中

在使用 Claude 构建聊天应用时,存在一个重大的用户体验挑战:生成响应可能需要 10 到 30 秒,这会让用户一直盯着加载转圈动画。解决方案就是响应流式传输,它让用户能够看到文本随着 Claude 生成而逐块出现,从而带来更灵敏的使用体验。

聊天应用将"什么是量子计算?"发送到我们的服务器,服务器将其转发给 Claude 并取回一条助手消息。

标准响应方式存在的问题

在典型的聊天设置中,您的服务器会将用户消息发送给 Claude,并等待完整的响应后才向客户端发送任何内容。这会造成一段令人尴尬的延迟,期间用户完全没有任何迹象表明正在发生什么。

我们的服务器将"什么是量子计算?"传递给 Claude,这可能需要 10 到 30 秒,而应用的 AI 回复处显示着三个圆点。

流式传输的工作原理

启用流式传输后,Claude 会立即返回一个初始响应,表明它已收到您的请求并开始生成文本。随后您会收到一系列事件,每个事件都包含整体响应中的一小部分内容。

Claude 以一条初始响应回复"什么是量子计算?",随后依次出现"Quantum"、"computing"和"is"这几个事件。

您的服务器可以在这些文本块到达时将它们转发给客户端应用,让用户逐字逐句地看到响应逐渐构建出来。所有这些事件都属于对 Claude 的同一个请求。

了解流事件

启用流式传输后,Claude 会返回几种类型的事件:

  • MessageStart —— 正在发送一条新消息
  • ContentBlockStart —— 包含文本、工具使用或其他内容的新块的开始
  • ContentBlockDelta —— 实际生成文本的分块内容
  • ContentBlockStop —— 当前内容块已完成
  • MessageDelta —— 当前消息已完成
  • MessageStop —— 当前消息相关信息的结束

上面列出的流事件类型按顺序从 Claude 到达,其中 ContentBlockDelta 重复出现三次。

ContentBlockDelta 事件包含您希望展示给用户的实际生成文本。

基本的流式传输实现

要启用流式传输,请在您的 messages.create 调用中添加 stream=True:

python
messages = []
add_user_message(messages, "Write a 1 sentence description of a fake database")

stream = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    stream=True
)

for event in stream:
    print(event)

上述流式传输代码在 Notebook 中的输出,首先是一个 RawMessageStartEvent,然后是一个 RawContentBlockStartEvent。

简化的文本流式传输

您无需手动解析事件,而是可以使用 SDK 提供的简化流式传输接口,该接口只会提取文本内容:

python
with client.messages.stream(
    model=model,
    max_tokens=1000,
    messages=messages
) as stream:
    for text in stream.text_stream:
        print(text, end="")

这种方式会自动过滤掉除实际文本内容之外的所有内容,而这通常正是您向用户展示响应时所需要的。

获取完整消息

虽然逐块流式传输有利于用户体验,但您通常还需要完整的消息用于存储或进一步处理。流式传输完成后,您可以获取组装好的最终消息:

python
with client.messages.stream(
    model=model,
    max_tokens=1000,
    messages=messages
) as stream:
    for text in stream.text_stream:
        # 将每个数据块发送给您的客户端
        pass
    
    # 获取完整消息以存入数据库
    final_message = stream.get_final_message()

这样您便能两全其美:既为用户提供实时流式传输,又为您的应用逻辑获得完整的消息对象。