📗 第 3 章 · Accessing the AI with the API

所属课程：课程 004 Building with the the AI API
官方章节名：Accessing the AI with the API
课时数：13
CCAR-F 主命中领域：D3 20% ＋ D5 15%
归档日期：2026-10-15

📋 本章课时清单

🎯 本章考点提示

D3（20%）＋ D5（15%）主战场之一，13 课时。核心：system prompt、temperature、response streaming、structured data。

⭐ 官方 What You'll Learn 第 2、3 条落在这里：多轮对话的消息格式与上下文处理、用 temperature / 流式 / 结构化输出控制模型行为。 ⚠️ 与 课程003 第 1–2 课重叠，可复用。

📖 逐课精译

课时 1 · Accessing the API

类型：🎬 视频 ｜ lesson ID：287726 ｜ 官方直链 精译状态：✅ 已完成（2026-10-15，用户提供官方讲稿原文） ⭐ 本课权重提示：全章地基课。官方在这一课把一次 API 调用的完整生命周期从客户端一路讲到模型内部，是后面 12 个课时（system prompt / temperature / 流式 / 结构化输出）的公共底座。五步请求流与必须走自建服务端这两条是 D5 的送分点，停止生成三条件与响应三字段是 D3 的高频题眼。

🎯 本课学习目标（据官方 Key Takeaways 反推）

⚠️ 本课官方未提供独立的 What you'll learn 区块，以下按讲稿结构反推：

1. 能顺序背出五步请求流，并指出每一步发生在哪一侧（客户端 / 你的服务端 / 官方 API）。
2. 能说清为什么绝不能从客户端直连官方 API，并给出三条官方理由。
3. 能列出一次 API 请求的四个必填字段，并说明 max_tokens 管的是输出还是输入。
4. 能说出模型内部处理的四个阶段，以及「多义词」是在哪一步被消歧的。
5. 能读懂响应的三个字段，并据 stop_reason 在应用逻辑里做分支处理。

一、开场：懂生命周期的价值

官方原句：When building applications with the AI, understanding the complete request lifecycle helps you make better architectural decisions and debug issues more effectively. Let's walk through what happens from the moment a user clicks "send" in your chat interface to when the AI's response appears on screen.

精译：在用 the AI 构建应用时，理解完整的请求生命周期能帮你做出更好的架构决策，并更有效地排查问题。我们来走一遍：从用户在聊天界面点下「发送」的那一刻起，到 the AI 的回答出现在屏幕上，中间到底发生了什么。

💡 架构师视角：官方把「理解生命周期」的目的明确拆成两半——做架构决策与排障定位。后者尤其值得记：当你能按阶段切分时，「回答慢」就不再是一个模糊的抱怨，而是可以定位到检索、生成、流式或网络各环节的具体问题。

二、⭐⭐ 五步请求流（The Five-Step Request Flow）

官方原句：Every interaction with the AI follows a predictable pattern with five distinct phases: request to server, request to the AI provider API, model processing, response to server, and response to client.

精译：每一次与 the AI 的交互都遵循一个可预测的、包含五个明确阶段的模式：请求发往服务端 → 请求发往官方 API → 模型处理 → 响应回到服务端 → 响应回到客户端。

⭐⭐ 记忆锚：「模型永远不直接面对用户，中间永远夹着你自己那一层服务端。」 这张表的骨架价值在于：五个阶段里，有四个跨越了「你的系统」与「官方系统」的边界。第 2 与第 4 步是唯一的两个跨网边界，也是唯一需要凭证、需要超时与重试、需要限流与审计的地方。 ⚠️ 考点提示：题干若问「API key 应该在哪一步被使用」，答案恒为第 2 步（你的服务端 → 官方 API）。若选项说「在客户端直接调用官方 API」或「把 key 下发给客户端」，一律判死。

三、⭐⭐ 为什么必须有自建服务端（Why You Need a Server）— D5 送分点

官方原句：You should never make requests to the the AI provider API directly from client-side code. Here's why:

• API requests require a secret API key for authentication
• Exposing this key in client code creates a serious security vulnerability
• Anyone could extract the key and make unauthorized requests

Instead, your web or mobile app sends requests to your own server, which then communicates with the the AI provider API using the securely stored key.

精译：你绝不应该从客户端代码里直接向官方 API 发起请求。原因如下：

• API 请求需要一个保密的 API key 来完成鉴权；
• 把这个 key 暴露在客户端代码中会造成严重的安全漏洞；
• 任何人都能提取出这个 key 并发起未授权的请求。

正确做法是你的 web 或移动应用把请求发给你自己的服务端，再由服务端使用妥善存储的 key 与官方 API 通信。

┌──────────┐   ①   ┌───────────────┐   ②   ┌──────────────────┐
│  客户端   │ ────▶ │  你的服务端    │ ────▶ │  官方 API         │
│ (浏览器)  │ ◀──── │ (持有 API key) │ ◀──── │ (模型处理)        │
└──────────┘   ⑤   └───────────────┘   ④   └──────────────────┘
        无 key              ✅ key 只存在于此处         ③

⭐⭐ 架构师总结（可直接作答题模板）： 客户端 ⇄ 你的服务端 ⇄ 官方 API，key 只存在于中间那一格。 这不只是安全要求，它同时是你做限流、做审计、做配额、做缓存、做内容过滤的唯一位置——因为所有流量都必经此处。 ⚠️ 避坑：本课的对应精讲词是 authenticate（生词表 015）。注意官方在此用的是 secret API key，形容词 secret 强调不可分发性，与「用户自己的密码」不是一回事。

四、发起 API 请求（Making API Requests）

官方原句：When your server contacts the the AI provider API, you can use either an official SDK or make plain HTTP requests. the AI provider provides SDKs for Python, TypeScript, JavaScript, Go, and Ruby.

Every request must include these essential fields:

• API Key - Identifies your request to the AI provider
• Model - Name of the model to use (like "claude-3-sonnet")
• Messages - List containing the user's input text
• Max Tokens - Limit for how many tokens the AI can generate

精译：当你的服务端联系官方 API 时，你既可以使用官方 SDK，也可以发普通 HTTP 请求。官方为 Python、TypeScript、JavaScript、Go 和 Ruby 提供了 SDK。

每个请求必须包含以下基本字段：

⭐ 两个高频题眼： 1. max_tokens 管的是「生成」而不是「输入」——官方原词是 how many tokens the AI can generate。它是一道硬闸门：达到即用完即停，并触发对应的 stop_reason（见下文第六节）。 2. messages 是「列表」而非「字符串」——官方强调 List。这正是多轮对话（课时 4）能把历史消息一并按序传入的结构基础。 🔗 跨课串联：本课只讲四个必填字段；temperature（课时 8）、system（课时 6）、stream（课时 10）都属可选**的控行为字段。考题若问「哪个字段是必填」，从这四项里选。

五、⭐ 模型内部四阶段（Inside the AI's Processing）

官方原句：Once the AI provider receives your request, the AI processes it through four main stages: tokenization, embedding, contextualization, and generation.

精译：官方收到你的请求后，the AI 会通过四个主要阶段来处理它：分词（tokenization）、嵌入（embedding）、上下文化（contextualization）与生成（generation）。

1. Tokenization（分词）

官方原句：the AI first breaks your input text into smaller chunks called tokens. These can be whole words, parts of words, spaces, or symbols. For simplicity, think of each word as one token.

精译：the AI 首先把你的输入文本切成更小的块，称为 token。token 可以是完整的词、词的一部分、空格或符号。为简便起见，可以先粗浅地把每个词想成一个 token。

⚠️ 考点提示：官方此处主动做了简化（For simplicity）。真实分词是子词（subword）级的——这正是计费与上下文长度要按 token 而非按「字数」计算的原因。考试若问「token 大致等于什么」，按官方口径答「一个词」；若问「token 是否严格等于一个词」，答否。

2. Embedding（嵌入）

官方原句：Each token gets converted into an embedding - a long list of numbers that represents all possible meanings of that word. Think of embeddings as numerical definitions that capture semantic relationships.

精译：每个 token 会被转换成一个 embedding（嵌入）——一长串数字，代表这个词所有可能的含义。可以把 embedding 理解为数值化的词义定义，它捕捉了语义关系。

官方举的「quantum（量子）」四义：

💡 记忆锚：embedding 阶段是「一词多义并存」，不是「选定一义」。这四个义项会同时被编码进那串数字里。谁来做消歧？下一步。

3. Contextualization（上下文化）

官方原句：the AI refines each embedding based on surrounding words to determine the most likely meaning in context. This process adjusts the numerical representations to highlight the appropriate definition.

精译：the AI 根据周围的词来精调每个 embedding，以确定在当前语境下最可能的含义。这个过程会调整那些数值表示，从而凸显出恰当的义项。

⭐⭐ 本课最核心的理解点：消歧发生在 contextualization，不在 embedding。 这直接解释了 RAG 的经典失效（生词表 021 contextual）：一个被切出来、脱离了原文档主语句的片段，等于被剥夺了做 contextualization 所必需的周围词，因此向量召回不准。 🔗 与生词表 006 contextual retrieval、021 contextual、004 chunking 构成同一条因果链。

4. Generation（生成）

官方原句：The contextualized embeddings pass through an output layer that calculates probabilities for each possible next word. the AI doesn't always pick the highest probability word - it uses a mix of probability and controlled randomness to create natural, varied responses.

After selecting each word, the AI adds it to the sequence and repeats the entire process for the next word.

精译：上下文化后的 embedding 会经过一个输出层，该层为每一个可能的下一个词计算概率。the AI 并不总是挑选概率最高的那个词——它把概率与受控的随机性混合使用，以生成自然、多样的回答。

每选出一个词后，the AI 就把它加入序列，并对下一个词重复整个过程。

⭐⭐ 两个必记结论： 1. 生成是「逐词、自回归、串行」的——选完一个词 → 追加进序列 → 重算下一个。这解释了三件事：为什么长输出必然慢、为什么 token 数与延迟近似线性相关、为什么流式（课时 10）能显著改善体验却不能缩短总时长。 2. 「不总选最高概率」正是 temperature 存在的前提（课时 8 展开）。官方此处的 controlled randomness 就是 temperature 的语义原型——temperature 调的是这个「受控随机性」的幅度。 ⚠️ 避坑：考题若说「模型总是输出概率最高的词，所以结果确定」，直接判错。

六、停止生成的三个条件（When the AI Stops Generating）

官方原句：After each token, the AI checks several conditions to decide whether to continue:

• Max tokens reached - Has it hit the limit you specified?
• Natural ending - Did it generate an end-of-sequence token?
• Stop sequence - Did it encounter a predefined stop phrase?

精译：每生成一个 token 之后，the AI 都会检查若干条件以决定是否继续：

⭐ 考点提示（D3 高频）：三者互斥且穷尽——响应的 stop_reason 必然落在这三种之一。 ⚠️ 实务要点：条件 1 与条件 3 都是外部硬约束。若业务上出现「回答被截断」，根因通常是 max_tokens 设小了，此时 stop_reason 会明确告诉你；不要靠把上限一味调大来解决，那会同时抬高成本与最坏延迟。 📌 补充（非本课原文）：官方 API 的实际取值为 end_turn / max_tokens / stop_sequence，与本节三个条件一一对应。讲稿在此处用的是描述性说法（end-of-sequence token），未给出字面取值，答题时按上面的映射理解即可。

七、API 响应（The API Response）

官方原句：When generation completes, the API sends back a structured response containing:

• Message - The generated text
• Usage - Count of input and output tokens
• Stop Reason - Why generation ended

Your server receives this response and forwards the generated text back to your client application, where it appears in the user interface.

精译：生成完成后，API 会返回一个结构化响应，包含：

你的服务端收到该响应后，把生成的文本转发回客户端应用，最终呈现在用户界面上。

⭐ 架构师视角：三个字段里，usage 与 stop_reason 是给系统看的，message 是给人看的。生产级实现必须把前两者落进日志与指标——否则你既不知道花了多少钱，也无法区分「模型说完了」和「被上限截断了」。

八、Key Takeaways（官方收官四条）

官方原句：Understanding this flow helps you:

• Design secure architectures that protect your API keys
• Set appropriate token limits for your use case
• Handle different stop reasons in your application logic
• Debug issues by understanding where they might occur in the pipeline

Don't worry about memorizing every detail - the goal is familiarizing yourself with the terminology and overall process you'll encounter when working with the AI's API.

精译：理解这个流程能帮助你：

• 设计保护 API key 的安全架构；
• 为你的用例设定恰当的 token 上限；
• 在应用逻辑中处理不同的停止原因；
• 通过理解问题可能出现在管线的哪个环节来排障。

不必担心要记住每一个细节——目标是熟悉你在用 the AI API 时会遇到的术语与整体流程。

📌 官方自述的学习目标：末句明确说「不必记细节，重在熟悉术语与流程」。因此本课在考试中偏概念识别与顺序判断，不太会考实现细节——背阶段名与顺序的性价比，远高于背实现参数。

🔤 本课新生词（临时小表 · 已回灌 30-单词表/04- 第 3 章分组）

课时 2 · Getting an API key

类型：📄 图文 ｜ lesson ID：296766 ｜ 官方直链 精译状态：✅ 已完成（2026-10-15，用户提供官方图文指南原文） ⭐ 本课权重提示：全章唯一的纯操作课，内容极短，但它是官方唯一一处正面演示密钥生命周期的地方。考点不在「点哪个按钮」，而在三个可迁移的治理原则：只显示一次、可命名可归属、丢了只能吊销重建。这三条是 D5 的高频判据，与精讲词 015 authenticate、024 vulnerability 直接咬合。

🎯 本课学习目标（据官方 Steps 反推）

⚠️ 本课为图文操作指南，官方未提供 What you'll learn 区块。

1. 能说出获取 API key 的五个步骤及其顺序。
2. 能解释为什么 key 必须立即复制保存（只显示一次）。
3. 能说明 key 命名与 workspace 在密钥治理中的作用。
4. 能给出 key 丢失或泄露后的正确处理流程。

一、开场：为什么需要 key

官方原句：In the next video we will be making a request to the the AI provider API. To do so, you will need a secret API key. This guide will walk you through the process of creating an API key.

精译：在下一个视频里，我们将向官方 API 发起一次请求。为此，你需要一个保密的 API key。本指南将带你走完创建 API key 的全过程。

💡 架构师视角：注意官方用的形容词是 secret（保密的），不是 "your"（你的）。这个措辞在 015 authenticate 与 024 vulnerability 里都出现过——它强调 key 的性质是不可分发的凭证，而非个人身份标识。

二、五步流程（官方原文 ＋ 精译）

Step One · 进入控制台

官方原句：Navigate to the the AI provider API Console

In your browser, navigate to https://console.anthropic.com/ and log in to your the AI provider account. You'll then see a page like this:

精译：进入官方 API 控制台。在浏览器中打开 https://console.anthropic.com/ 并登录你的官方账号，随后你会看到一个类似下图（官方配图）的页面。

Step Two · 点击「Get API Keys」

官方原句：Click the 'Get API Keys' button

This button can be found towards the top right of the main dashboard page.

精译：点击 「Get API Keys」 按钮。该按钮位于主仪表盘（dashboard）页面的右上方。

Step Three · 点击「Create Key」

官方原句：Click the 'Create Key' button

At the top right of the page, find the 'Create Key' button and click it.

精译：点击 「Create Key」 按钮。在页面右上方找到该按钮并点击。

Step Four · 选择工作区并为 key 命名

官方原句：Enter a workspace and name for your key

Create the key in workspace 'Default' and enter a name for your key. This name is used to help you identify the keys you generate. Let's use a name of 'the AI provider Course'.

精译：为你的 key 选择一个工作区（workspace）并命名。在 Default 工作区中创建该 key，并为它输入一个名称。这个名称用来帮助你区分自己生成的各个 key。我们就用 the AI provider Course 作为名称。

⭐⭐ 本课最有治理价值的一句：This name is used to help you identify the keys you generate. 官方明说了命名的目的——可识别、可归属。这在生产环境里直接对应三条实践： 1. 按用途与环境命名（如 prod-checkout-svc、dev-laptop-alice），而不是 key1 / test； 2. 一个服务一把 key，出问题能精确定位到是哪个调用方，吊销时影响面可控； 3. 禁止多人共用一把 key——一旦共用，就无法归因，出事后只能全部吊销。

Step Five · 复制并妥善保存

官方原句：Copy the Key

Your API key will then be displayed in a pop up window. Copy this key and hold onto it - we will use it in the next video. This key will only be displayed once, so make sure you copy it!

If you accidentally close the window, delete the old key and generate it again.

精译：复制这个 Key。你的 API key 会在一个弹窗中显示出来。复制它并妥善保管——我们在下一个视频里会用到它。这个 key 只会显示这一次，所以务必复制下来！

如果你不小心关掉了窗口，就删除旧 key 并重新生成一个。

⭐⭐ 两句必背（D5 高频判据）： 1. This key will only be displayed once（只显示一次）——这是密钥类凭证的标准设计：服务端只保存 hash，不保存明文，因此没有任何「再给我看一次」的机制。对应到工程实践就是：生成即写入密钥管理服务（Secrets Manager），绝不依赖人肉记忆或聊天记录传递。 2. delete the old key and generate it again（删除旧的、重新生成）——官方给出的补救路径不是「找回」，而是吊销 ＋ 重建。这正是 key rotation（密钥轮转）与 revocation（吊销）的原型动作。 ⚠️ 考场避坑：题干若说「key 忘了可以找客服再要一次」或「在控制台能随时再次查看明文 key」，一律判错。同理，若问「疑似泄露怎么办」，正解恒为先吊销（delete/revoke）再重建，而不是「改个名字继续用」。

三、⭐ 本课的三条可迁移治理原则

🔗 跨条目串联：原则 1、3 → 精讲 015 authenticate（凭证怎么管）；原则 2、3 → 精讲 024 vulnerability（漏洞怎么收口，以及 threat / exploit / risk 的辨析）。本课是这两条抽象原则的操作层落地。

🔤 本课新生词（临时小表 · 已回灌 30-单词表/04- 第 3 章分组）

课时 3 · Making a request

类型：🎬 视频 ｜ lesson ID：287725 ｜ 官方直链 精译状态：✅ 已完成（2026-10-15，用户提供官方讲稿原文） ⭐ 本课权重提示：全课第一次真正写代码。官方在这里给出了 client.messages.create() 的三个关键参数与 messages 的两类型结构——这是后面所有课时（system prompt / 多轮 / 温度 / 结构化）的共同底座。max_tokens 是安全上限而非目标这一句是 D3 的高频题眼；key 走 .env ＋ .gitignore 是 015 authenticate 与 024 vulnerability 的代码层落地。

🎯 本课学习目标（据官方段落反推）

⚠️ 本课官方未提供独立的 What you'll learn 区块。

1. 能完成环境准备：装依赖、用 .env 存 key、把 .env 加进 .gitignore。
2. 能列出 client.messages.create() 的三个关键参数并说明各自作用。
3. 能说清 max_tokens 是上限不是目标。
4. 能写出 messages 的两类消息与 role / content 两个字段。
5. 能取出响应里的生成文本（message.content[0].text）。

一、开场

官方原句：Making your first request to the the AI provider API is straightforward once you understand the basic setup and structure. This guide walks through the essential steps to get the AI responding to your prompts using Python.

精译：一旦理解了基本的环境配置与结构，向官方 API 发出你的第一个请求是很 straightforward（直截了当）的。本指南将用 Python 带你走完让 the AI 响应你提示词的必要步骤。

二、⭐⭐ 环境准备（Setting Up Your Environment）— key 的代码层治理

官方原句：Before making any API calls, you need to install the required packages and configure your API key securely.

First, install the necessary dependencies in your Jupyter notebook:

%pip install anthropic python-dotenv

Next, create a .env file in the same directory as your notebook to store your API key securely:

ANTHROPIC_API_KEY="your-api-key-here"

This approach keeps your API key out of your code and prevents accidentally committing it to version control. Always add .env to your .gitignore file.

精译：在发起任何 API 调用之前，你需要安装所需的包并安全地配置你的 API key。

首先，在 Jupyter notebook 中安装必要的依赖：%pip install anthropic python-dotenv

接着，在与 notebook 同一目录下创建一个 .env 文件，用于安全存放你的 API key：ANTHROPIC_API_KEY="your-api-key-here"

这种做法能把 key 挡在你的代码之外，并防止不小心把它提交进版本控制。务必把 .env 加进你的 .gitignore 文件。

⭐⭐ 架构师视角（D5 送分点）：官方在这里给的是一套三件套防线，缺一不可：

防线	官方做法	挡住的是什么
① 代码分离	key 放 .env，不写进代码	代码分享/开源时泄露
② 版本控制隔离	.env 加入 .gitignore	提交时泄露（最常见的事故点）
③ 运行时注入	load_dotenv() 读入环境变量	硬编码

⚠️ 两个高频坑： 1. 「加了 .gitignore 就安全」是假命题——.gitignore 只对尚未被跟踪的文件生效。若 .env 已经被 git add 过，之后再加忽略无效，历史提交里的 key 依然可被爬到。正解是立即吊销并轮转（见课时 2 的 delete the old key and generate it again）。 2. ANTHROPIC_API_KEY 这个变量名不是随意起的——官方 SDK 会自动读取该环境变量，所以本例中 client = the AI provider() 无需显式传 key。考题若问「SDK 如何找到 key」，答案是约定环境变量名自动注入。 🔗 与精讲 015 authenticate（凭证怎么管）、024 vulnerability（泄露是哪种漏洞）构成完整链条：本课是它们在代码层的具体动作。

三、创建客户端与变量

官方原句：Load the environment variables and create your API client:

``` from dotenv import load_dotenv load_dotenv()

from anthropic import the AI provider

client = the AI provider() model = "current-model-fast" ```

精译：加载环境变量并创建你的 API 客户端：

from dotenv import load_dotenv
load_dotenv()

from anthropic import the AI provider

client = the AI provider()      # 自动从 ANTHROPIC_API_KEY 读取
model = "current-model-fast"    # 模型名（示例占位）

📌 语料说明：the AI provider 与 current-model-fast 为去品牌化占位残留（原应分别为官方客户端类名与具体模型名），与课程 003 的处理一致，未作改动。

四、⭐⭐ messages.create() 的三个关键参数（The Create Function）

官方原句：The core of making API requests is the client.messages.create() function. This function requires three key parameters:

• model - The name of the the AI model you want to use
• max_tokens - A safety limit on response length (not a target)
• messages - The conversation history you're sending to the AI

精译：发起 API 请求的核心是 client.messages.create() 函数。该函数需要三个关键参数：

⭐⭐ max_tokens 的官方定义（必背）： The max_tokens parameter acts as a safety mechanism. If you set it to 1000, the AI will stop generating after 1000 tokens even if it has more to say. the AI doesn't try to reach this limit - it just writes what it thinks is appropriate and stops if it hits the maximum.

「max_tokens 参数是一道安全机制。如果你设为 1000，那么即使 the AI 还有话要说，它也会在生成满 1000 个 token 后停下。the AI 不会去试图凑满这个上限——它只写它认为恰当的内容，只有在撞到上限时才会停。」

考点提炼：这三句话把 max_tokens 的性质钉死了—— 1. 它是上限（ceiling）不是目标（target）：设 1000 不会让模型写满 1000 字； 2. 它是安全机制（safety mechanism），目的是防失控（防死循环、防成本爆炸），不是控长度的手段； 3. 想控制输出长度，正确做法是在提示词里提要求（如本课示例的 Answer in one sentence），而不是调小 max_tokens 硬截断。 ⚠️ 考场避坑：题干若说「把 max_tokens 设为 50 可以让回答更简洁」，判错——那只会在句子中间截断，且 stop_reason 变成 max_tokens。正确做法是提示词里要求简短（呼应精讲 023 takeaways 考点的选项 D）。 🔗 与课时 1 的口径差异（易混点）：课时 1 说一次请求有四个必填字段（含 API Key），本课说 create() 有三个关键参数。二者不矛盾——HTTP 请求层需要显式带 key，而 SDK 层的 key 已在构造 client 时注入，故参数里不再出现。考题问「几个」时，务必先看它问的是哪一层。

五、⭐ 理解 messages（Understanding Messages）

官方原句：Messages represent the conversation between you and the AI, similar to a chat application. There are two types of messages:

• User messages - Content you want to send to the AI (written by humans)
• Assistant messages - Responses that the AI has generated

Each message is a dictionary with a role (either "user" or "assistant") and content (the actual text).

精译：messages 表示你与 the AI 之间的对话，类似一个聊天应用。共有两类消息：

每条消息都是一个字典，包含 role（取 "user" 或 "assistant"）与 content（实际文本）两个字段。

⭐ 三个结构要点： 1. messages 是「列表」而非单条——官方称之为 the conversation history。这正是下一课时「Multi-Turn conversations」能把交替历史整体传入的基础。 2. assistant 消息也要由你显式传回——模型没有服务端会话状态。所谓「多轮对话」= 你每次都把完整历史重发一遍。这是 D1/D3 的经典考点（API 是无状态的）。 3. role / content 的键值结构是后续一切高级用法的容器：system prompt（课时 6）走独立 system 参数、tool use（第 6 章）让 content 变成 block 列表。本课是它们的最小形态。

六、发出第一个请求（Making Your First Request）

官方原句：Here's a complete example of making a request to the AI:

message = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=[
        {
            "role": "user",
            "content": "What is quantum computing? Answer in one sentence"
        }
    ]
)

精译：以下是向 the AI 发起请求的完整示例（同上代码）。

官方原句：When you run this code, the AI will process your request and return a response object containing the generated text along with metadata about the request.

精译：运行这段代码后，the AI 会处理你的请求，并返回一个响应对象，其中包含生成的文本以及关于本次请求的元数据。

💡 注意提示词里的那句 Answer in one sentence：这是官方在用提示词控制长度的现场示范，正好与上一节的 max_tokens 形成对照——想要短，就在提示词里说；想防失控，才设 max_tokens。

七、取出响应（Extracting the Response）

官方原句：The response object contains a lot of information, but you usually just want the generated text. Access it using:

message.content[0].text

This gives you clean, readable output like: "Quantum computing is a type of computation that leverages quantum mechanics principles like superposition and entanglement to process information using quantum bits (qubits), potentially solving certain complex problems exponentially faster than classical computers."

精译：响应对象包含很多信息，但你通常只想要生成的文本。用 message.content[0].text 取用即可。

这会得到干净可读的输出，例如：「量子计算是一种利用叠加（superposition）与纠缠（entanglement）等量子力学原理，以量子比特（qubits）处理信息的计算方式，在求解某些复杂问题时，可能比经典计算机快上指数级。」

⭐ 两个结构信号（为后续章节埋的伏笔）： 1. content 是列表（[0]）——说明响应内容是分块（block）组织的。本课只有纯文本块，所以取 [0].text；到第 6 章 Tool use 时，content 里会出现 tool_use 块，届时必须先按块类型筛选，再取文本——不能无脑 content[0].text。这是 D4 的经典陷阱。 2. 响应对象「包含很多信息」——即 usage、stop_reason、id、model 等元数据。呼应课时 1 的响应三字段：message 给人看，usage / stop_reason 给系统看。

八、收束

官方原句：With these basics in place, you can start experimenting with different prompts and building more complex interactions with the AI.

精译：打好这些基础后，你就可以开始尝试不同的提示词，并构建与 the AI 更复杂的交互了。

🔤 本课新生词（临时小表 · 已回灌 30-单词表/04- 第 3 章分组）

课时 4 · Multi-Turn conversations

类型：🎬 视频 ｜ lesson ID：287735 ｜ 官方直链 精译状态：✅ 已完成（2026-10-15，用户提供官方讲稿原文） ⭐⭐ 本课权重提示：全章最重要的概念课，没有之一。官方在这里给出了一个会反复考的结论：the AI 不保存任何对话历史，每次请求完全独立（stateless）。多轮对话不是 API 提供的功能，而是调用方自己维护状态的结果。这一条同时命中 D1（27% 架构）、D3（20% 提示与上下文）与 D5（15% 成本），且是后面 context management、prompt caching、tool use 多轮等一切高级话题的前提。

🎯 本课学习目标（据官方段落反推）

⚠️ 本课官方未提供独立的 What you'll learn 区块。

1. 能一句话说清 API 是无状态的，以及这意味着谁负责保存上下文。
2. 能解释「为什么直接连续提问会答非所问」。
3. 能列出维持多轮上下文的两件必做事与四步流程。
4. 能读懂三个 helper 函数的分工。
5. 能识别由此引出的成本与上下文窗口问题（见第七节，含非原文补充部分）。

一、⭐⭐ 核心事实：API 是无状态的（stateless）

官方原句：When working with the the AI provider API and the AI, there's a crucial concept you need to understand: the AI doesn't store any of your conversation history. Each request you make is completely independent, with no memory of previous exchanges.

精译：在使用官方 API 与 the AI 时，有一个关键概念你必须理解：the AI 不会保存你的任何对话历史。你发出的每一次请求都完全独立，对先前的往来没有任何记忆。

官方原句：This means if you want to have a multi-turn conversation where the AI remembers context from earlier messages, you need to handle the conversation state yourself.

精译：这意味着，如果你想进行多轮对话、让 the AI 记住前面消息里的上下文，你就必须自己处理对话状态。

⭐⭐ 记忆锚（本课唯一必背句）： 「模型没有记忆，记忆在你手里。」 三个官方用词把这件事钉死了：doesn't store（不存）、completely independent（完全独立）、no memory（无记忆）；而责任归属也只有一句：you need to handle the conversation state yourself（状态由你管）。 ⚠️ 考场避坑：任何声称「模型会记住上一轮对话」「API 有会话 ID 会自动保留上下文」「多轮是服务端维护的」的选项，一律判错。

二、无状态会怎样出错（The Problem with Stateless Conversations）

官方原句：Let's say you ask the AI "What is quantum computing?" and get a good response. Then you follow up with "Write another sentence" - the AI has no idea what you're referring to. It will write a sentence about something completely random because it has no memory of the quantum computing discussion.

精译：假设你问 the AI「什么是量子计算？」并得到了一个不错的回答。接着你追问一句「再写一句话」——the AI 完全不知道你在指什么。它会写出一句关于某个完全随机的东西的话，因为它对刚才那段量子计算的讨论毫无记忆。

💡 架构师视角：这个例子值得记牢，因为它是「指代消解失败」的最小复现。Write another sentence 里没有任何实体，它的全部语义都依赖前文；前文一旦缺失，模型只能自由发挥。把这个例子换成企业场景就是——用户问「那它的价格呢？」，系统若没带上历史，Assistant 就只能瞎猜。

三、⭐⭐ 多轮对话怎么做对（How Multi-Turn Conversations Work）

官方原句：To maintain conversation context, you need to do two things:

• Manually maintain a list of all messages in your code
• Send the complete message history with every request

精译：要维持对话上下文，你需要做两件事：

1. 在你的代码里手动维护一个包含所有消息的列表；
2. 每一次请求都把完整的消息历史一并发送。

官方原句：Here's the flow that actually works:

1. Send your initial user message to the AI
2. Take the AI's response and add it to your message list as an assistant message**
3. Add your follow-up question as another user message**
4. Send the entire conversation history to the AI

精译：真正可行的流程是这样的：

⭐⭐ 第 2 步是整个多轮机制的关键：你必须把模型的回复自己存回来。 很多初学者以为「发过一次模型就知道了」——这就是无状态带来的直觉错误。官方用 assistant message 这个词明确了回写时的 role 取值（呼应课时 3 的两类消息）。 ⚠️ 考场避坑：若代码里只 add_user_message 而不 add_assistant_message，对话依然是断的——因为历史里全是你的提问、没有模型的回答，模型看不到自己说过什么。

四、三个辅助函数（Building Helper Functions）

官方原句：To make conversation management easier, you can create three helper functions:

def add_user_message(messages, text):
    user_message = {"role": "user", "content": text}
    messages.append(user_message)

def add_assistant_message(messages, text):
    assistant_message = {"role": "assistant", "content": text}
    messages.append(assistant_message)

def chat(messages):
    message = client.messages.create(
        model=model,
        max_tokens=1000,
        messages=messages,
    )
    return message.content[0].text

精译：为了让对话管理更轻松，你可以创建三个辅助函数：

💡 两个值得注意的实现细节： 1. 三个函数都在原地 append 修改同一个 messages 列表——这个列表就是唯一的状态载体。它没有存在模型里，也没有存在服务端，就在你的进程内存里。 2. chat() 里 max_tokens=1000 与课时 3 一致，再次印证它是安全上限；message.content[0].text 的取法也与课时 3 相同（本课只有文本块，故 [0] 安全）。

五、串起来（Putting It All Together）

官方原句：Here's how you use these functions to maintain a conversation:

# Start with an empty message list
messages = []

# Add the initial user question
add_user_message(messages, "Define quantum computing in one sentence")

# Get the AI's response
answer = chat(messages)

# Add the AI's response to the conversation history
add_assistant_message(messages, answer)

# Add a follow-up question
add_user_message(messages, "Write another sentence")

# Get the follow-up response with full context
final_answer = chat(messages)

精译：以下是用这些函数维持一段对话的方式（代码同上）。要点依次为：从一个空的消息列表开始 → 加入首条用户提问 → 取得 AI 回复 → 把 AI 回复加回对话历史 → 加入追问 → 带着完整上下文取得追问的回复。

官方原句：Now the AI will understand that "Write another sentence" refers to expanding on the quantum computing definition, because you've provided the complete conversation context.

精译：现在 the AI 会明白「再写一句话」指的是对量子计算定义作进一步展开，因为你已经提供了完整的对话上下文。

六、收束

官方原句：These helper functions will be useful throughout your work with the AI, making it much easier to build applications that can maintain meaningful conversations over multiple exchanges.

精译：这些辅助函数在你后续使用 the AI 的过程中会一直很有用，能让你更容易构建出可在多轮往来中维持有意义对话的应用。

七、⭐ 由无状态引出的两个架构后果

📌 以下为本课的架构延伸，非官方原文——官方在本课只讲了「怎么做对」，没有讲代价。但这两条是 D1/D5 的常考点，务必提前建立意识。

后果 1：token 成本与延迟随轮次累积。 因为每一轮都要重发完整历史，第 n 轮的输入 token ≈ 前 n−1 轮的全部内容之和。对话越长，单轮成本越高、延迟越长，近似随轮次增长。这直接引出上下文管理策略：滑动窗口（只保留最近 k 轮）、历史摘要压缩、以及提示缓存（prompt caching，第 8 章 / What You'll Learn 9）——后者正是官方给出的、针对「长且稳定的前缀反复重发」这一痛点的解法（呼应精讲 018 latency：缓存同时降成本与延迟）。

后果 2：上下文窗口是硬约束。 历史不可能无限累积。超过上下文窗口就必须裁剪或压缩，而裁剪什么、保留什么本身就是一个架构决策——剪掉系统指令与剪掉最近一轮，后果完全不同。 🔗 跨课串联：本课 → 第 8 章 prompt caching → 第 11 章 agents（智能体的循环同样依赖外部状态管理）；与精讲 006 contextual retrieval、020 retrieval 共享同一个底层命题：模型看到什么，完全由你这一次请求里送进去的东西决定。

🔤 本课新生词（临时小表 · 已回灌 30-单词表/04- 第 3 章分组）

课时 5 · Chat exercise

类型：🎬 视频 ｜ lesson ID：287727 ｜ 官方直链

• 精译状态：⏸ 不补（决定 2026-10-16）——练习课，官方无讲稿/字幕正文，仅动手任务，无可精译语料。
• 建议复习指向：巩固课时 3《Making a request》与课时 4《Multi-Turn conversations》，考点已覆盖——messages.create() 三参数、.env ＋ load_dotenv()、message.content[0].text、API 无状态与多轮拼接。自测即按课时 4 的 add_user_message / add_assistant_message 辅助函数重写一遍。
• 本章新生词：无（练习课不产生新语料；相关词已随课时 3、4 回灌）

课时 6 · System prompts

类型：🎬 视频 ｜ lesson ID：287733 ｜ 官方直链 精译状态：✅ 已完成（2026-10-15，用户提供官方讲稿原文） ⭐⭐ 本课权重提示：D3（20%）的核心课，也是全章第二重点。系统提示词是官方给出的「控行为第一手段」，与课时 8 的 temperature 并列构成 What You'll Learn 第 3 条的两大抓手。本课有两个必考点：system 是独立参数、不属于 messages；以及它必须每轮重发（无状态，呼应课时 4）。

🎯 本课学习目标（据官方段落反推）

⚠️ 本课官方未提供独立的 What you'll learn 区块。

1. 能说清 system prompt 的作用：塑造语气、风格与处理方式。
2. 能指出 system 在 create() 中是独立参数，不在 messages 里。
3. 能解释为什么 system=None 不可行、应如何条件性传入。
4. 能写出一个可复用的 chat(messages, system=None)。

一、开场：系统提示词能做什么

官方原句：System prompts are a powerful way to customize how the AI responds to user input. Instead of getting generic answers, you can shape the AI's tone, style, and approach to match your specific use case.

精译：系统提示词是一种强有力的方式，用来定制 the AI 回应用户输入的方式。你不再只能得到千篇一律的通用回答，而是可以塑造 the AI 的语气、风格与处理方式，使之契合你的具体用例。

🔗 词源串联：customize（定制）与 generic（通用的）是本课的一对反义。精讲 026 appropriate（恰当的）与 025 essential（必要的）也出自本课附近的官方措辞。

二、为什么需要它（Why System Prompts Matter）

官方原句：Consider building a math tutor chatbot. When a student asks "How do I solve 5x + 2 = 3 for x?", you want the AI to act like a real tutor, not just spit out the answer. A good math tutor should:

• Initially give hints rather than complete solutions
• Patiently walk students through problems step by step
• Show solutions for similar problems as examples

You definitely don't want the AI to:

• Immediately give direct answers
• Tell students to just use a calculator

精译：设想你在构建一个数学辅导聊天机器人。当学生问「怎么解 5x + 2 = 3 中的 x？」时，你希望 the AI 像一个真正的家教那样行事，而不是直接把答案吐出来。一个好的数学家教应该：

⭐ 架构师视角：这个例子之所以被官方选中，是因为它演示了一件提示词能做到、而参数做不到的事——约束输出的「方式」而不只是「内容」。 注意官方要的是「先给提示、一步步引导」，这是一种行为策略；没有任何 API 参数能表达它。这类需求只能写在 system prompt 里。 💡 反过来说：凡是能用参数表达的（如输出长度上限、随机性幅度），就不该塞进提示词——那是精讲 018 latency 与课时 3 反复强调的分工原则。

三、⭐⭐ 它是怎么工作的（How System Prompts Work）

官方原句：System prompts provide the AI with guidance on how to respond. You define them as plain strings and pass them into the create function call. The key benefits are:

• System prompts provide the AI guidance on how to respond
• the AI will try to respond in the same way someone in the specified role would respond
• Helps keep the AI on task**

精译：系统提示词为 the AI 提供关于「该如何回应」的指导。你把它们定义成普通字符串，并传入 create 函数调用。主要好处是：

官方原句（基础结构）：

system_prompt = """
You are a patient math tutor.
Do not directly answer a student's questions.
Guide them to a solution step by step.
"""

client.messages.create(
    model=model,
    messages=messages,
    max_tokens=1000,
    system=system_prompt
)

⭐⭐ 本课头号考点：system 是独立参数，不在 messages 里。 请对照课时 3、4 的用法——messages 里的每条消息都是 {"role": ..., "content": ...}，而 role 的取值官方只给过 "user" 与 "assistant" 两种（课时 3）。 system 是 create() 的顶层参数，与 model / max_tokens / messages 平级，不是一条消息，也不存在 "role": "system" 这种写法。 ⚠️ 考场避坑： 1. 选项若写 messages=[{"role": "system", ...}] —— 判错（那是其他厂商 API 的惯例，不是本 API 的结构）。 2. 它是字符串（plain strings），不是字典、不是列表。 🔗 与无状态的关系（呼应课时 4）：system 同样每轮都要重发。它不在服务端保存，也不靠会话 ID 留存——每一轮请求都必须带上，否则行为立刻回落为默认。这一点在多轮应用中极易漏掉。

四、效果对比（Seeing the Difference）

官方原句：Without a system prompt, the AI gives a complete step-by-step solution immediately. This might be helpful, but it doesn't encourage the student to think through the problem themselves.

With the math tutor system prompt, the AI's response changes dramatically. Instead of providing the full solution, the AI asks guiding questions like "What do you think would be a good first step to isolate x? Consider what operation we might need to perform on both sides to start moving terms around."

精译：没有系统提示词时，the AI 会立刻给出完整的分步解答。这也许有帮助，但它不会促使学生自己去把问题想通。

加上数学家教系统提示词后，the AI 的回答会发生戏剧性的变化。它不再提供完整解答，而是提出引导式问题，例如：「你认为 isolating x（把 x 单独留在一边）的第一步该做什么？想想我们可能需要在等式两边做怎样的运算，才能开始移项。」

💡 架构师视角：官方用 dramatically（戏剧性地）这个词，是在强调 system prompt 的杠杆率——改一段字符串，就改变了整个应用的行为模式，无需改代码、无需微调模型。这正是它被称为 powerful 的原因。

五、⭐ 把 system 变成可选参数（Building a Flexible Chat Function）

官方原句：Rather than hard-coding system prompts, you can make your chat function more reusable by accepting system prompts as parameters:

def chat(messages, system=None):
    params = {
        "model": model,
        "max_tokens": 1000,
        "messages": messages,
    }

    if system:
        params["system"] = system

    message = client.messages.create(**params)
    return message.content[0].text

精译：与其把系统提示词硬编码进函数，不如让它接受 system 作为参数，从而使你的 chat 函数更具复用性（代码同上）。

官方原句：This approach handles an important detail: the AI's API doesn't accept system=None, so you need to conditionally include the system parameter only when it's provided.

精译：这种做法处理了一个重要细节：本 API 不接受 system=None，因此你必须只在确实提供了 system 时，才条件性地把它加入参数。

⭐ 两个工程要点： 1. system=None 会报错——这是本 API 的硬性约束，不是风格偏好。所以必须 if system: 之后再塞进 params，不能无条件传。这是考题里很实在的一个细节。 2. **params 字典解包是这里的标准写法：把参数先在字典里拼装好，再一次解包传入。这种写法在多参数、可选参数多的场景（后面会加 temperature、tools）里会一直用到。

两种调用方式（官方原句）：

# Without system prompt
answer = chat(messages)

# With system prompt
system = """
You are a patient math tutor.
Do not directly answer a student's questions.
Guide them to a solution step by step.
"""
answer = chat(messages, system=system)

六、收束

官方原句：System prompts are essential for creating AI applications that behave consistently and appropriately for their intended purpose. They transform generic AI responses into specialized, role-appropriate interactions.

精译：系统提示词对于构建行为一致、且契合其预期用途的 AI 应用而言是必不可少的。它们把通用的 AI 回答，转变为专门的、符合角色定位的交互。

🔗 精讲互引：essential → 025；consistent / appropriately → 026 appropriate；generic ↔ specialized 构成本课的反义主轴。 ⭐ 一句话总结本课：system prompt 决定「它是谁、怎么说话」；user message 决定「这一轮要做什么」。

🔤 本课新生词（临时小表 · 已回灌 30-单词表/04- 第 3 章分组）

课时 7 · System prompts exercise

类型：🎬 视频 ｜ lesson ID：287724 ｜ 官方直链

• 精译状态：⏸ 不补（决定 2026-10-16）——练习课，官方无讲稿/字幕正文。
• 建议复习指向：巩固课时 6《System prompts》的 system 参数与 if system: 条件传入模式（chat(messages) → chat(messages, system=None)）。重点：system=None 不可直接传入，必须条件化。
• 本章新生词：无（相关词已随课时 6 回灌：conditionally / hard-coding / reusable 等均已收录）

课时 8 · Temperature

类型：🎬 视频 ｜ lesson ID：287728 ｜ 官方直链 精译状态：✅ 已完成（2026-10-15，用户提供官方讲稿原文） ⭐⭐ 本课权重提示：D3（20%）的核心课，全章第三重点，与课时 6 的 system prompt 并列构成 What You'll Learn 第 3 条的两大控行为抓手。必考点有三个：temperature 的取值范围与默认值、三档任务对照表（枚举题高频）、以及 Key Takeaways 那句「不保证输出不同」。

🎯 本课学习目标（据官方段落反推）

⚠️ 本课官方未提供独立的 What you'll learn 区块。

1. 能说清 temperature 控制的是可预测性 ↔ 创造性这一对张力。
2. 能列出生成的三个步骤（tokenization / prediction / sampling）。
3. 能背出三档温度区间各自适合的任务类型。
4. 能说清 temperature 不保证输出不同这一关键限定。

一、开场

官方原句：Temperature is a powerful parameter that controls how predictable or creative the AI's responses will be. Understanding how to use it effectively can dramatically improve your AI applications.

精译：Temperature 是一个强有力的参数，它控制 the AI 的回应有多可预测或多有创造性。理解如何有效地使用它，能显著改善你的 AI 应用。

二、生成过程三步骤（How the AI Generates Text）

官方原句：Before diving into temperature, it helps to understand the AI's text generation process. When you send the AI a prompt like "What do you think?", it goes through three key steps:

• Tokenization - Breaking your input into smaller chunks
• Prediction - Calculating probabilities for possible next words
• Sampling - Choosing a token based on those probabilities

In this example, the AI might assign a 30% probability to "about", 20% to "would", 10% to "of", and so on. The model then selects one token and repeats this entire process to build complete sentences.

精译：在深入 temperature 之前，先理解 the AI 的文本生成过程会有帮助。当你向 the AI 发送诸如「你怎么看？」这样的提示时，它会经过三个关键步骤：

以该例来说，the AI 可能给 "about" 分配 30% 的概率、给 "would" 20%、给 "of" 10%，以此类推。模型随后选出一个 token，并重复整个过程以构建完整的句子。

⭐⭐ 与课时 1 的口径差异（重要串联点）： 课时 1 讲的是四阶段（tokenization → embedding → contextualization → generation），本课讲的是三步骤（tokenization → prediction → sampling）。二者不矛盾，是同一件事的两种粒度：

课时 1（四阶段，讲「理解与生成」）	课时 8（三步骤，讲「怎么选词」）
tokenization	tokenization
embedding ＋ contextualization	（合并进前置理解，本课略过）
generation	prediction ＋ sampling

也就是说，本课把课时 1 的 generation 拆成了「先算概率（prediction）」与「再按概率挑一个（sampling）」两步——而 temperature 作用的正是第二步：sampling。 ⚠️ 考场避坑：题干若问「temperature 影响哪一步」，答案是采样（sampling），不是「改变概率计算（prediction）」本身。这个区分很细，但正是 D3 爱考的地方。

三、⭐⭐ temperature 到底做了什么（What Temperature Does）

官方原句：Temperature is a decimal value between 0 and 1 that directly influences these selection probabilities. It's like adjusting the "creativity dial" on the AI's responses.

At low temperatures (near 0), the AI becomes very deterministic - it almost always picks the highest probability token. At high temperatures (near 1), the AI distributes probability more evenly across options, leading to more varied and creative outputs.

精译：Temperature 是一个介于 0 与 1 之间的小数，它直接影响这些选择概率。它就像是调节 the AI 回答上的「创造力旋钮」。

低温（接近 0）时，the AI 变得非常确定（deterministic）——它几乎总是选择概率最高的那个 token。高温（接近 1）时，the AI 会把概率更均匀地分布到各个候选项上，从而产生更多样、更有创造性的输出。

官方原句（Interactive Temperature Demo）：You can see temperature in action with the AI's interactive demo. Watch how the probability distribution changes as you adjust the temperature slider:

At temperature 0.0, "about" gets 100% probability - completely deterministic. At temperature 1.0, probabilities spread more evenly across all possible tokens, introducing randomness and creativity.

精译：你可以通过官方的交互式演示直观看到 temperature 的作用。观察当你拖动 temperature 滑块时，概率分布如何变化：

⭐⭐ 记忆锚：temperature 不是在「加噪声」，而是在「压平或锐化概率分布」。 * 低温 → 分布锐化（赢家通吃，最高概率项接近 100%） * 高温 → 分布压平（大家机会均等，长尾候选也有机会被采到） 🔗 回扣课时 1：课时 1 说模型「并不总是挑选概率最高的词，而是把概率与受控的随机性混合使用」——那个 controlled randomness 的控制旋钮就是 temperature。本课的 creativity dial 与课时 1 的 controlled randomness 是同一件事的两个说法。

四、⭐⭐ 三档温度区间与适用任务（Choosing the Right Temperature）

官方原句：Different tasks call for different temperature ranges:

⭐⭐ 这是一道现成的枚举题，建议按「任务性质」而非死记来理解： * 低温 = 有唯一正确答案或需要稳定的任务（事实、代码、抽取、审核）——错了就是 bug； * 中温 = 需要结构但允许措辞变化（摘要、教学、解题）——「带约束的创意写作」这一项尤其值得注意：它说明创意与约束并不冲突，约束由提示词给，自由度由温度给（呼应课时 6 的 system prompt 分工）； * 高温 = 要的就是多样性（头脑风暴、创意、营销、笑话）——结果越出人意料越好。 ⚠️ 考场避坑：若题干是「从发票中抽取金额字段」或「判定内容是否违规」，一定选低温；选高温即判错——数据抽取与内容审核绝不能用高温，这是送分或送命的区别。

五、代码实现（Implementing Temperature in Code）

官方原句：Adding temperature support to your chat function is straightforward. Here's how to modify your existing function:

def chat(messages, system=None, temperature=1.0):
    params = {
        "model": model,
        "max_tokens": 1000,
        "messages": messages,
        "temperature": temperature
    }

    if system:
        params["system"] = system

    message = client.messages.create(**params)
    return message.content[0].text

精译：为你的 chat 函数加上 temperature 支持是很直接的。以下是修改现有函数的方式（代码同上）。

官方原句：The key changes are adding temperature=1.0 as a parameter and including "temperature": temperature in the params dictionary.

精译：关键的改动有两点：把 temperature=1.0 作为参数加入函数签名，以及把 "temperature": temperature 放进 params 字典。

⭐ 两个工程要点： 1. 默认值为 1.0——即不传就是最高创造性档。这与很多人的直觉（以为默认是 0）相反，是个实打实的考点。生产环境若要稳定输出，必须显式传低温。 2. 与课时 6 相同的 if system: 条件传入模式在此保留——因为 system=None 依然不被接受。两课合起来看，chat() 的签名演进是：chat(messages) → chat(messages, system=None) → chat(messages, system=None, temperature=1.0)。

六、效果实测（Testing Temperature Effects）

官方原句：To see temperature in action, try generating movie ideas with different settings:

# Low temperature - more predictable
answer = chat(messages, temperature=0.0)

# High temperature - more creative
answer = chat(messages, temperature=1.0)

精译：要看 temperature 的实际效果，可以试试用不同设置生成电影创意（代码同上）。

官方原句：At temperature 0.0, you might consistently get responses like "A time-traveling archaeologist must prevent ancient artifacts from being stolen." At temperature 1.0, you'll see much more variety in themes, characters, and plot elements.

精译：在 temperature 0.0 时，你可能每次都得到类似「一位时间旅行的考古学家必须阻止古代文物被盗」这样的回答。而在 temperature 1.0 时，你会看到在主题、角色与情节元素上丰富得多的多样性。

七、⭐⭐ Key Takeaways

官方原句：Remember that temperature doesn't guarantee different outputs - it just changes the probability of getting them. Even at high temperatures, the AI might occasionally produce similar responses. The key is matching your temperature choice to your specific use case:

• Need consistent, factual responses? Use low temperature**
• Want creative brainstorming? Dial up the temperature
• Somewhere in between? Medium temperatures work well for most general tasks**

Temperature is one of the most practical parameters you can adjust to fine-tune the AI's behavior for your specific needs.

精译：请记住——temperature 并不保证输出会不同，它只是改变了得到不同输出的概率。即使在高温下，the AI 也可能偶尔产生相似的回答。关键在于让你的温度选择匹配你的具体用例：

• 需要一致、事实性的回答？用低温。
• 想要有创造性的头脑风暴？把温度调高。
• 介于两者之间？中温对大多数通用任务都很合适。

Temperature 是你可以调整的、最实用的参数之一，用来为你的具体需求微调 the AI 的行为。

⭐⭐ 三个必记的限定（D3 送分点）： 1. 「不保证不同」（doesn't guarantee different outputs）——这是最容易被考的限定句。题干若说「把 temperature 设为 1.0 就能确保每次输出都不一样」，判错。它改变的只是概率。 2. 「中温适合大多数通用任务」——当题目没给明确场景、只问「一般任务该用什么」时，答案是中温（0.4–0.7）。 3. fine-tune 在此是「微调行为」的普通动词，不是「微调模型」——⚠️ 本课没有涉及模型训练意义上的 fine-tuning。考题若把 temperature 与 fine-tuning 混为一谈，那是偷换概念（真正的 fine-tuning 见精讲 014 retrieval-augmented 中 RAG vs. Fine-tuning 的辨析）。

🔤 本课新生词（临时小表 · 已回灌 30-单词表/04- 第 3 章分组）

课时 9 · Course satisfaction survey

类型：📝 测验 ｜ lesson ID：297284 ｜ 官方直链

• 精译状态：⏸ 不补（决定 2026-10-16）——课程满意度调研，无教学语料，仅一页问卷。
• 建议复习指向：本课唯一可考价值是标题词 satisfaction，已升级为 ⭐⭐ 精讲 022（D5 用户体验满意度 CSAT 反馈闭环 / D3 约束满足），无需再补。
• 本章新生词：satisfaction（对应生词表 022，⭐⭐ 已精讲）

课时 10 · Response streaming

类型：🎬 视频 ｜ lesson ID：287734 ｜ 官方直链

🎯 本课学习目标（据官方段落反推）

1. 能说出标准（非流式）响应在 UX 上的具体缺陷，以及它出现的数量级场景（10–30 秒）。
2. 能复述流式的两段式机制：先回一个「已收到、开始生成」的初始响应，再持续推送事件流。
3. 能按序列出六种流式事件，并指出哪一类事件才真正承载文本。
4. 能写出 stream=True 的基础写法，以及 client.messages.stream(...) ＋ text_stream 的简化写法。
5. 能解释为什么还需要 get_final_message()——「流式给用户看、完整对象给程序用」的双通道。

一、开场：10–30 秒的空窗（The UX Challenge）

官方原句：When building chat applications with the AI, there's a significant user experience challenge: responses can take 10-30 seconds to generate, leaving users staring at a loading spinner. The solution is response streaming, which lets users see text appear chunk by chunk as the AI generates it, creating a much more responsive feel.

精译：用 the AI 构建聊天应用时，存在一个相当大的用户体验难题：生成响应可能要花 10 到 30 秒，用户只能盯着加载转圈干等。解决办法就是响应流式——它让用户在 the AI 生成的同时一块一块地看到文字浮现，带来明显更即时的观感。

⭐ 三个原话数字/短语要记：10–30 秒、chunk by chunk、single request。这三个在本课各出现一次，都是题干爱直接引用的官方原话。

二、⭐⭐ 标准响应出了什么问题（The Problem with Standard Responses）

官方原句：In a typical chat setup, your server sends a user message to the AI and waits for the complete response before sending anything back to the client. This creates an awkward delay where users have no feedback that anything is happening.

精译：在典型的聊天架构中，你的服务端把用户消息发给 the AI，然后等待完整响应生成完毕，才向客户端回传任何东西。这就造成了一段尴尬的延迟——在此期间用户得不到任何「事情正在发生」的反馈。

⚠️ 本课最值得咬文嚼字的一句：官方措辞是 no feedback that anything is happening——痛点不是「慢」，而是没有「正在发生」的反馈。考题若把流式的价值说成「让生成更快」，判错。

三、⭐⭐ 流式是怎么工作的（How Streaming Works）

官方原句：With streaming enabled, the AI immediately sends back an initial response indicating it has received your request and is starting to generate text. Then you receive a series of events, each containing a small piece of the overall response.

Your server can forward these text chunks to your client application as they arrive, allowing users to see the response building up word by word. All of these events are part of a single request to the AI.**

精译：开启流式后，the AI 会立即返回一个初始响应，表明它已收到请求、正在开始生成文本。随后你会收到一连串事件，每个事件携带整体响应中的一小片。

你的服务端可以在这些文本块到达的同时就将其转发给客户端应用，让用户看到响应逐字累积起来。而所有这些事件都属于对 the AI 的同一个请求。

⭐⭐ 两句必背限定（D1/D3 送分点）： 1. 「同一个请求」（a single request）——这是本课最常被考的陷阱。流式不是「发很多次请求」，而是一次请求、多次事件。题干出现「streaming sends multiple requests」→ 判错。 2. 优化的是感知延迟，不是实际速度——流式改变的是用户看到反馈的时机，不改变模型生成 token 的总耗时。它优化的是 perceived latency（感知延迟），而非 actual latency（实际延迟）。🔗 精讲 018 latency

四、⭐⭐ 六种流式事件（Understanding Stream Events）

官方原句：When you enable streaming, the AI sends back several types of events:

官方原句：The ContentBlockDelta events contain the actual generated text that you'll want to display to users.

精译：ContentBlockDelta 事件承载着你要展示给用户的实际生成文本。

⭐⭐ 两条必须能答的枚举题： 1. 「哪些事件携带真正要显示的文本？」→ 只有 ContentBlockDelta。MessageStart、ContentBlockStop 等只是结构信号，本身不含文本。 2. 「ContentBlockStart 里可能装什么？」→ text、tool use 或其他内容。这句直接埋了第 6 章 Tool use 的伏笔：届时 content 数组里会混进 tool_use 块，必须先按块类型筛，再取文本，不能无脑取 [0]（与课时 3 的提醒呼应）。

五、基础流式实现（Basic Streaming Implementation）

官方原句：To enable streaming, add stream=True to your messages.create call:

messages = []
add_user_message(messages, "Write a 1 sentence description of a fake database")

stream = client.messages.create(
    model=model,
    max_tokens=1000,
    messages=messages,
    stream=True
)

for event in stream:
    print(event)

精译：要启用流式，只需在 messages.create 调用里加上 stream=True（代码同上）。

⭐ 三点注意： 1. 开关就是 stream=True——这是 D3 的直接题眼，与课时 8 的 temperature 同属「参数 → 行为」映射题。 2. 与课时 3 的 create() 相比，原有参数一个没少（model / max_tokens / messages），只是多了一个 stream。调用签名的演进是：create(...) → create(..., system=...) → create(..., temperature=...) → create(..., stream=True)。 3. for event in stream: 迭代拿到的是原始事件对象——六种事件混在一起，需要你自己按类型分辨。这正是下一段「简化接口」存在的理由。

六、⭐⭐ 简化文本流（Simplified Text Streaming）

官方原句：Rather than manually parsing events, you can use the SDK's simplified streaming interface that extracts just the text content:

with client.messages.stream(
    model=model,
    max_tokens=1000,
    messages=messages
) as stream:
    for text in stream.text_stream:
        print(text, end="")

精译：与其手工解析事件，你可以使用 SDK 的简化流式接口，它只抽取文本内容（代码同上）。

官方原句：This approach automatically filters out everything except the actual text content, which is usually what you need for displaying responses to users.

精译：这种方式会自动过滤掉除实际文本内容以外的一切，而这通常正是你向用户展示响应所需要的。

⭐⭐ 两个形式差异必须记住： 1. with ... as stream:——简化接口是上下文管理器，官方示例用 with 包起来。漏掉 with 是典型写法错误。 2. print(text, end="")——end="" 是为了不换行，让文字连续浮现。这一行本身就是「流式观感」的落地点。

七、⭐⭐ 拿到完整消息（Getting the Complete Message）

官方原句：While streaming individual chunks is great for user experience, you often need the complete message for storage or further processing. After streaming completes, you can get the assembled final message:

with client.messages.stream(
    model=model,
    max_tokens=1000,
    messages=messages
) as stream:
    for text in stream.text_stream:
        # Send each chunk to your client
        pass

    # Get the complete message for database storage
    final_message = stream.get_final_message()

精译：虽然把一个个分块流式推给用户很棒，但为了存储或后续处理，你常常还需要完整的消息。在流式结束后，你可以拿到组装好的最终消息（代码同上）。

官方原句：This gives you the best of both worlds: real-time streaming for users and a complete message object for your application logic.

精译：这让你两全其美：给用户实时的流式体验，给你的应用逻辑一个完整的消息对象。

⭐⭐ 本课第二高频考点（D1 架构题）： 「两条通道」必须并存—— * text_stream → 给用户看（实时、增量） * get_final_message() → 给程序用（落库、后处理、审计）

典型题干：「流式响应下如何把对话存入数据库？」正确答案不是「把收到的 chunk 自己拼起来」，而是调用 get_final_message() 取 SDK 组装好的对象。自己拼接会丢掉 stop_reason、usage、块结构等元数据。

八、⭐ Key Takeaways（本课官方无独立 Key Takeaways 段，据正文反推）

1. 流式的动机是 UX：消除 10–30 秒的无反馈空窗。
2. 机制是一次请求、多次事件；ContentBlockDelta 才带文本。
3. 三档写法递进：stream=True 拿全事件 → messages.stream() ＋ text_stream 只要文本 → get_final_message() 拿完整对象。
4. 流式不提速，它只改变反馈时机（感知延迟）。
5. 生产架构要双通道：text_stream 给用户，get_final_message() 给程序。

🔤 本课新生词（临时小表 · 已回灌 30-单词表/04- 第 3 章分组）

课时 11 · Structured data

类型：🎬 视频 ｜ lesson ID：287732 ｜ 官方直链

🎯 本课学习目标（据官方段落反推）

1. 能说出默认响应在结构化输出场景下的具体缺陷（不是内容错，而是被包装了）。
2. 能独立写出「预填 ＋ 停止序列」组合技，并解释每一步在做什么。
3. 能说清预填的是 assistant 消息而非 user 消息——这是本课最容易搞反的一点。
4. 能处理响应里的多余换行（strip() ＋ json.loads()）。
5. 能把这套技法迁移到 JSON 之外的其他结构化场景，并说出迁移的判断依据。

一、开场：好心办坏事的「解释欲」

官方原句：When you need the AI to generate structured data like JSON, Python code, or bulleted lists, you'll often run into a common problem: the AI wants to be helpful and add explanatory text around your content. While this is usually great, sometimes you need just the raw data with nothing else.

精译：当你需要 the AI 生成结构化数据（如 JSON、Python 代码或项目符号列表）时，常会碰到一个普遍问题：the AI 出于「乐于助人」，会在你的内容外面加上解释性文字。这通常很好，但有时你只需要纯粹的原始数据，别的什么都不要。

⭐ 题眼句：官方把问题定性为 wants to be helpful——内容本身没错，错的是包装。考题若问「默认响应的 JSON 有什么问题」，标准答案是被 markdown 代码块和解释文字包裹，无法直接复制，而不是「JSON 格式不合法」。

二、一个具体场景：AWS EventBridge 规则生成器

官方原句：Consider building a web app that generates AWS EventBridge rules. Users enter a description, click generate, and expect to see clean JSON they can immediately copy and use. If the AI returns the JSON wrapped in markdown code blocks with explanatory text, users can't simply copy the entire response - they have to manually select just the JSON portion.

精译：设想你在做一个生成 AWS EventBridge 规则的 Web 应用。用户输入描述、点击生成，期望看到干净的 JSON，可以立刻复制使用。如果 the AI 返回的 JSON 被包裹在 markdown 代码块里还附带解释文字，用户就没法直接复制整个响应——他们必须手动选中 JSON 那一部分。

⭐ UX 判据：本课的验收标准是「能否整段复制」。这与课时 10 的 UX 主线一致——两课都在讲减少用户的人工介入。

三、⭐⭐ 默认响应长什么样（The Problem with Default Responses）

官方原句：By default, when you ask the AI to generate JSON, you might get something like this:

```json
{
  "source": ["aws.ec2"],
  "detail-type": ["EC2 Instance State-change Notification"],
  "detail": {
    "state": ["running"]
  }
}
```

This rule captures EC2 instance state changes when instances start running.

官方原句：The JSON is correct, but it's wrapped in markdown formatting and includes explanatory text. For a web app where users need to copy the raw JSON, this creates friction in the user experience.

精译：JSON 是正确的，但它被包裹在 markdown 格式里，还包含了解释性文字。对于用户需要复制原始 JSON 的 Web 应用来说，这会在用户体验中制造摩擦。

⭐⭐ 必记的官方定性：The JSON is correct, but...——问题不在正确性，在包装。这句原话几乎就是一道判断题的题干和答案。

四、⭐⭐ 组合技：预填 ＋ 停止序列（The Solution）

官方原句：You can combine assistant message prefilling with stop sequences to get exactly the content you want. Here's how it works:

messages = []

add_user_message(messages, "Generate a very short event bridge rule as json")
add_assistant_message(messages, "```json")

text = chat(messages, stop_sequences=["```"])

精译：你可以把 assistant 消息预填与停止序列组合起来，精确得到你想要的内容。它的工作方式如下（代码同上）。

官方原句：This technique works by:

1. The user message tells the AI what to generate
2. The prefilled assistant message makes the AI think it already started a markdown code block
3. the AI continues by writing just the JSON content
4. When the AI tries to close the code block with ```, the stop sequence immediately ends generation**

精译：这项技法的原理是：

1. 用户消息告诉 the AI 要生成什么；
2. 预填的 assistant 消息让 the AI 以为自己已经开始了一个 markdown 代码块；
3. the AI 于是接着往下写，只写 JSON 内容；
4. 当 the AI 试图用 ``` 闭合代码块时，停止序列立刻终止生成。

⭐⭐ 四条里最容易考错的两条（D3 送分点）： 1. 预填的是 assistant 消息，不是 user 消息——add_assistant_message(messages, "```json")。写成 add_user_message 就完全失效。这是本课第一号陷阱，也与课时 4 的多轮对话机制（add_user_message / add_assistant_message 成对出现）直接衔接。 2. 第 2 步的机制是「让模型以为自己已经开始了」——不是指令、不是约束，而是续写。所以预填内容必须与模型本来的行文习惯一致（它本来就会用 json 开头），这就是为什么偏偏预填 `json ` 有效。

五、⭐ 结果：干净的输出

官方原句：The result is clean JSON with no extra formatting:

{
  "source": ["aws.ec2"],
  "detail-type": ["EC2 Instance State-change Notification"],
  "detail": {
    "state": ["running"]
  }
}

精译：结果是干净的 JSON，没有任何多余的格式。

⭐ stop_sequences 的双向作用（🔗 课时 1 停止条件）：课时 1 讲过，停止生成的三个条件之一是遇到预设停止短语，stop_reason 会是 "stop_sequence"。本课是它的首次实战——把模型自己要写的闭合标记 ``` 设成停止序列，等于在它画句号的前一瞬间掐断。

六、⭐ 处理响应（Processing the Response）

官方原句：You might notice some extra newline characters in the response. These are easy to handle:

import json

# Clean up and parse the JSON
clean_json = json.loads(text.strip())

精译：你可能会注意到响应里有一些多余的换行符。这些很容易处理（代码同上）。

⭐ 两步处理，顺序不能反： 1. text.strip()——先去掉首尾空白/换行（因为预填后开头常常多一个 \n）。 2. json.loads(...)——再解析成 Python 对象。

反过来（json.loads(text) 不 strip）在多数情况下也能过，但不稳健；官方明确给的写法是 strip() 之后再 loads()。🔗 课时 10 的 parse

七、⭐⭐ 不止于 JSON（Beyond JSON）

官方原句：This technique isn't limited to JSON generation. Use it anytime you need structured data without commentary:

• Python code snippets**
• Bulleted lists
• CSV data
• Any formatted content where you want just the content, not explanations

精译：这项技法不限于生成 JSON。任何需要「无解说」结构化数据的场合都可以用它：Python 代码片段、项目符号列表、CSV 数据、以及任何你只要内容不要解释的格式化内容。

官方原句：The key is identifying what the AI *naturally wants to wrap your content in, then using that as your prefill and stop sequence. For code, it's usually markdown code blocks. For lists, it might be different formatting markers.*

精译：关键在于识别出 the AI 自然倾向于用什么来包裹你的内容，然后把它用作你的预填内容和停止序列。对代码来说，通常是 markdown 代码块；对列表来说，则可能是不同的格式标记。

⭐⭐ 这是本课的迁移题答案（D3）： 题干若换成「如何只拿到一个 Python 列表 / CSV，不带解释？」——答案不是换个提示词，而是：观察模型默认会把内容包在什么标记里 → 用那个标记做 prefill → 用它的闭合标记做 stop_sequences。

八、⭐ Key Takeaways（本课官方无独立 Key Takeaways 段，据正文反推）

官方原句：This approach gives you precise control over the AI's output format, making it much easier to integrate AI-generated content into applications where clean, structured data is essential.

精译：这种方式让你能对 the AI 的输出格式拥有精确的控制，从而更容易把 AI 生成的内容集成到那些必需干净结构化数据的应用中。

1. 默认响应的问题在包装不在正确性（correct, but...）。
2. 预填 assistant 消息 ＋ 停止序列是取得纯净结构化输出的标准组合技。
3. 原理是让模型续写它本已开始的东西，而非下指令。
4. 响应要 strip() 后再 json.loads()。
5. 可迁移到任意结构化场景，判断依据是「模型自然想用什么包裹」。

🔤 本课新生词（临时小表 · 已回灌 30-单词表/04- 第 3 章分组）

课时 12 · Structured data exercise

类型：🎬 视频 ｜ lesson ID：287729 ｜ 官方直链

• 精译状态：⏸ 不补（决定 2026-10-16）——练习课，官方无讲稿/字幕正文。
• 建议复习指向：巩固课时 11《Structured data》的「预填 assistant 消息 ＋ 停止序列」组合技。自测要点：预填的是 assistant 消息（add_assistant_message），停止序列取闭合标记；响应需 strip() 后再 json.loads()。
• 本章新生词：无（相关词已随课时 11 回灌：prefill / stop sequence / raw / friction 等均已收录）

课时 13 · Quiz on accessing the AI with the API

类型：📝 测验 ｜ lesson ID：289117 ｜ 官方直链

• 精译状态：⏸ 不补（决定 2026-10-16）——章末测验，题目本身即考点，无讲稿语料，且需登录态取得。
• 建议复习指向：本章 8 课已精译完毕，测验覆盖的考点分布为——D5 自建服务端与 key 治理（课时 1、2）／ D3 请求参数与行为映射（课时 1、8、11）／D1 流式双通道架构（课时 10）／ D4 内容块结构（课时 10、11）。做题前建议重点回看各课的「⭐⭐ 必背限定」小节。
• 本章新生词：无（章末测验不产生新语料）

✅ 本章进度

• [x] 抓取本章讲稿/字幕（用户提供，2026-10-15）
• [x] 逐课精译（13 课时）—— 精译 8 课 ✅ ＋ 不补 5 课 ⏸ ＝ 13 课全覆盖（2026-10-16）
• 已精译（8）：课时 1–4、6、8、10、11
• ⏸ 不补（5）：课时 5、7、12 为练习课（无讲稿正文）；课时 9 为满意度调研；课时 13 为章末测验（题目需登录态）
• 说明：这 5 课官方均无可精译的讲稿/字幕语料，考点与生词已被相邻正课覆盖，故统一标注不补并各附复习指向
• [x] 生词回灌 30-单词表/04-—— 已建「第 3 章」速查分组（178 条）
• [x] ~~章节测验/练习（课时 13 Quiz）~~ —— ⏸ 不补（题目需登录态；复习指向见课时 13 条目）

🔗 关联

• 上级：课程 004 README
• 导读：01-课程导读与大纲全景
• 生词表：30-单词表/04-（⭐⭐ 精讲 36 条；速查 00 导读 30 条 ＋ 第 3 章 178 条）
• ⚠️ 语料说明：课时 1 的官方英文原句已逐段内嵌于本课「官方原句」引用块中（用户提供，需登录 Skilljar 取得）。文中 claude-3-sonnet 为官方讲稿原文中的模型名示例；the the AI provider API 为去品牌化叠词残留，未作改动。
• 登录 SOP：40-认证事务/08-Partner SSO