大模型API：从网页对话到代码调用的进阶之路

从聊天框到代码：为什么需要API

你可能已经习惯了在ChatGPT、豆包、DeepSeek、腾讯元宝的对话框里和大模型交流——输入问题，得到回答，简单直接。但当你想把大模型的能力真正融入自己的工作流时进行复杂细致化操作时，对话框的局限性就暴露出来了。

想象一下这些场景：你有1000份合同需要逐份审核，难道要手动复制粘贴1000次？你想让大模型查询公司数据库里的数据，但对话框里根本做不到；你需要每天自动生成运营日报，但每次都得人工打开网页手动输入；你想在客服系统中实时调用大模型回复用户，但对话框无法和你的系统集成。

这些场景有一个共同点：你需要程序自动执行，需要与其他系统集成，需要批量处理或定时触发——而这些都是对话框给不了的。

解决方案就是API调用：让大模型的能力可以被代码调用，嵌入到任何应用和流程中。

打个比方：用对话框和大模型交流，就像去餐厅点餐，服务员帮你完成一切，方便但受限；而API调用就像自己打电话给厨房下单，虽然需要知道怎么点，但你可以批量点、定时点、把点餐流程嵌入到任何系统中。

第一次API调用

最简示例：五分钟上手

API调用的本质很简单：你的程序向大模型服务端发送一个HTTP请求，携带问题和参数，服务端返回JSON格式的响应。听起来复杂，但OpenAI的Python SDK把这一切封装得非常简洁：

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI

client = OpenAI(api_key="sk-xxx")  # 身份认证

response = client.chat.completions.create(
    model="qwen3-32B",                 # 选择模型
    messages=[                      # 对话内容
        {"role": "user", "content": "你好，请介绍一下自己"}
    ]
)

print(response.choices[0].message.content)  # 输出模型回复

就这几行代码，你已经完成了一次API调用。核心就三个要素：谁在调用（api_key）、用哪个模型（model）、说什么（messages）。

连接不同的模型服务

上面的示例用的是OpenAI官方服务，但现实中你可能需要连接各种模型。好消息是，国内主流大模型平台几乎都兼容OpenAI的调用方式，只需要更换base_url和api_key即可：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
from openai import OpenAI

# 连接本地模型（如Ollama、vLLM）
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # 本地模型通常不需要真实密钥
)

# 智谱AI（GLM系列）
client = OpenAI(
    base_url="https://open.bigmodel.cn/api/paas/v4/",
    api_key="your-zhipu-api-key"
)

# 阿里云通义千问
client = OpenAI(
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
    api_key="your-dashscope-api-key"
)

# DeepSeek
client = OpenAI(
    base_url="https://api.deepseek.com/v1",
    api_key="your-deepseek-api-key"
)

这种”换地址不换代码”的兼容性，意味着你写一套代码就能在不同模型之间自由切换，非常方便。

搞懂核心参数：让模型按你的意图输出

掌握了最简调用后，下一步是理解核心参数。参数是你和模型之间的”沟通语言”——调好参数，模型才能按你的意图输出。

messages：对话的灵魂

messages是对话消息列表，每条消息包含role（角色）和content（内容）。三种角色各有分工：

  • system：设定AI的身份和行为规则，相当于给演员分配角色。比如"你是一个资深律师，擅长合同法"，模型就会以律师的视角和专业术语来回答。每次对话开始时设置一次即可。
  • user：用户的提问或指令，这是最常用的角色，所有用户输入都用它。
  • assistant：AI的历史回复记录，用于多轮对话时保持上下文连贯。

三种角色的关系可以这样理解：system是”导演”，告诉演员怎么演；user是”观众”，提出需求；assistant是”演员之前的台词”，让演员记得自己说过什么。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 单轮对话：只需要 user
messages = [
    {"role": "user", "content": "什么是机器学习？"}
]

# 带角色设定：system + user
messages = [
    {"role": "system", "content": "你是一个AI专家，用通俗易懂的语言解释概念"},
    {"role": "user", "content": "什么是神经网络？"}
]

# 多轮对话：包含历史记录
messages = [
    {"role": "system", "content": "你是一个Python助手"},
    {"role": "user", "content": "如何读取文件？"},
    {"role": "assistant", "content": "可以使用open()函数或with语句..."},
    {"role": "user", "content": "能举个例子吗？"}  # AI会基于上下文回答
]

temperature：在确定与创意之间找平衡

temperature控制输出的随机性，范围0到2（有的模型范围是0到1），默认1.0。用热力学概念理解温度参数更简单：

低温下分子运动缓慢，排列有序稳定——对应模型的输出确定、一致、可预测；
高温下分子运动剧烈，排列混乱随机——对应输出多样、创意、不可预测。
temperature=0像冰一样稳定，temperature=2像蒸汽一样活跃。

具体来说：

  • 0：确定性输出，同一个问题调用多次，结果几乎一样。适合事实性任务，比如数据提取、检索式问答。
  • 0.3-0.7：低到中等随机性，输出稳定但略有变化。适合翻译、摘要、格式化任务。
  • 0.7-1.0：平衡创造性和一致性，适合日常对话、内容创作。
  • 1.5-2.0：高随机性，适合创意写作、头脑风暴，但过高可能导致输出不连贯。
1
2
3
4
5
6
7
8
9
10
11
12
13
# 事实性任务：确保答案稳定
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Python中list和tuple的区别？"}],
    temperature=0
)

# 创意写作：增加多样性
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "写一个科幻故事的开头"}],
    temperature=1.5
)

top_p：temperature的搭档还是替代？

top_p是核采样参数，和temperature一样控制随机性，但机制不同。temperature是”调节概率分布的陡峭程度”，全局影响所有词的选择概率；而top_p是”直接截断低概率词”，只保留累计概率达到p的候选词。

举个例子：假设模型预测下一个词的概率是”好”0.4、”很”0.3、”非”0.2、”挺”0.08、”超”0.02。top_p=0.9时，”好”+”很”+”非”的累计概率达到0.9，模型只从这三个词中选择；top_p=0.5时，”好”+”很”的累计概率已经0.7超过0.5，模型只从这两个词中选择，更加保守。

实际使用中，通常只调整temperature和top_p中的一个，推荐优先用temperature，因为它更直观、更容易理解。常见的组合是temperature=0.7 + top_p=0.9。

max_tokens：给输出加个预算上限

max_tokens限制生成的最大Token数，注意它只限制输出，不包括输入。比如输入500 tokens + max_tokens=100，最多生成100 tokens输出，总共消耗600 tokens。

Token是什么？简单理解：英文约4个字符（或0.75个单词）算1个Token，中文约1.5-2个汉字算1个Token。"Hello world"约2个Token，"你好世界"约2-3个Token。也和不同模型使用的分词器有关，分词器不同，Token数也会不同。

设置max_tokens的主要目的是控制成本和响应时间，防止模型生成过长内容。

stream：让输出像打字机一样逐字出现

stream参数决定是否流式输出。非流式（默认）是等模型生成完整内容后一次性返回，就像发邮件——写完再发；流式是模型生成一点就返回一点，像打字机一样逐字出现。

流式输出的好处很明显：用户可以实时看到内容生成，不用干等；长文本生成时不会让人以为程序卡死；发现生成方向不对还能提前中断，节省成本。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 流式输出：实时显示
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "写一篇500字的文章"}],
    stream=True
)

# 处理流式输出：实时显示并收集完整内容
full_content = ""
for chunk in response:
    if chunk.choices[0].delta.content:
        content = chunk.choices[0].delta.content
        print(content, end="", flush=True)  # 实时显示
        full_content += content  # 同时收集完整内容

一次性看全：完整参数示例

1
2
3
4
5
6
7
8
9
10
11
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "你是一个助手"},
        {"role": "user", "content": "你好"}
    ],
    temperature=0.7,      # 平衡创造性和一致性
    max_tokens=500,       # 限制最大长度
    top_p=0.9,           # 核采样参数
    stream=False         # 非流式输出
)

API认证：安全地证明”你是你”

三种认证方式

调用API首先要证明你的身份，主流的认证方式有三种：

API Key认证是最常见的方式，OpenAI、智谱、DeepSeek、Kimi等都采用这种方式。原理很简单：在HTTP请求头中携带Authorization: Bearer sk-xxx，就像进小区刷门禁卡——卡是你的身份凭证，谁拿着卡谁就能进。实现简单，但安全性中等，因为Key一旦泄露别人就能冒用。

OAuth 2.0认证更安全，Google Gemini、百度文心等采用。它不是直接传密钥，而是通过授权流程获取一个有时效的Access Token，Token过期后需要刷新。就像酒店房卡——入住时前台给你一张有时效的房卡，过期了需要重新验证身份续卡。安全性高，但实现复杂度也高。

签名认证是安全性最高的方式，阿里通义千问、百度文心（部分接口）采用。它用Secret Key对请求参数进行签名，服务端验签确认请求未被篡改。就像银行转账——不仅要验证身份，还要对转账金额等关键信息进行加密签名，确保信息不被中途篡改。

API Key的最佳实践

对于大多数开发者，API Key认证是日常使用最多的方式。这里重点讲讲如何安全地管理你的Key。

第一原则：绝不硬编码。 把Key直接写在代码里，就像把家门钥匙贴在门上——方便了自己也方便了小偷。一旦代码上传到Git，Key就泄露了。

正确做法是用环境变量存储Key：

1
2
3
4
# 在项目根目录创建 .env 文件
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxx
ZHIPU_API_KEY=xxxxxxxxxxxxx.xxxxxxxxxxxxx
1
2
3
4
5
6
# 使用 python-dotenv 读取 .env
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()  # 加载 .env 文件中的环境变量
client = OpenAI()  # SDK自动读取 OPENAI_API_KEY 环境变量

然后确保.env被.gitignore排除，不会提交到Git。同时提供一个.env.example模板文件（不含真实Key），供团队成员参考需要配置哪些变量。

.gitignore例子：

1
.env

如果你想更深入地了解API Key在HTTP请求中是怎么传递的，可以看这个底层实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
import requests

# 手动设置请求头（SDK自动帮你做了这件事）
url = "https://api.openai.com/v1/chat/completions"
headers = {
    "Authorization": "Bearer sk-proj-xxxxxxxxxxxxx",
    "Content-Type": "application/json"
}
data = {
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "你好"}]
}
response = requests.post(url, headers=headers, json=data)

其实本质还是调用HTTP API，只是SDK帮你做了这些细节。以上面的例子为例：

1
2
3
4
5
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
    stream=True
)

其实就是SDK方法client.chat.completions.create()帮你调用了HTTP API， 并自动处理了请求头、参数、响应解析等细节，让你更专注于业务逻辑。

四种调用模式：选对方式事半功倍

根据不同的使用场景，API调用有四种模式，选择合适的模式能让你的应用更高效。

同步调用：最简单直接

发送请求，等待完整响应返回。就像打电话——拨出去之后等对方说完再挂断。适合批量处理、后端任务等不需要实时交互的场景。实现最简单，但用户等待第一次响应的时间长。

流式调用（SSE）：体验优先

服务端逐步推送Token，客户端实时接收。就像看直播——内容一点一点出现，不用等整场播完才看。适合聊天界面、实时交互等场景，用户体验好，但流式处理实现稍复杂。

流式调用的底层协议是SSE（Server-Sent Events），基于HTTP长连接，服务端使用text/event-stream内容类型持续推送数据。与WebSocket不同，SSE是单向的——只有服务端向客户端推送。

SSE 流程：

1
2
3
4
5
6
7
8
9
10
客户端                          服务端
  |                               |
  |--- POST /chat/completions --->|
  |   stream: true                |
  |                               |
  |<-- data: {"choices":[...]} ---|  第1个Token
  |<-- data: {"choices":[...]} ---|  第2个Token
  |<-- data: {"choices":[...]} ---|  第3个Token
  |          ...                  |
  |<-- data: [DONE] -------------|  结束标记

异步调用：高并发利器

提交任务后立即返回一个Job ID，之后通过轮询获取结果。就像去餐厅取号——不用站在门口等，拿到号可以先去做别的事，过一会儿再来看。适合长文本生成、批量任务等场景，非阻塞，但需要轮询逻辑。

批量调用：大规模数据处理

一次提交多个请求，批量处理。就像批发——单买和批发的区别，批量处理通常有折扣。适合数据标注、批量评估等场景，吞吐量高，但实现复杂度也高。

在Web框架中实现流式响应

流式调用在实际项目中最常用，这里展示如何在FastAPI中实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic import BaseModel
from openai import OpenAI
import json

app = FastAPI()
client = OpenAI()

class ChatRequest(BaseModel):
    message: str = "你好"

@app.post("/chat")
async def chat(request: ChatRequest):
    async def generate():
        response = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": request.message}],
            stream=True
        )
        for chunk in response:
            if chunk.choices[0].delta.content:
                data = json.dumps({'content': chunk.choices[0].delta.content})
                yield f"data: {data}\n\n"
        yield "data: [DONE]\n\n"

    return StreamingResponse(generate(), media_type="text/event-stream")

读懂返回结果：从JSON中提取你需要的

API返回的不只是文本内容，还包含丰富的元信息。理解这些信息，才能更好地处理响应和控制成本。

非流式响应的结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}]
)

# 响应基本信息
print(response.id)              # 响应唯一ID: "chatcmpl-abc123..."
print(response.model)           # 使用的模型: "gpt-4o-mini"

# 回复内容
print(response.choices[0].message.content)   # "你好！有什么我可以帮助你的吗？"
print(response.choices[0].finish_reason)     # 结束原因

# Token使用统计
print(response.usage.prompt_tokens)      # 输入token数
print(response.usage.completion_tokens)  # 输出token数
print(response.usage.total_tokens)       # 总token数

其中finish_reason值得关注，它告诉你模型为什么停止生成：

  • stop：正常结束，模型完整生成了回复
  • length：达到max_tokens限制，输出被截断——如果你发现回复不完整，检查这个字段
  • content_filter：内容被安全过滤器拦截
  • tool_calls：模型调用了工具（Function Calling场景）

流式响应的元信息获取

流式响应的元信息分散在各个chunk中，需要逐步收集：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
    stream=True,
    stream_options={"include_usage": True}  # 请求包含usage信息
)

full_content = ""
metadata = {}

for chunk in response:
    if not metadata.get('id'):
        metadata['id'] = chunk.id
        metadata['model'] = chunk.model

    if chunk.choices[0].delta.content:
        full_content += chunk.choices[0].delta.content

    if chunk.choices[0].finish_reason:
        metadata['finish_reason'] = chunk.choices[0].finish_reason

    if hasattr(chunk, 'usage') and chunk.usage:
        metadata['usage'] = {
            'prompt_tokens': chunk.usage.prompt_tokens,
            'completion_tokens': chunk.usage.completion_tokens,
            'total_tokens': chunk.usage.total_tokens
        }

print(f"模型: {metadata['model']}")
print(f"结束原因: {metadata['finish_reason']}")
print(f"Token统计: {metadata['usage']}")

Token计费：理解大模型的”计价单位”

Token是什么

Token是大模型处理文本的最小单位，也是计费的基本单位。咱们刚提到英文大约4个字符（0.75个单词）算1个Token，中文大约1.5-2个汉字算1个Token。不同模型的分词器略有差异，同样的文本计算出的token数不同，但量级差不多。

计费时，输入Token和输出Token分别计价，输出Token的价格通常是输入的2-5倍。这是因为生成比理解更消耗计算资源——就像阅读一篇文章和写一篇文章的难度不同。

成本优化策略

理解了计费机制，就能有针对性地优化成本：

模型分级是最有效的策略——简单任务用小模型，复杂任务用大模型。就像出行选交通工具：买菜骑自行车，出差坐飞机，没必要每次都开大卡车。简单分类任务用gpt-4o-mini，复杂推理才用gpt-4o，成本可以降低50%-80%。

Prompt精简也很重要——压缩系统提示词，减少冗余上下文。每多传一个Token都是钱，就像寄快递——能压缩打包的别用两个箱子。

上下文窗口管理——多轮对话时，历史消息越来越长，Token消耗越来越大。适时截断或摘要压缩早期对话，可以节省20%-40%的成本。

缓存机制——相同请求缓存结果，避免重复调用。如果多个用户问同样的问题，没必要每次都调API，直接从缓存中取结果即可，大模型的K-V存储机制也支持缓存命中，大模型厂商对缓存命中的定价一般是没命中的1/10。

国产替代——非核心场景使用国产高性价比模型。DeepSeek、通义千问等国产模型在很多任务上表现已经很好，价格却低得多。

还有其他一些技巧可以看看这篇文章： 一文搞懂Token经济学

错误处理：让调用更健壮

常见错误类型

API调用不会总是成功，了解常见错误才能写出健壮的代码：

401认证错误：API Key无效或过期。就像门禁卡失效——检查Key是否正确、是否过期。

429速率限制：请求频率超过限制。API不是无限速的，每个账户都有RPM（每分钟请求数）和TPM（每分钟Token数）的限制。就像高速公路限速——不是你想开多快就能开多快。一般大模型厂商提供的免费模型都有这个限制，或者在某些付费套餐里也有速率限制。

400请求过大：Token数超过模型的上下文窗口。就像往杯子里倒水——杯子容量有限，倒多了就溢出。

500/502/503服务端错误：服务端临时故障，重试通常能解决。

指数退避重试

遇到429和5xx错误时，不要立即重试，而应该用指数退避策略：第1次等1秒，第2次等2秒，第3次等4秒，第4次等8秒……每次等待时间翻倍。

为什么不能立即重试？想象一下：如果100个客户端同时遇到429错误，都立即重试，服务端刚恢复就被新一轮请求打垮，形成”雪崩效应”。指数退避让重试请求分散开来，给服务端喘息的时间。

1
2
3
from openai import OpenAI

client = OpenAI(max_retries=5)  # SDK内置重试机制，自动使用指数退避

OpenAI SDK已经内置了指数退避重试，设置max_retries即可。如果你需要更精细的控制，可以使用tenacity库自定义重试策略。

多模态API：不止于文字

大模型的能力早已超越纯文本，通过API你可以调用图像理解、图像生成、语音识别、语音合成、视频理解等多模态能力。

图像理解：让模型”看懂”图片

通过Vision API，你可以让模型分析图片内容。图片可以通过URL或Base64编码传递：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
from openai import OpenAI
import base64

client = OpenAI()

# 方式1：使用图片URL
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "这张图片里有什么？"},
                {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
            ]
        }
    ],
    max_tokens=300
)

# 方式2：使用Base64编码的本地图片
def encode_image(image_path):
    with open(image_path, "rb") as f:
        return base64.b64encode(f.read()).decode('utf-8')

base64_image = encode_image("photo.png")
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "描述这张图片的内容"},
                {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{base64_image}"}}
            ]
        }
    ]
)

图像生成：从文字到画面

GPT-Image系列模型可以根据文字描述生成图片，就像一个随叫随到的画师（注意：DALL-E 2/3已于2026年5月退役，推荐使用GPT-Image系列）：

1
2
3
4
5
6
7
8
9
10
11
12
13
import base64

response = client.images.generate(
    model="gpt-image-1",
    prompt="一只可爱的猫咪在阳光下打盹，水彩画风格",
    size="1024x1024",
    quality="medium",  # 可选: low, medium, high
    n=1
)
# GPT-Image系列返回Base64编码，需解码保存
image_bytes = base64.b64decode(response.data[0].b64_json)
with open("output.png", "wb") as f:
    f.write(image_bytes)

语音输入输出：听与说的能力

Whisper模型负责”听”——语音转文字，TTS模型负责”说”——文字转语音。两者结合，就能构建完整的语音交互链路：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 语音转文字（听）
audio_file = open("speech.mp3", "rb")
transcript = client.audio.transcriptions.create(model="whisper-1", file=audio_file)
print(transcript.text)

# 文字转语音（说）
response = client.audio.speech.create(
    model="tts-1",  # 也可选 tts-1-hd（高音质）
    voice="nova",  # 可选: alloy, echo, fable, onyx, nova, shimmer
    input="你好，欢迎使用语音合成服务！",
    response_format="mp3"  # 可选: mp3, opus, aac, flac, wav, pcm
)
response.stream_to_file("output.mp3")

语音助手：一个完整的多模态应用

把语音识别、文本对话、语音合成串联起来，就是一个完整的语音助手：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
def voice_assistant(audio_path):
    # 1. 语音转文字
    with open(audio_path, "rb") as audio:
        transcript = client.audio.transcriptions.create(model="whisper-1", file=audio)

    # 2. 文字对话
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": transcript.text}]
    )

    # 3. 文字转语音
    speech = client.audio.speech.create(
        model="tts-1",
        voice="nova",
        input=response.choices[0].message.content
    )
    speech.stream_to_file("response.mp3")
    return response.choices[0].message.content

多模态API的注意事项

  • 单张图片大小限制通常为20MB，建议使用压缩后的图片
  • 支持的图片格式：PNG、JPEG、GIF、WebP
  • 多模态API的成本通常高于纯文本API，按需选择

小结

回顾一下这篇文章的核心内容：

我们从”为什么需要API”出发，理解了对话框的局限性和API调用的必要性；然后通过最简示例快速上手，掌握了api_key、model、messages三个核心要素；接着深入理解了temperature、top_p、max_tokens、stream等参数如何影响模型输出；学习了API认证的安全实践和四种调用模式的适用场景；了解了如何从返回结果中提取内容和元信息；最后扩展到Token计费、错误处理和多模态API。

掌握这些知识后，你已经具备了通过API调用大模型完成实际工作的能力。接下来，当你想进一步解决大模型的知识截止和幻觉问题、构建企业级知识库问答系统时，RAG（检索增强生成）技术将是你的下一个进阶方向。