面向工程师的实战技术博客，从 0 到生产级 LLM API 调用架构

一、为什么要通过 API 调用大模型？

​ 过去我们调用模型通常是，本地部署，Notebook 试验，单机脚本推理。

​ 而现在，大模型逐渐成为基础设施服务（Model-as-a-Service），典型调用方式是：应用系统 → API → LLM

• 通过 API 调用模型，可以实现：

  • 智能客服
  • 自动报告生成
  • 数据分析助手
  • 企业知识库问答

• 本文以 OpenAI 和 Ark（企业级模型服务平台） 为例，介绍工程级调用方式与最佳实践。

二、OpenAI API 快速上手

2.1 获取 API Key

​ 在 OpenAI 控制台创建 API Key，并建议通过环境变量管理：

export OPENAI_API_KEY="your_api_key"

不要把 Key 写入 Git 仓库或代码文件。

2.2 Python 调用示例（Chat Completion）

from openai import OpenAI
import os


# =========================
# 1. 初始化 OpenAI 客户端
# =========================
# 建议将 API Key 存放在环境变量中，避免硬编码泄露
# export OPENAI_API_KEY="your_api_key"
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))


# =========================
# 2. 调用 Chat Completions API
# =========================
# model: 指定使用的模型（不同模型在能力、延迟、成本上不同）
# messages: 对话上下文，支持 system / user / assistant 角色
resp = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},  # 系统级指令
        {"role": "user", "content": "解释ROC曲线的意义"}                # 用户输入
    ],
    temperature=0.3,   # 控制输出随机性（0-1 越小越稳定）
    max_tokens=512     # 限制输出长度，避免 token 过度消耗
)


# =========================
# 3. 解析模型返回结果
# =========================
# choices[0].message.content 为模型生成的文本内容
answer = resp.choices[0].message.content
print("模型回答：")
print(answer)


# =========================
# 4. Token 使用情况（成本分析）
# =========================
# usage 中包含 prompt_tokens / completion_tokens / total_tokens
if hasattr(resp, "usage"):
    print("\nToken 使用情况：")
    print(f"Prompt tokens: {resp.usage.prompt_tokens}")
    print(f"Completion tokens: {resp.usage.completion_tokens}")
    print(f"Total tokens: {resp.usage.total_tokens}")

• 输出：

  模型回答：
  好的，我们来详细解释一下ROC曲线的意义。这是一个在机器学习、医学诊断和统计学中非常重要的概念。
  
  ### 一、核心定义
  
  **ROC曲线**，全称为**受试者工作特征曲线**，是一种用于评估**二分类模型**性能的图形化工具。它描绘的是模型在不同判定阈值下，**“真正例率”** 与 **“假正例率”** 之间的权衡关系。
  
  要理解它，必须先了解两个核心概念：
  
  1.  **真正例率**：在所有**实际为正例**的样本中，被模型**正确预测为正例**的比例。
      *   **公式：TPR = TP / (TP + FN)**
      *   **意义：** 也叫**灵敏度**或**召回率**。它衡量模型“抓对”正例的能力。TPR越高，说明漏掉的真实正例越少。
  
  2.  **假正例率**：在所有**实际为负例**的样本中，被模型**错误预测为正例**的比例。
      *   **公式：FPR = FP / (FP + TN)**
      *   **意义：** 它衡量模型“误伤”负例的程度。FPR越低越好。
  
  ### 二、ROC曲线的绘制与解读
  
  *   **横轴：** 假正例率
  *   **纵轴：** 真正例率
  
  **曲线是如何生成的？**
  1.  一个分类模型（如逻辑回归、SVM）通常不会直接输出“是/否”，而是输出一个**概率值**或**得分**（例如，患病的概率为0.8）。
  2.  我们需要设定一个**阈值**（例如0.5）来做出最终判断：得分 > 阈值，则预测为正例；否则为负例。
  3.  **ROC曲线就是通过不断移动这个“阈值”来绘制的。** 从最高分到最低分，每一个可能的阈值都会对应一组(TPR, FPR)，在图上形成一个点。
  4.  将所有点连接起来，就得到了ROC曲线。
  
  **关键点与区域：**
  *   **左下角 (0, 0)点：** 阈值设为最高（如1.0），所有样本都被预测为负例。此时TPR=0（没抓到任何正例），FPR=0（也没误伤任何负例）。
  *   **右上角 (1, 1
  
  Token 使用情况：
  Prompt tokens: 14
  Completion tokens: 512
  Total tokens: 526
  

2.3 使用 curl 直接调用 REST API

curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4.1-mini",
"messages": [{"role": "user", "content": "写一段Python代码"}]
}'

2.4 Client 与 Prompt：工程视角理解 LLM API

​ 在 OpenAI SDK 中，OpenAI() 返回的对象通常称为 client（客户端实例），它负责：

• 维护 API Key
• 管理 HTTP 请求
• 统一调用接口风格
• 支持不同模型服务端（OpenAI、Ark、私有部署）

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

(1) Client 的工程意义

• 在生产系统中，client 通常是全局单例或连接池级对象：

  • 避免重复初始化
  • 统一日志与监控
  • 方便封装成 SDK 或微服务

• 典型工程结构：

  llm_client.py   # 统一封装 client
  service.py      # 业务逻辑
  api.py          # HTTP 服务入口
  

(2) Prompt 的本质：模型行为控制接口

​ 在 Chat Completion API 中，prompt 通过 messages 结构传入：

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "解释ROC曲线"}
]

​ Prompt 本质是：给模型的上下文指令与对话历史

• 三种角色说明：

role	含义	工程用途
system	系统指令	设定模型人格、规则
user	用户输入	真实业务请求
assistant	模型历史回答	多轮对话上下文

• Prompt Engineering 工程实践示例

messages = [
    {"role": "system", "content": "你是一个严谨的机器学习专家，用论文风格回答"},
    {"role": "user", "content": "解释ROC曲线"}
]

👉 同一个模型，不同 system prompt，输出风格会完全不同。

(3) Prompt 在企业系统中的位置

​ 真实生产架构：

用户输入 → Prompt 模板 → LLM API → 后处理

• 企业通常会：
  • 模板化 Prompt
  • 版本管理 Prompt
  • A/B Test Prompt
  • 动态插入业务上下文

​ Client 是访问大模型的统一工程入口，而 Prompt 是控制模型行为的核心接口。在生产系统中，Prompt 通常会被模板化、参数化并纳入版本管理，成为 LLM 应用的“业务逻辑代码”。

三、Ark API：企业级模型服务的调用方式

​ Ark 是字节跳动火山引擎（Volcengine）推出的企业级大模型服务平台，通常提供 兼容 OpenAI API 标准的接口，这意味着：OpenAI SDK 可以直接调用 Ark。

3.1 Ark Endpoint 示例

​ Ark Endpoint 本质上就是：火山引擎 Ark 提供的大模型 API 服务地址（URL）。

https://ark-api.xxx.com/v1

3.2 Python 调用 Ark（OpenAI SDK 兼容模式）

from openai import OpenAI


client = OpenAI(
api_key="ARK_API_KEY",
base_url="https://ark-api.xxx.com/v1"
)


resp = client.chat.completions.create(
model="ark-gpt-4",
messages=[{"role": "user", "content": "总结AUC的意义"}]
)


print(resp.choices[0].message.content)

​ 这里使用 OpenAI SDK，但请求不发给 OpenAI，而是发给火山 Ark 平台。

​ 也就是说：OpenAI SDK = 通用客户端，Endpoint = 真正的模型服务提供方

四、Chat Completions vs Responses：新一代 LLM API 调用范式

4.1 两种不同的设计范式

• 在调用大模型 API 时，你可能会看到两种不同的调用方式：

  • Chat Completions API（传统对话接口）
  • Responses API（新一代统一接口）

• 例如：

  # Chat Completions
  resp = client.chat.completions.create(...)
  # Responses
  response = client.responses.create(...)
  

  这两者并不是不同厂商的接口，而是 同一代 SDK 中不同代际的 API 设计范式。

4.2 Chat Completions API：经典对话模型接口

​ Chat Completions 是最早为 ChatGPT 类应用设计的接口，输入采用 messages 结构：

resp = client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "解释ROC曲线的意义"}
    ],
    temperature=0.3,
    max_tokens=512
)

print(resp.choices[0].message.content)

• 特点

  • 专为 聊天对话 场景设计
  • 支持 system / user / assistant 角色
  • 输出结构固定：choices[0].message.content
  • 教程与生态最成熟

• 适合 Chatbot、对话助手、知识问答等传统应用场景。

4.3 Responses API：统一 AI Runtime 接口（新一代）

​ Responses API 是 OpenAI 新一代接口设计范式，Ark 从一开始就对齐了该模式，用于构建企业级 AI Runtime 层。

response = client.responses.create(
    model=ARK_MODEL_ID,
    input=[
        {"role": "system", "content": "你是一名技术文档写作助手"},
        {"role": "user", "content": "什么是大模型的上下文窗口？"}
    ],
    max_output_tokens=512
)

print(response.output_text)

(1) 核心设计理念：从 Chat API 到 AI Runtime API

​ 传统的 Chat Completions API 是为对话机器人设计的接口，而 Responses API 的目标是：用一个统一接口抽象所有 AI 能力，构建 AI Runtime 层。

​ 也就是说，Responses 更像是 AI 操作系统的系统调用接口（syscall），而不仅仅是聊天 API。

(2 )Responses API 支持的能力范畴

​ Responses API 覆盖了传统 SDK 中分散的多种接口能力，包括：

• 文本与对话生成

  • Chat 对话
  • 长文本生成
  • 技术文档、代码生成

• 多模态输入与输出

  • 图像输入（Vision）
  • 图像生成
  • 语音输入（Speech-to-Text）
  • 语音输出（Text-to-Speech）

• 工具与函数调用（Tool / Function Calling）

  • 调用数据库
  • 调用 REST API
  • 调用 Python / SQL / 搜索引擎
  • 作为 Agent 的 Action Executor

• Agent 与工作流执行

  • 自动规划任务（Planning）
  • 多步骤推理（Chain-of-Thought / ReAct）
  • AI Workflow orchestration
  • 企业 Copilot 系统

• 多模态推理（Multimodal Reasoning）

  • 文本 + 图像联合推理
  • 文本 + 表格分析
  • 文本 + 语音理解

(3) Chat Completions 只是 Responses 的一个子集

​ 从架构角度：

Responses API
 ├── Chat Completion
 ├── Text Generation
 ├── Vision
 ├── Audio
 ├── Tools
 ├── Agents
 └── Workflows

Chat Completions 只是 Responses 的 聊天模式子接口。

(4) 架构级理解：Responses = AI Runtime Layer

​ 可以将 Responses API 理解为：

系统层级	类比
Chat Completion API	聊天应用 API
Responses API	AI Runtime / Agent OS API

​ 它承担的角色类似于：

• Linux syscall
• JVM runtime
• Kubernetes API Server

👉 是 AI 系统的 基础运行时抽象层。

4.4 两种 API 的工程级对比

• 输入结构对比

API	输入字段
Chat Completions	messages
Responses	input

• 输出结构对比

API	输出方式
Chat Completions	resp.choices[0].message.content
Responses	response.output_text 或 response.output[…]

• 设计定位对比

API	定位
chat.completions	ChatGPT 风格聊天接口
responses	通用 AI Runtime / Agent API

4.5 为什么 Ark 强调 Responses API？

​ 在理解 Ark 的 API 设计之前，需要先理解 OpenAI SDK 的历史接口体系。

(1) OpenAI的SDK的接口演进路线

​ 早期 OpenAI SDK 提供的是多接口并行的功能 API，每种任务一个 endpoint：

client.chat.completions.create()   → 对话模型（GPT-3.5 / GPT-4）
client.completions.create()        → 文本补全（旧版接口）
client.embeddings.create()         → 向量嵌入
client.images.generate()           → 图像生成
client.audio.transcriptions.create() → 语音转文字
client.audio.speech.create()         → 文字转语音

• 这种设计的特点是：

  • 每种模态一个 API
  • SDK 分散、调用逻辑割裂
  • 工程系统需要维护多套调用逻辑

• 这是一种 “功能 API 时代” 的设计范式。

(2) Responses API：统一 AI Runtime 接口

​ 随着大模型能力从「聊天」扩展到「Agent、工具调用、多模态」，OpenAI 推出了 Responses API：

client.responses.create()

​ Responses API 的设计目标是：用一个统一接口覆盖所有 AI 能力。

• 它可以统一处理：

  • Chat / Text generation
  • Embedding
  • Vision / Image
  • Audio
  • Tool Calling
  • Function Calling
  • Agent Workflow

• 本质上是 AI Runtime Layer（AI 操作系统级接口）。

(3) 为什么 Ark 从一开始就对齐 Responses API？

​ Ark（火山引擎）的定位不是聊天机器人 SDK，而是企业级大模型基础设施平台（LLM Platform-as-a-Service）。

• 核心场景包括：

  • 企业知识库问答（RAG）
  • 自动化 Agent
  • 数据分析 Copilot
  • 工作流自动化
  • 多模态 AI 应用

• 这些场景 远远超出传统 Chatbot 范畴，需要：

  • 工具调用
  • 多模态输入输出
  • 长上下文管理
  • Agent orchestration
  • Workflow runtime

• 因此 Ark 在架构层面直接采用 Responses 统一接口范式，而不是传统 Chat Completions。

4.6 工程实践建议

(1) 学习和教学阶段

推荐使用：

client.chat.completions.create()

原因：

• 教程丰富
• API 结构简单
• 易于理解对话模型原理

(2) 生产级系统（强烈推荐）

推荐使用：

client.responses.create()

原因：

• 支持多模态与 Agent
• 统一接口，避免未来迁移成本
• OpenAI 官方长期主推方向
• Ark / Azure / Anthropic 均在对齐该范式

4.7 API 演进视角（工程架构理解）

​ 从架构角度，大模型 API 的演进路径为：

Completions → Chat Completions → Responses

​ 对应能力升级：

文本生成 → 对话 → AI Runtime / Agent OS

​ Chat Completions API 是为对话模型设计的传统接口，而 Responses API 是新一代统一 AI Runtime 接口。
前者适合聊天应用，后者面向多模态、Agent 和企业级 AI 系统，是未来主流方向。

总结

​ 本文介绍了 OpenAI 与 Ark 的 API 调用方式，并从工程视角解释了 Client、Prompt 与 Endpoint 的作用。大模型时代的核心不只是模型能力，而是围绕 API、Prompt 与工程架构构建的系统能力。