使用Return Generator模式获得可以for循环的流式输出

在某些情景中，开发者需要使用generator的方式获得模型请求的流式数据结果。从3.3版本起， Agently 框架就已经支持您通过以下方式使用generator替代原本的模型请求完整返回值作为返回结果，让开发者更方便地使用for循环逐项处理流式输出结果。

全新的Generator获取方法

v3.4.0.4版本更新：您现在可以通过以下方法获得不同的模型请求Generator，以使用于不同场景：

获取常规的流式输出Generator

generator = (
    agent
        .input("今天天气不错")
        .get_generator()
)

for event, data in generator:
    print(event, data)

最常规的流式输出Generator包括以下三个事件(event)

response:start：在模型开始第一个流式输出结果前发送，不包含任何事件数据(data)，常用于正式流式输出前，进行换行或其他准备操作
response:delta：每次模型输出增量文本块时，都会发送，事件数据(data)为增量文本块，类型为str
response:done：当模型完成全部内容输出后发送，事件数据块(data)为本次输出的完整文本块，类型为str

获取全量事件流式输出Generator

generator = (
    agent
        .input("今天天气不错")
        .get_complete_generator()
)

for event, data in generator:
    print(event, data)

在Agently 框架的模型请求执行过程中，除了上面最常规的流式输出事件外，通常还会包括更多其他事件，如：

response:delta_origin：会将模型接口流式返回的全量结构化数据从事件数据(data)里抛出，数据结构与模型相关，需要开发者自行查阅自己选用的模型流式返回的数据结构进行使用
response:done_origin：会将模型接口在停止输出时的结构化数据从事件数据(data)里抛出，数据结构与模型相关，需要开发者自行查阅自己选用的模型流式返回的数据结构进行使用，通常会包括安全风险信息、停止原因、token用量等有用信息
response:finally：通常用于框架内部对本次请求的所有后置处理工作完成时，发出的提示信号，开发者也可以根据这个时机自行决定是否需要添加后置处理逻辑
instant和instant:相关事件：如果手动通过agent.use_instant()方法打开了Agently Instant 模式，但没有设置该模式的监听器，也没有使用该模式的特殊Generator进行流式输出，您也可以在全量事件流式输出的Generator中捕获到相关的事件

获取Agently Instant模式的实时结构数据解析结果

使用以下监听器将自动开启Agently Instant 模式。关于该模式的详细说明请阅读此文档。

监听全量instant事件：

generator = (
    agent
        .input("Generator 10 sentences")
        .output({
            "sentences": ([("str", )]),
        })
        .get_instant_generator()
)

for item in generator:
    print(item["key"], item["delta"])

监听指定instant事件：

generator = agent.get_instant_keys_generator("instant:value_a&dict_a.key_1&list_b.[].list_with_dict_in_list_b.[].key_3?_,0")

for item in generator:
    print(item["key"], item["delta"])

与前面的常规事件Generator不同，Agently Instant 模式监听的所有事件都是instant事件，因此Generator返回的结果都是遵循instant事件数据结构的字典类数据，事件数据结构说明如下：

key: 当前正在输出的键（采用Agently Instant表达方法）
indexes: 如果当前正在输出的键路径中存在数组，indexes里会提供当前输出是路径中数组的第几项
delta: 当前正在输出的键值，如果键值类型是str，此字段更新每次添加的新内容，否则只在键值完全生成完毕后抛出事件，此时字段值和value字段值一致
value: 当前正在输出的键值，如果键值类型是str，此字段更新当前已生成的全量值，否则只在键值完全生成完毕后抛出事件，此时字段值和delta字段值一致
complete_value: 在当前事件抛出时，已经输出的结构化数据的全量内容

更多Agently Instant 模式细节欢迎阅读Agently Realtime模式说明文档

Warn

以下方法在v3.4.0.3版本之后已经过时，建议使用上面的方法获取Generator

获取generator的方式

generator = (
    agent
        .input("今天天气不错")
        #通过传递return_generator=True获取generator
        .start(return_realtime_generator=True)
)

消费generator

和其他generator类似，使用for循环即可逐项访问generator中的事件

for event in generator:
    print(event)