收益：
- 可以描述LLM API请求的基本结构（端点、模型、消息、max_tokens）
- 了解系统、用户和助理角色之间的区别以及无状态对话历史记录
- 可以读取和解释返回响应的字段（内容块、stop_reason、用法）
在之前的模块中，我们在聊天窗口中使用了人工智能。但如果你想将人工智能嵌入到你自己的产品、自动化或工作流程中，聊天界面就不够了。您需要以编程方式连接到模型，即使用代码或自动化工具。这座桥的名字是API（应用程序编程接口，允许两个软件按照一定规则进行通信的合约）。完成本单元后，您将了解 LLM（大型语言模型）API 请求的构成、消息角色的作用以及如何读取响应。这是构建模块其余部分的基础。
API 是如何工作的？
API 中的基本流程是这样的：您以某种格式发送请求；服务器以特定格式返回响应。在 LLM 中，这通常是对单个地址（端点，处理请求的服务器上的固定地址）的 HTTP 调用（HTTP：在 Web 上承载请求-响应的标准协议）。例如，在消息传递 API 中，所有请求都发送到单个地址，并以 JSON（JavaScript 对象表示法 — 一种由人类和机器都可以读取的键/值对组成的文本格式）形式携带在正文中。
在请求中，您至少指定以下三件事：
- 型号：您将使用哪种型号（例如快速且便宜的型号或功能强大的型号）。
- max_tokens：模型能够产生的最大token数（处理文本的最小单元，下一个单元会详细处理）；即输出限制。
- messages：组成对话的消息列表。
一步一步：如何设置请求
- 准备端点和凭据。您将 API 密钥（证明您身份的秘密字符串）添加到请求的标头中。您永远不会将密钥嵌入到代码中；我们将在第 9 单元介绍安全存储。
- 选择型号和输出限制。轻量级模型+小 max_tokens 用于简单任务；强大的模型+复杂任务的更大限制。
- 设置消息列表。 List the system instruction, user message, and past rounds (if any).
- 发送请求并解析响应。从返回的 JSON 中读取文本内容、停止原因和令牌使用情况。
消息角色：系统、用户、助理
会话由按顺序排列的消息组成，每条消息都有一个角色。该角色决定模型如何处理该文本。
角色
谁写的
目的
系统
开发商/运营商
适用于整个对话的永久指示、个性和规则
用户
最终用户
用户当前的问题或输入
助理
模型
模型产生的响应（以及之前的响应）
在大多数提供商中，系统角色可作为请求正文中的单独系统字段使用；用户和助理在消息列表中按顺序列出。 Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "您是一名企业支持助理。请给出简短、正式且经过验证的回复。不要编造您不确定的信息。", "messages": [ { "role": "user", "content": "如何开始我的退货流程？" } ]}
语音是无状态的
以下是最常见的误解：LLM API 调用是无状态的——服务器在两个请求之间不保留任何内存。该模型不记得您之前的请求。如果您要设置多轮聊天，则需要针对每个新请求重新发送过去的轮次。该模型的“内存”由您已发送的消息列表组成。
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "你好，我叫 Deniz。" }, { "role": "assistant", "content": "您好 Deniz，有什么可以帮您的吗？" }, { "role": "user", "content": "我刚刚说了我的名字，你还记得吗？" } ]}
正确回复第三条消息取决于您发送了前两条消息。如果您不发送，模型将不知道“Sea”并且会错误回答。这也直接影响成本：会话越长，列表越大，每个请求消耗更多的令牌。
提示：在长时间对话中，总结和移动旧回合（摘要+最后几轮）而不是发送整个历史记录可以降低成本并保留上下文窗口。我们将在第 6 单元和第 11 单元中深化这一点。
阅读答案
当模型返回响应时，您会收到结构化对象，而不是纯文本。典型领域：
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "要发起退货，请转到帐户中的“我的订单”页面..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, “输出令牌”：88}}
- 内容：响应本身；它是内容块的列表。文本块的文本字段是实际答案。
- stop_reason：模型停止的原因。 end_turn = 自然结束； max_tokens = 卡在输出限制（响应可能不完整）；拒绝=出于安全原因拒绝。您的代码应始终首先查看 stop_reason。
- 用法：输入和输出令牌编号。它是成本和限额跟踪的基础。
注意：如果stop_reason为max_tokens，则响应未完成。将其视为“成功响应”并向用户显示一半文本是生产中最常见的错误之一。增加 max_tokens 或使用流式传输。
弱提示/强提示
相同的任务有两个不同的系统提示：
# 弱你是一名助手。回答问题。
# STRONG您是一名企业支持助理。规则：- 仅依赖所提供的保单文件中的信息；如果文件中没有，请说“我没有此信息，我正在将其转给相关单位”。 - 答案不应超过 3 句话，正式且清晰。 - 请勿索取个人数据（TC ID 号、卡号）且请勿重复。 - 当你不确定时不要猜测。
强大版本；它定义了范围、形式、安全裕度和不确定性行为。模型输出的一致性直接来自于这种清晰度。
三个迷你箱
案例 1 — 支持机器人（无状态陷阱）。电子商务团队上线了该机器人；当用户说“取消之前的订单”时，机器人“忘记”了订单号。原因：他们只发送最后一条消息来发送每个请求。解决方案：他们将最后 6 轮添加到消息列表中。结果：上下文得以保留，但每个请求的输入从 40 个令牌增加到约 600 个令牌 — 我们将在第 2 单元中介绍成本课程。
案例 2 — 合同摘要不完整。一个法律团队正在制定 10 页的合同； max_tokens：300 仍然很低，摘要在句子中被切断。 stop_reason 每次都是 max_tokens 但没有人在看。将 max_tokens 增加到 1500 并添加 stop_reason 检查；截断摘要率从 18% 降至 0%。
案例 3 — 混合角色。营销团队将所有说明写入用户消息中，使系统保持空白。当用户输入与指令混合时，模型有时会遵守用户的命令“忘记以前的规则”。他们将永久规则移至系统中；通过将用户输入与指令分开，违规行为显着减少。
常见错误
- 忘记发送过去：模型被认为“不记得”；而它是无状态的。你携带了上下文。
- 不查看“stop_reason”：以 max_tokens 停止的响应被认为是完整的。
- 在‘user’中嵌入指令：将规则持久化到系统中；即时输入发送给用户。混合会产生安全漏洞。
- 将“content”误认为是普通字符串：答案是块列表；读取第一个文本块的文本字段，在使用盲索引获取 content[0] 之前验证其类型。
- 在代码中嵌入密钥：使用环境变量（单元 9）。
更深入：内容块和多部分答案
了解响应中的内容字段为何是列表对于您稍后将遇到的高级功能至关重要。有时，模型返回的不是单个文本块，而是多个块：一个思维块，后面跟着一个文本块；或后面跟着工具使用块的文本块。这就是为什么盲目地将 content[0] 算作“答案”是脆弱的。正确的做法是遍历列表并按类型排序：收集类型字段为文本的块的文本内容，并单独对待其他类型（思维、工具）。
这种区别在实践中的作用是，您可以记录模型的推理（如果有），而无需向用户透露，将工具调用重定向到单独的逻辑，并且仅在屏幕上打印实际答案。随着模块的进展（特别是在单元 4 和 11 中），您将看到此块结构对于验证和指导输出有多么有用。
另一个实用点：您可以从不同的提供商平台访问相同的模型（直接 API，通过云提供商）。尽管端点地址和身份验证格式可能会发生变化，但消息角色、无状态性和响应结构等基本概念保持不变。因此，无论您使用什么平台，本单元的基础知识都适用。
综上所述
LLM API请求由模型、输出限制和消息列表组成；角色（系统、用户、助理）决定模型的行为。调用是无状态的：您在每个请求中携带上下文。响应是一个结构化对象；阅读和解释内容、stop_reason 和使用字段是生产持久性的基础。
应用任务
从您自己的职业中选择一项任务（例如，对收到的电子邮件进行排序、创建简短摘要）。在一张纸上：（1）用 4-5 条规则编写系统提示，（2）设置示例用户消息和 2 轮历史记录（如果有），（3）确定 max_tokens 的合理值并写出理由，（4）列出您将在返回的响应中处理哪些 stop_reason 值以及如何处理。
清单
- [ ] 我可以计算请求的三个必需部分（模型、max_tokens、消息）。
- [ ] 我可以解释系统、用户和助理角色之间的区别。
- [ ] 我知道调用是无状态的，我需要承载过去。
- 我可以阅读并评论 [ ] 内容、stop_reason 和使用字段。
- [ ] 使用 max_tokens 我可以注意到并处理被截断的响应。