第13课

流式输出：让结果一点点出现

长回答不用等全部生成完，可以像打字一样逐步显示。

本课项目：流式 AI 聊天页面

学习重点：Streaming、异步、用户体验。工具重点：Streaming Responses。

AI 工具地图

OpenAI 项目工具栈

页面里加入 OpenAI、Node.js、Python 和 JSON 图标，帮助学生把 AI 能力、后端调用、脚本实验和结构化输出放在同一条学习路线里理解。

学习路线

阶段入口与周课入口

先用阶段卡片看清大方向，再用周课卡片进入具体项目。每节课都保留理论、例子、Node.js、Python、练习和自测，学生可以直接按卡片推进。

OpenAI 项目地图

阶段入口

第1-3课

第01阶段：AI应用基础与 OpenAI 入门

先看懂 AI 应用的工作流程，再完成第一次 API 调用，最后学会写清楚提示词。

理论路线项目示例阶段闯关

进入学习

第4-5课

第02阶段：让 AI 输出程序能读懂的结果

AI 不只要会说话，还要按固定格式交答案，这样程序才能稳定处理。

理论路线项目示例阶段闯关

进入学习

第6-7课

第03阶段：Function Calling：让 AI 调用函数

AI 负责理解语言，函数负责精确计算；两者配合，结果更可靠。

理论路线项目示例阶段闯关

进入学习

第8-9课

第04阶段：多模态应用：文字 + 图片

把图片也交给 AI 看，再让它用清楚的文字或 JSON 结果回答。

理论路线项目示例阶段闯关

进入学习

第10-11课

第05阶段：内置工具：Web Search 与 File Search

需要最新消息时查网页；需要班级资料时查文件。先找资料，再回答。

理论路线项目示例阶段闯关

进入学习

第12-13课

第06阶段：前后端 AI 应用开发

把 AI 能力做成网页：前端收集输入，后端保护密钥，页面展示结果。

理论路线项目示例阶段闯关

进入学习

第14-15课

第07阶段：AI Agent、安全与成本

Agent 会按步骤完成任务，但你要给它工具、边界、检查规则和预算意识。

理论路线项目示例阶段闯关

进入学习

第16课

第08阶段：毕业项目发布会

把前面学过的提示词、JSON、函数、检索、网页和安全设计合在一个作品里。

理论路线项目示例阶段闯关

进入学习

周课入口

第06阶段

第12课：AI Web应用搭建

把 AI 做成一个网页：用户输入，后端调用，页面显示。

项目：AI故事生成网页Node.jsPython

进入学习

第06阶段

第13课：流式输出：让结果一点点出现

长回答不用等全部生成完，可以像打字一样逐步显示。

项目：流式 AI 聊天页面Node.jsPython

进入学习

13.1 今天你要完成什么

流式输出就像水流。模型生成一点，页面就显示一点，用户会觉得应用反应更快。

能解释普通输出和流式输出的区别。
能让页面逐步显示模型回复。
能在生成中显示“正在思考”。
能处理用户连续点击的问题。

本课闯关：完成“流式 AI 聊天页面”，并用 3 组输入测试它。

13.2 核心理论

理论不是背概念，而是帮你判断项目为什么这样设计。下面这些规则会在代码里反复出现。

核心理论：网页 AI 应用通常分成前端和后端。前端负责界面，后端负责调用 OpenAI 和保护密钥。
交互理论：用户不只关心答案，也关心等待过程、错误提示、按钮状态和结果展示是否清楚。
流式理论：streaming 会把回答分片传回页面，适合长回答和聊天体验。
输入契约：先规定用户要给什么资料。本课的输入要围绕“流式 AI 聊天页面”，不要让用户随便输入到程序无法处理。
输出契约：先规定 AI 必须交出什么结果。本课重点是“Streaming、异步、用户体验”，所以输出要能被人读懂，也要方便程序检查。
验证思维：AI 的一次好结果不等于项目可靠。至少用正常输入、边界输入、异常输入各测一次。
安全边界：API Key 是密码，不能写进浏览器前端，不能发截图，不能提交到公开仓库。

13.3 课堂讲解

这一课的项目是“流式 AI 聊天页面”，重点是“Streaming、异步、用户体验”。你可以把它当成一个小实验：先给它一个清楚输入，再观察代码里哪些地方用到了 Streaming Responses。课堂里我们不会一上来就追求复杂功能，而是先把最小版本做出来。最小版本跑通以后，你再改输入、改提示词、改输出格式，变化就会看得很清楚。

这几课把能力做成网页。网页项目会让你看到真实用户体验：按钮、等待、错误提示、结果展示，一个都不能少。

本课有一条很实用的学习线索：先问“用户到底给了什么”，再问“程序希望拿到什么”。比如你可以试这些输入：写一个 300 字故事；解释递归，慢慢显示；生成一份 5 步学习计划。这些输入故意有简单的，也有容易出问题的。正常输入能帮你确认功能；短输入、空输入、奇怪输入能帮你发现系统边界。

写代码时建议你分三轮。第一轮只跑通官方调用，不加自己的想法；第二轮把输入换成自己的例子，看看结果是否还合理；第三轮才开始改结构，比如增加字段、加错误提示、做网页交互。这个顺序有点慢，但很稳。真正浪费时间的不是慢，而是一下子改太多，最后不知道错在哪里。

前端不能保存 API Key。浏览器里的代码别人能看到，密钥一旦放进去，就像把钥匙贴在门上。

理论部分要和代码一起看。比如“输入契约”不是一个漂亮词，它在代码里就是长度检查、必填字段、表单校验；“输出契约”也不是空话，它在代码里就是 JSON Schema、固定字段或页面渲染规则。你每写一行检查代码，都是在告诉系统：什么结果可以接受，什么结果需要退回去重新处理。

课堂里可以把同桌当成第一个用户。你把项目跑给同桌看，让对方换一个输入，观察系统会不会乱。很多问题都是别人随手一试才出现的，比如输入太短、问题太模糊、连续点击按钮、图片看不清。能处理这些小麻烦，作品就会从“我电脑上能跑”变成“别人也能用”。

最后做复盘时，不要只写“我学会了调用 API”。可以写得更具体：我学会了怎样限制输入，怎样让输出固定，怎样判断结果不可靠，怎样把报错变成用户看得懂的提示。这样的复盘有用，因为下一课你真的会再次用到它。

课堂讨论题

如果把“流式 AI 聊天页面”交给低年级学生使用，哪一步最容易让他们困惑？
这个项目里，哪些事情适合交给模型，哪些事情应该交给普通代码？
如果模型给出一个看起来不错但没有依据的答案，你打算怎样提醒用户？
你能不能把今天的项目换一个主题，但保持同样的输入、处理、输出结构？
如果只能保留一个测试用例，你会保留正常输入、边界输入还是异常输入？为什么？

13.4 先看例子

先把例子看懂，再动手写代码。你不需要一次记住所有概念，先能说清楚“输入是什么、输出是什么、程序要检查什么”。

普通输出

等完整故事生成完，页面一次性显示。

流式输出

标题先出现，第一句出现，第二句出现……用户不用一直等。

页面提示

按钮变成“生成中”，输入框暂时禁用，生成完成后恢复。

你可以替换成这些输入

写一个 300 字故事。
解释递归，慢慢显示。
生成一份 5 步学习计划。
连续点击两次生成按钮。
网络失败后重试。

13.5 完整代码实现

下面同时给出 Node.js 和 Python 两套完整最小实现。先任选一种原样跑通，再改输入、改提示词、改输出格式。

Node.js 运行方式

新建文件 lesson-13.mjs，把下面完整代码放进去。
在终端运行：npm init -y
安装依赖：npm install openai express
设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
运行：node lesson-13.mjs
运行后打开浏览器访问 http://localhost:3000。

Node.js 完整代码

import express from "express";
import OpenAI from "openai";

const app = express();
const client = new OpenAI();
const MODEL = process.env.OPENAI_MODEL || "gpt-5.5";

app.get("/", (req, res) => {
  res.send(`
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>流式 AI 聊天页面</title>
  <style>
    body { font-family: sans-serif; max-width: 760px; margin: 40px auto; line-height: 1.7; }
    input, button { width: 100%; padding: 10px; margin: 6px 0 14px; }
    #result { white-space: pre-wrap; background: #f4f7ff; padding: 16px; border-radius: 8px; min-height: 120px; }
  </style>
</head>
<body>
  <h1>流式 AI 聊天页面</h1>
  <input id="question" value="用简单例子解释递归。">
  <button id="btn">开始生成</button>
  <div id="result"></div>
  <script>
    const btn = document.querySelector("#btn");
    const result = document.querySelector("#result");
    btn.onclick = () => {
      btn.disabled = true;
      result.textContent = "";
      const q = encodeURIComponent(document.querySelector("#question").value);
      const events = new EventSource("/api/stream?question=" + q);
      events.onmessage = (event) => {
        const data = JSON.parse(event.data);
        if (data.delta) result.textContent += data.delta;
        if (data.done) {
          events.close();
          btn.disabled = false;
        }
      };
      events.onerror = () => {
        events.close();
        btn.disabled = false;
        result.textContent += "\\n[连接中断，请重试]";
      };
    };
  </script>
</body>
</html>`);
});

app.get("/api/stream", async (req, res) => {
  const question = String(req.query.question || "").slice(0, 300);

  res.setHeader("Content-Type", "text/event-stream; charset=utf-8");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");

  const stream = await client.responses.create({
    model: MODEL,
    input: `请给 10-14 岁学生回答：${question}`,
    stream: true,
  });

  for await (const event of stream) {
    if (event.type === "response.output_text.delta") {
      res.write(`data: ${JSON.stringify({ delta: event.delta })}\n\n`);
    }
  }

  res.write(`data: ${JSON.stringify({ done: true })}\n\n`);
  res.end();
});

app.listen(3000, () => {
  console.log("打开 http://localhost:3000");
});

Python 运行方式

新建文件 lesson-13.py，把下面完整代码放进去。
建议新建虚拟环境后再安装依赖。
安装依赖：pip install openai flask
设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
运行：python lesson-13.py
运行后打开浏览器访问 http://localhost:3000。

Python 完整代码

from flask import Flask, Response, request
from openai import OpenAI
import json
import os

app = Flask(__name__)
client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")


@app.get("/")
def index():
    return """
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>流式 AI 聊天页面</title>
  <style>
    body { font-family: sans-serif; max-width: 760px; margin: 40px auto; line-height: 1.7; }
    input, button { width: 100%; padding: 10px; margin: 6px 0 14px; }
    #result { white-space: pre-wrap; background: #f4f7ff; padding: 16px; border-radius: 8px; min-height: 120px; }
  </style>
</head>
<body>
  <h1>流式 AI 聊天页面</h1>
  <input id="question" value="用简单例子解释递归。">
  <button id="btn">开始生成</button>
  <div id="result"></div>
  <script>
    const btn = document.querySelector("#btn");
    const result = document.querySelector("#result");
    btn.onclick = () => {
      btn.disabled = true;
      result.textContent = "";
      const q = encodeURIComponent(document.querySelector("#question").value);
      const events = new EventSource("/api/stream?question=" + q);
      events.onmessage = (event) => {
        const data = JSON.parse(event.data);
        if (data.delta) result.textContent += data.delta;
        if (data.done) {
          events.close();
          btn.disabled = false;
        }
      };
      events.onerror = () => {
        events.close();
        btn.disabled = false;
        result.textContent += "\\n[连接中断，请重试]";
      };
    };
  </script>
</body>
</html>
"""


@app.get("/api/stream")
def stream_answer():
    question = request.args.get("question", "")[:300]

    def generate():
        stream = client.responses.create(
            model=MODEL,
            input=f"请给 10-14 岁学生回答：{question}",
            stream=True,
        )
        for event in stream:
            if event.type == "response.output_text.delta":
                payload = json.dumps({"delta": event.delta}, ensure_ascii=False)
                yield f"data: {payload}\n\n"
        yield f"data: {json.dumps({'done': True})}\n\n"

    return Response(generate(), mimetype="text/event-stream")


if __name__ == "__main__":
    app.run(port=3000, debug=True, threaded=True)

13.6 跟着做

先跑通非流式版本。
打开流式输出。
前端一边接收片段，一边追加到页面。
生成时禁用按钮，避免重复请求。
结束后显示完成状态。

13.7 常见错误

还没跑通普通版本就直接做流式。
重复点击导致多个回答混在一起。
生成失败时页面一直显示等待。
没有给用户停止或重试的机会。

排查顺序：先看输入，再看提示词，再看输出格式，最后看程序逻辑。

13.8 课后练习

给你的 AI 网页加“生成中”状态。
让长回答逐步显示。
记录一次失败情况，并设计重试按钮文案。

13.9 自测清单

我能说出流式输出的好处吗？
生成时按钮状态是否正确？
失败时页面有没有恢复？
用户体验是不是比等待整段结果更好？

上一课返回第06阶段下一课