🏠 总目录📚 本教程 01 · 本地跑通与部署准备 ← →

AI全栈 / 01

页面能聊天,就算完成上线了吗?

先分清本地 mock、真实模型和公网部署三个完成状态,再跑通最小链路。

能说明当前验证到了哪一步,并指出还缺的部署证据。

执行本地 mock 路线

📑 本页目录(点开跳转)

01 · 第一天:先在本地跑通,再准备上线

⏱ 阅读时间仅供参考 | ⭐ 核心 | 可分次完成 | 先交付本地流式演示


🎯 一句话

先用两个文件跑通“输入一句话 → 浏览器逐步显示响应”。 默认使用模拟响应,不需要模型账号。它验证网页到后端的链路,不代表真实模型能力或已经公网部署。 这一版故意缺一大堆东西——缺什么、分别在第几章补,末尾那张表就是整个板块的路线图。


🧩 一、把三个完成状态分清

状态 能观察到什么 还不能说明什么
本地跑通 本机浏览器能收发模拟响应 别人可访问、真实模型可用
真实模型接通 显式选择真实模式后,能确认供应商接收了请求且返回内容 公网可访问、回复质量已验证
公网验收 停掉本机服务后,另一网络仍可完成请求 已具备生产安全性与稳定性

部署准备是检查文件、依赖、启动命令和配置的过程。公网验收需要独立环境实际完成请求。临时内网穿透仍依赖本机进程,平台服务也可能休眠或中断。

本页边界: 公网部分是准备与验收清单,不是已实跑的某平台操作教程;没有“两小时一定完成”的保证。


🧩 二、最短路径的四个选择

位置 选什么 为什么是这个形状
后端 FastAPI,一个文件 要一个「能异步、能分批往外写响应」的 HTTP 框架。这两条是硬需求,框架名字 🗓️ 会变
前端 一个 HTML 文件,原生 JS 现在要验证的是链路通不通,不是构建工具链。暂时不引入额外的打包工具
模型 先用模拟响应,按需再接云 API 自建推理是另一条路(全景导论 07 展开),第一天不走
部署 能跑常驻进程的平台 核对流式支持与限制,不只按平台类别判断

🧩 三、后端:先说形状,再看代码

① 密钥必须从环境变量读。 不只是安全洁癖——环境变量是常见配置入口;平台也可能支持挂载文件或密钥服务。写进代码意味着每换一次 Key 都要重新提交、重新部署,而且这份代码从此不能公开。

② 需要一个「能分批往外写、且连接保持打开」的返回方式。 浏览器想边收边显示,后端就要能在生成完之前交出一部分内容。StreamingResponse 会逐步读取生成器产出的内容。yield 交出一段,浏览器可能分几次收到它,也可能一次收到几段。FastAPI 流式响应文档。

③ 往外写的东西要分帧。 你迟早要往回送「不是正文」的东西——错误、用量、工具状态。先分帧,以后加东西不用重写前端。

用 SSE:每帧一行 data: {JSON},帧间空一行,帧的类型放在 JSON 负载的 type 字段里(delta / usage / error / done)。

⭐ 类型不放进 SSE 的 event: 行,是因为前端用 fetch 手动解析(第四节说了为什么不用 EventSource),这里的简化解析器只读 data 行;完整解析器也能读 event 行。放进 JSON 是本例约定。

⭐ 全板块统一这个格式,05 / 10 都照它来。

# app.py —— 本地教学演示,公开前需补安全与稳定性
import json
import os
import time
from pathlib import Path

from fastapi import FastAPI, Request
from fastapi.responses import FileResponse, JSONResponse, StreamingResponse

app = FastAPI()
MODE = os.environ.get("CHAT_MODE", "mock")
MOCK_CUT = os.environ.get("CHAT_MOCK_CUT") == "1"
if MODE not in {"mock", "live"}:
    raise RuntimeError("CHAT_MODE 只能是 mock 或 live")

# 默认模式不读取模型凭证。切到真实模式才校验真实配置。
if MODE == "live":
    API_KEY = os.environ.get("ANTHROPIC_API_KEY")
    MODEL = os.environ.get("MODEL")
    if not API_KEY or not MODEL:
        raise RuntimeError("live 模式需要 ANTHROPIC_API_KEY 和 MODEL")


def stream_from_model(prompt):
    if MODE == "mock":
        for ch in "(假模型)我收到了:" + prompt:
            time.sleep(0.06)
            yield ch
        return

    import anthropic  # 仅真实模式需要 pip install anthropic

    client = anthropic.Anthropic(api_key=API_KEY)
    with client.messages.stream(
        model=MODEL,
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}],
    ) as stream:
        yield from stream.text_stream


def frame(data):
    return "data: " + json.dumps(data, ensure_ascii=False) + "\n\n"


@app.post("/api/chat")
async def chat(req: Request):
    try:
        data = await req.json()
    except ValueError:
        data = None
    raw = data.get("prompt") if isinstance(data, dict) else None
    if not isinstance(raw, str) or not raw.strip():
        return JSONResponse({"error": "prompt 必须是非空文本"}, status_code=400)
    prompt = raw.strip()

    def sse():
        try:
            for i, piece in enumerate(stream_from_model(prompt), start=1):
                yield frame({"type": "delta", "text": piece})
                if MODE == "mock" and MOCK_CUT and i == 5:
                    return  # 故障演练:直接收流,不发 done
        except Exception:
            # 响应已经开始。用流内消息报错,不回显上游原始异常。
            yield frame({"type": "error", "message": "生成失败"})
        yield frame({"type": "done"})

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


@app.get("/")
def index():
    return FileResponse(Path(__file__).with_name("index.html"))

先看三处。 chat() 检查输入,错误发生在开流前时返回 HTTP 400。stream_from_model() 默认逐字产出模拟回复,真实模式要主动开启。sse() 给每段文本加上类型,最后发 done。开流后发生异常时,若响应还能继续写,先发 error,再用 done 收尾。X-Accel-Buffering: no 提示支持该响应头的代理关闭缓冲,代理实际怎样转发仍需验收。


🧩 四、前端:核心就是「读流 + 拼帧」

点「发送」时,浏览器用 fetch 发送 POST /api/chat,把问题放进请求体。浏览器原生 EventSource 不支持自定义 POST 请求体,因此本例通过 response.body 逐段读取。

<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>本地聊天演示</title>
<label for="q">输入问题</label>
<textarea id="q" rows="3" style="width:100%"></textarea>
<button id="go" type="button">发送</button>
<p id="status" role="status"></p>
<div id="out" style="white-space:pre-wrap"></div>
<script>
const q = document.getElementById('q');
const go = document.getElementById('go');
const status = document.getElementById('status');
const out = document.getElementById('out');

go.onclick = async () => {
  go.disabled = true;
  out.textContent = '';
  status.textContent = '等待响应…';
  let reader;
  let failed = false;
  try {
    const resp = await fetch('/api/chat', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({prompt: q.value.trim()})
    });
    if (!resp.ok) {
      status.textContent = '出错了:HTTP ' + resp.status;
      return;
    }
    reader = resp.body.getReader();
    const decoder = new TextDecoder('utf-8', {fatal: true});
    let buf = '';
    status.textContent = '接收中…';

    while (true) {
      const {done, value} = await reader.read();
      if (done) {
        decoder.decode();  // 检查末尾是否截断了 UTF-8 字符
        status.textContent = failed ? '响应失败' : '响应未完成';
        return;
      }
      buf += decoder.decode(value, {stream: true});
      const frames = buf.split('\n\n');
      buf = frames.pop();  // 留住尚未收到分隔符的最后一段
      for (const f of frames) {
        if (!f.startsWith('data: ')) continue;
        const frame = JSON.parse(f.slice(6));
        if (frame.type === 'delta' && !failed) out.textContent += frame.text;
        if (frame.type === 'error') {
          failed = true;
          status.textContent = '响应失败';
        }
        if (frame.type === 'done') {
          status.textContent = failed ? '响应失败' : '接收完成';
          return;
        }
      }
    }
  } catch {
    status.textContent = failed ? '响应失败' : '响应未完成';
  } finally {
    if (reader) await reader.cancel().catch(() => {});
    go.disabled = false;
  }
};
</script>
</html>

回复区只追加文本,状态行单独显示进度。 delta 追加到回复区,error 保留已收到的字并显示失败。收到 done 且此前无错误,才显示「接收完成」。网络读取返回的 done 只表示响应体读完,和应用发的 {"type":"done"} 属于不同层。一次网络读取也可能落在字符或帧的中间,所以有下面两处缓冲。

字符缓冲的参数说明可查 MDN:TextDecoder.decode 的 stream 选项。本例前端只约定了后端发出的这类数据帧,不是完整的通用 SSE 解析器。


🧩 五、先跑通本地模拟响应

准备: 已安装的 Python、终端和浏览器。新建文件夹,把第三节保存为 app.py,第四节保存为 index.html;在这个文件夹打开终端。

第一次明确使用 mock。在同一终端执行 $env:CHAT_MODE = 'mock'(PowerShell)或 export CHAT_MODE=mock(Bash),再启动。下列命令安装本地 Web 服务依赖,然后启动服务。已经装好依赖时,只执行第二行。

python -m pip install fastapi uvicorn
python -m uvicorn app:app --reload --port 8000

保持终端运行,在浏览器打开 http://127.0.0.1:8000。这个地址指向正在运行服务的本机,由服务返回 index.html。从文件夹双击页面会绕过这一步。

按三步验收这次聊天

输入「你好」后,浏览器会发出 POST /api/chat,请求体是 {"prompt":"你好"}。如需核对,可在浏览器开发者工具的「网络」面板找到 chat 这一项,检查请求、状态码及响应。

① 发问题请求体带上 prompt。
② 收到片段HTTP 200 后,delta 一段段补进回复区。
③ 看结束状态无 error 且收到 done,状态才变成「接收完成」。
正常发送

输入「你好」。回复是「(假模型)我收到了:你好」,中文完整,状态为「接收完成」。若文字一次出现,记下「整段到达」,再检查传输是否缓冲。

空输入

清空输入后点发送。服务返回 HTTP 400,页面显示「出错了:HTTP 400」,回复区为空。修改输入后可再次发送。

少了结束帧

按下文开启断流演练,再输入「你好」。这次仍收到 HTTP 200,页面只保留开头「(假模型)」,状态为「响应未完成」。

要复现第三种情况,先在终端按 Ctrl+C 停止服务。保持 CHAT_MODE 为 mock,再设置 CHAT_MOCK_CUT 为 1。PowerShell 用 $env:CHAT_MOCK_CUT = '1',Bash 用 export CHAT_MOCK_CUT=1。然后原样执行上面的启动命令并刷新网页。

测完后再次停止服务。PowerShell 用 Remove-Item Env:CHAT_MOCK_CUT,Bash 用 unset CHAT_MOCK_CUT。重启后重新发送「你好」,确认又能完成。这项演练主动让模拟流提前结束,适合重复核对界面状态。

找不到 app,先检查终端目录;缺 fastapi 或 uvicorn,确认安装与启动使用同一个 Python。停止服务后页面不能继续请求,说明它仍依赖本机进程。

验收记录。 记下浏览器看到的状态码、回复区内容和状态行。开发者工具里出现 200 只确认响应已开始;流是否完成还要看最后一项。若页面没有发出请求,先检查是否从本地服务打开,再看终端是否仍在运行。

接真实模型是另一步。 准备好账号后安装 anthropic SDK,配置 ANTHROPIC_API_KEY 和账号可用的 MODEL,再设置 CHAT_MODE=live 并重启。此时请求可能产生费用。模型、权限和费用以供应商文档为准。Anthropic 流式接口文档。


🧩 六、部署准备:暂不算公网验收

此处没有完成外部平台实跑。 先准备,再部署,最后做跨网络验收:

准备项 要确认什么
依赖 requirements.txt 记录本地验证过的版本
启动 平台要求的监听地址与端口;是否经过 shell 展开变量
流式 应用、平台和代理都允许及时转发响应
资源 请求时限覆盖目标响应;冷启动和并发可接受
配置与安全 HTTPS、密钥管理、访问控制、配额、日志与错误处理

常驻容器可以是一个选项,但 Serverless 并非默认不可用;部分函数平台支持流式,仍需核对其运行时与限制。Vercel 官方流式文档

如果平台提供 PORT 环境变量,并要求监听所有网卡,POSIX shell 中常见启动方式为:

python -m uvicorn app:app --host 0.0.0.0 --port "$PORT"

这不是所有终端都通用的命令。PowerShell 使用 $env:PORT;没有 shell 的启动配置可能不会展开变量。平台不提供 PORT 时,按文档填写端口。

部署后,用另一网络完成一次请求;停止本机服务后再测。只打开首页不等于接口可用,还要检查中文、空输入、错误响应与分批到达。

公开真实模型接口前先补护栏。 当前没有登录、配额与可靠异常处理,不要将带收费密钥的无保护端点直接开放。


🧩 七、⭐ 这一版缺什么(= 整个板块的路线图)

上一节已完成本地模拟演示。准备公开收费模型接口时,先检查访问控制、密钥和成本护栏。

十七行保留了后续主题与章节入口;编号用于查找,不是适用于所有项目的优先级或必修顺序。

# 缺什么 现在的后果 在哪补
1 ⭐ 没有限流和配额 公开收费接口后,重复或恶意请求可能消耗预算 12 章 限流与成本护栏
2 ⭐ 配置分环境与密钥轮换仍需完善 环境变量避免把密钥写进源码,但泄露后仍要撤销、替换并更新运行配置 13 章 配置与密钥
3 ⭐ 跨域、CSRF、XSS 边界尚未完整验收 当前用 textContent 显示纯文本;以后加跨域、Cookie 登录或富文本时,应分别检查相关安全边界 08b 同源策略与 CORS · 08c CSRF 与 XSS
4 ⭐ 缺少业务日志、指标与请求关联 服务启动日志不足以解释某次模型请求为何失败或变慢 15 章 可观测性
5 ⭐ 重复请求没有幂等控制 用户重发或以后加入自动重试时,可能重复生成并产生额外费用 03c 幂等与条件请求
6 未明确应用的超时、重试与缓存策略 界面会提示流未完成;SDK 默认行为不等于应用已有完整恢复策略 04 章 调用层
7 ⭐ POST /api/chat 尚未定义兼容与演进约定 接口可以改,但已有客户端依赖它时需要兼容安排 03b 接口的形状
8 真实上游取消与中途失败尚未验收 本地已能演练不带结束帧的部分回复;还要验证关页面后真实上游是否停止 05 / 10 章
9 没有数据库 请求与回复不能持久保存,刷新后无法恢复 06 章 关系数据库
10 没有登录或其他访问控制 当前接口不能验证调用者身份,也不能隔离不同用户的数据 08 章 · 08d OAuth2 与 OIDC
11 示例尚未配套项目内的自动化测试 除了协议与错误处理,还需要按任务评估模型输出;不能只靠固定全文相等判断生成质量 15b 怎么测不确定的系统
12 改一行要手动重部署 越怕出事越不敢发版 14 章 容器化与部署
13 界面只有基础发送与报错 还需加载状态、取消操作,以及读者能理解的恢复提示 09 章 最小可用前端
14 长任务依赖当前请求连接 耗时任务若需断线后继续、重试或排队,应设计后台任务机制 11 章 长任务与队列
15 没有自动检索自己的资料 可以手动把少量文字放进输入,但尚不能从资料库中检索相关片段 07 章 向量检索落地
16 没有文件上传与存储 不能直接上传文档;粘贴文本不等于具备文件处理能力 07b 文件上传与对象存储
17 没有「我的历史对话」列表 加存储后还需列表接口;数据变化时要检查分页的重复与漏项 06b 列表接口与分页

按影响范围安排下一步。 只在本机跑模拟回复,可以先理解请求与响应;准备让别人调用真实模型,应先检查身份、权限、密钥、配额和错误处理,同时保留排查问题的日志。

一条接口本身不是缺陷。 第 7 行要补的是字段、错误格式与兼容约定。已有客户端时,改名或删字段需要迁移安排;并不是接口一旦发布就永远不能修改。

第 3 行的前提可查 MDN:textContent 与 innerHTML 的区别。纯文本插入不等于将模型输出作为 HTML 执行,也不代表整个应用已完成安全验收。

💡 带字母后缀的行(03b / 03c / 06b / 07b / 08b / 08c / 15b)补的是「这个零件本来的规矩」, 主编号的章补的是「它被 AI 那四件事咬到的那一面」。⭐ 赶时间可以先跳过后缀章把主干跑通。


🔄 换个栈怎么对应

概念 FastAPI Node(Express / Hono) Go
分批往外写响应 StreamingResponse(生成器) 多次 res.write() / 返回 ReadableStream w.Write() + Flusher.Flush() ⭐
读环境变量 os.environ.get process.env os.Getenv
监听所有网卡 --host 0.0.0.0 app.listen(port, '0.0.0.0') ListenAndServe(":"+port, h)

⭐ Go 的 ResponseWriter 默认带缓冲,不手动 Flush 就攒着不发——可见「分批往外写」在每个栈里都要显式表达,只是 FastAPI 把它藏进了名字里。


🔗 这一章连到哪里

去哪 为什么
智能体工程 01 · 10 分钟造出你的第一个 Agent 同样「先跑通再问为什么」。那边是模型侧的最小闭环(模型+工具+循环),这边是产品侧的(后端+流式+公网)
智能体工程 16c · 接进真实产品 ⭐ 你刚写的流式只是能用级别。为什么必须流式、错误怎么在流里传、取消怎么穿透调用栈,都在那一章
全景导论 07 · 本地部署与开源生态 第二节那格「先用云 API」的另一条路——什么时候值得自己跑模型
ML基础 01 · 10 分钟训练你的第一个模型 连模型都还没训过就先去那边。本板块假设「模型已经好了」

✅ 检查点

  1. 本地跑通与公网验收有什么区别?
  2. 模拟响应能验证什么,不能验证什么?
  3. 流式返回有什么要求?为什么前端要保留半帧?
  4. HTTP 200 后只看到「(假模型)」且状态为「响应未完成」。还能把这次记作接收完成吗?
  5. event 行是否只能被 EventSource 理解?
  6. 判断平台能否使用,要检查什么?
  7. 公开真实模型接口前还缺什么?
👀 答案
  1. 本地只证明本机链路;公网还需另一网络的实际请求,且不依赖本机服务。
  2. 可验证收发链路,不能验证真实 API、权限、模型能力或公网部署。
  3. 应用与代理都需及时转发;流式解码保护跨分片字符,保留半帧避免 JSON 未收全就解析。Go 中还要注意刷新缓冲。
  4. 不能。HTTP 200 表示响应已开始;这条流缺少应用发出的 done。应保留部分文字,标记未完成。
  5. 不是。完整 SSE 解析器也能读它;本例把类型放在 JSON,是简化解析的约定。
  6. 流式支持、资源与时限、启动和端口、HTTPS、配置、安全与成本,不能只看平台类别。
  7. 访问控制、配额、密钥保护、超时与错误处理、日志和部署检查;环境变量不等于完整安全体系。

本节回顾

⚡ 走神救援

下一节 👉 02-一个AI产品的解剖.md。先保留这次请求的观测记录。下一章会沿着同一条路径看清各个组件的分工。

打卡记录保存在你的浏览器里,首页能看到总进度