Assistant API 流式传输中的事件流原理细节

一、Assistant API流式传输事件流基础

OpenAI Assistant API的流式输出在特定操作时会生成新事件，每个事件由event和data构成。data存放如大模型回复等关键数据 ，event则表明大模型的处理阶段，像运行、排队、完成等状态信息。

二、事件流核心流程

1. 整体流程：从创建assistant对象、thread对象并追加message开启run状态（即start模式）起，到获取模型回复结束。一开始触发thread.run.created事件，标志线程运行状态被创建；之后依据thread.run.completed事件判断模型回复是否完成，若完成则结束流传输，前端可关闭连接；若未完成，进入正常执行分支。
2. 正常执行分支：创建run后，线程进入thread.run.in_progress实际执行状态，接着创建run step（thread.run.step.created） ，随后开始生成模型回复。模型回复以消息形式输出，先创建thread.message.created消息流，进入in progress状态，通过thread.message.delta事件存储消息增量。这个过程不断循环，直到消息全部生成（以none标识），触发thread.run.step.completed事件，最后到达thread.run.completed事件，标志整个流式输出文本生成完毕，告知客户端执行结束。

三、事件流的复杂性及相关文档

除普通问答的标准事件流外，还有线程进入队列、正在进行中等诸多事件。OpenAI官方文档对所有事件有详细说明，并提供了涵盖事件描述和数据描述的表格，涉及创建线程、运行、消息处理等各类事件。

事件	描述	数据描述
thread.created	创建新线程时发生	数据是一个线程
thread.run.created	创建新运行时发生	数据是一个运行
thread.run.queued	当运行转入排队状态时发生	数据是一个运行
thread.run.in_progress	当运行进入进行中状态时发生	数据是一个运行
thread.run.requires_action	当运行需要执行外部函数调用等操作时进入该状态	数据是一个运行
thread.run.completed	运行完成时发生	数据是一个运行
thread.run.incomplete	当运行以未完成状态结束时发生	数据是一个运行
thread.run.failed	运行失败时发生	数据是一个运行
thread.run.cancelling	当运行进入取消过程中时发生	数据是一个运行
thread.run.cancelled	运行成功取消时发生	数据是一个运行
thread.run.expired	当运行超时期限时发生	数据是一个运行
thread.run.step.created	创建运行步骤时发生	数据是一个运行步骤
thread.run.step.in_progress	当运行步骤进入进行中状态时发生	数据是一个运行步骤
thread.run.step.delta	在流式传输运行步骤的过程中，按增量传输数据时发生	数据是运行步骤的增量
thread.run.step.completed	当运行步骤完成时发生	数据是一个运行步骤
thread.run.step.cancelled	取消运行步骤时发生	数据是一个运行步骤
thread.run.step.expired	当运行步骤超时期限时发生	数据是一个运行步骤
thread.message.created	创建消息时发生	数据是一条消息
thread.message.in_progress	当消息进入处理中状态时发生	数据是一条消息
thread.message.delta	当消息的一部分被传输时发生	数据是消息增量
thread.message.completed	当消息完成时发生	数据是一条消息
thread.message.incomplete	当消息在完成之前结束时发生	数据是一条消息
error	发生错误时触发，可能由内部服务器错误或超时而引发	数据包含错误信息
done	当流结束时发生	数据显示为“Done”

四、数据提取与输出方式

1. 实时回复提取：在thread.message.delta事件阶段，判断event等于thread.message.delta，提取data.delta.content[0].text.value，就能获取大模型实时回复文本。在代码中设置判断后，可实时打印出如“在一个晴朗的早晨”等模型回复内容。

run = client.threads.runs.create(
    assistant_id=assistant.id,
    thread_id=thread.id,
    stream=True  # 开启流媒体传输
)
for event in run:
    # print(event.event)
    if event.event == 'thread.message.delta':
        # 提取text delta的value
        value = event.data.delta.content[0].text.value
        print(value)

2. 最终结果获取：若想像非流式那样获取最终结果，可监听thread.message.completed事件并提取相关数据。但非流式输出等待时间长，用户无法实时了解处理进度；而流式输出能实时响应，在构建实时聊天机器人等应用时优势明显，多被采用。

run = client.threads.runs.create(
    assistant_id=assistant.id,
    thread_id=thread.id,
    stream=True  # 开启流媒体传输
)
for event in run:
    # print(event.event)
    if event.event == 'thread.message.completed':
        # 提取text delta的value
        value = event.data.content[0].text.value
        print(value)

五、其他端点启用流式传输

create thread and run方法将创建线程、追加消息和开启run状态整合为一个集成方法。使用时指定assistant_id ，在thread中追加message，用stream=true开启流式传输。它的事件流与create run本质一样，打印大模型响应文本或获取最终结果的方式也相似，实际使用时可根据需求选择分开创建或集成创建。

print(f"assistant_id:{assistant.id}")
run = client.threads.create_and_run(
    assistant_id=assistant.id,
    thread={
        "messages":[
            {"role":"user", "content":"写一篇歌颂中国的文章"}
        ]
    },
    stream=True
)
for event in run:
    print(event)