📑 本页目录(点开跳转)
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 是本例约定。
# 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"} 属于不同层。一次网络读取也可能落在字符或帧的中间,所以有下面两处缓冲。
decoder.decode(value, {stream: true}):先保留不完整的 UTF-8 字节。常见汉字通常占 3 字节,也有 4 字节字符;如果切片从字符中间断开,直接逐片解码可能出现�。只测 ASCII 文本不容易发现这个问题。frames.pop():先保留最后一段,等下一批数据补齐。例如刚收到data: {"te时还不能解析 JSON;遇到帧分隔符后再处理完整消息。
字符缓冲的参数说明可查 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 这一项,检查请求、状态码及响应。
输入「你好」。回复是「(假模型)我收到了:你好」,中文完整,状态为「接收完成」。若文字一次出现,记下「整段到达」,再检查传输是否缓冲。
清空输入后点发送。服务返回 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 分钟训练你的第一个模型 | 连模型都还没训过就先去那边。本板块假设「模型已经好了」 |
✅ 检查点
- 本地跑通与公网验收有什么区别?
- 模拟响应能验证什么,不能验证什么?
- 流式返回有什么要求?为什么前端要保留半帧?
- HTTP 200 后只看到「(假模型)」且状态为「响应未完成」。还能把这次记作接收完成吗?
- event 行是否只能被 EventSource 理解?
- 判断平台能否使用,要检查什么?
- 公开真实模型接口前还缺什么?
👀 答案
- 本地只证明本机链路;公网还需另一网络的实际请求,且不依赖本机服务。
- 可验证收发链路,不能验证真实 API、权限、模型能力或公网部署。
- 应用与代理都需及时转发;流式解码保护跨分片字符,保留半帧避免 JSON 未收全就解析。Go 中还要注意刷新缓冲。
- 不能。HTTP 200 表示响应已开始;这条流缺少应用发出的
done。应保留部分文字,标记未完成。 - 不是。完整 SSE 解析器也能读它;本例把类型放在 JSON,是简化解析的约定。
- 流式支持、资源与时限、启动和端口、HTTPS、配置、安全与成本,不能只看平台类别。
- 访问控制、配额、密钥保护、超时与错误处理、日志和部署检查;环境变量不等于完整安全体系。
本节回顾
⚡ 走神救援
- 先做本地模拟响应,不把它当成真实模型或公网上线。
- 两个文件同一目录,安装与启动使用同一个 Python。
- 流式解码保住多字节字符,缓冲区保住尚未收齐的帧。收到正常结束帧后才记为完成。
- 外部 API 与公网分别验证,公开前补安全护栏。
下一节 👉 02-一个AI产品的解剖.md。先保留这次请求的观测记录。下一章会沿着同一条路径看清各个组件的分工。