Transformers 怎么把生成结果逐段返回给网页

如果网页要边生成边显示回答，关键不是把 generate() 的最终返回值拆开，而是把生成过程接到一个可迭代的流上。Transformers 提供的 TextIteratorStreamer 会把已经整理成可读文本的片段放进队列；模型生成放到后台线程，FastAPI 再把这些片段包装成 SSE，浏览器就能逐段渲染。

一、先把模型线程和网页响应分开

一条稳定链路可以拆成四层：请求处理器接收 prompt，生成线程调用 model.generate()，TextIteratorStreamer 作为队列边界，HTTP 层把文本编码成 data: ...\n\n。网页只读取 HTTP 流，不直接接触模型对象。

这样划分的好处是模型生成速度和网络读取速度可以暂时解耦。需要注意，streamer 给出的通常是已经形成词或文本片段的内容，不等于每个 token 都立刻变成一个浏览器事件。

二、用 TextIteratorStreamer 把生成接进 FastAPI

下面的示例假设 model 和 tokenizer 已经加载。生成线程只负责调用模型；外层生成器负责把片段写成 SSE。timeout 让队列在模型线程异常或长时间没有输出时有机会退出，生产代码还应把异常状态写入事件。

from threading import Thread
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from transformers import TextIteratorStreamer

app = FastAPI()

@app.get("/generate")
def generate(prompt: str):
    # 跳过提示词，只把新生成的可读文本交给网页
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, timeout=30.0)
    generation_kwargs = {
        **inputs,
        "streamer": streamer,
        "max_new_tokens": 256,
    }

    def run_model():
        # 模型生成放到后台线程，避免阻塞响应的迭代器
        model.generate(**generation_kwargs)

    Thread(target=run_model, daemon=True).start()

    def events():
        # 每个空行结束一个 SSE 事件，浏览器才能及时收到片段
        for piece in streamer:
            safe_piece = piece.replace("\\n", "\\ndata: ")
            yield f"data: {safe_piece}\\n\\n"
        yield "event: done\\ndata: [DONE]\\n\\n"

    return StreamingResponse(
        events(),
        media_type="text/event-stream",
        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
    )

这里的两个线程边界要同时保留：如果在请求函数里直接调用 generate()，网页仍要等模型结束；如果只返回 streamer 却没有持续消费它，队列也可能堆积。模型、输入张量和显卡设备的放置方式则要按实际模型调整。

三、浏览器按事件片段更新回答

浏览器可以用 fetch() 读取响应体。网络分片不一定刚好落在 SSE 空行处，所以先把新字节追加到缓冲区，再按 \n\n 拆事件；不能假设一次 reader.read() 就是一段完整文本。

async function start(prompt) {
  // 通过 URL 参数传入本次问题，输出区持续追加文本
  const response = await fetch(`/generate?prompt=${encodeURIComponent(prompt)}`);
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  const output = document.querySelector("#output");
  let buffer = "";

  while (true) {
    // 网络分片可能截断一条 SSE，先放进缓冲区再解析
    const { value, done } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    const events = buffer.split("\\n\\n");
    buffer = events.pop() || "";
    for (const event of events) {
      const line = event.split("\\n").find((item) => item.startsWith("data: "));
      if (line && line.slice(6) !== "[DONE]") output.textContent += line.slice(6);
    }
  }
}

如果服务端把换行拆成多条 data:，前端应按 SSE 规范合并同一事件的多行数据；示例为了突出主链路只取一行。回答区使用 textContent 追加，能避免把模型输出误当作 HTML 执行。

四、卡住或提前结束时检查这几个边界

第一，模型线程抛出的异常不会自动变成友好的网页提示，实际项目应共享一个错误状态，并在事件流中发送 event: error。第二，客户端断开后要停止继续生成；可在生成器的 finally 中记录断开，再配合模型支持的取消策略。第三，Nginx 等代理可能缓冲响应，除了响应头，还要确认代理配置允许 text/event-stream 及时转发。

排查时先看三个现象：模型线程是否已经启动、streamer 是否持续产生片段、浏览器是否收到以两个换行结尾的事件。只看到完整结果，通常是 HTTP 缓冲或前端拆包逻辑的问题；完全没有结果，则优先检查输入设备、模型线程异常和 streamer 的超时。

相关问题

TextIteratorStreamer 会严格按 token 返回吗？

不会。它面向可读文本片段，会等待合适的词或文本边界后再交给迭代器，因此网页看到的是适合展示的增量内容。

为什么用了 streamer，接口仍然最后一次性返回？

常见原因是把 generate() 放在请求线程、没有用空行结束 SSE 事件，或反向代理开启了缓冲。按线程、事件格式和代理三层逐项排查即可。

参考：Hugging Face Transformers Utilities for Generation。