在网页上和 AI 聊天很方便，但要把 AI 能力集成到自己的产品、脚本或工作流中，就需要通过 API 调用大模型。大多数主流模型服务的 API 设计思路相近，掌握基本概念后，切换不同服务商的成本并不高。 本文介绍从第一次请求到生产环境需要了解的核心知识。具体的接口地址、参数名称和模型名称，请以所用服务商的官方文档为准。

准备工作

  1. 注册账号并获取 API 密钥：在服务商的开发者平台创建密钥；
  2. 了解计费方式：通常按输入和输出 Token 分别计费，参见 Token 与分词器；
  3. 安装客户端库：大多数服务商提供官方的各语言客户端库，也可以直接发送 HTTP 请求。

核心概念：消息结构

现代对话模型 API 通常采用“消息列表”的形式组织输入，每条消息包含角色和内容：

  • 系统消息：设定模型的身份、行为规则和背景信息，参见 System Prompt 设计指南；
  • 用户消息：用户的输入；
  • 助手消息：模型之前的回复，用于多轮对话。

一次最简单的请求，包括选择模型、提供一条系统消息和一条用户消息。模型返回的响应中包含生成的文本，以及本次请求消耗的 Token 数量等信息。

关键参数

  • 模型名称：选择使用哪个模型，不同模型的能力、速度和价格不同；
  • 最大输出长度：限制模型生成的最大 Token 数，防止输出过长和成本失控；
  • 温度等采样参数：控制输出的随机性，参见采样参数实用指南；
  • 停止条件：遇到指定的字符串时停止生成；
  • 结构化输出设置：要求模型按照指定格式输出，参见让大模型稳定输出 JSON。

多轮对话

API 本身是无状态的，模型不会记住之前的请求。要实现多轮对话，需要在每次请求中把之前的对话历史（用户消息和助手回复）一起发送。对话越长，每次请求的输入 Token 越多，成本也越高，需要适时压缩或截断历史。

流式输出

默认情况下，API 在生成完整回答后才返回结果。开启流式输出后，模型每生成一部分内容就立即推送，用户可以更快看到响应。面向用户的交互式应用应该优先使用流式输出，参见降低大模型应用延迟。

工具调用

在请求中声明可用的工具（函数），模型可以决定调用哪个工具并给出参数，由你的程序执行后把结果返回给模型。这是构建 Agent 的基础，详见 Function Calling 详解。

生产环境必备实践

1. 密钥安全

  • 绝不把 API 密钥写在代码中或提交到代码仓库；
  • 使用环境变量或密钥管理服务存放密钥；
  • 不要在前端网页或移动应用中直接调用 API，否则密钥会暴露给所有用户，应通过自己的后端服务转发；
  • 为不同的项目和环境使用不同的密钥，定期轮换，发现泄露立即作废。

2. 错误处理与重试

API 调用可能因为网络问题、服务过载、限流等原因失败：

  • 对于临时性错误（如超时、服务暂时不可用、触发限流），使用指数退避的方式重试；
  • 对于请求本身的错误（如参数错误、内容违规），不要重试，记录并处理；
  • 设置最大重试次数。

3. 超时设置

为请求设置合理的超时时间。生成长内容可能需要较长时间，超时设置过短会导致正常请求失败，过长则会让用户等待过久。

4. 限流与并发控制

服务商通常对每分钟请求数和 Token 数设有限制。在自己的服务中实现并发控制和排队机制，避免突发流量触发限流。

5. 成本控制

  • 设置账户级别的消费上限和告警；
  • 记录每次请求的 Token 消耗，按功能和用户统计；
  • 对单个用户设置使用上限，防止滥用；
  • 更多方法参见大模型 API 成本优化。

6. 日志与监控

记录请求和响应的关键信息（注意脱敏）、耗时、Token 消耗和错误情况，便于排查问题和分析使用情况，参见大模型应用上线后的监控。

7. 抽象模型调用层

在代码中封装统一的模型调用接口，而不是在业务代码中直接调用某个服务商的 SDK。这样以后更换模型或服务商、实现模型路由和降级时会容易得多。

本地模型也能用同样的方式调用

很多本地运行工具提供与常见云端 API 风格兼容的接口，只需修改服务地址和模型名称，就能用相同的代码调用本地模型，参见用 Ollama 在本地运行大模型。

小结

调用大模型 API 的基础是理解消息结构和关键参数，掌握多轮对话、流式输出和工具调用的用法。进入生产环境后，密钥安全、错误重试、超时与限流、成本控制、日志监控和调用层抽象都是必不可少的。打好这些基础，后续构建更复杂的 AI 应用就会顺利很多。