Hello LLM：第一次调用模型 API#

这是本站第一个实战案例。目标很简单：完成一次可复用的大模型 API 调用，并把后续 RAG、Agent、模型切换都会用到的工程习惯先建立起来。

这一节不追求复杂框架，只关注最小闭环：

安全保存 API Key。
组织一次模型请求。
拿到模型回答。
支持流式输出。
处理常见错误。
估算一次调用成本。

你会得到什么#

完成后，你应该能得到一个最小项目骨架：

1
hello-llm/
2
├─ .env
3
├─ .gitignore
4
├─ package.json
5
└─ src/
6
   ├─ basic.ts
7
   ├─ stream.ts
8
   └─ errors.ts

这个骨架后面可以继续扩展成 Prompt 工具、RAG 问答或 Agent 工作流。

第一步：准备 API Key#

API Key 不要写进代码。推荐放到 .env：

1
MODEL_API_KEY=你的模型平台密钥
2
MODEL_BASE_URL=https://api.example.com/v1
3
MODEL_NAME=your-model-name

.gitignore 至少要包含：

1
.env
2
node_modules
3
dist

如果你还不熟悉 API Key，可以先看学习地图里的《API Key 与调用额度》。

第二步：理解一次请求#

一次模型 API 调用通常包含四类信息：

字段	作用
model	使用哪个模型
messages/input	给模型的任务和上下文
temperature	控制输出随机性
max_tokens	控制输出长度

最小消息结构可以这样理解：

1
[
2
  {
3
    "role": "system",
4
    "content": "你是一个简洁、准确的 AI 应用开发助手。"
5
  },
6
  {
7
    "role": "user",
8
    "content": "请用三句话解释什么是 RAG。"
9
  }
10
]

system 负责长期规则，user 负责当前任务。后续做多轮对话时，还会把历史 assistant 回答放回上下文。

第三步：最小调用脚本#

下面是一个平台无关的 TypeScript 写法。你可以把 MODEL_BASE_URL 换成具体模型服务的 OpenAI-compatible 地址。

1
const apiKey = process.env.MODEL_API_KEY;
2
const baseUrl = process.env.MODEL_BASE_URL;
3
const model = process.env.MODEL_NAME;
4

5
if (!apiKey || !baseUrl || !model) {
6
  throw new Error("缺少 MODEL_API_KEY、MODEL_BASE_URL 或 MODEL_NAME");
7
}
8

9
const response = await fetch(`${baseUrl}/chat/completions`, {
10
  method: "POST",
11
  headers: {
12
    "Content-Type": "application/json",
13
    Authorization: `Bearer ${apiKey}`,
14
  },
15
  body: JSON.stringify({
16
    model,
17
    messages: [
18
      {
19
        role: "system",
20
        content: "你是一个简洁、准确的 AI 应用开发助手。",
21
      },
22
      {
23
        role: "user",
24
        content: "请用三句话解释什么是 RAG。",
25
      },
26
    ],
27
    temperature: 0.3,
28
  }),
29
});
30

31
if (!response.ok) {
32
  const errorText = await response.text();
33
  throw new Error(`模型调用失败：${response.status} ${errorText}`);
34
}
35

36
const data = await response.json();
37
console.log(data.choices?.[0]?.message?.content);

这段代码有三个重点：

密钥从环境变量读取。
请求失败时读取错误信息。
输出只取模型回答正文。

第四步：加入流式输出#

流式输出能让用户更快看到结果，适合聊天、长文生成和代码生成场景。

1
const response = await fetch(`${baseUrl}/chat/completions`, {
2
  method: "POST",
3
  headers: {
4
    "Content-Type": "application/json",
5
    Authorization: `Bearer ${apiKey}`,
6
  },
7
  body: JSON.stringify({
8
    model,
9
    stream: true,
10
    messages: [
11
      { role: "system", content: "你是一个简洁、准确的 AI 应用开发助手。" },
12
      { role: "user", content: "请解释一次模型 API 调用的完整流程。" },
13
    ],
14
  }),
15
});
16

17
if (!response.body) {
18
  throw new Error("当前环境不支持流式响应");
19
}
20

21
const reader = response.body.getReader();
22
const decoder = new TextDecoder();
23

24
while (true) {
25
  const { done, value } = await reader.read();
26
  if (done) break;
27
  const chunk = decoder.decode(value);
28
  process.stdout.write(chunk);
29
}

真实项目中，流式响应通常还需要解析 Server-Sent Events。初学阶段先理解“边接收边显示”的模式即可。

第五步：处理常见错误#

大模型 API 常见错误可以先分成五类：

错误	可能原因	处理方式
401	API Key 错误或过期	检查环境变量，重新生成 Key
429	触发限流或额度不足	降低频率，增加重试和排队
400	请求格式错误	检查 model、messages、参数类型
413	输入过长	压缩上下文，减少历史或资料
500/503	服务端异常	稍后重试，切换备用模型

推荐封装一个统一错误处理函数：

1
function explainApiError(status: number) {
2
  if (status === 401) return "API Key 无效或权限不足";
3
  if (status === 429) return "触发限流或额度不足";
4
  if (status === 400) return "请求参数格式错误";
5
  if (status === 413) return "输入内容过长";
6
  if (status >= 500) return "模型服务暂时异常";
7
  return "未知错误";
8
}

第六步：估算成本#

一次调用成本可以粗略拆成：

1
总成本 = 输入 token * 输入单价 + 输出 token * 输出单价

开发阶段至少要记录：

用户输入长度。
系统提示词长度。
检索资料长度。
模型输出长度。
本次使用的模型。

如果模型服务返回 usage 字段，可以直接记录：

1
{
2
  "usage": {
3
    "prompt_tokens": 320,
4
    "completion_tokens": 180,
5
    "total_tokens": 500
6
  }
7
}

你也可以把典型 Prompt 放到本站实验室的 Token 成本估算器里，先估算大致成本。

最小可复用封装#

最后，把模型调用封装成函数：

1
type ChatMessage = {
2
  role: "system" | "user" | "assistant";
3
  content: string;
4
};
5

6
export async function callModel(messages: ChatMessage[]) {
7
  const response = await fetch(`${process.env.MODEL_BASE_URL}/chat/completions`, {
8
    method: "POST",
9
    headers: {
10
      "Content-Type": "application/json",
11
      Authorization: `Bearer ${process.env.MODEL_API_KEY}`,
12
    },
13
    body: JSON.stringify({
14
      model: process.env.MODEL_NAME,
15
      messages,
16
      temperature: 0.3,
17
    }),
18
  });
19

20
  if (!response.ok) {
21
    throw new Error(explainApiError(response.status));
22
  }
23

24
  const data = await response.json();
25
  return data.choices?.[0]?.message?.content ?? "";
26
}