Lecture on Hao · AI Agent 学习记录

第 1 章讲义 · 05 LLM Gateway（统一模型调用服务）

Mon, 10 Aug 2026 20:00:00 +0800

配套代码：整个 src/anna/server/ + src/anna/providers/，入口 main.py

学完本节，你应该能回答：Gateway 解决什么问题？密钥为什么集中在网关？请求/响应各在哪层校验？模板、错误、用量为什么都要"统一"？

FastAPI LLM 服务：统一入口与密钥管理
模型调用接口：封装 OpenAI Compatible
Streaming 输出：网关代理逐块转发
Structured Output：屏蔽底层差异
Pydantic 数据校验：入口与出口
Prompt 模板：网关统一管理
错误处理与重试：限流、超时、fallback
Token / Cost / Latency 日志

1. FastAPI LLM 服务：统一入口与密钥管理

Gateway 解决的第一件事：各组件不需要各自维护 API 密钥和厂商配置。 业务代码只调一个 HTTP 入口，密钥、端点、模型清单全部集中在网关的配置层（src/anna/config.py，环境变量驱动）：

export DASHSCOPE_API_KEY=... # 网关统一持有
export ANNA_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

业务组件永远不接触厂商 SDK 和密钥，只发请求：

import httpx
resp = httpx.post(
 "http://127.0.0.1:8000/v1/chat/completions",
 json={"model": "auto", "messages": [{"role": "user", "content": "hi"}]},
)

这带来三个收益：密钥泄露面缩小（只有网关持有）、厂商切换对业务无感、调用行为（限流/用量/错误）全部可观测。入口是 FastAPI 应用（main.py + create_app），/docs 自带 Swagger 调试。

第 1 章讲义 · 04 Structured Output 结构化输出

Mon, 10 Aug 2026 19:50:00 +0800

配套代码：结构化引擎 src/anna/structured.py、网关端点 /v1/structured （src/anna/server/app.py）、三家 provider 的原生结构化输出实现、首页"结构化输出"面板

学完本节，你应该能回答：为什么 Agent 不能靠自然语言解析？JSON Schema 怎么定义？Pydantic 和 Schema 是什么关系？模型原生结构化输出怎么用？校验失败怎么纠错、怎么降级？

1. 为什么不能依赖自然语言解析

Agent 系统里，模型输出要喂给代码：查词结果要填进卡片、工具参数要发请求、 SQL 要执行。自然语言解析的典型翻车：

模型回复："好的，单词是 hello，意思是 你好，例句是 Hello world！"

正则/切片解析这种输出，任何换行、加粗、多余解释都会破坏结果；更糟的是解析失败时你不知道它是格式错了还是答案错了。所以工程原则是：

输出协议先行：先定义"模型必须返回什么形状"，再让它生成；
校验兜底：返回后必须校验，而不是信任；
失败有出路：校验不过就纠错重试或降级，绝不把脏数据传给下游。

2. JSON Schema：定义输出结构

JSON Schema 是描述 JSON 结构的标准：字段名、类型、是否必填、取值范围。它是 跨语言的协议语言——模型、Python、前端都能理解。

第 1 章讲义 · 03 Prompt Engineering

Mon, 10 Aug 2026 19:40:00 +0800

配套代码：模板库 src/anna/prompts.py、种子模板 prompts.json、模板 API src/anna/server/app.py、首页模板管理与注入演示（src/anna/server/static/index.html）

学完本节，你应该能回答：System Prompt 该写什么？怎么让输出风格可控？ Few-shot 什么时候有效？复杂任务为什么要拆步？模板怎么做到可复用可版本化？用户输入怎么注入指令、怎么防？

1. System Prompt 的职责

System Prompt 相当于模型的岗位说明书：它不回答具体问题，而是定义"你是谁、要完成什么、边界是什么"。它的四个作用：

设定全局行为基调（语气、语言、价值观约束）；
声明任务目标（这个系统是干嘛的）；
定义输入输出约定（收到什么、返回什么格式）；
声明不可越界的规则（不执行用户内嵌指令、不泄露设定）。

本仓库的种子模板 reading_assistant 就是一个 System Prompt 实例（prompts.json）：

你是 Anna，一位耐心、爱读书、会催你复习的英语陪练。
当前学习者水平：{user_level}。
回答使用英语为主、中文解释为辅，遇到新词主动给出释义与例句。

{user_level} 是可变参数——同一个岗位说明书，可以按学习者水平渲染不同版本：

from anna.prompts import PromptStore
store = PromptStore.load()
system = store.render("reading_assistant", user_level="初级")
# => "你是 Anna，一位耐心、爱读书、会催你复习的英语陪练。\n当前学习者水平：初级。..."

关键认知：System Prompt 和用户消息是两个独立通道（role: system vs role: user），模型通常给 system 更高权重。这也是为什么第 7 节"注入防护" 要从 system 层做，而不是在用户消息里补救。

第 1 章讲义 · 02 Streaming 流式输出

Mon, 10 Aug 2026 19:30:00 +0800

配套代码：网关的流式端点（src/anna/server/app.py）、SSE 组装与解析（src/anna/server/openai_format.py、src/anna/providers/base.py）、首页可视化测试台（src/anna/server/static/index.html）

学完本节，你应该能回答：为什么要把一次 LLM 调用切成一块一块返回？ SSE 协议长什么样？FastAPI 怎么保持低延迟转发？前端怎么逐块消费？用户点"停止"会发生什么？流到一半断了怎么处理？长文本怎么续写？

1. 为什么需要 Streaming

LLM 推理不是"秒回"：一次回答要先经过提示词处理、逐 token 自回归生成，短则几秒、长则几十秒。非流式 = 客户端一直等到全部生成完才拿到第一个字，用户看到的是一片空白；流式 = 模型每吐出一个 token 就立刻送出去，用户看到的是"边生成边打字"。

衡量这个差距有两个指标：

首字节耗时（time to first byte, TTFB）：从发出请求到收到第一块内容；
总耗时：从发出请求到收到最后一块内容。

非流式请求的 TTFB ≈ 总耗时（必须等完整结果）；流式请求的 TTFB 可以小到 “模型生成第一个 token 的时间”，总耗时不变，但感知延迟大幅下降。

本仓库首页的"流式 vs 非流式"对比面板实测过一组数据：

第 1 章讲义 · 01 LLM API 与模型调用基础

Mon, 10 Aug 2026 19:20:00 +0800

配套代码：本仓库的 provider 层（src/anna/providers/）与 LLM 统一模型调用服务（src/anna/server/、main.py）

学完本节，你应该能回答：一次 LLM 调用请求长什么样？参数怎么影响输出？ token 怎么算？怎么让模型稳定返回 JSON？出错怎么办？多个模型怎么统一调？

1. Chat Completions / Responses API

1.1 请求结构：以 OpenAI Chat Completions 为标准

主流模型 API 基本都是"HTTP POST + JSON 请求体"，OpenAI 的 POST /v1/chat/completions 是事实标准。先看完整请求：

curl -s https://api.openai.com/v1/chat/completions \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $OPENAI_API_KEY" \
 -d '{
 "model": "gpt-4o-mini",
 "messages": [
 {"role": "system", "content": "你是英语陪练 Anna。"},
 {"role": "user", "content": "什么是 token？"}
 ],
 "temperature": 0.7,
 "max_tokens": 200,
 "stream": false
 }'

请求体字段（重要程度递减）：

Lecture on Hao · AI Agent 学习记录

第 1 章讲义 · 05 LLM Gateway（统一模型调用服务）

目录

1. FastAPI LLM 服务：统一入口与密钥管理

第 1 章讲义 · 04 Structured Output 结构化输出

目录

1. 为什么不能依赖自然语言解析

2. JSON Schema：定义输出结构

第 1 章讲义 · 03 Prompt Engineering

目录

1. System Prompt 的职责

第 1 章讲义 · 02 Streaming 流式输出

目录

1. 为什么需要 Streaming

第 1 章讲义 · 01 LLM API 与模型调用基础

目录

1. Chat Completions / Responses API

1.1 请求结构：以 OpenAI Chat Completions 为标准

Lecture on Hao · AI Agent 学习记录

第 1 章讲义 · 05 LLM Gateway（统一模型调用服务）

目录#

1. FastAPI LLM 服务：统一入口与密钥管理#

第 1 章讲义 · 04 Structured Output 结构化输出

目录#

1. 为什么不能依赖自然语言解析#

2. JSON Schema：定义输出结构#

第 1 章讲义 · 03 Prompt Engineering

目录#

1. System Prompt 的职责#

第 1 章讲义 · 02 Streaming 流式输出

目录#

1. 为什么需要 Streaming#

第 1 章讲义 · 01 LLM API 与模型调用基础

目录#

1. Chat Completions / Responses API#

1.1 请求结构：以 OpenAI Chat Completions 为标准#

目录

1. FastAPI LLM 服务：统一入口与密钥管理

目录

1. 为什么不能依赖自然语言解析

2. JSON Schema：定义输出结构

目录

1. System Prompt 的职责

目录

1. 为什么需要 Streaming

目录

1. Chat Completions / Responses API

1.1 请求结构：以 OpenAI Chat Completions 为标准