模型 API 与基础编程

「产品经理的大模型基础」系列之四
上一篇：提示词与任务设计 · 系列入口 · 下一篇：Embedding 与 RAG

在聊天产品中使用大模型时，用户只需要输入问题并等待回答。但当大模型成为某个产品功能的一部分，系统需要通过程序把用户输入发给模型，再把返回结果展示出来或交给后续流程。

理解这个过程，不要求产品经理成为开发者。只要能看懂 Python、JSON、HTTP 和 API 之间的关系，就可以更准确地讨论接口、成本、延迟、错误和产品边界。

一、API 是什么

API 是不同软件之间约定好的调用接口。

可以把它理解为餐厅的点单窗口：菜单说明可以提交哪些内容，服务员接收订单，后厨处理，再把结果返回。使用者不需要知道后厨每一步怎样工作，但必须按照菜单规定的格式提交请求。

模型 API 也是如此。程序会提交：

• 使用哪个模型或能力。
• 系统和用户提供了什么信息。
• 是否要求特定输出格式。
• 是否允许使用工具。
• 是否采用流式返回。

模型服务处理后，会返回生成内容、用量信息、工具请求或错误。

二、HTTP：请求怎样在网络中传递

HTTP 是互联网上常见的通信协议。调用模型 API，通常就是向一个网络地址发送 HTTP 请求。

一条请求大致包括：

• URL：请求发送到哪里。
• Method：要执行什么类型的操作，常见的有 GET 和 POST。
• Headers：认证方式、数据格式等附加信息。
• Body：真正提交的数据。

调用模型生成内容时，常见做法是使用 POST，把输入数据放在请求 Body 中。

服务器收到请求后，会返回状态码和响应数据。常见含义包括：2xx 表示请求成功；400 Bad Request 多半是参数或格式有误；401 Unauthorized 表示认证失败；429 Too Many Requests 表示请求过于频繁；5xx 表示服务端暂时异常。不同平台的具体错误体不完全相同，所以程序还要读取响应里的错误代码和说明。

产品设计中的超时、重试、错误提示和降级策略，都建立在这层通信之上。

三、JSON：程序之间交换结构化数据

JSON 是 API 中非常常见的数据格式。它使用键和值表达结构，例如：

{
  "model": "example-model",
  "input": "请总结下面的访谈记录",
  "temperature": 0.2
}

其中：

• model、input、temperature 是字段名。
• 字符串使用引号表示。
• 数字可以直接写。
• 多项内容可以放入数组。
• 更复杂的信息可以嵌套为对象。

模型返回结果也通常使用 JSON。程序从指定字段读取文字、用量或错误信息。

JSON 对产品经理很重要，因为它把“模型回答”变成了可定义的数据接口。PRD 中的输入字段、输出 Schema 和工具参数，最终常常会落实为类似结构。

四、Python 在其中做什么

Python 是常用于数据处理和 AI 原型开发的编程语言。它可以：

• 读取文本、CSV 或 JSON 文件。
• 向模型 API 发送请求。
• 遍历多条数据进行批量处理。
• 检查和保存模型返回结果。
• 处理错误并记录日志。

下面是一段简化的示意代码。它读取本地访谈文本、调用模型，再把结果保存为 JSON。具体地址和字段会因模型服务而不同，这里只用于说明完整链路：

import json
import os
import requests

with open("interview.txt", "r", encoding="utf-8") as file:
    interview = file.read()

payload = {
    "model": "example-model",
    "input": f"请把下面的访谈总结为三个要点：\n\n{interview}"
}

response = requests.post(
    "https://api.example.com/v1/generate",
    headers={
        "Authorization": f"Bearer {os.environ['EXAMPLE_MODEL_API_KEY']}",
        "Content-Type": "application/json"
    },
    json=payload,
    timeout=30
)

response.raise_for_status()
result = response.json()
print(result["output"])

with open("analysis.json", "w", encoding="utf-8") as file:
    json.dump(result, file, ensure_ascii=False, indent=2)

这段代码完成了一条最小数据链路：读取文件，准备 JSON 数据，通过环境变量取得密钥，发送 POST 请求，检查 HTTP 状态，把响应解析为 JSON，最后保存结果。

环境变量不是绝对安全方案，但比把 API Key 直接写进代码更合适。密钥不应提交到代码仓库、粘贴到公开文档，也不应发送给浏览器中不受信任的前端代码；生产系统通常还会使用专门的密钥管理服务和权限控制。

真实项目还会安全管理密钥、检查状态码、限制重试次数，并避免把敏感数据直接写进日志。

五、从一次调用到批量处理

如果要处理多份访谈，程序可以逐条读取输入并调用模型：

for interview in interviews:
    result = call_model(interview)
    save_result(result)

这看起来只是一个循环，但产品化时需要考虑很多问题：

• 某一条失败后，是否继续处理其他内容？
• 请求过快触发限流时怎么办？
• 返回格式不符合要求时是否重试？
• 怎样记录输入、模型配置和输出版本？
• 相同内容是否需要重复调用？
• 处理一百份材料需要多少时间和成本？

这些问题说明，模型能力只是系统的一部分。批量处理的稳定性往往更多取决于普通软件工程。

六、怎样读懂模型的响应和 Token 用量

一条成功响应除了正文，通常还包含请求标识、结束原因和用量。示意结构如下：

{
  "request_id": "req_123",
  "output": "用户最关心的是……",
  "finish_reason": "stop",
  "usage": {
    "input_tokens": 1850,
    "output_tokens": 320,
    "total_tokens": 2170
  }
}

input_tokens 是本次送入模型的上下文用量，output_tokens 是模型生成的用量。平台通常按模型和 Token 数计费，但具体价格、缓存折扣和计费字段会变化，应以所用服务的文档为准。

产品侧最好记录模型版本、请求 ID、Token 用量、耗时、结束原因和错误类型。它们分别帮助团队回答：哪次请求出了问题、成本花在哪里、回答是否因为长度限制而截断，以及新旧版本差异来自哪里。日志中则应对个人信息、商业机密和密钥进行脱敏。

七、同步返回与流式返回

同步返回是等待模型生成完整答案后一次性返回。流式返回则是在生成过程中不断发送小段事件，用户可以逐步看到内容出现。

流式返回不会一定缩短模型完成全部内容的时间，但可以降低用户感受到的等待。聊天产品常采用流式输出，就是因为用户能够更早看到第一部分结果。

对于结构化批处理，系统可能更适合等待完整 JSON；对于长文本生成或对话界面，流式展示通常体验更好。

八、模型 API 常见的错误类型

并不是所有错误都应该自动重试。参数错误重试相同请求通常没有意义；网络抖动可以有限重试；写操作还要避免重试造成重复执行。

九、模型参数和产品体验

模型 API 常提供多种参数。不同平台名称可能不同，但产品经理通常需要关注：

• 模型选择：能力、成本和延迟不同。
• 最大输出长度：影响回答完整性和费用。
• Temperature：影响生成多样性。
• 超时与重试：影响可靠性和等待体验。
• 流式输出：影响用户感知延迟。
• 结构化输出：影响后续程序能否稳定读取。

这些参数不是孤立的技术配置。它们最终会体现在用户等待多久、答案是否完整、单次任务花多少钱，以及失败后发生什么。

十、产品经理需要具备的最低编程理解

不需要从头编写完整系统，但最好能够：

• 看懂简单 Python 变量、函数、循环和异常处理。
• 识别 JSON 中的对象、数组和字段。
• 理解请求、响应、状态码和超时。
• 看懂一次模型调用的输入与返回。
• 明白 API Key 不应直接写入公开代码。
• 能与工程师讨论批处理、日志、重试和成本。

这些基础足以让产品经理从“接一下大模型”走到更具体的系统设计讨论。

本篇小结

这篇文章的核心关系是：

Python 等程序准备数据
→ 使用 JSON 描述请求
→ 通过 HTTP 调用模型 API
→ 接收包含正文、状态和 Token 用量的 JSON 响应
→ 展示、保存或继续处理结果

下一篇将介绍怎样让模型使用外部知识：Embedding 如何表示语义，RAG 又怎样完成文档切分、检索、召回、生成和引用。

上一篇：提示词与任务设计　下一篇：Embedding 与 RAG