过去十年，API 沿着 REST → GraphQL → gRPC 的路径演进，核心始终围绕「结构化契约、精准调用、数据读写」展开。而大模型的普及正在打破这一范式：接口不再只是数据的出入口，更成为推理能力、生成能力与工具编排的载体。本文从三个核心维度，拆解大模型时代 API 设计的底层变化，并附可落地的工程实现。
一、范式重构：从「命令式调用」到「意图式交互」
传统 API 的本质是「契约驱动」：客户端必须严格按照接口文档传入指定字段、枚举值、分页参数，差一个字符就会返回 400。这种设计在确定性系统里高效可靠，但面对复杂业务场景时，会导致参数爆炸、调用方学习成本高、版本迭代僵硬。
大模型引入的第一个核心变化，是让 API 从「接收精确指令」转向「理解用户意图」。接口不再强制要求结构化输入，而是通过自然语言解析层，将模糊需求映射为内部可执行的结构化参数。
设计思路
- 外层：暴露自然语言入口，接收用户的非结构化描述
- 中间层：通过大模型做意图识别、参数提取、合法性校验
- 内层：仍然调用原有业务 RPC/REST 接口，保证执行确定性
代码实现：意图解析 API 封装
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import openai
import json
app = FastAPI()
class IntentRequest(BaseModel):
query: str
user_id: str
class OrderQueryParams(BaseModel):
order_id: str = None
status: str = None
start_date: str = None
end_date: str = None
page: int = 1
page_size: int = 20
def parse_intent_with_llm(query: str) -> OrderQueryParams:
"""用大模型从自然语言中提取订单查询参数"""
prompt = f"""
从用户查询中提取订单查询参数，输出严格的JSON格式，字段如下：
- order_id: 订单号，提取不到则为null
- status: 订单状态，枚举值 pending/paid/shipped/completed/cancelled
- start_date, end_date: 日期范围，格式 YYYY-MM-DD，提取不到则为null
- page: 页码，默认1
- page_size: 每页条数，默认20
用户查询：{query}
只输出JSON，不要其他文字。
"""
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{
"role": "user", "content": prompt}],
temperature=0
)
try:
data = json.loads(response.choices[0].message.content.strip())
return OrderQueryParams(**data)
except Exception:
raise HTTPException(status_code=400, detail="无法解析查询意图")
@app.post("/api/v1/orders/query")
def query_orders(request: IntentRequest):
"""意图式订单查询接口：支持自然语言输入"""
params = parse_intent_with_llm(request.query)
# 下游仍然调用传统的结构化订单查询接口
# result = order_service.query(params, request.user_id)
return {
"parsed_params": params.dict(),
"message": "参数解析完成，已转发至业务接口",
"query": request.query
}
这种设计的价值在于：业务侧无需维护数十个面向不同场景的细分接口，一个意图入口即可覆盖绝大多数查询需求；前端也无需再做复杂的表单校验和参数拼接，直接透传用户输入即可。
二、能力升级：从「数据读写」到「生成与推理」
传统 API 的能力边界是 CRUD：创建、读取、更新、删除。而大模型 API 带来了两类全新能力：生成式输出与函数调用（Function Calling）。与之对应，接口设计必须解决两个工程问题：流式响应、工具扩展。
1. 流式响应成为标配
生成式内容（文本、代码、结构化数据）通常需要几秒到几十秒的生成时间。传统的一次性响应会导致前端长时间空白、超时风险高、用户体验差。SSE（Server-Sent Events）成为大模型 API 的标准交付方式。
from fastapi.responses import StreamingResponse
import time
@app.post("/api/v1/generate/report")
def generate_report(topic: str):
"""流式生成业务报告"""
def report_generator():
full_prompt = f"请生成一份关于{topic}的数据分析报告，分三个部分：现状、问题、建议。"
stream = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{
"role": "user", "content": full_prompt}],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
yield f"data: {chunk.choices[0].delta.content}\n\n"
yield "data: [DONE]\n\n"
return StreamingResponse(report_generator(), media_type="text/event-stream")
2. Function Calling：让 API 具备「自我扩展」能力
大模型不再只是输出内容，还可以根据用户意图决定调用哪些后端工具。API 设计从「固定功能集合」转向「能力插件化」。接口层需要维护工具注册表、参数校验、执行沙箱。
import inspect
from typing import Dict, Callable
# 工具注册表
tool_registry: Dict[str, Callable] = {
}
def register_tool(name: str, description: str, parameters: dict):
"""工具注册装饰器"""
def decorator(func):
tool_registry[name] = {
"func": func,
"definition": {
"name": name,
"description": description,
"parameters": parameters
}
}
return func
return decorator
# 注册具体工具
@register_tool(
name="get_user_balance",
description="查询用户账户余额",
parameters={
"type": "object",
"properties": {
"user_id": {
"type": "string", "description": "用户ID"}
},
"required": ["user_id"]
}
)
def get_user_balance(user_id: str):
# 实际业务逻辑：查数据库、调账户服务
return {
"user_id": user_id, "balance": 12580.68, "currency": "CNY"}
def execute_tool(tool_name: str, arguments: dict):
"""执行工具调用"""
if tool_name not in tool_registry:
raise ValueError(f"未知工具: {tool_name}")
tool = tool_registry[tool_name]
return tool["func"](**arguments)
# 使用时：将所有工具定义传给大模型，由模型决策调用哪个工具
def chat_with_tools(user_query: str):
tools_def = [{
"type": "function", "function": t["definition"]} for t in tool_registry.values()]
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo-0613",
messages=[{
"role": "user", "content": user_query}],
tools=tools_def
)
message = response.choices[0].message
if message.tool_calls:
for call in message.tool_calls:
args = json.loads(call.function.arguments)
result = execute_tool(call.function.name, args)
return {
"tool_called": call.function.name, "result": result}
return {
"answer": message.content}
这种架构下，新增业务能力不再需要新增 API 路由，只需注册一个工具函数即可。大模型会自动判断何时调用、如何传参，接口的扩展性得到数量级提升。
三、架构演进：从「无状态请求」到「有状态 Agent」
传统 API 是无状态的：每次请求独立，上下文靠 Token、Session 维持轻量关联。而大模型驱动的业务场景天然是多轮对话、多步推理、多工具协作的，这要求 API 从「单次请求处理」进化为「有状态的 Agent 编排」。
核心设计要点
- 会话状态持久化：每轮对话的历史消息、工具调用结果、中间变量都需要存储
- 状态机驱动执行：思考 → 工具调用 → 结果回填 → 再思考 → 最终输出
- 中断与续跑能力：长任务支持暂停、恢复、人工介入
代码实现：极简 Agent API 架构
import uuid
from typing import List, Dict
# 内存版会话存储，生产环境可用 Redis/MySQL
session_store: Dict[str, List[Dict]] = {
}
@app.post("/api/v1/agent/chat")
def agent_chat(session_id: str = None, message: str = ""):
"""有状态 Agent 对话接口"""
# 初始化或恢复会话
if not session_id:
session_id = str(uuid.uuid4())
session_store[session_id] = [
{
"role": "system", "content": "你是一个智能业务助手，可以调用工具帮助用户。"}
]
messages = session_store[session_id]
messages.append({
"role": "user", "content": message})
# 第一轮：模型决策是否调用工具
tools_def = [{
"type": "function", "function": t["definition"]} for t in tool_registry.values()]
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo-0613",
messages=messages,
tools=tools_def
)
assistant_msg = response.choices[0].message
messages.append(assistant_msg)
# 循环执行工具调用，直到无需调用
while assistant_msg.tool_calls:
for tool_call in assistant_msg.tool_calls:
func_name = tool_call.function.name
func_args = json.loads(tool_call.function.arguments)
result = execute_tool(func_name, func_args)
# 将工具结果回填到对话历史
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"name": func_name,
"content": json.dumps(result, ensure_ascii=False)
})
# 再次调用模型，基于工具结果生成最终回答
second_response = openai.ChatCompletion.create(
model="gpt-3.5-turbo-0613",
messages=messages,
tools=tools_def
)
assistant_msg = second_response.choices[0].message
messages.append(assistant_msg)
# 保存会话状态
session_store[session_id] = messages
return {
"session_id": session_id,
"answer": assistant_msg.content,
"rounds": len([m for m in messages if m["role"] == "user"])
}
大模型 API 的设计原则
总结下来，大模型重塑 API 并不是要推翻 REST、gRPC 等现有体系，而是在其之上叠加一层「智能交互层」。底层业务接口仍然追求稳定、高效、结构化；上层面向用户的接口则走向自然化、生成化、Agent 化。
三个核心方向可以作为团队演进的路线图：
- 输入层升级：从结构化参数到意图解析，降低接入成本
- 能力层扩展：从数据 CRUD 到生成+工具调用，拓宽接口边界
- 架构层进化：从无状态请求到有状态 Agent，支持复杂多步任务
工程落地时不必一步到位，可以从某一个场景切入（比如客服查询、报表生成），先验证意图解析或流式输出的价值，再逐步向完整的 Agent 架构演进。
