Skip to main content
对话与会话

流式输出

默认情况下，模型一轮回复要等完整产出后才作为整段消息送达。启用流式输出后，SDK 在生成过程中持续推送细粒度增量片段，可以做打字机效果，或单独渲染推理过程、工具调用过程。

启用

在 options 里启用 partial messages（TypeScript 为 includePartialMessages，Python 为 include_partial_messages，Java 为 includePartialMessages(true)）： 
import { qodercliAuth, query } from '@qodercn-ai/qodercn-agent-sdk';

const q = query({
  prompt: 'Write a short analysis report',
  options: {
    auth: qodercliAuth(),
    includePartialMessages: true,
  },
});
Java 没有类型化的流事件。增量片段以 PartialMessage 送达，事件内容从 rawJson() 解析。下面的 Java 示例用 delta(...) 辅助方法取出事件里的 delta 对象，后面两节沿用它。

打字机效果

模型生成的文本以增量片段连续到达，逐片打印就是打字机效果： 
for await (const msg of q) {
  if (msg.type === 'stream_event') {
    const delta = msg.event.delta;
    if (delta?.type === 'text_delta') {
      process.stdout.write(delta.text);
    }
  }
}

推理过程

推理类模型在正式回复前会产出"思考"片段： 
if (delta?.type === 'thinking_delta') {
  process.stdout.write(delta.thinking);
}

工具调用入参

工具调用的参数也是逐步生成的，例如可以拿来在 UI 里实时渲染模型正在写入的文件内容： 
if (delta?.type === 'input_json_delta') {
  process.stdout.write(delta.partial_json);
}

推送式读取（Java）

上面的 Java 示例用游标逐条拉取消息。也可以让 SDK 推送：messages().consume(handler, executor) 在给定的执行器上按顺序逐条调用处理器，上一条处理完才投递下一条，消息流结束时返回的 stage 正常完成。
Java
ExecutorService executor = Executors.newSingleThreadExecutor();
try {
    query.messages().consume(msg -> {
        if (msg instanceof PartialMessage) {
            JsonObject delta = delta((PartialMessage) msg);
            if (JsonString.of("text_delta").equals(delta.get("type"))) {
                System.out.print(delta.get("text").asString());
            }
        }
    }, executor).toCompletableFuture().join();
} finally {
    executor.shutdown();
}
每个消息流只能消费一次，游标和 consume() 二选一，第二次订阅抛出 MessageStreamAlreadyConsumedException。处理器抛出异常时，consume() 返回的 stage 以 CallbackExecutionException 结束，所属的查询或会话随之关闭。不要在处理器里阻塞等待，也不要调用阻塞式 close()。 完整事件结构见 SDK References。Java 的消息类型见 Message Types。