第28章 LMQL 输出流式传输

Output Streaming Stream Query Progress In Real Time

LMQL 支持多种与周围环境交互的机制，用于实时反馈查询进度和结果，包括将中间值流式传输给调用方或通过 HTTP 连接的客户机。

本章首先介绍开箱即用的标准输出写入器，然后说明如何创建自定义输出写入器，以应对更复杂的流式场景。

标准输出写入器

若只需将当前查询输出打印到标准输出，可以使用 `lmql.printing` 输出写入器。它会在执行过程中显示查询进度以及中间验证结果。

```lmql await lmql.run("'Q: Hello\n A:[WHAT]'", output_writer=lmql.printing) ```

输出示例： Q: Hello A: Hi there! How can I assist you?

valid=True, final=True

或者，如果你只想流式传输特定变量的结果，可以使用 `lmql.stream("VAR")` 输出写入器。随着查询生成结果，它只会打印变量 VAR 的内容。

```lmql await lmql.run("'{:user} Hello\n {:assistant}[RESPONSE]'", model="chatgpt", output_writer=lmql.stream("RESPONSE")) ```

输出示例： Hello! How can I assist you today?

此外，还有 `lmql.headless` 和 `lmql.silent` 两个选项，分别用于禁用所有输入输出，以及仅禁用所有输出。两者的区别在于：`headless` 模式在查询请求用户输入（通过 `input()`）时会抛出异常，而 `silent` 模式会请求用户输入，但不会向标准输出打印任何内容。

自定义输出写入器

除了标准输出写入器，你还可以提供自己的实现，并在运行查询时通过 `output_writer=` 参数传入。

输出写入器的基本接口如下：

```python class BaseOutputWriter: async def input(self, *args): """ 处理带有 *args 提示的用户输入。当查询通过 `await input()` 请求用户输入时调用此方法。

返回: str: 用户输入。 """

async def add_interpreter_head_state(self, variable, head, prompt, where, trace, is_valid, is_final, mask, num_tokens, program_variables): """ 每当查询解释器取得有意义的进展时调用（例如添加新令牌、新变量、更新变量等）。

参数: variable (str): 当前活动变量的名称。 head (int): 当前解释头部的索引（已弃用，始终为 0）。 prompt (str): 查询的完整交互轨迹/提示词。 where (object): 查询验证条件的 AST 表示。 trace (object): 在生成过程中基于当前程序变量评估 'where' 的条件时产生的执行轨迹。 is_valid (bool): 当前程序变量是否满足验证条件。 is_final (bool): 'valid' 的值是否可视为最终结果（即再解码更多令牌也不会改变 'valid' 的值）。 mask (np.ndarray): 当前活动令牌掩码。 num_tokens (int): 当前 'prompt' 中的令牌数量。 program_variables (ProgramState): 当前程序状态（lmql.runtime.program_state）。例如，program_variables.variable_values 是变量名称与其当前值的映射。 """ ```

基于此接口，你可以实现自己的输出写入器以支持自定义流式传输。有关该接口的使用示例，请参阅 `lmql.runtime.output_writer` 中标准输出写入器的实现。