Langchain-Chatchat/callbacks.md at c49b048976d31f0f7e13a5f1d11ac209ebdd06c0

27 KiB

Raw Blame History

FunctionDef dumps(obj)

dumps: 该函数的功能是将字典对象转换为JSON格式的字符串。

参数:

obj: 需要被转换为JSON字符串的字典对象。

代码描述: dumps函数是一个简单但非常核心的功能，它接受一个字典对象作为输入参数，并使用json.dumps方法将该字典转换为一个JSON格式的字符串。在转换过程中，ensure_ascii=False参数确保了字符串中的非ASCII字符不会被转义，从而保持了原始数据的可读性和完整性。

在项目中，dumps函数被多个异步回调处理器中的方法调用，这些方法包括on_tool_start、on_tool_end、on_tool_error、on_llm_new_token、on_llm_start、on_chat_model_start、on_llm_end、on_llm_error和on_agent_finish。这些方法通常在处理某些事件（如工具开始、结束、出错等）时，需要将当前工具的状态或其他相关信息序列化为JSON字符串，并将其放入队列中等待进一步处理。通过使用dumps函数，确保了这些信息在序列化过程中的格式统一和准确性。

注意:

在使用dumps函数时，需要确保传入的对象是字典类型，因为json.dumps方法只能处理字典类型的数据。
考虑到ensure_ascii=False参数的使用，确保在处理JSON字符串的环境中支持非ASCII字符。

输出示例: 假设有一个字典对象{"name": "测试工具", "status": "运行中"}，使用dumps函数处理后的输出示例为：

{"name": "测试工具", "status": "运行中"}

这个输出是一个标准的JSON格式字符串，可以被进一步用于网络传输、存储或其他需要JSON格式数据的场景中。

ClassDef Status

Status: Status 类用于定义不同状态的常量。

属性:

start: 表示开始状态。
running: 表示运行中状态。
complete: 表示完成状态。
agent_action: 表示代理执行动作状态。
agent_finish: 表示代理完成状态。
error: 表示错误状态。
tool_finish: 表示工具执行完成状态。

代码描述: Status 类在项目中扮演了重要的角色，它通过定义一系列的整型常量来表示不同的状态，这些状态在异步回调处理中被广泛使用，以便于跟踪和管理异步任务的执行流程。例如，在处理工具启动、结束、错误等事件时，会根据不同的事件类型更新当前工具的状态。这些状态不仅帮助开发者理解当前任务的执行阶段，还能够在出现错误或完成任务时提供明确的指示，进而采取相应的处理措施。

在项目中，Status 类的状态值被用于标识异步操作的不同阶段，如在工具开始执行时标记为 agent_action，在工具执行结束时标记为 tool_finish，在遇到错误时标记为 error 等。这些状态值在 CustomAsyncIteratorCallbackHandler 类的各个方法中被引用，以便于在异步操作过程中管理和响应不同的事件。

例如，在 on_tool_start 方法中，使用 Status.agent_action 来标记当前工具的状态为代理执行动作状态；在 on_tool_end 方法中，使用 Status.tool_finish 来更新工具状态为执行完成状态；在 on_tool_error 方法中，使用 Status.error 来标记错误状态。这种状态管理机制使得异步操作的管理变得更加清晰和有序。

注意:

在使用 Status 类时，开发者需要确保正确地引用了对应的状态常量，以保证异步操作的状态能够被准确地跟踪和管理。
状态值的更新应该与实际的异步操作流程相匹配，以避免状态不一致导致的逻辑错误。
在处理异步操作时，应该根据状态值来决定下一步的操作，如是否继续执行、是否需要处理错误等，以确保程序的健壮性。

ClassDef CustomAsyncIteratorCallbackHandler

CustomAsyncIteratorCallbackHandler: CustomAsyncIteratorCallbackHandler类的功能是作为异步迭代器回调处理器，用于处理工具的启动、结束、错误以及与长期语言模型(LLM)交互的各个阶段的回调。

属性:

queue: 用于存储处理结果的异步队列。
done: 一个事件，用于标记处理完成。
cur_tool: 当前处理的工具信息。
out: 用于控制输出的标志。

代码描述: CustomAsyncIteratorCallbackHandler类继承自AsyncIteratorCallbackHandler，提供了一系列异步方法来处理不同的事件，如工具的启动(on_tool_start)、结束(on_tool_end)、错误(on_tool_error)、与LLM交互的新令牌(on_llm_new_token)、LLM的启动(on_llm_start)和结束(on_llm_end)等。这些方法通过更新cur_tool字典和向queue队列中添加信息来记录每个事件的处理结果。

在处理工具启动事件时，该类会对输入字符串进行预处理，移除可能导致处理中断的特定停止词，然后将处理后的信息加入到队列中。在工具结束或发生错误时，也会相应地更新cur_tool字典，并将结果加入队列。对于LLM的交互，该类能够处理新令牌的接收、LLM的启动和结束事件，以及错误处理，同样通过更新cur_tool字典和队列来记录状态。

此类在项目中被用于处理与长期语言模型(LLM)的交互过程中的回调，特别是在server/chat/agent_chat.py/agent_chat/agent_chat_iterator中，它被用作回调处理器来管理异步聊天迭代器的状态。通过这种方式，它能够收集和整理从LLM和其他工具中得到的输出，为最终的用户交互提供必要的信息。

注意:

在使用此类时，需要注意其异步特性，确保在适当的异步环境中调用其方法。
由于它处理的信息可能来自不同的来源（如LLM或其他工具），需要确保输入的数据格式正确，以避免处理过程中的错误。

输出示例: 假设处理了一个工具的启动和结束事件，队列中的一个可能的输出示例为：

{
  "tool_name": "示例工具",
  "input_str": "处理前的输入",
  "output_str": "处理后的输出",
  "status": "tool_finish",
  "run_id": "示例运行ID",
  "llm_token": "",
  "final_answer": "",
  "error": ""
}

这表示一个工具已经完成了它的任务，其中包含了工具的名称、输入输出字符串、状态、运行ID等信息。

FunctionDef init(self)

init: 该函数用于初始化CustomAsyncIteratorCallbackHandler类的实例。

参数: 该函数不接受任何外部参数。

代码描述: 此函数是CustomAsyncIteratorCallbackHandler类的构造函数，负责初始化类实例。在这个初始化过程中，首先通过super().__init__()调用父类的构造函数来继承父类的初始化逻辑。接着，函数创建了一个异步队列self.queue，这个队列用于存储异步操作的结果。此外，self.done是一个异步事件（asyncio.Event），用于标记异步操作何时完成。self.cur_tool是一个字典，用于存储当前工具的状态或数据。最后，self.out被设置为True，这可能表示某种输出状态或标志。

注意:

在使用CustomAsyncIteratorCallbackHandler类之前，了解异步编程和asyncio库的基本概念是非常重要的，因为该类的实现依赖于Python的异步编程特性。
self.queue用于异步任务之间的通信，确保在使用时正确处理队列中的数据。
self.done事件用于控制异步流程，特别是在需要等待某些异步操作完成时。
self.cur_tool字典的具体用途和结构应根据实际应用场景进行定义和使用。
self.out的具体含义和用途可能根据实际代码逻辑有所不同，开发者应根据上下文来理解和使用它。

FunctionDef on_tool_start(self, serialized, input_str)

on_tool_start: 该函数的功能是在工具开始执行时进行初始化和预处理操作。

参数:

serialized: 一个字典，包含序列化后的工具信息。
input_str: 字符串类型，表示工具的输入文本。
run_id: UUID类型，表示当前运行的唯一标识符。
parent_run_id: UUID类型或None，表示父运行的唯一标识符，可选参数。
tags: 字符串列表或None，表示与当前运行相关的标签，可选参数。
metadata: 字典或None，包含与当前运行相关的元数据，可选参数。
**kwargs: 接受任意额外的关键字参数。

代码描述: on_tool_start函数是CustomAsyncIteratorCallbackHandler类的一个方法，它在工具开始执行时被调用。该方法首先对输入字符串input_str进行预处理，移除可能导致处理中断的特定停止词，如"Observation:", "Thought", 等。这一步骤是为了确保输入字符串在后续处理中不会因为包含特定词汇而提前中断。

接着，方法使用serialized参数中的工具名称和处理后的input_str，以及其他相关信息（如运行ID、状态等），构建一个表示当前工具状态的字典cur_tool。这个字典包括工具名称、输入输出字符串、状态、运行ID等关键信息。

最后，on_tool_start方法调用dumps函数将cur_tool字典序列化为JSON格式的字符串，并使用queue.put_nowait方法将其异步地放入队列中。这一步是为了将当前工具的状态信息传递给其他部分的处理流程，例如用于监控、日志记录或进一步的数据处理。

在整个过程中，Status.agent_action状态被用来标记当前工具的状态，表示代理正在执行动作。这与Status类中定义的其他状态一起，帮助系统跟踪和管理异步任务的执行流程。

注意:

在使用on_tool_start方法时，确保传入的serialized参数包含必要的工具信息，如工具名称。
输入字符串input_str可能会根据预定义的停止词被截断，这一点在设计输入内容时需要考虑。
该方法是异步的，因此在调用时需要使用await关键字。
通过**kwargs参数，on_tool_start方法能够灵活接收并处理额外的关键字参数，这提供了更大的灵活性，但同时也要求调用者注意参数的正确性和相关性。

FunctionDef on_tool_end(self, output)

on_tool_end: 该函数的功能是在工具执行结束时更新工具的状态并处理输出。

参数:

output: 字符串类型，表示工具执行的输出内容。
run_id: UUID类型，表示当前运行的唯一标识符。
parent_run_id: UUID类型或None，表示父运行的唯一标识符，可选参数。
tags: 字符串列表或None，表示与当前运行相关的标签，可选参数。
**kwargs: 接收任意额外的关键字参数。

代码描述: on_tool_end函数是CustomAsyncIteratorCallbackHandler类的一个异步方法，用于处理工具执行结束后的逻辑。该函数首先将实例变量out设置为True，表示输出已经准备好。然后，使用cur_tool.update方法更新当前工具的状态为Status.tool_finish，表示工具执行完成，并将工具的输出字符串中的"Answer:"部分替换为空字符串。最后，该函数将当前工具的状态和更新后的输出通过dumps函数序列化为JSON格式的字符串，并使用queue.put_nowait方法将其放入队列中，以便进一步处理。

该函数与dumps函数和Status类有直接的关联。dumps函数用于将字典对象转换为JSON格式的字符串，确保了工具状态和输出信息在序列化过程中的格式统一和准确性。Status类提供了一系列状态常量，其中Status.tool_finish表示工具执行完成的状态，用于在工具执行结束时更新当前工具的状态。

注意:

在调用on_tool_end函数时，必须确保传入的output和run_id参数有效，且run_id应为唯一标识符。
可选参数parent_run_id和tags可以根据需要传入，以提供更多关于当前运行的上下文信息。
在处理输出字符串时，output.replace("Answer:", "")操作是为了去除可能存在的前缀"Answer:"，以获取纯净的输出内容。
该函数是异步的，因此在调用时需要使用await关键字。
在使用queue.put_nowait方法将信息放入队列时，应确保队列已经正确初始化并准备好接收数据。

FunctionDef on_tool_error(self, error)

on_tool_error: 该函数的功能是处理工具执行过程中发生的错误。

参数:

error: 异常或键盘中断的实例，表示发生的错误。
run_id: UUID格式，表示当前运行的唯一标识。
parent_run_id: UUID格式或None，表示父运行的唯一标识，如果存在的话。
tags: 字符串列表或None，表示与当前错误相关的标签。
**kwargs: 接受任意额外的关键字参数。

代码描述: on_tool_error函数是CustomAsyncIteratorCallbackHandler类中的一个异步方法，用于处理在工具执行过程中发生的错误。当工具执行过程中遇到异常或键盘中断时，此方法会被调用。函数首先使用self.cur_tool.update方法更新当前工具的状态为Status.error，并记录错误信息。接着，它将当前工具的状态和错误信息序列化为JSON格式的字符串，并使用self.queue.put_nowait方法将该字符串放入队列中，以便后续处理。

该函数与dumps函数和Status类有直接的关联。dumps函数用于将字典对象转换为JSON格式的字符串，确保错误信息和工具状态以正确的格式被序列化和传输。Status类则提供了一个error状态常量，用于明确标识工具当前处于错误状态。这种设计使得错误处理过程既清晰又高效，便于后续的错误追踪和处理。

注意:

在调用此函数时，必须确保传入的error参数是一个异常或键盘中断的实例，以便正确记录错误信息。
run_id和parent_run_id参数应为有效的UUID格式，以确保能够准确追踪到具体的运行实例和其父实例（如果有）。
tags参数可以用于提供额外的错误上下文信息，有助于错误的分类和分析。
该函数是异步的，调用时需要使用await关键字。

FunctionDef on_llm_new_token(self, token)

on_llm_new_token: 该函数的功能是处理新的LLM（Large Language Model）生成的令牌。

参数:

token: 字符串类型，表示LLM生成的新令牌。
**kwargs: 接收任意数量的关键字参数，这些参数可以在函数体内使用，但在当前函数实现中未直接使用。

代码描述: on_llm_new_token函数是CustomAsyncIteratorCallbackHandler类的一个异步方法，主要用于处理由大型语言模型生成的新令牌。函数首先定义了一个名为special_tokens的列表，其中包含了特定的令牌字符串，如"Action"和"<|observation|>"。这些特殊令牌用于识别LLM生成的令牌中是否包含特定的动作或观察结果。

函数接着遍历special_tokens列表，检查传入的token是否包含列表中的任一特殊令牌。如果发现token中包含特殊令牌，函数将执行以下操作：

使用split方法分割token，以特殊令牌为界，取分割后的第一部分作为before_action。
调用self.cur_tool.update方法更新当前工具的状态为Status.running，并将before_action加上换行符后设置为llm_token。
使用dumps函数将self.cur_tool对象转换为JSON格式的字符串，并通过self.queue.put_nowait方法将其放入队列中。
设置self.out为False，并终止循环。

如果token非空且self.out为True（即未找到特殊令牌），则直接将token作为llm_token更新到self.cur_tool中，并同样将其序列化后放入队列。

此函数通过检查LLM生成的令牌是否包含特定的动作或观察结果，来决定是否更新当前工具的状态和内容，并将更新后的信息放入队列中，以供后续处理。

注意:

函数中使用了dumps函数将字典对象序列化为JSON字符串，这一步骤是为了确保队列中的数据格式统一，便于后续的处理和传输。
Status.running是从Status类中引用的一个状态值，表示当前工具或任务正在运行中。在更新工具状态时，需要确保使用正确的状态值。
函数的异步性质要求调用者在使用时配合await关键字，以确保异步操作的正确执行。
函数实现中未直接使用**kwargs参数，这意味着函数设计上允许接收额外的关键字参数，以便于未来扩展或在不同上下文中灵活使用。

FunctionDef on_llm_start(self, serialized, prompts)

on_llm_start: 该函数的功能是在长期学习模型（LLM）启动时更新当前工具的状态并将其序列化后放入队列中。

参数:

serialized: 一个字典，包含序列化信息，其类型为Dict[str, Any]。
prompts: 一个字符串列表，包含提示信息，其类型为List[str]。
**kwargs: 接收任意数量的关键字参数，其类型为Any。

代码描述: on_llm_start函数是CustomAsyncIteratorCallbackHandler类的一个异步方法，主要用于处理长期学习模型（LLM）启动时的逻辑。在该方法中，首先通过调用self.cur_tool.update方法更新当前工具的状态为Status.start，并将llm_token设置为空字符串。这表示当前工具已经开始执行，但尚未生成或接收到任何LLM令牌。

接下来，该方法使用dumps函数将self.cur_tool对象序列化为JSON格式的字符串。dumps函数是一个核心功能，它接受一个字典对象作为输入，并将其转换为JSON格式的字符串，确保了非ASCII字符的可读性和完整性。在本方法中，dumps函数的使用确保了当前工具状态的序列化信息格式统一和准确性。

最后，序列化后的字符串通过self.queue.put_nowait方法立即放入队列中，等待进一步处理。这一步骤是异步操作的一部分，确保了即使在高并发环境下，也能高效地处理大量的任务。

注意:

在使用on_llm_start方法时，需要确保传入的serialized参数是正确格式的字典，以及prompts参数是一个字符串列表。这些参数对于方法的执行至关重要。
该方法是异步的，因此在调用时需要使用await关键字。
更新状态和序列化操作应该与实际的LLM启动逻辑相匹配，以确保状态的准确性和信息的完整性。
在处理异步任务时，应当注意异常处理，确保即使在遇到错误的情况下，也能保证程序的稳定运行。

FunctionDef on_chat_model_start(self, serialized, messages)

on_chat_model_start: 该函数的功能是在聊天模型开始时进行初始化设置。

参数:

serialized: 一个字典类型参数，包含序列化信息。
messages: 一个列表类型参数，包含消息列表。
run_id: 一个UUID类型参数，表示运行的唯一标识。
parent_run_id: 一个可选的UUID类型参数，表示父运行的唯一标识。
tags: 一个可选的字符串列表类型参数，包含标签信息。
metadata: 一个可选的字典类型参数，包含元数据信息。
**kwargs: 接收任意额外的关键字参数。

代码描述: on_chat_model_start函数是CustomAsyncIteratorCallbackHandler类的一个方法，它主要用于处理聊天模型开始时的初始化工作。在这个方法中，首先通过self.cur_tool.update方法更新当前工具的状态为Status.start，并将llm_token设置为空字符串。这表示聊天模型开始执行，且当前没有任何长寿命模型（Long-Lived Model）的令牌。接着，使用self.queue.put_nowait方法将self.cur_tool的序列化信息（通过dumps函数转换为JSON格式的字符串）立即放入队列中，以便后续处理。

这个方法中调用了两个重要的对象：Status和dumps。Status类用于定义不同的状态常量，其中Status.start表示开始状态，用于标识聊天模型的启动。dumps函数用于将字典对象转换为JSON格式的字符串，这里它被用来序列化self.cur_tool的信息，以便将这些信息以字符串形式放入队列中。

注意:

在调用on_chat_model_start方法时，需要确保传入的参数符合要求，特别是run_id必须是有效的UUID。
serialized参数应包含所有必要的序列化信息，以确保聊天模型可以正确初始化。
使用tags和metadata参数可以提供额外的上下文信息，但它们是可选的。
该方法是异步的，因此在调用时需要使用await关键字。
在实际应用中，应注意**kwargs参数的使用，确保不会传入意外的关键字参数，以避免潜在的错误。

FunctionDef on_llm_end(self, response)

on_llm_end: 该函数的功能是在LLM(大型语言模型)任务结束时更新当前工具的状态并将其放入队列中。

参数:

response: LLMResult类型，表示LLM任务的结果。
**kwargs: 接受任意额外的关键字参数，提供了函数调用的灵活性。

代码描述: on_llm_end函数是CustomAsyncIteratorCallbackHandler类的一个异步方法，它在大型语言模型(LLM)任务结束时被调用。此函数首先使用self.cur_tool.update方法更新当前工具的状态为Status.complete，表示任务已完成，并设置llm_token为换行符("\n")。这一步骤是为了标记当前处理的工具或任务已经完成，准备进行下一步操作。

接着，函数使用self.queue.put_nowait方法将self.cur_tool的JSON字符串表示（通过调用dumps函数转换得到）放入队列中，以便后续处理。dumps函数将self.cur_tool字典对象转换为JSON格式的字符串，确保了信息在序列化过程中的格式统一和准确性。这一步骤是异步处理流程中的一个关键环节，它确保了任务状态的更新和信息的传递能够及时且准确地完成。

在整个项目中，dumps函数和Status类是与on_llm_end函数紧密相关的两个对象。dumps函数负责将字典对象序列化为JSON字符串，而Status类提供了一组预定义的状态常量，用于标识异步操作的不同阶段。这些工具和机制共同支持了on_llm_end函数的实现，使其能够有效地管理和传递LLM任务的结束状态。

注意:

在调用on_llm_end函数时，需要确保传入的response参数是LLMResult类型，以保证函数能够正确处理LLM任务的结果。
函数内部使用了**kwargs来接受任意额外的关键字参数，这提供了调用时的灵活性，但调用者应注意只传递需要的参数，避免不必要的混淆。
更新状态和放入队列的操作是异步执行的，调用此函数时应注意处理可能出现的异步执行相关的问题，如并发控制和异常处理。

FunctionDef on_llm_error(self, error)

on_llm_error: 该函数的功能是处理LLM错误事件。

参数:

error: 接收一个异常对象，可以是Exception或KeyboardInterrupt类型，表示发生的错误。
**kwargs: 接收任意数量的关键字参数，提供额外的灵活性以处理不同的错误情况。

代码描述: on_llm_error函数是CustomAsyncIteratorCallbackHandler类的一个方法，专门用于处理LLM（长寿命模型）在执行过程中遇到的错误。当LLM执行过程中发生错误时，此函数会被触发。

在函数内部，首先通过self.cur_tool.update方法更新当前工具的状态为Status.error，并记录错误信息。这里的Status.error是一个从Status类中定义的常量，表示当前工具处于错误状态。错误信息则通过将error参数转换为字符串形式来记录。

接下来，函数使用self.queue.put_nowait方法将当前工具的状态信息异步地放入队列中。在放入队列之前，使用dumps函数将工具状态信息序列化为JSON格式的字符串。dumps函数是一个关键的功能，它将字典对象转换为JSON格式的字符串，确保了信息在网络传输或存储过程中的格式统一和准确性。

注意:

在处理LLM错误时，确保传递给on_llm_error函数的error参数包含了足够的错误信息，以便于准确记录和后续处理。
使用**kwargs参数提供了额外的灵活性，但在调用时需要注意传递的关键字参数应与错误处理逻辑相匹配。
在更新工具状态和序列化状态信息时，应确保操作的原子性和错误处理机制，避免因异常处理不当导致的进一步错误。
考虑到dumps函数的使用，确保传入的对象符合JSON序列化的要求，并注意处理非ASCII字符的情况。

FunctionDef on_agent_finish(self, finish)

on_agent_finish: 该函数的功能是在代理执行完成时更新当前工具的状态，并将其最终结果放入队列中。

参数:

finish: 一个AgentFinish类型的对象，包含代理执行的最终结果。
run_id: 一个UUID类型的对象，表示当前运行的唯一标识。
parent_run_id: 一个可选的UUID类型的对象，表示父运行的唯一标识。
tags: 一个可选的字符串列表，包含与当前运行相关的标签。
**kwargs: 接受任意额外的关键字参数。

代码描述: on_agent_finish函数是CustomAsyncIteratorCallbackHandler类的一个异步方法，它在代理执行完成时被调用。该方法首先使用finish.return_values["output"]获取代理执行的最终输出结果，并将当前工具的状态更新为Status.agent_finish，同时设置最终答案为代理的输出结果。然后，它使用dumps函数将当前工具的状态序列化为JSON格式的字符串，并使用put_nowait方法将这个字符串放入队列中，以便后续处理。最后，cur_tool被重置为空字典，为下一次代理执行做准备。

在这个过程中，dumps函数负责将字典对象转换为JSON格式的字符串，确保了信息在序列化过程中的格式统一和准确性。Status类提供了agent_finish状态，标识代理执行已完成，这对于跟踪和管理异步任务的执行流程至关重要。

注意:

确保finish参数提供了有效的代理执行结果，特别是finish.return_values["output"]能够正确获取到输出结果。
使用dumps函数时，需要确保传入的对象是字典类型，以避免序列化错误。
在将信息放入队列时，使用put_nowait方法可以避免阻塞，但需要确保队列处理速度足以应对放入的速度，避免队列溢出。

输出示例: 由于on_agent_finish方法没有返回值，其主要作用是更新状态并将信息放入队列，因此没有直接的输出示例。但可以假设在代理执行完成后，队列中将包含一个类似于以下的JSON格式字符串：

{"status": 5, "final_answer": "代理执行的输出结果"}

这表示当前工具的状态已更新为代理完成状态，且最终答案已设置为代理的输出结果。

27 KiB Raw Blame History Unescape Escape