Ch1 on Hao · AI Agent 学习记录

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

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

目标岗位：Agent Harness 研发/工程方向（参考 ~/agent/jb/jd.md）配套讲义：讲义 05 · LLM Gateway 用法：先自己口头答一遍，再对照"参考回答"；重点看"考察点"和"坑"。原则：所有回答结论先行 → 项目证据 → 原理 → 边界与改进，不要背概念。

0. 面试官视角：Gateway 题到底在考什么

Gateway 是"把分散的厂商调用收敛成平台能力"的典型系统设计题：

概念层：Gateway 解决什么问题（密钥、协议、可观测）；
实践层：你的网关怎么分层、每个模块在哪、有没有测试；
判断层：为什么这么设计？并发和性能边界？新增厂商要改什么？——拉差距。

回答公式：一句话结论 → 你项目里的实现/例子 → 原理 → 边界与改进。

1. 按讲义章节的题目与参考回答

Q1：LLM Gateway 解决什么问题？为什么不直接让业务调厂商 SDK？

参考回答：四个问题——密钥分散（每个组件持 key，泄露面大）、协议差异（每家格式不同）、不可观测（没有统一日志）、无法统一治理（限流/回退/成本）。网关收敛成一层：密钥集中在 config 层、协议统一成 OpenAI Compatible、每次调用留痕、限流回退统一做。我的网关 create_app 组装了路由、限流、模板、用量、provider 链，业务只发 HTTP。

Q2：密钥为什么集中？怎么防泄露？

参考回答：集中后业务组件不碰厂商密钥，泄露面从"每个组件"缩小到"网关一个点"。密钥从环境变量读（config.py，支持 DASHSCOPE_API_KEY 等厂商命名空间），不进代码库。诚实边界：网关本身是新的攻击面——生产上密钥应放密钥管理服务（KMS/Vault），网关进程还要做最小权限和审计。

Q3：为什么对外统一成 OpenAI Compatible，而不是自定义协议？

参考回答：OpenAI Compatible 是事实标准，DeepSeek、DashScope、本地 Ollama/vLLM 都兼容，生态里现成 SDK 和工具直接可用。对内用 ChatProvider 接口 + adapter 屏蔽差异（讲义 01 §6），对外格式稳定、对内可演进。收益：换厂商不改业务代码、OpenAI 官方 SDK 能直连网关。

第 1 章面试 · 04 Structured Output 结构化输出

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

目标岗位：Agent Harness 研发/工程方向（参考 ~/agent/jb/jd.md）配套讲义：讲义 04 · Structured Output 用法：先自己口头答一遍，再对照"参考回答"；重点看"考察点"和"坑"。原则：所有回答结论先行 → 项目证据 → 原理 → 边界与改进，不要背概念。

0. 面试官视角：结构化输出题到底在考什么

结构化输出是 Agent 工程的地基——工具调用、下游解析全靠它。面试官三层递进：

概念层：JSON Schema、Pydantic、原生结构化输出是什么；
实践层：你项目里三家厂商怎么实现的？校验失败怎么处理？
判断层：为什么不能只靠 prompt？失败降级怎么设计？流式 + 结构化怎么组合？——拉开差距的地方。

回答公式：一句话结论 → 你项目里的实现/例子 → 原理 → 边界与改进。

1. 按讲义章节的题目与参考回答

Q1：为什么 Agent 系统不能依赖自然语言解析？

参考回答：模型输出要喂给代码——查词结果填卡片、工具参数发请求、SQL 要执行。自然语言输出换行、加粗、解释文字都会破坏解析；更糟的是解析失败时分不清是"格式错了"还是"答案错了"。所以原则是协议先行 + 校验兜底 + 失败有出路：先定义输出形状，返回后校验，不过就纠错重试或降级，绝不把脏数据传给下游。

考察点：能不能说出"解析失败无法区分错误类型"这个深层原因。

Q2：JSON Schema 有哪些关键字段？additionalProperties 为什么重要？

参考回答：type（对象/数组/标量）、required（必填）、properties （字段类型）、数组的 items/minItems、字符串的 enum。additionalProperties: false 很重要——它禁止模型自作主张加字段，协议边界一旦被突破，下游解析就容易悄悄出错。我 /v1/structured 的 schema 都关掉了多余字段。

第 1 章面试 · 03 Prompt Engineering

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

目标岗位：Agent Harness 研发/工程方向（参考 ~/agent/jb/jd.md）配套讲义：讲义 03 · Prompt Engineering 用法：先自己口头答一遍，再对照"参考回答"；重点看"考察点"和"坑"。原则：所有回答结论先行 → 项目证据 → 原理 → 边界与改进，不要背概念。

0. 面试官视角：Prompt 题到底在考什么

Prompt 题最容易答成"背技巧"，面试官想听的是：

概念层：System Prompt、Few-shot、注入是什么；
实践层：你的模板怎么管理、注入怎么防、版本怎么回滚，代码在哪；
判断层：隔离为什么不是银弹？Prompt 变更怎么灰度？怎么评估 Prompt 好坏？——这里拉开差距。

回答公式：一句话结论 → 你项目里的实现/例子 → 背后的原理 → 边界与可改进点。

1. 按讲义章节的题目与参考回答

Q1：System Prompt 和普通用户消息有什么区别？你们怎么管理 System Prompt？

参考回答：System Prompt 是"岗位说明书"——定义角色、目标、边界和输出约定，独立于用户消息（role: system），模型通常给它更高权重。我把 System Prompt 当成模板资产管理：prompts.json 里存 reading_assistant 这类模板，带变量（{user_level}）和版本号，网关 /v1/prompts 统一渲染，业务层只传变量。这样角色设定变更走模板版本，不碰业务代码。

考察点：能不能区分"角色设定"和"用户消息"两个通道；模板化管理的动机。

Q2：角色定义怎么写才有效？

参考回答：角色定义 = “你是谁 + 怎么干活”，关键是行为约束要具体。弱约束 “你是代码审查助手"模型会自由发挥；强约束要写明审查维度、每个问题的输出要素、以及"没有问题时明确说无问题，不要编造”。我的种子模板 translate_assistant 就是"只输出译文"这种带边界的角色，约束和输出协议分开写。

第 1 章面试 · 02 Streaming 流式输出

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

目标岗位：Agent Harness 研发/工程方向（参考 ~/agent/jb/jd.md）配套讲义：讲义 02 · Streaming 流式输出用法：先自己口头答一遍，再对照"参考回答"；重点看"考察点"和"坑"。原则：所有回答结论先行 → 项目证据 → 原理 → 边界与改进，不要背概念。

0. 面试官视角：流式题到底在考什么

流式是"理论简单、工程全是坑"的题目，面试官按三层递进：

概念层：SSE 是什么、TTFB 是什么；
实践层：你的网关/前端怎么实现的，能不能现场演示；
判断层：两段流式缺一段会怎样？取消怎么贯穿三层？流中出错为什么不能重试？长文本断了怎么办？——这一层才是拉开差距的地方。

回答公式：一句话结论 → 你项目里的实现/例子 → 背后的原理 → 边界与可改进点。主动说"这里我做得不彻底，我的方案是 X"，比被追问出来强得多。

1. 按讲义章节的题目与参考回答

1.1 为什么需要 Streaming

Q1：流式和非流式在用户体验上差在哪？你项目里有数据吗？

参考回答：LLM 生成要几十秒，非流式是"等全部生成完才出现第一个字"，用户看到一片空白；流式是"边生成边显示"，用户感知延迟从"总耗时"降到"第一个 token 的时间"。我首页有个对比面板：同一消息 × 两种模式并排跑，流式栏会显示首字节耗时、总耗时、分片数和分片表。改流式链路之前实测过一次：非流式总耗时 20662ms，流式首字节 20655ms——首字节几乎等于总耗时，这恰恰暴露了"上游整体缓冲后回放"的问题，说明只传 stream: true 而不打通传输层，用户体验没有任何提升。

考察点：是否真的理解"感知延迟"；能不能用自己项目里的指标讲，而不是背概念。

Q2：首字节耗时（TTFB）和总耗时有什么区别？

参考回答：TTFB 是请求发出到收到第一块内容的时间，总耗时是收到最后一块的时间。非流式里两者基本相等（必须等完整结果）；真流式里 TTFB 约等于"模型生成第一个 token 的时间"，总耗时不变但感知变快。工程上这是流式最重要的监控指标——如果首字节≈总耗时，说明链路里某一段被缓冲了（浏览器、反向代理、或者上游 HTTP 客户端整体读 body）。

第 1 章面试 · 01 LLM API 与模型调用基础

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

目标岗位：Agent Harness 研发/工程方向（参考 ~/agent/jb/jd.md）用法：先自己口头答一遍，再对照"参考回答"；重点看"考察点"和"坑"。原则：所有回答结论先行 → 项目证据 → 原理 → 边界与改进，不要背概念。

0. 面试官视角：这类题到底在考什么

同样的知识点，面试官会按三层递进考察：

概念层：懂不懂（Chat Completions 结构、token 是什么）；
实践层：做没做过（你项目里怎么实现的，代码在哪）；
判断层：为什么这么设计、哪里做得不好、怎么改（这是拉开差距的地方）。

回答公式：一句话结论 → 你项目里的实现/例子 → 背后的原理 → 边界与可改进点。最后一步尤其重要——主动说"这里我还没做/做得不好，我的方案是 X"，比被追问出来强得多。

1. 按讲义章节的题目与参考回答

1.1 Chat Completions / Responses API

Q1：你们网关为什么对外暴露 chat.completions，而不是直接调各家 SDK？

参考回答：因为 chat.completions 是事实标准，DeepSeek、DashScope、Moonshot、本地 Ollama 都提供兼容端点。我在 provider 层定义了统一接口 ChatProvider，各家用 adapter 做格式转换（openai_compatible.py / anthropic.py / gemini.py），上层代码只认一个接口。收益是：换模型不改业务代码、可以跨厂商回退、用量和错误统一统计。本质是把"协议差异"收敛到 adapter 层。

考察点：是否理解"统一抽象"的动机（协议差异、切换成本、回退、可观测）。

Q2：Chat Completions 和 Responses API 有什么区别？你们为什么没做 Responses？

第 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
 }'

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

Ch1 on Hao · AI Agent 学习记录

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

0. 面试官视角：Gateway 题到底在考什么

1. 按讲义章节的题目与参考回答

第 1 章面试 · 04 Structured Output 结构化输出

0. 面试官视角：结构化输出题到底在考什么

1. 按讲义章节的题目与参考回答

第 1 章面试 · 03 Prompt Engineering

0. 面试官视角：Prompt 题到底在考什么

1. 按讲义章节的题目与参考回答

第 1 章面试 · 02 Streaming 流式输出

0. 面试官视角：流式题到底在考什么

1. 按讲义章节的题目与参考回答

1.1 为什么需要 Streaming

第 1 章面试 · 01 LLM API 与模型调用基础

0. 面试官视角：这类题到底在考什么

1. 按讲义章节的题目与参考回答

1.1 Chat Completions / Responses API

第 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 为标准

Ch1 on Hao · AI Agent 学习记录

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

0. 面试官视角：Gateway 题到底在考什么#

1. 按讲义章节的题目与参考回答#

第 1 章面试 · 04 Structured Output 结构化输出

0. 面试官视角：结构化输出题到底在考什么#

1. 按讲义章节的题目与参考回答#

第 1 章面试 · 03 Prompt Engineering

0. 面试官视角：Prompt 题到底在考什么#

1. 按讲义章节的题目与参考回答#

第 1 章面试 · 02 Streaming 流式输出

0. 面试官视角：流式题到底在考什么#

1. 按讲义章节的题目与参考回答#

1.1 为什么需要 Streaming#

第 1 章面试 · 01 LLM API 与模型调用基础

0. 面试官视角：这类题到底在考什么#

1. 按讲义章节的题目与参考回答#

1.1 Chat Completions / Responses API#

第 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 为标准#

0. 面试官视角：Gateway 题到底在考什么

1. 按讲义章节的题目与参考回答

0. 面试官视角：结构化输出题到底在考什么

1. 按讲义章节的题目与参考回答

0. 面试官视角：Prompt 题到底在考什么

1. 按讲义章节的题目与参考回答

0. 面试官视角：流式题到底在考什么

1. 按讲义章节的题目与参考回答

1.1 为什么需要 Streaming

0. 面试官视角：这类题到底在考什么

1. 按讲义章节的题目与参考回答

1.1 Chat Completions / Responses API

目录

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

目录

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

2. JSON Schema：定义输出结构

目录

1. System Prompt 的职责

目录

1. 为什么需要 Streaming

目录

1. Chat Completions / Responses API

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